When you boot your system, you will notice lots of text floating by. If you pay close attention, you will notice this text is the same every time you reboot your system. The sequence of all these actions is called the boot sequence and is (more or less) statically defined.

First, your boot loader will load the kernel image you have defined in the boot loader configuration into memory after which it tells the CPU to run the kernel. When the kernel is loaded and run, it initializes all kernel-specific structures and tasks and starts the init process.

This process then makes sure that all filesystems (defined in /etc/fstab) are mounted and ready to be used. Then it executes several scripts located in /etc/init.d, which will start the services you need in order to have a successfully booted system.

Finally, when all scripts are executed, init activates the terminals (in most cases just the virtual consoles which are hidden beneath Alt-F1, Alt-F2, etc.) attaching a special process called agetty to it. This process will then make sure you are able to log on through these terminals by running login.

Now init doesn't just execute the scripts in /etc/init.d randomly. Even more, it doesn't run all scripts in /etc/init.d, only the scripts it is told to execute. It decides which scripts to execute by looking into /etc/runlevels.

First, init runs all scripts from /etc/init.d that have symbolic links inside /etc/runlevels/boot. Usually, it will start the scripts in alphabetical order, but some scripts have dependency information in them, telling the system that another script must be run before they can be started.

When all /etc/runlevels/boot referenced scripts are executed, init continues with running the scripts that have a symbolic link to them in /etc/runlevels/default. Again, it will use the alphabetical order to decide what script to run first, unless a script has dependency information in it, in which case the order is changed to provide a valid start-up sequence.

Of course init doesn't decide all that by itself. It needs a configuration file that specifies what actions need to be taken. This configuration file is /etc/inittab.

If you remember the boot sequence we have just described, you will remember that init's first action is to mount all filesystems. This is defined in the following line from /etc/inittab:

si::sysinit:/sbin/rc sysinit

This line tells init that it must run /sbin/rc sysinit to initialize the system. The /sbin/rc script takes care of the initialisation, so you might say that init doesn't do much -- it delegates the task of initialising the system to another process.

Second, init executed all scripts that had symbolic links in /etc/runlevels/boot. This is defined in the following line:

rc::bootwait:/sbin/rc boot

Again the rc script performs the necessary tasks. Note that the option given to rc (boot) is the same as the subdirectory of /etc/runlevels that is used.

Now init checks its configuration file to see what runlevel it should run. To decide this, it reads the following line from /etc/inittab:

id:3:initdefault:

In this case (which the majority of Gentoo users will use), the runlevel id is 3. Using this information, init checks what it must run to start runlevel 3:

l0:0:wait:/sbin/rc shutdown
l1:S1:wait:/sbin/rc single
l2:2:wait:/sbin/rc nonetwork
l3:3:wait:/sbin/rc default
l4:4:wait:/sbin/rc default
l5:5:wait:/sbin/rc default
l6:6:wait:/sbin/rc reboot

The line that defines level 3, again, uses the rc script to start the services (now with argument default). Again note that the argument of rc is the same as the subdirectory from /etc/runlevels.

When rc has finished, init decides what virtual consoles it should activate and what commands need to be run at each console:

c1:12345:respawn:/sbin/agetty 38400 tty1 linux
c2:12345:respawn:/sbin/agetty 38400 tty2 linux
c3:12345:respawn:/sbin/agetty 38400 tty3 linux
c4:12345:respawn:/sbin/agetty 38400 tty4 linux
c5:12345:respawn:/sbin/agetty 38400 tty5 linux
c6:12345:respawn:/sbin/agetty 38400 tty6 linux

You have seen that init uses a numbering scheme to decide what runlevel it should activate. A runlevel is a state in which your system is running and contains a collection of scripts (runlevel scripts or initscripts) that must be executed when you enter or leave a runlevel.

In Gentoo, there are seven runlevels defined: three internal runlevels, and four user-defined runlevels. The internal runlevels are called sysinit, shutdown and reboot and do exactly what their names imply: initialize the system, powering off the system and rebooting the system.

The user-defined runlevels are those with an accompanying /etc/runlevels subdirectory: boot, default, nonetwork and single. The boot runlevel starts all system-necessary services which all other runlevels use. The remaining three runlevels differ in what services they start: default is used for day-to-day operations, nonetwork is used in case no network connectivity is required, and single is used when you need to fix the system.

The scripts that the rc process starts are called init scripts. Each script in /etc/init.d can be executed with the arguments start, stop, restart, pause, zap, status, ineed, iuse, needsme, usesme or broken.

