summaryrefslogtreecommitdiff
path: root/docs/services.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/services.md')
-rw-r--r--docs/services.md171
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
}
-