
  Warning, rhgb is somewhat tricky. It is not so much a problem
of complexity of the code but rather due to the extreme environment in
which it sits during the boot process.

Starting rhgb and X:
--------------------

rhgb is started by the initscripts which drives the boot process,
just after the device detections (needed for example to get at least
the input devices needed for X recognized) but before the filesystems
are checked or mounted. 
So rhgb is started from /etc/rc.sysinit as soon as device detection
is done, and if the binary is found (which need /usr to be available).
At that point only the root filesystem is mounted, read-only and 
we are about running fsck checks on the filesystems. If /usr is not
present of if rhgb can't start X the start is retryed later once the
filesystems have been mounted.
To make sure X is started on an environment where it is being configured
properly we check that the init default from /etc/inittab is 5 or
that that init level was passed on the command line.
The problem is that X and rhgb needs a writable filesystem to export 
communication channels with the boot process. To do this a small memory
temporary filesystem is mounted under /etc/rhgb/temp first. To also
allow communication at the X level, the network loopback device lo0
is also started and initialized prior to running X.
Once both the filesystem and lo0 are ready /usr/bin/X11/X is started
using vt8 and display :1 (not :0 to allow smoothing the transition
from the temporary X server to the one started when going multiuser).
Once X is sucessfully started, the graphic code instanciates the simple
display with the progress bar and the detailed view using a vte widget.
If a specific /etc/rhgb/xorg.conf configuration file for X under rhgb 
is provided then it will be passed to the X command line to allow
a specific configuration for X boot.
Starting X from the read-only root breaks a number of things like keyboard
setting and the ability to use Ctrl+number to switch to virtual console
this has to be worked around within rhgb.

Communicating between the boot process and rhgb:
------------------------------------------------

The initscripts indicate progresses to rhgb using the rhgb_client
tool which communicates with the rhgb process using a specific socket
set-up by rhgb in /etc/rhgb/temp/rhgb-socket this is read/write
for example rhgb_client ping allows to check that rhgb is running.
rhgb_client is called on a number of predefined steps in the boot process
and the graphic view is updated accordingly.
Some of the communication is also done using a write only fifo
/etc/rhgb/temp/rhgb-console which allows to output early bootup output
and especially the fsck output which is especially important if the
check is forced so one can follow the progresses from the fsck directly
in the detailed view.
When rc.sysinit finishes and rc starts all the services, the shell scripts
used to start services (/etc/init.d/functions) also call rhgb_client to
get the status of starting all the services. At that point rhgb can also
check for failed started service and switch to detailed view to alert the
user.

The specific case of firstboot:
-------------------------------

If firstboot need to be started it will reuse the X server from rhgb,
to this rhbg export the display string to use in /etc/rhgb/temp/display.
Another problem is that X11 keyboard initialization per the information
provided in the X configuration file fails because the keymap is built
from an external process and needs a writable filesystem. To avoid confusing
the user in first boot the X keyboard setting are reset to the users
preference at that point. rhgb will then hide his own widget to let
firstboot take over the graphical display. There is some nastyness with
this too, firstboot will start a window manager (metacity) at that point
but no WM has been running up to that point.

Detecting and exposing errors:
------------------------------

rhgb will switch to detailed view when errors seems to be occuring.
Basically if the initscripts didn't report progresses for 10 seconds
rhgb will switch to detailed view to show what is happening, this can
occur for example if a filesystem is being checked, or if some timeout
occurs (network/DNS for example), once the timeout is over and further
progresses are reported, then rhbg will switch back to the normal view.
rhgb can also get failure informations from initscripts and in that 
will switch to detailed mode permanently.
Lastly if no information at all from the initscripts or from the rhgb-console
have been received for 30 seconds, rhgb will switch back to the vt1 text
console as something really serious seems to have happened and direct
manual intervention is likely to be needed.

Daniel Veillard <veillard@redhat.com>
$Id: HOW_IT_WORKS,v 1.2 2004/10/13 16:05:41 veillard Exp $
