chiark / gitweb /
networkd: support vxlan parameters
[elogind.git] / man / systemd.service.xml
index 8b17f85..da9079c 100644 (file)
                                 as. This option is mandatory for
                                 services where
                                 <varname>Type=</varname> is set to
-                                <option>dbus</option>, but its use
-                                is otherwise recommended if the process
-                                takes a name on the D-Bus bus.</para>
+                                <option>dbus</option>.</para>
+                                </listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>BusPolicy=</varname></term>
+
+                                <listitem><para>If specified, a custom
+                                <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>
+                                endpoint will be created and installed as the
+                                default bus node for the service. Such a custom
+                                endpoint can hold an own set of policy rules
+                                that are enforced on top of the bus-wide ones.
+                                The custom endpoint is named after the service
+                                it was created for, and its node will be
+                                bind-mounted over the default bus node
+                                location, so the service can only access the
+                                bus through its own endpoint. Note that custom
+                                bus endpoints default to a 'deny all' policy.
+                                Hence, if at least one
+                                <varname>BusPolicy=</varname> directive is
+                                given, you have to make sure to add explicit
+                                rules for everything the service should be able
+                                to do.</para>
+                                <para>The value of this directive is comprised
+                                of two parts; the bus name, and a verb to
+                                specify to granted access, which is one of
+                                <option>see</option>,
+                                <option>talk</option>, or
+                                <option>own</option>.
+                                <option>talk</option> implies
+                                <option>see</option>, and <option>own</option>
+                                implies both <option>talk</option> and
+                                <option>see</option>.
+                                If multiple access levels are specified for the
+                                same bus name, the most powerful one takes
+                                effect.
+                                </para>
+                                <para>Examples:</para>
+                                <programlisting>BusPolicy=org.freedesktop.systemd1 talk</programlisting>
+                                <programlisting>BusPolicy=org.foo.bar see</programlisting>
+                                <para>This option is only available on kdbus enabled systems.</para>
                                 </listitem>
                         </varlistentry>
 
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this
-                                service is started. For each of the
-                                specified commands, the first argument
-                                must be an absolute and literal path
-                                to an executable.</para>
+                                service is started. The value is split
+                                into zero or more command lines is
+                                according to the rules described below
+                                (see section "Command Lines" below).
+                                </para>
 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one
                                 command may and must be given. When
                                 <varname>Type=oneshot</varname> is
-                                used, none or more than one command
-                                may be specified. Multiple command
-                                lines may be concatenated in a single
-                                directive by separating them with
-                                semicolons (these semicolons must be
-                                passed as separate
-                                words). Alternatively, this directive
-                                may be specified more than once with
-                                the same effect.  Lone semicolons may
-                                be escaped as
-                                <literal>\;</literal>. If the empty
-                                string is assigned to this option, the
-                                list of commands to start is reset,
-                                prior assignments of this option will
-                                have no effect. If no
+                                used, zero or more commands may be
+                                specified. This can be specified by
+                                providing multiple command lines in
+                                the same directive, or alternatively,
+                                this directive may be specified more
+                                than once with the same effect. If the
+                                empty string is assigned to this
+                                option, the list of commands to start
+                                is reset, prior assignments of this
+                                option will have no effect. If no
                                 <varname>ExecStart=</varname> is
                                 specified, then the service must have
                                 <varname>RemainAfterExit=yes</varname>
                                 set.</para>
 