To start, stop or restart a service (and all depending services), start, stop and restart should be used:

# /etc/init.d/postfix start

If you want to stop a service, but not the services that depend on it, you can use the pause argument:

# /etc/init.d/postfix pause

If you want to see what status a service has (started, stopped, paused, ...) you can use the status argument:

# /etc/init.d/postfix status

If the status information tells you that the service is running, but you know that it is not, then you can reset the status information to "stopped" with the zap argument:

# /etc/init.d/postfix zap

To also ask what dependencies the service has, you can use iuse or ineed. With ineed you can see the services that are really necessary for the correct functioning of the service. iuse on the other hand shows the services that can be used by the service, but are not necessary for the correct functioning.

# /etc/init.d/postfix ineed

Similarly, you can ask what services require the service (needsme) or can use it (usesme):

# /etc/init.d/postfix needsme

Finally, you can ask what dependencies the service requires that are missing:

# /etc/init.d/postfix broken

Gentoo's init system uses a dependency-tree to decide what service needs to be started first. As this is a tedious task that we wouldn't want our users to have to do manually, we have created tools that ease the administration of the runlevels and init scripts.

With rc-update you can add and remove init scripts to a runlevel. The rc-update tool will then automatically ask the depscan.sh script to rebuild the dependency tree.

You have already added init scripts to the "default" runlevel during the installation of Gentoo. At that time you might not have had a clue what the "default" is for, but now you should. The rc-update script requires a second argument that defines the action: add, del or show.

To add or remove an init script, just give rc-update the add or del argument, followed by the init script and the runlevel. For instance:

# rc-update del postfix default

The rc-update show command will show all the available init scripts and list at which runlevels they will execute:

# rc-update show

Init scripts can be quite complex. It is therefore not really desirable to have the users edit the init script directly, as it would make it more error-prone. It is however important to be able to configure such a service. For instance, you might want to give more options to the service itself.

A second reason to have this configuration outside the init script is to be able to update the init scripts without the fear that your configuration changes will be undone.

Gentoo provides an easy way to configure such a service: every init script that can be configured has a file in /etc/conf.d. For instance, the apache2 initscript (called /etc/init.d/apache2) has a configuration file called /etc/conf.d/apache2, which can contain the options you want to give to the Apache 2 server when it is started:

APACHE2_OPTS="-D PHP4"

Such a configuration file contains variables and variables alone (just like /etc/make.conf), making it very easy to configure services. It also allows us to provide more information about the variables (as comments).

No, writing an init script is usually not necessary as Gentoo provides ready-to-use init scripts for all provided services. However, you might have installed a service without using Portage, in which case you will most likely have to create an init script.

Do not use the init script provided by the service if it isn't explicitly written for Gentoo: Gentoo's init scripts are not compatible with the init scripts used by other distributions!

The basic layout of an init script is shown below.

#!/sbin/runscript

depend() {
  (Dependency information)
}

start() {
  (Commands necessary to start the service)
}

stop() {
  (Commands necessary to stop the service)
}

restart() {
  (Commands necessary to restart the service)
}

Any init script requires the start() function to be defined. All other sections are optional.

There are two dependencies you can define: use and need. As we have mentioned before, the need dependency is more strict than the use dependency. Following this dependency type you enter the service you depend on, or the virtual dependency.

A virtual dependency is a dependency that a service provides, but that is not provided solely by that service. Your init script can depend on a system logger, but there are many system loggers available (metalogd, syslog-ng, sysklogd, ...). As you cannot need every single one of them (no sensible system has all these system loggers installed and running) we made sure that all these services provide a virtual dependency.

Let us take a look at the dependency information for the postfix service.

depend() {
  need net
  use logger dns
  provide mta
}

As you can see, the postfix service:

• requires the (virtual) net dependency (which is provided by, for instance, /etc/init.d/net.eth0)
• uses the (virtual) logger dependency (which is provided by, for instance, /etc/init.d/syslog-ng)
• uses the (virtual) dns dependency (which is provided by, for instance, /etc/init.d/named)
• provides the (virtual) mta dependency (which is common for all mail servers)

In some cases you might not require a service, but want your service to be started before (or after) another service if it is available on the system (note the conditional - this is no dependency anymore) and run in the same runlevel (note the conditional - only services in the same runlevel are involved). You can provide this information using the before or after settings.

As an example we view the settings of the Portmap service:

depend() {
  need net
  before inetd
  before xinetd
}

You can also use the "*" glob to catch all services in the same runlevel, although this isn't advisable.

