From d44efb621acfbd09973b7e63246536fd53405d4e Mon Sep 17 00:00:00 2001 From: Christian Seiler Date: Tue, 27 Jan 2015 17:38:02 +0100 Subject: [PATCH] man: systemd.service(5): add some simple examples Add a couple of exampels, at least one for each service type that include some explanations and pointers to various relevant options. --- man/systemd.service.xml | 296 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 296 insertions(+) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 4c890dfb7..f33e8df05 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1357,6 +1357,302 @@ ExecStart=/bin/echo $ONE $TWO $THREE + + 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. + + + See Also -- 2.30.2