-                                <para>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 ("...") 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
-                                (<literal>\</literal>) may be used to
-                                merge lines. This syntax is intended
-                                to be very similar to shell syntax,
-                                but only the meta-characters and
-                                expansions described in the following
-                                paragraphs are understood.
-                                Specifically, redirection using
-                                <literal>&lt;</literal>,
-                                <literal>&lt;&lt;</literal>,
-                                <literal>&gt;</literal>, and
-                                <literal>&gt;&gt;</literal>, pipes
-                                using <literal>|</literal>, and
-                                running programs in the background
-                                using <literal>&amp;</literal>
-                                and <emphasis>other elements of shell
-                                syntax are not supported</emphasis>.
-                                </para>
+                                <para>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
+                                <literal>@</literal>, the second token
+                                will be passed as
+                                <literal>argv[0]</literal> to the
+                                executed process, followed by the
+                                further arguments specified. If the
+                                absolute filename is prefixed with
+                                <literal>-</literal>, an exit code of
+                                the command normally considered a
+                                failure (i.e. non-zero exit status or
+                                abnormal exit due to signal) is
+                                ignored and considered success. If
+                                both <literal>-</literal> and
+                                <literal>@</literal> are used, they
+                                can appear in either order.</para>
 
                                 <para>If more than one command is
                                 specified, the commands are invoked
                                 sequentially in the order they appear
                                 in the unit file. If one of the
                                 commands fails (and is not prefixed
-                                with <literal>-</literal>), other lines
-                                are not executed, and the unit is
-                                considered failed.</para>
+                                with <literal>-</literal>), other
+                                lines are not executed, and the unit
+                                is considered failed.</para>
 
                                 <para>Unless
                                 <varname>Type=forking</varname> is
                                 command line will be considered the
                                 main process of the daemon.</para>
 
-                                <para>The command line accepts
-                                <literal>%</literal> specifiers as
-                                described in
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                Note that the first argument of the
-                                command line (i.e. the program to
-                                execute) may not include
-                                specifiers.</para>
-
-                                <para>Basic environment variable
-                                substitution is supported. Use
-                                <literal>${FOO}</literal> as part of a
-                                word, or as a word of its own, on the
-                                command line, in which case it will be
-                                replaced by the value of the
-                                environment variable including all
-                                whitespace it contains, resulting in a
-                                single argument. Use
-                                <literal>$FOO</literal> as a separate
-                                word on the command line, in which
-                                case it will be replaced by the value
-                                of the environment variable split at
-                                whitespace, resulting in zero or more
-                                arguments. To pass a literal dollar
-                                sign, use <literal>$$</literal>.
-                                Variables whose value is not known at
-                                expansion time are treated as empty
-                                strings. Note that the first argument
-                                (i.e. the program to execute) may not
-                                be a variable.</para>
-
-                                <para>Variables to be used in this
-                                fashion may be defined through
-                                <varname>Environment=</varname> and
-                                <varname>EnvironmentFile=</varname>.
-                                In addition, variables listed in the
-                                section "Environment variables in
-                                spawned processes" in
-                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                                which are considered "static
-                                configuration", may be used (this includes
-                                e.g. <varname>$USER</varname>, but not
-                                <varname>$TERM</varname>).</para>
-
-                                <para>Optionally, if the absolute file
-                                name is prefixed with
-                                <literal>@</literal>, the second token
-                                will be passed as
-                                <literal>argv[0]</literal> to the
-                                executed process, followed by the
-                                further arguments specified. If the
-                                absolute filename is prefixed with
-                                <literal>-</literal>, an exit code of
-                                the command normally considered a
-                                failure (i.e. non-zero exit status or
-                                abnormal exit due to signal) is ignored
-                                and considered success. If both
-                                <literal>-</literal> and
-                                <literal>@</literal> are used, they
-                                can appear in either order.</para>
-
-                                <para>Note that this setting does not
-                                directly support shell command
-                                lines. If shell command lines are to
-                                be used, they need to be passed
-                                explicitly to a shell implementation
-                                of some kind. Example:</para>
-                                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
-                                <para>Example:</para>
-                                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> two
-                                times, each time with one argument:
-                                <literal>one</literal> and
-                                <literal>two two</literal>,
-                                respectively. Because two commands are
-                                specified,
-                                <varname>Type=oneshot</varname> must
-                                be used.</para>
-
-                                <para>Example:</para>
-                                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
-/bin/ls</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> with five
-                                arguments: <literal>/</literal>,
-                                <literal>&gt;/dev/null</literal>,
-                                <literal>&amp;</literal>,
-                                <literal>;</literal>, and
-                                <literal>/bin/ls</literal>.</para>
-
-                                <para>Example:</para>
-                                <programlisting>Environment="ONE=one" 'TWO=two two'
-ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
-                                <para>This will execute
-                                <command>/bin/echo</command> with four
-                                arguments: <literal>one</literal>,
-                                <literal>two</literal>,
-                                <literal>two</literal>, and
-                                <literal>two two</literal>.</para>
                               </listitem>
                         </varlistentry>
 
