From 0d624a785aed0423ee87f70d33de97df9662844b Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Thu, 1 Jul 2010 19:39:35 +0200 Subject: [PATCH] man: finish service man page --- man/systemd.service.xml | 516 +++++++++++++++++++++++++++++-------- man/systemd.special.xml.in | 4 +- man/systemd.unit.xml | 10 + src/service.c | 2 +- 4 files changed, 420 insertions(+), 112 deletions(-) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 5230a783..449fe656 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -62,140 +62,437 @@ specific to this unit type. See systemd.unit5 for the common options of all unit configuration - files. + files. The common configuration items are configured + in the generic [Unit] and [Install] sections. The + service specific configuration options are configured + in the [Service] section. + + Additional options are listed in systemd.exec5. Options + Service files must include a [Service] section, + which carries information about the service and the + process it supervises. A number of options that may be + used in this section are shared with other unit + types. These options are documented in + systemd.exec5. The + options specific to the [Service] section of service + units are the following: + Type= - - One of - forking, - simple, - finish, - dbus. - - If set to - forking - (the default) it is expected - that the process configured - with - ExecStart= - will start up and call - fork(). The - parent process is expected to - finish when start-up is - complete and all communication - channels set up. The child - continues to run as the main - daemon process. This is the - behaviour of traditional UNIX - daemons. If this setting is - used, it is recommended to also - use the - PIDFile= - option, so that systemd can - identify the main process of - the daemon. systemd will proceed - starting follow-up units as soon - as the parent process exits. - - If set to - simple (the - recommended value) it is - expected that the process - configured with - ExecStart= - is the main process of the - daemon. In this mode, - communication channels must be - available before the daemon is - started up (sockets set up by systemd), - as systemd will immediately proceed - starting follow-up units. - - Behaviour of - finish is - similar to - simple, - however it is expected that - the process has to exit before - systemd starts follow-up - units. ValidNoProcess= - is particularly useful for - this type of service. - - Behaviour of - dbus is - similar to - simple, - however it is expected that - the daemon acquires a name on - the D-Bus bus, as configured - by - BusName=. Systemd will - proceed starting follow-up - units after the D-Bus bus name has been - acquired. + + Configures the process + start-up type for this service + unit. One of , + , + , + , + . + + If set to + (the default + value) it is expected that the process + configured with + ExecStart= is the + main process of the service. In this + mode, communication channels must be + installed before the daemon is started + up (e.g. sockets set up by systemd, + via socket activation), as systemd + will immediately proceed starting + follow-up units. + + If set to + it is + expected that the process configured + with ExecStart= + will start up and call + fork(). The + parent process is expected to finish + when start-up is complete and all + communication channels set up. The + child continues to run as the main + daemon process. This is the behaviour + of traditional UNIX daemons. If this + setting is used, it is recommended to + also use the + PIDFile= option, so + that systemd can identify the main + process of the daemon. systemd will + proceed starting follow-up units as + soon as the parent process + exits. + + Behaviour of + is similar + to , however + it is expected that the process has to + exit before systemd starts follow-up + units. ValidNoProcess= + is particularly useful for this type + of service. + + Behaviour of + is similar to + , however it + is expected that the daemon acquires a + name on the D-Bus bus, as configured + by + BusName=. systemd + will proceed starting follow-up units + after the D-Bus bus name has been + acquired. + + Behaviour of + is similar to + , however it is + expected that the daemon sends a + notification message via + sd_notify3 + or an equivalent call when it finished + starting up. systemd will proceed + starting follow-up units after this + notification message has been sent. If + this option is used + (see + below) must be set to open access to + the notification socket provided by + systemd. + ValidNoProcess= - - Takes a boolean value - that specifies whether the service - shall be considered active - even when all its processes - exited. Defaults to no. + + Takes a boolean value + that specifies whether the service + shall be considered active even when + all its processes exited. Defaults to + . PIDFile= - - Takes an absolute file - name pointing to the PID file - of this daemon. Use of this - option is recommended for - services where - Type= is - set to - forking. + + Takes an absolute file + name pointing to the PID file of this + daemon. Use of this option is + recommended for services where + Type= is set to + . BusName= - - Takes a D-Bus bus name, - where this service is reachable - as. This option is mandatory - for services where - Type= is - set to - dbus, but - its use is otherwise - recommended as well if the - process takes a name on the - D-Bus bus. + + Takes a D-Bus bus + name, where this service is reachable + as. This option is mandatory for + services where + Type= is set to + , but its use + is otherwise recommended as well if + the process takes a name on the D-Bus + bus. ExecStart= - - Takes a command line - that is executed when this - service shall be started - up. The first word of the - command line must be an - absolute file name. It is - mandatory to set this option - for all services. - + Takes a command line + that is executed when this service + shall be started up. The first token + of the command line must be an + absolute file name, then followed by + arguments for the process. It is + mandatory to set this option for all + services. This option may not be + specified more than once. Optionally, + if the absolute file name is prefixed + with @, the second token will be + passed as argv[0] to the executed + process, followed by the further + arguments specified. Unless + is set, + the process started via this command + line will be considered the main + process of the + daemon. + + + + ExecStartPre= + ExecStartPost= + Additional commands + that are executed before (resp. after) + the command in + ExecStart=. If + specified more than once, all commands + are executed one after the other, + serially. Use of these settings is + optional. + + + + ExecReload= + Commands to execute to + trigger a configuration reload in the + service. If used more than once, all + commands are executed one after the + other, serially. Use of this setting is optional. + + + + + ExecStop= + Commands to execute to + stop the service started via + ExecStart=. If used + more than once, all commands are + executed one after the other, + serially. Use of this setting is + optional. All processes remaining for + a service after the commands + configured in this option are run are + terminated according to the + KillMode= setting + (see below). If this option is not + specified the process is terminated + right-away when service stop is + requested. + + + + ExecStopPost= + Additional commands + that are executed after the service + was stopped using the commands + configured in + ExecStop=. If + specified more than once, all commands + are executed one after the other, + serially. Use of these settings is + optional. + + + + RestartSec= + Configures the time to + sleep before restarting a service (as + configured with + Restart=). Takes a + unit-less value in seconds, or a time + span value such as "5min + 20s". Defaults to + 100ms. + + + + TimeoutSec= + Configures the time to + wait for start-up and stop. If a + daemon service does not signal + start-up completion within the + configured time the service will be + considered failed and be shut down + again. If a service is asked to stop + but does not terminate in the + specified time it will be terminated + forcibly via SIGTERM, and after + another delay of this time with + SIGKILL. (See + + below.) Takes a unit-less value in seconds, or a + time span value such as "5min + 20s". Pass 0 to disable the timeout + logic. Defaults to + 60s. + + + + Restart= + Configures whether the + main service process shall be restarted when + it exists. Takes one of + , + or + . If + set to (the + default) the service will not be + restarted when it exits. If set to + it + will be restarted only when it exited + cleanly, i.e. terminated with an exit + code of 0. If set to + the + service will be restarted regardless + whether it exited cleanly or not, or + got terminated abnormally by a + signal. + + + + PermissionsStartOnly= + Takes a boolean + argument. If true, the permission + related execution options as + configured with + User= and similar + options (see + systemd.exec5 + for more information) are only applied + to the process started with + ExecStart=, and not + to the various other + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, + ExecStopPost= + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false. + + + + RootDirectoryStartOnly= + Takes a boolean + argument. If true, the root directory + as configured with the + RootDirectory= + option (see + systemd.exec5 + for more information) is only applied + to the process started with + ExecStart=, and not + to the various other + ExecStartPre=, + ExecStartPost=, + ExecReload=, + ExecStop=, + ExecStopPost= + commands. If false, the setting is + applied to all configured commands the + same way. Defaults to + false. + + + + SysVStartPriority= + Set the SysV start + priority to use to order this service + in relation to SysV services lacking + LSB headers. This option is only + necessary to fix ordering in relation + to legacy SysV services, that have no + ordering information encoded in the + script headers. As such it should only + be used as temporary compatibility + option, and not be used in new unit + files. Almost always it is a better + choice to add explicit ordering + directives via + After= or + Before=, + instead. For more details see + systemd.unit5. If + used, pass an integer value in the + range 0-99. + + + + KillMode= + Specifies how + processes of this service shall be + killed. One of + , + , + , + . + + If set to + all + remaining processes in the control + group of this service will be + terminated on service stop, after the + stop command (as configured with + ExecStop=) is + executed. If set to + only + the members of the process group of + the main service process are + killed. If set to + only the main + process itself is killed. If set to + no process is + killed. In this case only the stop + command will be executed on service + stop, but no process be killed + otherwise. Processes remaining alive + after stop are left in their control + group and the control group continues + to exist after stop unless it is + empty. Defaults to + . + + Processes will first be + terminated via SIGTERM. If then after + a delay (configured via the + option) + processes still remain, the + termination request is repeated with + the SIGKILL signal. See + kill2 + for more + information. + + + + NonBlocking= + Set O_NONBLOCK flag + for all file descriptors passed via + socket-based activation. If true, all + file descriptors >= 3 (i.e. all except + STDIN/STDOUT/STDERR) will have + the O_NONBLOCK flag set and hence are in + non-blocking mode. This option is only + useful in conjunction with a socket + unit, as described in + systemd.socket5. Defaults + to false. + + + + NotifyAccess= + Controls access to the + service status notification socket, as + accessible via the + sd_notify3 + call. Takes one of + (the default), + or + . If + no daemon status + updates are accepted by the service + processes, all status update messages + are ignored. If + only service updates sent from the + main process of the service are + accepted. If all + services updates from all members of + the service's control group are + accepted. This option must be set to + open access to the notification socket + when using + Type=notify (see above). @@ -205,8 +502,9 @@ See Also systemd8, - systemctl8 - systemd.unit5 + systemctl8, + systemd.unit5, + systemd.exec5 diff --git a/man/systemd.special.xml.in b/man/systemd.special.xml.in index 0c86902a..79c6db1a 100644 --- a/man/systemd.special.xml.in +++ b/man/systemd.special.xml.in @@ -246,8 +246,8 @@ mounts listed in /etc/fstab that have the - auto and - comment=systemd.mount + and + mount options set. systemd automatically diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 3509388c..81634410 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -102,6 +102,16 @@ and are equivalent. + Time span values encoded in unit files can be + written in various formats. A stand-alone number + specifies a time in seconds. If suffixed with a time + unit, the unit is honored. A concatentation of + multiple value with units is supported, in which case + the values are added up. Example: "50" refers to 50 + seconds; "2min 200ms" refers to 2 minutes plus 200 + milliseconds, i.e. 120200ms. The following time units + are understood: s, min, h, d, w, ms, us. + Empty lines and lines starting with # or ; are ignored. This may be used for commenting. diff --git a/src/service.c b/src/service.c index d5e681a3..10e9ccfb 100644 --- a/src/service.c +++ b/src/service.c @@ -2625,8 +2625,8 @@ static const char* const service_restart_table[_SERVICE_RESTART_MAX] = { DEFINE_STRING_TABLE_LOOKUP(service_restart, ServiceRestart); static const char* const service_type_table[_SERVICE_TYPE_MAX] = { - [SERVICE_FORKING] = "forking", [SERVICE_SIMPLE] = "simple", + [SERVICE_FORKING] = "forking", [SERVICE_FINISH] = "finish", [SERVICE_DBUS] = "dbus", [SERVICE_NOTIFY] = "notify" -- 2.39.5