X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd.service.xml;h=f33e8df05697529c2012f09178cee6f546277fd9;hp=da9079cbb8dfe37aafeae9c534711e7eeb50af0b;hb=6c2b9c8da1eb1bac7e8f170b913f63dbd13a16d7;hpb=f4e9cdbc6259237b2cb779a16e7c1aca0fd44e58
diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index da9079cbb..f33e8df05 100644
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -377,11 +377,10 @@
For each of the specified
commands, the first argument must be
- an absolute and literal path to an
- executable. Optionally, if the
- absolute file name is prefixed with
- @, the second token
- will be passed as
+ an absolute path to an executable.
+ Optionally, if this file name is
+ prefixed with @,
+ the second token will be passed as
argv[0] to the
executed process, followed by the
further arguments specified. If the
@@ -1118,6 +1117,35 @@
command.
+
+ FileDescriptorStoreMax=
+ Configure how many
+ file descriptors may be stored in the
+ service manager for the service using
+ sd_pid_notify_with_fds3's
+ FDSTORE=1
+ messages. This is useful for
+ implementing service restart schemes
+ where the state is serialized to
+ /run and the file
+ descriptors passed to the service
+ manager, to allow restarts without
+ losing state. Defaults to 0, i.e. no
+ file descriptors may be stored in the
+ service manager by default. All file
+ descriptors passed to the service
+ manager from a specific service are
+ passed back to the service's main
+ process on the next service
+ restart. Any file descriptors passed
+ to the service manager are
+ automatically closed when POLLHUP or
+ POLLERR is seen on them, or when the
+ service is fully stopped and no job
+ queued or being executed for
+ it.
+
+
Check
@@ -1148,13 +1176,15 @@
Each command line is split on whitespace, with
the first item being the command to execute, and the
- subsequent items being the arguments. Double quotes
+ subsequent items being the arguments. Double quotes
("...") and single quotes ('...') may be used, in
which case everything until the next matching quote
- becomes part of the same argument. Quotes themselves
- are removed after parsing. In addition, a trailing
- backslash (\) may be used to merge
- lines.
+ becomes part of the same argument. C-style escapes are
+ also supported, see table below. Quotes themselves are
+ removed after parsing and escape sequences
+ substituted. In addition, a trailing backslash
+ (\) may be used to merge lines.
+ This syntax is intended to be very similar to
shell syntax, but only the meta-characters and
@@ -1168,6 +1198,10 @@
other elements of shell syntax are not
supported.
+ The command to execute must an absolute path
+ name. It may contain spaces, but control characters
+ are not allowed.
+
The command line accepts %
specifiers as described in
systemd.unit5.
@@ -1253,6 +1287,370 @@ ExecStart=/bin/echo $ONE $TWO $THREE
>/dev/null,
&, ;, and
/bin/ls.
+
+
+ C escapes supported in command lines and environment variables
+
+
+
+
+
+ Literal
+ Actual value
+
+
+
+
+ \a
+ bell
+
+
+ \b
+ backspace
+
+
+ \f
+ form feed
+
+
+ \n
+ newline
+
+
+ \r
+ carriage return
+
+
+ \t
+ tab
+
+
+ \v
+ vertical tab
+
+
+ \\
+ backslash
+
+
+ \"
+ double quotation mark
+
+
+ \'
+ single quotation mark
+
+
+ \s
+ space
+
+
+ \xxx
+ character number xx in hexadecimal encoding
+
+
+ \nnn
+ character number nnn in octal encoding
+
+
+
+
+
+
+
+ Examples
+
+
+ Simple service
+
+ The following unit file creates a service
+ that will execute
+ /usr/sbin/foo-daemon.
+ Since no Type= is specified,
+ the default
+ Type=
+ will be assumed. systemd will assume the unit
+ to be started immediately after the program has
+ begun executing.
+
+ [Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+[Install]
+WantedBy=multi-user.target
+
+ Note that systemd assumes here that the
+ process started by systemd will continue
+ running until the service terminates. If the
+ program daemonizes itself (i.e. forks), please
+ use
+ Type=
+ instead.
+
+ Since no ExecStop= was
+ specified, systemd will send SIGTERM to all
+ processes started from this service, and after
+ a timeout also SIGKILL. This behavior can be
+ modified, see
+ systemd.kill5
+ for details.
+
+ Note that this unit type does not include
+ any type of notification when a service has
+ completed initialization. For this, you should
+ use other unit types, such as
+ Type=
+ if the service understands systemd's
+ notification protocol,
+ Type=
+ if the service can background itself or
+ Type=
+ if the unit acquires a DBus name once
+ initialization is complete. See below.
+
+
+
+ Oneshot service
+
+ Sometimes units should just execute an
+ action without keeping active processes, such
+ as a filesystem check or a cleanup action on
+ boot. For this,
+ Type=
+ exists. Units of this type will wait until the
+ process specified terminates and then fall back
+ to being inactive. The following unit will
+ perform a clenaup action:
+
+ [Unit]
+Description=Cleanup old Foo data
+
+[Service]
+Type=oneshot
+ExecStart=/usr/sbin/foo-cleanup
+
+[Install]
+WantedBy=multi-user.target
+
+ Note that systemd will consider the unit
+ to be in the state 'starting' until the program
+ has terminated, so ordered dependencies will
+ wait for the program to finish before starting
+ themselves. The unit will revert to the
+ 'inactive' state after the execution is
+ done, never reaching the 'active' state. That
+ means another request to start the unit will
+ perform the action again.
+
+ Type=
+ are the only service units that may have more
+ than one ExecStart=
+ specified. They will be executed in order until
+ either they are all successful or one of them
+ fails.
+
+
+
+ Stoppable oneshot service
+
+ Similarly to the oneshot services, there
+ are sometimes units that need to execute a
+ program to set up something and then execute
+ another to shut it down, but no process remains
+ active while they are considered
+ 'started'. Network configuration can sometimes
+ fall into this category. Another use case is if
+ a oneshot service shall not be executed a
+ each time when they are pulled in as a
+ dependency, but only the first time.
+
+ For this, systemd knows the setting
+ RemainAfterExit=,
+ which causes systemd to consider the unit to be
+ active if the start action exited successfully.
+ This directive can be used with all types, but
+ is most useful with
+ Type=
+ and
+ Type=.
+ With
+ Type=
+ systemd waits until the start action has
+ completed before it considers the unit to be
+ active, so dependencies start only after the
+ start action has succeeded. With
+ Type=
+ dependencies will start immediately after the
+ start action has been dispatched. The following
+ unit provides an example for a simple static
+ firewall.
+
+ [Unit]
+Description=Simple firewall
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/simple-firewall-start
+ExecStop=/usr/local/sbin/simple-firewall-stop
+
+[Install]
+WantedBy=multi-user.target
+
+ Since the unit is considered to be
+ running after the start action has exited,
+ invoking systemctl start on
+ that unit again will cause no action to be
+ taken.
+
+
+
+ Traditional forking services
+
+ Many traditional daemons/services
+ background (i.e. fork, daemonize) themselves
+ when starting. Set
+ Type=
+ in the service's unit file to support this mode
+ of operation. systemd will consider the service
+ to be in the process of initialization while
+ the original program is still running. Once
+ it exits successfully and at least a process
+ remains (and
+ RemainAfterExit=),
+ the service is considered started.
+
+ Often a traditional daemon only consists
+ of one process. Therefore, if only one process
+ is left after the original process terminates,
+ systemd will consider that process the main
+ process of the service. In that case, the
+ $MAINPID variable will be
+ available in ExecReload=,
+ ExecStop=, etc.
+
+ In case more than one process remains,
+ systemd will be unable to determine the main
+ process, so it will not assume there is one.
+ In that case, $MAINPID will
+ not expand to anything. However, if the process
+ decides to write a traditional PID file,
+ systemd will be able to read the main PID from
+ there. Please set PIDFile=
+ accordingly. Note that the daemon should write
+ that file before finishing with its
+ initialization, otherwise systemd might try to
+ read the file before it exists.
+
+ The following example shows a simple
+ daemon that forks and just starts one process
+ in the background:
+
+ [Unit]
+Description=Some simple daemon
+
+[Service]
+Type=forking
+ExecStart=/usr/sbin/my-simple-daemon -d
+
+[Install]
+WantedBy=multi-user.target
+
+ Please see
+ systemd.kill5
+ for details on how you can influence the way
+ systemd terminates the service.
+
+
+
+ DBus services
+
+ For services that acquire a name on the
+ DBus system bus, use
+ Type=
+ and set BusName=
+ accordingly. The service should not fork
+ (daemonize). systemd will consider the service
+ to be initialized once the name has been
+ acquired on the system bus. The following
+ example shows a typical DBus service:
+
+ [Unit]
+Description=Simple DBus service
+
+[Service]
+Type=dbus
+BusName=org.example.simple-dbus-service
+ExecStart=/usr/sbin/simple-dbus-service
+
+[Install]
+WantedBy=multi-user.target
+
+ For bus-activatable
+ services, don't include a
+ [Install] section in the
+ systemd service file, but use the
+ SystemdService= option in
+ the corresponding DBus service file, for
+ example
+ (/usr/share/dbus-1/system-services/org.example.simple-dbus-service.service):
+
+ [D-BUS Service]
+Name=org.example.simple-dbus-service
+Exec=/usr/sbin/simple-dbus-service
+User=root
+SystemdService=simple-dbus-service.service
+
+ Please see
+ systemd.kill5
+ for details on how you can influence the way
+ systemd terminates the service.
+
+
+
+ Services that notify systemd about their initialization
+
+ Type=
+ services are really easy to write, but have the
+ major disadvantage of systemd not being able to
+ tell when initialization of the given service
+ is complete. For this reason, systemd supports
+ a simple notification protocol that allows
+ daemons to make systemd aware that they are
+ done initializing. Use
+ Type=
+ for this. A typical service file for such a
+ daemon would look like this:
+
+ [Unit]
+Description=Simple notifying service
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/simple-notifying-service
+
+[Install]
+WantedBy=multi-user.target
+
+ Note that the daemon has to support
+ systemd's notification protocol, else systemd
+ will think the service hasn't started yet and
+ kill it after a timeout. For an example of how
+ to update daemons to support this protocol
+ transparently, take a look at
+ sd_notify3.
+ systemd will consider the unit to be in the
+ 'starting' state until a readiness notification
+ has arrived.
+
+ Please see
+ systemd.kill5
+ for details on how you can influence the way
+ systemd terminates the service.
+