1SYSTEMD.SERVICE(5) systemd.service SYSTEMD.SERVICE(5)
2
6 systemd.service - systemd service configuration files
7
9 systemd.service
10
12 A unit configuration file whose name ends in .service encodes
13 information about a process controlled and supervised by systemd.
14 This man page lists the configuration options specific to this unit
16 type. See systemd.unit(5) for the common options of all unit
17 configuration files. The common configuration items are configured in
18 the generic [Unit] and [Install] sections. The service specific
19 configuration options are configured in the [Service] section.
20 Additional options are listed in systemd.exec(5), which define the
22 execution environment the commands are executed in.
23 Unless DefaultDependencies= is set to false, service units will
25 implicitly have dependencies of type Requires= and After= on
26 basic.target as well as dependencies of type Conflicts= and Before= on
27 shutdown.target. These ensure that normal service units pull in basic
28 system initialization, and are terminated cleanly prior to system
29 shutdown. Only services involved with early boot or late system
30 shutdown should disable this option.
31 If a service is requested under a certain name but no unit
33 configuration file is found, systemd looks for a SysV init script by
34 the same name (with the .service suffix removed) and dynamically
35 creates a service unit from that script. This is useful for
36 compatibility with SysV.
37
39 Service files must include a [Service] section, which carries
40 information about the service and the process it supervises. A number
41 of options that may be used in this section are shared with other unit
42 types. These options are documented in systemd.exec(5). The options
43 specific to the [Service] section of service units are the following:
44 Type=
46 Configures the process start-up type for this service unit. One of
47 simple, forking, oneshot, dbus, notify.
48 If set to simple (the default value) it is expected that the
50 process configured with ExecStart= is the main process of the
51 service. In this mode, if the process offers functionality to other
52 processes on the system its communication channels should be
53 installed before the daemon is started up (e.g. sockets set up by
54 systemd, via socket activation), as systemd will immediately
55 proceed starting follow-up units.
56 If set to forking it is expected that the process configured with
58 ExecStart= will call fork() as part of its start-up. The parent
59 process is expected to exit when start-up is complete and all
60 communication channels set up. The child continues to run as the
61 main daemon process. This is the behaviour of traditional UNIX
62 daemons. If this setting is used, it is recommended to also use the
63 PIDFile= option, so that systemd can identify the main process of
64 the daemon. systemd will proceed starting follow-up units as soon
65 as the parent process exits.
66 Behaviour of oneshot is similar to simple, however it is expected
68 that the process has to exit before systemd starts follow-up units.
69 RemainAfterExit= is particularly useful for this type of service.
70 Behaviour of dbus is similar to simple, however it is expected that
72 the daemon acquires a name on the D-Bus bus, as configured by
73 BusName=. systemd will proceed starting follow-up units after the
74 D-Bus bus name has been acquired. Service units with this option
75 configured implicitly gain dependencies on the dbus.target unit.
76 Behaviour of notify is similar to simple, however it is expected
78 that the daemon sends a notification message via sd_notify(3) or an
79 equivalent call when it finished starting up. systemd will proceed
80 starting follow-up units after this notification message has been
81 sent. If this option is used NotifyAccess= (see below) should be
82 set to open access to the notification socket provided by systemd.
83 If NotifyAccess= is not set, it will implicitly be set to main.
84 RemainAfterExit=
86 Takes a boolean value that specifies whether the service shall be
87 considered active even when all its processes exited. Defaults to
88 no.
89 PIDFile=
91 Takes an absolute file name pointing to the PID file of this
92 daemon. Use of this option is recommended for services where Type=
93 is set to forking.
94 BusName=
96 Takes a D-Bus bus name, where this service is reachable as. This
97 option is mandatory for services where Type= is set to dbus, but
98 its use is otherwise recommended as well if the process takes a
99 name on the D-Bus bus.
100 ExecStart=
102 Takes a command line that is executed when this service shall be
103 started up. The first token of the command line must be an absolute
104 file name, then followed by arguments for the process. It is
105 mandatory to set this option for all services. This option may not
106 be specified more than once, except when Type=oneshot is used in
107 which case more than one ExecStart= line is accepted which are then
108 invoked one by one, sequentially in the order they appear in the
109 unit file.
110 Optionally, if the absolute file name is prefixed with @, the
112 second token will be passed as argv[0] to the executed process,
113 followed by the further arguments specified. If the first token is
114 prefixed with - an exit code of the command normally considered a
115 failure (i.e. non-zero exit status or abormal exit due to signal)
116 is ignored and considered success. If both - and @ are used for the
117 same command the former must preceed the latter. Unless
118 Type=forking is set, the process started via this command line will
119 be considered the main process of the daemon. The command line
120 accepts % specifiers as described in systemd.unit(5). On top of
121 that basic environment variable substitution is supported, where
122 ${FOO} is replaced by the string value of the environment variable
123 of the same name. Also $FOO may appear as separate word on the
124 command line in which case the variable is replaced by its value
125 split at whitespaces.
126 ExecStartPre=, ExecStartPost=
128 Additional commands that are executed before (resp. after) the
129 command in ExecStart=. Multiple command lines may be concatenated
130 in a single directive, by seperating them by semicolons (these
131 semicolons must be passed as separate words). In that case, the
132 commands are executed one after the other, serially. Alternatively,
133 these directives may be specified more than once whith the same
134 effect. However, the latter syntax is not recommended for
135 compatibility with parsers suitable for XDG .desktop files. Use of
136 these settings is optional. Specifier and environment variable
137 substitution is supported.
138 ExecReload=
140 Commands to execute to trigger a configuration reload in the
141 service. This argument takes multiple command lines, following the
142 same scheme as pointed out for ExecStartPre= above. Use of this
143 setting is optional. Specifier and environment variable
144 substitution is supported here following the same scheme as for
145 ExecStart=. One special environment variable is set: if known
146 $MAINPID is set to the main process of the daemon, and may be used
147 for command lines like the following: /bin/kill -HUP $(MAINPID).
148 ExecStop=
150 Commands to execute to stop the service started via ExecStart=.
151 This argument takes multiple command lines, following the same
152 scheme as pointed out for ExecStartPre= above. Use of this setting
153 is optional. All processes remaining for a service after the
154 commands configured in this option are run are terminated according
155 to the KillMode= setting (see below). If this option is not
156 specified the process is terminated right-away when service stop is
157 requested. Specifier and environment variable substitution is
158 supported (including $(MAINPID), see above).
159 ExecStopPost=
161 Additional commands that are executed after the service was stopped
162 using the commands configured in ExecStop=. This argument takes
163 multiple command lines, following the same scheme as pointed out
164 for ExecStartPre. Use of these settings is optional. Specifier and
165 environment variable substitution is supported.
166 RestartSec=
168 Configures the time to sleep before restarting a service (as
169 configured with Restart=). Takes a unit-less value in seconds, or a
170 time span value such as "5min 20s". Defaults to 100ms.
171 TimeoutSec=
173 Configures the time to wait for start-up and stop. If a daemon
174 service does not signal start-up completion within the configured
175 time the service will be considered failed and be shut down again.
176 If a service is asked to stop but does not terminate in the
177 specified time it will be terminated forcibly via SIGTERM, and
178 after another delay of this time with SIGKILL. (See KillMode=
179 below.) Takes a unit-less value in seconds, or a time span value
180 such as "5min 20s". Pass 0 to disable the timeout logic. Defaults
181 to 60s.
182 Restart=
184 Configures whether the main service process shall be restarted when
185 it exists. Takes one of once, restart-on-success or restart-always.
186 If set to once (the default) the service will not be restarted when
187 it exits. If set to restart-on-success it will be restarted only
188 when it exited cleanly, i.e. terminated with an exit code of 0. If
189 set to restart-always the service will be restarted regardless
190 whether it exited cleanly or not, or got terminated abnormally by a
191 signal.
192 PermissionsStartOnly=
194 Takes a boolean argument. If true, the permission related execution
195 options as configured with User= and similar options (see
196 systemd.exec(5) for more information) are only applied to the
197 process started with ExecStart=, and not to the various other
198 ExecStartPre=, ExecStartPost=, ExecReload=, ExecStop=,
199 ExecStopPost= commands. If false, the setting is applied to all
200 configured commands the same way. Defaults to false.
201 RootDirectoryStartOnly=
203 Takes a boolean argument. If true, the root directory as configured
204 with the RootDirectory= option (see systemd.exec(5) for more
205 information) is only applied to the process started with
206 ExecStart=, and not to the various other ExecStartPre=,
207 ExecStartPost=, ExecReload=, ExecStop=, ExecStopPost= commands. If
208 false, the setting is applied to all configured commands the same
209 way. Defaults to false.
210 SysVStartPriority=
212 Set the SysV start priority to use to order this service in
213 relation to SysV services lacking LSB headers. This option is only
214 necessary to fix ordering in relation to legacy SysV services, that
215 have no ordering information encoded in the script headers. As such
216 it should only be used as temporary compatibility option, and not
217 be used in new unit files. Almost always it is a better choice to
218 add explicit ordering directives via After= or Before=, instead.
219 For more details see systemd.unit(5). If used, pass an integer
220 value in the range 0-99.
221 KillMode=
223 Specifies how processes of this service shall be killed. One of
224 control-group, process-group, process, none.
225 If set to control-group all remaining processes in the control
227 group of this service will be terminated on service stop, after the
228 stop command (as configured with ExecStop=) is executed. If set to
229 process-group only the members of the process group of the main
230 service process are killed. If set to process only the main process
231 itself is killed. If set to none no process is killed. In this case
232 only the stop command will be executed on service stop, but no
233 process be killed otherwise. Processes remaining alive after stop
234 are left in their control group and the control group continues to
235 exist after stop unless it is empty. Defaults to control-croup.
236 Processes will first be terminated via SIGTERM. If then after a
238 delay (configured via the TimeoutSec= option) processes still
239 remain, the termination request is repeated with the SIGKILL
240 signal. See kill(2) for more information.
241 NonBlocking=
243 Set O_NONBLOCK flag for all file descriptors passed via
244 socket-based activation. If true, all file descriptors >= 3 (i.e.
245 all except STDIN/STDOUT/STDERR) will have the O_NONBLOCK flag set
246 and hence are in non-blocking mode. This option is only useful in
247 conjunction with a socket unit, as described in systemd.socket(5).
248 Defaults to false.
249 NotifyAccess=
251 Controls access to the service status notification socket, as
252 accessible via the sd_notify(3) call. Takes one of none (the
253 default), main or all. If none no daemon status updates are
254 accepted by the service processes, all status update messages are
255 ignored. If main only service updates sent from the main process of
256 the service are accepted. If all all services updates from all
257 members of the service´s control group are accepted. This option
258 must be set to open access to the notification socket when using
259 Type=notify (see above).
260
262 systemd(1), systemctl(8), systemd.unit(5), systemd.exec(5)
263
265 Lennart Poettering <lennart@poettering.net>
266 Developer
267systemd 09/14/2010 SYSTEMD.SERVICE(5)