init/docs/services.md

Service Files

The init process reads service descriptions from /etc/init.d which usually contains symlinks to the actual service files which can be conveniently removed or added to disable or enable services.

Default services provided by this package are installed in /usr/share/init, i.e. this is where the symlinks point to.

Note that the actual locations may be different, depending on the configure flags used.

Service descriptions can be parameterized. The arguments are extracted from the name of the symlink. Currently only 1 parameter is supported. The argument value is separated from the service name by an '@' character in the symlink name.

The file name of the sysmlink, excluding any parameters, is accepted as the canonical name of a service and used when referring to it via command line utilities or when injecting dependencies from a service file.

Syntax

Each line in a service description is made up of a keyword, followed by one or more arguments and terminated by a line break.

Blank lines are ignored and shell-style comments can be used.

Arguments are separated by space. Quotation marks can be used to treat something containing spaces or comment character as a single argument.

In between quotation marks, C-style escape sequences can be used.

Argument substitution (arguments derived from the symlink name) can be done using a '%' sign, followed by the argument index. A '%' sign can be escaped by writing '%%'.

Targets and Types

Service files specify a target which is basically like a SystemV runlevel and can be one of the following:

• boot
• reboot
• shutdown

After parsing the configuration files, the init process starts running the services for the boot target in a topological order as determined by their dependencies.

Services can be of one of the following types:

• wait
• once
• respawn

Services of type wait are started exactly once and the init process waits until they terminate before continuing with other services.

The type once also only runs services once, but immediately continues starting other services in the mean time without waiting. The init process only waits for once types when transitioning to another target.

Services of type respawn also don't stall the init process and are re-started whenever they terminate.

The keyword limit can be used a after respawn to specify how often a service may be restarted before giving up.

Dependencies

A service description file can specify dependencies using the keywords after and before, each followed by a space separated list of service names.

The init program executes a service after all the services specified by the after keyword have been started (type once or respawn) or have been completed (type wait).

The before keyword injects dependencies in reverse, i.e. all services specified after the before keyword are only executed after the service in question has been started.

If a service specified by after or before does not exist, it is simply ignored. This can occur for instance if the specified service is not enabled at all in the current configuration.

Running Services

If a service contains an exec line, the init process attempts to run it using the runsvc helper program that sets up the environment, attempts to execute the specified command line and passes the exit status back to the init process.

If multiple exec lines are specified, runsvc executes them sequentially and stops if any one returns a non-zero exit status.

The environment variables visible to the service processes are read from /etc/initd.env.

If the service description contains a tty field, the specified device file is opened by runsvc and standard I/O is redirected to it and a new session is created. The keyword truncate can be used to make runsvc truncate the file to zero size first.

For convenience, multiple exec lines can be wrapped into braces, as can be seen in one of the examples below.

Example

Below is an annotated example for a simple, service description for a generic, parameterized getty service:

#
# The text that init should print out when the status of the
# service changes.
#
# The '%0' is replaced with the first argument extracted from the
# symlink name.
#
description "agetty on %0"

# Restart the getty when it terminates.
type respawn

# We want to spawn gettys when booting the system
target boot

# Only run this service after the 'sysinit' service is done
after sysinit

#
# Redirect all I/O of the process to this file. The specified device file
# is used as a controlling tty for the process and a new session is created
# with the service process as session leader.
#
# In this example, we derive the controlling tty from the service
# description argument.
#
tty "/dev/%0"

# In order to run the service, simply fire up the agetty program
exec agetty %0 linux

If a service should sequentially run multiple commands, they can be grouped inside braces as can be seen in the following, abbreviated example:

description "mount /var"
type wait
target boot
before vfs
exec {
    mount -t tmpfs none /var
    mkdir /var/log -m 0755
    mkdir /var/spool -m 0755
    mkdir /var/lib -m 0755
    mkdir /var/tmp -m 0755
    mount --bind /cfg/preserve/var_lib /var/lib
}