@@ -620,7 +546,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 when <varname>Type=oneshot</varname> is
                                 used, in which case the timeout
                                 is disabled by default
-                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                 </para></listitem>
                         </varlistentry>
 
@@ -641,7 +567,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 the timeout logic. Defaults to
                                 <varname>DefaultTimeoutStopSec=</varname> from the
                                 manager configuration file
-                                (see <citerefentry><refentrytitle>systemd-systemd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+                                (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
                                 </para></listitem>
                         </varlistentry>
 
@@ -665,8 +591,9 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 (i.e. the "keep-alive ping"). If the time
                                 between two such calls is larger than
                                 the configured time, then the service
-                                is placed in a failed state. By
-                                setting <varname>Restart=</varname> to
+                                is placed in a failed state and it will
+                                be terminated with <varname>SIGABRT</varname>.
+                                By setting <varname>Restart=</varname> to
                                 <option>on-failure</option> or
                                 <option>always</option>, the service
                                 will be automatically restarted. The
@@ -1040,21 +967,24 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
                                 <term><varname>Sockets=</varname></term>
                                 <listitem><para>Specifies the name of
                                 the socket units this service shall
-                                inherit the sockets from when the
-                                service is started. Normally it
-                                should not be necessary to use this
-                                setting as all sockets whose unit
+                                inherit socket file descriptors
+                                from when the service is
+                                started. Normally it should not be
+                                necessary to use this setting as all
+                                socket file descriptors whose unit
                                 shares the same name as the service
-                                (ignoring the different suffix of course)
-                                are passed to the spawned
-                                process.</para>
-
-                                <para>Note that the same socket may be
-                                passed to multiple processes at the
-                                same time. Also note that a different
-                                service may be activated on incoming
-                                traffic than that which inherits the
-                                sockets. Or in other words: the
+                                (subject to the different unit name
+                                suffix of course) are passed to the
+                                spawned process.</para>
+
+                                <para>Note that the same socket file
+                                descriptors may be passed to multiple
+                                processes simultaneously. Also note
+                                that a different service may be
+                                activated on incoming socket traffic
+                                than the one which is ultimately
+                                configured to inherit the socket file
+                                descriptors. Or in other words: the
                                 <varname>Service=</varname> setting of
                                 <filename>.socket</filename> units
                                 does not have to match the inverse of
@@ -1199,44 +1129,137 @@ ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
         </refsect1>
 
         <refsect1>
-                <title>Compatibility Options</title>
+                <title>Command lines</title>
+
+                <para>This section describes command line parsing and
+                variable and specifier substitions for
+                <varname>ExecStart=</varname>,
+                <varname>ExecStartPre=</varname>,
+                <varname>ExecStartPost=</varname>,
+                <varname>ExecReload=</varname>,
+                <varname>ExecStop=</varname>, and
+                <varname>ExecStopPost=</varname> options.</para>
+
+                <para>Multiple command lines may be concatenated in a
+                single directive by separating them with semicolons
+                (these semicolons must be passed as separate words).
+                Lone semicolons may be escaped as
+                <literal>\;</literal>.</para>
+
+                <para>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
+                ("...") 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 (<literal>\</literal>) may be used to merge
+                lines. </para>
+
+                <para>This syntax is intended to be very similar to
+                shell syntax, but only the meta-characters and
+                expansions described in the following paragraphs are
+                understood.  Specifically, redirection using
+                <literal>&lt;</literal>, <literal>&lt;&lt;</literal>,
+                <literal>&gt;</literal>, and
+                <literal>&gt;&gt;</literal>, pipes using
+                <literal>|</literal>, running programs in the
+                background using <literal>&amp;</literal>, and
+                <emphasis>other elements of shell syntax are not
+                supported</emphasis>.</para>
+
+                <para>The command line accepts <literal>%</literal>
+                specifiers as described in
+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                Note that the first argument of the command line
+                (i.e. the program to execute) may not include
+                specifiers.</para>
+
+                <para>Basic environment variable substitution is
+                supported. Use <literal>${FOO}</literal> as part of a
+                word, or as a word of its own, on the command line, in
+                which case it will be replaced by the value of the
+                environment variable including all whitespace it
+                contains, resulting in a single argument. Use
+                <literal>$FOO</literal> as a separate word on the
+                command line, in which case it will be replaced by the
+                value of the environment variable split at whitespace
+                resulting in zero or more arguments. For this type of
+                expansion, quotes and respected when splitting into
+                words, and afterwards removed.</para>
+
+                <para>Example:</para>
+
+                <programlisting>Environment="ONE=one" 'TWO=two two'
+ExecStart=/bin/echo $ONE $TWO ${TWO}</programlisting>
 
-                <para>The following options are also available in the
-                <literal>[Service]</literal> section, but exist purely
-                for compatibility reasons and should not be used in
-                newly written service files.</para>
+                <para>This will execute <command>/bin/echo</command>
+                with four arguments: <literal>one</literal>,
+                <literal>two</literal>, <literal>two</literal>, and
+                <literal>two two</literal>.</para>
+
+                <para>Example:</para>
+                <programlisting>Environment=ONE='one' "TWO='two two' too" THREE=
+ExecStart=/bin/echo ${ONE} ${TWO} ${THREE}
+ExecStart=/bin/echo $ONE $TWO $THREE</programlisting>
+                <para>This results in <filename>echo</filename> being
+                called twice, the first time with arguments
+                <literal>'one'</literal>,
+                <literal>'two two' too</literal>, <literal></literal>,
+                and the second time with arguments
+                <literal>one</literal>, <literal>two two</literal>,
+                <literal>too</literal>.
+                </para>
 
-                <variablelist class='unit-directives'>
-                        <varlistentry>
-                                <term><varname>SysVStartPriority=</varname></term>
-                                <listitem><para>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 a temporary compatibility
-                                option and should not be used in new unit
-                                files. Almost always, it is a better
-                                choice to add explicit ordering
-                                directives via
-                                <varname>After=</varname> or
-                                <varname>Before=</varname>,
-                                instead. For more details, see
-                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-                                If used, pass an integer value in the
-                                range 0-99.</para></listitem>
-                        </varlistentry>
-                </variablelist>
+                <para>To pass a literal dollar sign, use
+                <literal>$$</literal>. Variables whose value is not
+                known at expansion time are treated as empty
+                strings. Note that the first argument (i.e. the
+                program to execute) may not be a variable.</para>
+
+                <para>Variables to be used in this fashion may be
+                defined through <varname>Environment=</varname> and
+                <varname>EnvironmentFile=</varname>.  In addition,
+                variables listed in the section "Environment variables
+                in spawned processes" in
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                which are considered "static configuration", may be
+                used (this includes e.g. <varname>$USER</varname>, but
+                not <varname>$TERM</varname>).</para>
+
+                <para>Note that shell command lines are not directly
+                supported. If shell command lines are to be used, they
+                need to be passed explicitly to a shell implementation
+                of some kind. Example:</para>
+                <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'</programlisting>
+
+                <para>Example:</para>
+
+                <programlisting>ExecStart=/bin/echo one ; /bin/echo "two two"</programlisting>
+
+                <para>This will execute <command>/bin/echo</command>
+                two times, each time with one argument:
+                <literal>one</literal> and <literal>two two</literal>,
+                respectively. Because two commands are specified,
+                <varname>Type=oneshot</varname> must be used.</para>
+
+                <para>Example:</para>
+
+                <programlisting>ExecStart=/bin/echo / &gt;/dev/null &amp; \; \
+/bin/ls</programlisting>
+
+                <para>This will execute <command>/bin/echo</command>
+                with five arguments: <literal>/</literal>,
+                <literal>&gt;/dev/null</literal>,
+                <literal>&amp;</literal>, <literal>;</literal>, and
+                <literal>/bin/ls</literal>.</para>
         </refsect1>
 
         <refsect1>
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,