depend() {
  before *
}

If your service must write to local disks, it should need localmount. If it places anything in /var/run such as a pidfile, then it should start after bootmisc:

depend() {
  need localmount
  after bootmisc
}

Next to the depend() functionality, you also need to define the start() function. This one contains all the commands necessary to initialize your service. It is advisable to use the ebegin and eend functions to inform the user about what is happening:

start() {
  ebegin "Starting my_service"
  start-stop-daemon --start --exec /path/to/my_service \
    --pidfile /path/to/my_pidfile
  eend $?
}

Both --exec and --pidfile should be used in start and stop functions. If the service does not create a pidfile, then use --make-pidfile if possible, though you should test this to be sure. Otherwise, don't use pidfiles. You can also add --quiet to the start-stop-daemon options, but this is not recommended unless the service is extremely verbose. Using --quiet may hinder debugging if the service fails to start.

If you need more examples of the start() function, please read the source code of the available init scripts in your /etc/init.d directory.

Other functions you can define are: stop() and restart(). You are not obliged to define these functions! Our init system is intelligent enough to fill these functions by itself if you use start-stop-daemon.

Although you do not have to create a stop() function, here is an example:

stop() {
  ebegin "Stopping my_service"
  start-stop-daemon --stop --exec /path/to/my_service \
    --pidfile /path/to/my_pidfile
  eend $?
}

If your service runs some other script (for example, bash, python, or perl), and this script later changes names (for example, foo.py to foo), then you will need to add --name to start-stop-daemon. You must specify the name that your script will be changed to. In this example, a service starts foo.py, which changes names to foo:

start() {
  ebegin "Starting my_script"
  start-stop-daemon --start --exec /path/to/my_script \
    --pidfile /path/to/my_pidfile --name foo
  eend $?
}

start-stop-daemon has an excellent man page available if you need more information:

$ man start-stop-daemon

Gentoo's init script syntax is based on the Bourne Again Shell (bash) so you are free to use bash-compatible constructs inside your init script.

If you want your init script to support more options than the ones we have already encountered, you should add the option to the opts variable, and create a function with the same name as the option. For instance, to support an option called restartdelay:

opts="${opts} restartdelay"

restartdelay() {
  stop
  sleep 3    # Wait 3 seconds before starting again
  start
}

You don't have to do anything to support a configuration file in /etc/conf.d: if your init script is executed, the following files are automatically sourced (i.e. the variables are available to use):

• /etc/conf.d/<your init script>
• /etc/conf.d/basic
• /etc/rc.conf

Also, if your init script provides a virtual dependency (such as net), the file associated with that dependency (such as /etc/conf.d/net) will be sourced too.

Many laptop users know the situation: at home you need to start net.eth0 while you don't want to start net.eth0 while you're on the road (as there is no network available). With Gentoo you can alter the runlevel behaviour to your own will.

For instance you can create a second "default" runlevel which you can boot that has other init scripts assigned to it. You can then select at boottime what default runlevel you want to use.

First of all, create the runlevel directory for your second "default" runlevel. As an example we create the offline runlevel:

# mkdir /etc/runlevels/offline

Add the necessary init scripts to the newly created runlevels. For instance, if you want to have an exact copy of your current default runlevel but without net.eth0:

(Copy all services from default runlevel to offline runlevel)
# cd /etc/runlevels/default
# for service in *; do rc-update add $service offline; done
(Remove unwanted service from offline runlevel)
# rc-update del net.eth0 offline
(Display active services for offline runlevel)
# rc-update show offline
(Partial sample Output)
               acpid | offline
          domainname | offline
               local | offline
            net.eth0 |

Even though net.eth0 has been removed from the offline runlevel, udev will still attempt to start any devices it detects and launch the appropriate services. Therefore, you will need to add each network service you do not want started (as well as services for any other devices that may be started by udev) to /etc/conf.d/rc as shown.

RC_COLDPLUG="yes"
(Next, specify the services you do not want automatically started)
RC_PLUG_SERVICES="!net.eth0"

Now edit your bootloader configuration and add a new entry for the offline runlevel. For instance, in /boot/grub/grub.conf:

title Gentoo Linux Offline Usage
  root (hd0,0)
  kernel (hd0,0)/kernel-2.4.25 root=/dev/hda3 softlevel=offline

Voilà, you're all set now. If you boot your system and select the newly added entry at boot, the offline runlevel will be used instead of the default one.

Using bootlevel is completely analogous to softlevel. The only difference here is that you define a second "boot" runlevel instead of a second "default" runlevel.