1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
7 This file is part of systemd.
9 Copyright 2010 Lennart Poettering
11 systemd is free software; you can redistribute it and/or modify it
12 under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 2 of the License, or
14 (at your option) any later version.
16 systemd is distributed in the hope that it will be useful, but
17 WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 General Public License for more details.
21 You should have received a copy of the GNU General Public License
22 along with systemd; If not, see <http://www.gnu.org/licenses/>.
25 <refentry id="systemd.exec">
27 <title>systemd.exec</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.exec</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.exec</refname>
47 <refpurpose>systemd execution environment configuration</refpurpose>
51 <para><filename>systemd.service</filename>,
52 <filename>systemd.socket</filename>,
53 <filename>systemd.mount</filename></para>
57 <title>Description</title>
59 <para>Unit configuration files for services, sockets
60 and mount points share a subset of configuration
61 options which define the execution environment of
62 spawned processes.</para>
64 <para>This man page lists the configuration options
65 shared by these three unit types. See
66 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
67 for the common options of all unit configuration
69 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
71 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
72 for more information on the specific unit
73 configuration files. The execution specific
74 configuration options are configured in the [Service],
75 [Socket] resp. [Mount] section, depending on the unit
80 <title>Options</title>
85 <term><varname>WorkingDirectory=</varname></term>
87 <listitem><para>Takes an absolute
88 directory path. Sets the working
89 directory for executed
90 processes.</para></listitem>
94 <term><varname>RootDirectory=</varname></term>
96 <listitem><para>Takes an absolute
97 directory path. Sets the root
98 directory for executed processes, with
100 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
101 system call. If this is used it must
102 be ensured that the process and all
103 its auxiliary files are available in
104 the <function>chroot()</function>
105 jail.</para></listitem>
109 <term><varname>User=</varname></term>
110 <term><varname>Group=</varname></term>
112 <listitem><para>Sets the Unix user
113 resp. group the processes are executed
114 as. Takes a single user resp. group
115 name or ID as argument. If no group is
116 set the default group of the user is
117 chosen.</para></listitem>
121 <term><varname>SupplementaryGroups=</varname></term>
123 <listitem><para>Sets the supplementary
124 Unix groups the processes are executed
125 as. This takes a space separated list
126 of group names or IDs. This option may
127 be specified more than once in which
128 case all listed groups are set as
129 supplementary groups. This option does
130 not override but extends the list of
131 supplementary groups configured in the
132 system group database for the
133 user.</para></listitem>
137 <term><varname>Nice=</varname></term>
139 <listitem><para>Sets the default nice
140 level (scheduling priority) for
141 executed processes. Takes an integer
142 between -20 (highest priority) and 19
143 (lowest priority). See
144 <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>
145 for details.</para></listitem>
149 <term><varname>OOMScoreAdjust=</varname></term>
151 <listitem><para>Sets the adjustment
152 level for the Out-Of-Memory killer for
153 executed processes. Takes an integer
154 between -1000 (to disable OOM killing
155 for this process) and 1000 (to make
156 killing of this process under memory
157 pressure very likely). See <ulink
158 url="http://www.kernel.org/doc/Documentation/filesystems/proc.txt">proc.txt</ulink>
159 for details.</para></listitem>
163 <term><varname>IOSchedulingClass=</varname></term>
165 <listitem><para>Sets the IO scheduling
166 class for executed processes. Takes an
167 integer between 0 and 3 or one of the
168 strings <option>none</option>,
169 <option>realtime</option>,
170 <option>best-effort</option> or
171 <option>idle</option>. See
172 <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry>
173 for details.</para></listitem>
177 <term><varname>IOSchedulingPriority=</varname></term>
179 <listitem><para>Sets the IO scheduling
180 priority for executed processes. Takes
181 an integer between 0 (highest
182 priority) and 7 (lowest priority). The
183 available priorities depend on the
184 selected IO scheduling class (see
186 <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry>
187 for details.</para></listitem>
191 <term><varname>CPUSchedulingPolicy=</varname></term>
193 <listitem><para>Sets the CPU
194 scheduling policy for executed
195 processes. Takes one of
196 <option>other</option>,
197 <option>batch</option>,
198 <option>idle</option>,
199 <option>fifo</option> or
200 <option>rr</option>. See
201 <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry>
202 for details.</para></listitem>
206 <term><varname>CPUSchedulingPriority=</varname></term>
208 <listitem><para>Sets the CPU
209 scheduling priority for executed
210 processes. Takes an integer between 1
211 (lowest priority) and 99 (highest
212 priority). The available priority
213 range depends on the selected CPU
214 scheduling policy (see above). See
215 <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry>
216 for details.</para></listitem>
220 <term><varname>CPUSchedulingResetOnFork=</varname></term>
222 <listitem><para>Takes a boolean
223 argument. If true elevated CPU
224 scheduling priorities and policies
225 will be reset when the executed
226 processes fork, and can hence not leak
227 into child processes. See
228 <citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry>
229 for details. Defaults to false.</para></listitem>
233 <term><varname>CPUAffinity=</varname></term>
235 <listitem><para>Controls the CPU
236 affinity of the executed
237 processes. Takes a space-separated
238 list of CPU indexes. See
239 <citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry>
240 for details.</para></listitem>
244 <term><varname>UMask=</varname></term>
246 <listitem><para>Controls the file mode
247 creation mask. Takes an access mode in
249 <citerefentry><refentrytitle>umask</refentrytitle><manvolnum>2</manvolnum></citerefentry>
250 for details. Defaults to
251 0002.</para></listitem>
255 <term><varname>Environment=</varname></term>
257 <listitem><para>Sets environment
258 variables for executed
259 processes. Takes a space-separated
260 list of variable assignments. This
261 option may be specified more than once
262 in which case all listed variables
263 will be set. If the same variable is
264 set twice the later setting will
265 override the earlier setting. See
266 <citerefentry><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
267 for details.</para></listitem>
270 <term><varname>EnvironmentFile=</varname></term>
271 <listitem><para>Similar to
272 <varname>Environment=</varname> but
273 reads the environment variables from a
274 text file. The text file should
275 contain new-line separated variable
276 assignments. Empty lines and lines
277 starting with ; or # will be ignored,
278 which may be used for commenting. The
279 argument passed should be an absolute
280 file name, optionally prefixed with
281 "-", which indicates that if the file
282 does not exist it won't be read and no
283 error or warning message is
284 logged.</para></listitem>
288 <term><varname>StandardInput=</varname></term>
289 <listitem><para>Controls where file
290 descriptor 0 (STDIN) of the executed
291 processes is connected to. Takes one
292 of <option>null</option>,
293 <option>tty</option>,
294 <option>tty-force</option>,
295 <option>tty-fail</option> or
296 <option>socket</option>. If
297 <option>null</option> is selected
298 standard input will be connected to
299 <filename>/dev/null</filename>,
300 i.e. all read attempts by the process
301 will result in immediate EOF. If
302 <option>tty</option> is selected
303 standard input is connected to a TTY
305 <varname>TTYPath=</varname>, see
306 below) and the executed process
307 becomes the controlling process of the
308 terminal. If the terminal is already
309 being controlled by another process the
310 executed process waits until the current
311 controlling process releases the
313 <option>tty-force</option>
314 is similar to <option>tty</option>,
315 but the executed process is forcefully
316 and immediately made the controlling
317 process of the terminal, potentially
318 removing previous controlling
320 terminal. <option>tty-fail</option> is
321 similar to <option>tty</option> but if
322 the terminal already has a controlling
323 process start-up of the executed
325 <option>socket</option> option is only
326 valid in socket-activated services,
327 and only when the socket configuration
329 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
330 for details) specifies a single socket
331 only. If this option is set standard
332 input will be connected to the socket
333 the service was activated from, which
334 is primarily useful for compatibility
335 with daemons designed for use with the
337 <citerefentry><refentrytitle>inetd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
338 daemon. This setting defaults to
339 <option>null</option>.</para></listitem>
342 <term><varname>StandardOutput=</varname></term>
343 <listitem><para>Controls where file
344 descriptor 1 (STDOUT) of the executed
345 processes is connected to. Takes one
346 of <option>inherit</option>,
347 <option>null</option>,
348 <option>tty</option>,
349 <option>syslog</option>,
350 <option>kmsg</option> or
351 <option>socket</option>. If set to
352 <option>inherit</option> the file
353 descriptor of standard input is
354 duplicated for standard output. If set
355 to <option>null</option> standard
356 output will be connected to
357 <filename>/dev/null</filename>,
358 i.e. everything written to it will be
359 lost. If set to <option>tty</option>
360 standard output will be connected to a
361 tty (as configured via
362 <varname>TTYPath=</varname>, see
363 below). If the TTY is used for output
364 only the executed process will not
365 become the controlling process of the
366 terminal, and will not fail or wait
367 for other processes to release the
368 terminal. <option>syslog</option>
369 connects standard output to the
370 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
371 system logger. <option>kmsg</option>
372 connects it with the kernel log buffer
373 which is accessible via
374 <citerefentry><refentrytitle>dmesg</refentrytitle><manvolnum>1</manvolnum></citerefentry>. <option>socket</option>
375 connects standard output to a socket
376 from socket activation, semantics are
377 similar to the respective option of
378 <varname>StandardInput=</varname>.
379 This setting defaults to
380 <option>inherit</option>.</para></listitem>
383 <term><varname>StandardError=</varname></term>
384 <listitem><para>Controls where file
385 descriptor 2 (STDERR) of the executed
386 processes is connected to. The
387 available options are identical to
389 <varname>StandardOutput=</varname>,
390 with one exception: if set to
391 <option>inherit</option> the file
392 descriptor used for standard output is
393 duplicated for standard error. This
395 <option>inherit</option>.</para></listitem>
398 <term><varname>TTYPath=</varname></term>
399 <listitem><para>Sets the terminal
400 device node to use if standard input,
401 output or stderr are connected to a
402 TTY (see above). Defaults to
403 <filename>/dev/console</filename>.</para></listitem>
406 <term><varname>SyslogIdentifer=</varname></term>
407 <listitem><para>Sets the process name
408 to prefix log lines sent to syslog or
409 the kernel log buffer with. If not set
410 defaults to the process name of the
411 executed process. This option is only
413 <varname>StandardOutput=</varname> or
414 <varname>StandardError=</varname> are
415 set to <option>syslog</option> or
416 <option>kmsg</option>.</para></listitem>
419 <term><varname>SyslogFacility=</varname></term>
420 <listitem><para>Sets the syslog
421 facility to use when logging to
422 syslog. One of <option>kern</option>,
423 <option>user</option>,
424 <option>mail</option>,
425 <option>daemon</option>,
426 <option>auth</option>,
427 <option>syslog</option>,
428 <option>lpr</option>,
429 <option>news</option>,
430 <option>uucp</option>,
431 <option>cron</option>,
432 <option>authpriv</option>,
433 <option>ftp</option>,
434 <option>local0</option>,
435 <option>local1</option>,
436 <option>local2</option>,
437 <option>local3</option>,
438 <option>local4</option>,
439 <option>local5</option>,
440 <option>local6</option> or
441 <option>local7</option>. See
442 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
443 for details. This option is only
445 <varname>StandardOutput=</varname> or
446 <varname>StandardError=</varname> are
447 set to <option>syslog</option>.
449 <option>daemon</option>.</para></listitem>
452 <term><varname>SyslogLevel=</varname></term>
453 <listitem><para>Default syslog level
454 to use when logging to syslog or the
455 kernel log buffer. One of
456 <option>emerg</option>,
457 <option>alert</option>,
458 <option>crit</option>,
459 <option>err</option>,
460 <option>warning</option>,
461 <option>notice</option>,
462 <option>info</option>,
463 <option>debug</option>. See
464 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
465 for details. This option is only
467 <varname>StandardOutput=</varname> or
468 <varname>StandardError=</varname> are
469 set to <option>syslog</option> or
470 <option>kmsg</option>. Note that
471 individual lines output by the daemon
472 might be prefixed with a different log
473 level which can be used to override
474 the default log level specified
475 here. The interpretation of these
476 prefixes may be disabled with
477 <varname>SyslogLevelPrefix=</varname>,
478 see below. For details see
479 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
482 <option>info</option>.</para></listitem>
486 <term><varname>SyslogLevelPrefix=</varname></term>
487 <listitem><para>Takes a boolean
488 argument. If true and
489 <varname>StandardOutput=</varname> or
490 <varname>StandardError=</varname> are
491 set to <option>syslog</option> or
492 <option>kmsg</option> log lines
493 written by the executed process that
494 are prefixed with a log level will be
495 passed on to syslog with this log
496 level set but the prefix removed. If
497 set to false, the interpretation of
498 these prefixes is disabled and the
499 logged lines are passed on as-is. For
500 details about this prefixing see
501 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
502 Defaults to true.</para></listitem>
506 <term><varname>TimerSlackNSec=</varname></term>
507 <listitem><para>Sets the timer slack
508 in nanoseconds for the executed
509 processes. The timer slack controls the
510 accuracy of wake-ups triggered by
512 <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>
513 for more information. Note that in
514 contrast to most other time span
515 definitions this parameter takes an
516 integer value in nano-seconds and does
517 not understand any other
518 units.</para></listitem>
522 <term><varname>LimitCPU=</varname></term>
523 <term><varname>LimitFSIZE=</varname></term>
524 <term><varname>LimitDATA=</varname></term>
525 <term><varname>LimitSTACK=</varname></term>
526 <term><varname>LimitCORE=</varname></term>
527 <term><varname>LimitRSS=</varname></term>
528 <term><varname>LimitNOFILE=</varname></term>
529 <term><varname>LimitAS=</varname></term>
530 <term><varname>LimitNPROC=</varname></term>
531 <term><varname>LimitMEMLOCK=</varname></term>
532 <term><varname>LimitLOCKS=</varname></term>
533 <term><varname>LimitSIGPENDING=</varname></term>
534 <term><varname>LimitMSGQUEUE=</varname></term>
535 <term><varname>LimitNICE=</varname></term>
536 <term><varname>LimitRTPRIO=</varname></term>
537 <term><varname>LimitRTTIME=</varname></term>
538 <listitem><para>These settings control
539 various resource limits for executed
541 <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>
542 for details.</para></listitem>
546 <term><varname>PAMName=</varname></term>
547 <listitem><para>Sets the PAM service
548 name to set up a session as. If set
549 the executed process will be
550 registered as a PAM session under the
551 specified service name. This is only
552 useful in conjunction with the
553 <varname>User=</varname> setting. If
554 not set no PAM session will be opened
555 for the executed processes. See
556 <citerefentry><refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum></citerefentry>
557 for details.</para></listitem>
561 <term><varname>TCPWrapName=</varname></term>
562 <listitem><para>If this is a
563 socket-activated service this sets the
564 tcpwrap service name to check the
565 permission for the current connection
566 with. This is only useful in
567 conjunction with socket-activated
568 services, and stream sockets (TCP) in
569 particular. It has no effect on other
570 socket types (e.g. datagram/UDP) and on processes
571 unrelated to socket-based
572 activation. If the tcpwrap
573 verification fails daemon start-up
574 will fail and the connection is
576 <citerefentry><refentrytitle>tcpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
577 for details.</para></listitem>
581 <term><varname>Capabilities=</varname></term>
582 <listitem><para>Controls the
583 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
584 set for the executed process. Take a
585 capability string as described in
586 <citerefentry><refentrytitle>cap_from_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
587 Note that this capability set is
588 usually influenced by the capabilities
589 attached to the executed
590 file.</para></listitem>
594 <term><varname>SecureBits=</varname></term>
595 <listitem><para>Controls the secure
596 bits set for the executed process. See
597 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
598 for details. Takes a list of strings:
599 <option>keep-caps</option>,
600 <option>keep-caps-locked</option>,
601 <option>no-setuid-fixup</option>,
602 <option>no-setuid-fixup-locked</option>,
603 <option>no-setuid-noroot</option> and/or
604 <option>no-setuid-noroot-locked</option>.
609 <term><varname>CapabilityBoundingSetDrop=</varname></term>
611 <listitem><para>Controls the
612 capability bounding set drop set for
613 the executed process. See
614 <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
615 for details. Takes a list of
616 capability names as read by
617 <citerefentry><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
622 <term><varname>ControlGroup=</varname></term>
624 <listitem><para>Controls the control
625 groups the executed processes shall be
626 made members of. Takes a
627 space-separated list of cgroup
628 identifiers. A cgroup identifier has a
630 <filename>cpu:/foo/bar</filename>,
631 where "cpu" identifies the kernel
632 control group controller used, and
633 <filename>/foo/bar</filename> is the
634 control group path. The controller name
635 and ":" may be omitted in which case
636 the named systemd control group
637 hierarchy is implied. Alternatively,
638 the path and ":" may be omitted, in
639 which case the default control group
640 path for this unit is implied. This
641 option may be used to place executed
642 processes in arbitrary groups in
643 arbitrary hierachies -- which can be
644 configured externally with additional execution limits. By default
645 systemd will place all executed
646 processes in separate per-unit control
647 groups (named after the unit) in the
648 systemd named hierarchy. Since every
649 process can be in one group per
650 hierarchy only overriding the control group
651 path in the named systemd hierarchy
652 will disable automatic placement in
653 the default group. For details about control
655 url="http://www.kernel.org/doc/Documentation/cgroups/cgroups.txt">cgroups.txt</ulink>.</para></listitem>
659 <term><varname>ReadWriteDirectories=</varname></term>
660 <term><varname>ReadOnlyDirectories=</varname></term>
661 <term><varname>InaccessibleDirectories=</varname></term>
663 <listitem><para>Sets up a new
664 file-system name space for executed
665 processes. These options may be used
666 to limit access a process might have
667 to the main file-system
668 hierarchy. Each setting takes a
669 space-separated list of absolute
670 directory paths. Directories listed in
671 <varname>ReadWriteDirectories=</varname>
672 are accessible from within the
673 namespace with the same access rights
674 as from outside. Directories listed in
675 <varname>ReadOnlyDirectories=</varname>
676 are accessible for reading only,
677 writing will be refused even if the
678 usual file access controls would
679 permit this. Directories listed in
680 <varname>InaccessibleDirectories=</varname>
681 will be made inaccesible for processes
682 inside the namespace. Note that
683 restricting access with these options
684 does not extend to submounts of a
685 directory. You must list submounts
686 separately in these settings to
687 ensure the same limited access. These
688 options may be specified more than
689 once in which case all directories
690 listed will have limited access from
692 namespace.</para></listitem>
696 <term><varname>PrivateTmp=</varname></term>
698 <listitem><para>Takes a boolean
699 argument. If true sets up a new
700 namespace for the executed processes
702 <filename>/tmp</filename> directory
703 inside it, that is not shared by
704 processes outside of the
705 namespace. This is useful to secure
706 access to temporary files of the
707 process, but makes sharing between
709 <filename>/tmp</filename>
710 impossible. Defaults to false.</para></listitem>
714 <term><varname>MountFlags=</varname></term>
716 <listitem><para>Takes a mount
718 <option>shared</option>,
719 <option>slave</option> or
720 <option>private</option>, which
721 control whether namespaces set up with
722 <varname>ReadWriteDirectories=</varname>,
723 <varname>ReadOnlyDirectories=</varname>
725 <varname>InaccessibleDirectories=</varname>
726 receive or propagate new mounts
727 from/to the main namespace. See
728 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>1</manvolnum></citerefentry>
729 for details. Defaults to
730 <option>shared</option>, i.e. the new
731 namespace will both receive new mount
732 points from the main namespace as well
733 as propagate new mounts to
734 it.</para></listitem>
738 <term><varname>UtmpIdentifier=</varname></term>
740 <listitem><para>Takes a a four
741 character identifier string for an
742 utmp/wtmp entry for this service. This
743 should only be set for services such
744 as <command>getty</command>
745 implementations where utmp/wtmp
746 entries must be created and cleared
747 before and after execution. If the
748 configured string is longer than four
749 characters it is truncated and the
750 terminal four characters are
751 used. This setting interprets %I style
752 string replacements. This setting is
753 unset by default, i.e. no utmp/wtmp
754 entries are created or cleaned up for
755 this service.</para></listitem>
762 <title>See Also</title>
764 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
765 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
766 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
767 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
768 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
769 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>