diff options
Diffstat (limited to 'docs/services.md')
| -rw-r--r-- | docs/services.md | 171 |
1 files changed, 113 insertions, 58 deletions
diff --git a/docs/services.md b/docs/services.md index 223cfb5..de0bd21 100644 --- a/docs/services.md +++ b/docs/services.md @@ -1,22 +1,121 @@ # Service Files -Services that can be started and managed by init are described by service -description files stored in `/usr/share/init`. +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. -The init process actually reads from `/etc/init.d` which contains symlinks to -the actual service files. +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. -Enabling a service means adding a symlink, disabling means removing a symlink. 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 agetty service: +generic, parameterized getty service: # # The text that init should print out when the status of the @@ -27,70 +126,27 @@ generic, parameterized agetty service: # description "agetty on %0" - # - # How to run the service. 'respawn' means restart the service when it - # terminates, 'once' means run it only once and continue with other - # services in the mean while, 'wait' means run it once, but block until - # it exits. - # + # Restart the getty when it terminates. type respawn - # - # When to start the service. 'boot' means when booting the system. Other - # options are 'reboot', 'shutdown' and 'ctrlaltdel'. The system always - # starts into the 'boot' target and then later transitions to one of the - # others. - # + # We want to spawn gettys when booting the system target boot - # - # A list of service names that must be started before this service can - # be run, i.e. this services needs to be started after those. - # - # This can only refer to generic names, not specific instances. For - # instance, you can say "after getty" to make sure a service comes up after - # all gettys are started, but you cannot specify "after agetty@tty1". - # - # Similar to 'after', there is also a 'before' keyword for specifying - # dependencies. - # + # Only run this service after the 'sysinit' service is done after sysinit # - # The 'tty' directive specifies a file to which all I/O of the process is - # redirected. 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. + # 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" - - # - # The 'exec' directive specifies the command to execute in order to start - # the service. See in the example below on how to run multiple commands. - # - # Again we use the argument to specify what terminal our getty - # should run on. - # - exec agetty %0 linux - -As can be seen in this simple example, 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 '%%'. + # 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: @@ -107,4 +163,3 @@ inside braces as can be seen in the following, abbreviated example: mkdir /var/tmp -m 0755 mount --bind /cfg/preserve/var_lib /var/lib } - |