man: remove advice to avoid setting the same var more than once

[elogind.git] / man / systemd.service.xml

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 8eda85f62db6546684545c5a2082b5cdccd5781d..f6b9fe2965af863774b8c22a8db3bd67a12f3099 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -76,8 +76,8 @@
                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the way the processes of the service are
                 terminated, and in
                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                 which define the way the processes of the service are
                 terminated, and in

-                <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
-                which configure control group settings for the
+                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                which configure resource control settings for the

                 processes of the service.</para>
 
                 <para>Unless <varname>DefaultDependencies=</varname>
                 processes of the service.</para>
 
                 <para>Unless <varname>DefaultDependencies=</varname>


@@ -305,9 +305,10 @@
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this
                                 <term><varname>ExecStart=</varname></term>
                                 <listitem><para>Commands with their
                                 arguments that are executed when this

-                                service is started. The first
-                                argument must be an absolute path
-                                name.</para>
+                                service is started. For each of the
+                                specified commands, the first argument
+                                must be an absolute and literal path
+                                to an executable.</para>

 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one
 
                                 <para>When <varname>Type</varname> is
                                 not <option>oneshot</option>, only one


@@ -320,11 +321,7 @@
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than
                                 (these semicolons must be passed as
                                 separate words). Alternatively, this
                                 directive may be specified more than

-                                once with the same effect. However,
-                                the latter syntax is not recommended
-                                for compatibility with parsers
-                                suitable for XDG
-                                <filename>.desktop</filename> files.
+                                once with the same effect.

                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the
                                 Lone semicolons may be escaped as
                                 <literal>\;</literal>. If the empty
                                 string is assigned to this option, the


@@ -332,6 +329,35 @@
                                 prior assignments of this option will
                                 have no effect.</para>
 
                                 prior assignments of this option will
                                 have no effect.</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>If more than one command is
                                 specified, the commands are invoked
                                 one by one sequentially in the order
                                 <para>If more than one command is
                                 specified, the commands are invoked
                                 one by one sequentially in the order


@@ -350,10 +376,11 @@
                                 <para>The command line accepts
                                 <literal>%</literal> specifiers as
                                 described in
                                 <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>
+                                <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
 
                                 <para>Basic environment variable
                                 substitution is supported. Use


@@ -369,11 +396,10 @@
                                 case it will be replaced by the value
                                 of the environment variable split up
                                 at whitespace, resulting in zero or
                                 case it will be replaced by the value
                                 of the environment variable split up
                                 at whitespace, resulting in zero or

-                                more arguments. Note that the first
+                                more arguments. To pass a literal dollar sign,
+                                use <literal>$$</literal>. Note that the first

                                 argument (i.e. the program to execute)
                                 argument (i.e. the program to execute)

-                                may not be a variable, since it must
-                                be a literal and absolute path
-                                name.</para>
+                                may not be a variable.</para>

 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with
 
                                 <para>Optionally, if the absolute file
                                 name is prefixed with


@@ -401,13 +427,47 @@
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 
                                 <programlisting>ExecStart=/bin/sh -c 'dmesg | tac'
                                 </programlisting>
 

-                                <para>For services run by a user
-                                instance of systemd the special
-                                environment variable
-                                <varname>$MANAGERPID</varname> is set
-                                to the PID of the systemd
-                                instance.</para>
-                                </listitem>
+                                <para>Only select environment variables
+                                are set for executed commands. See
+                                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                </para>
+
+                                <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. Since 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>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -523,9 +583,10 @@
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout

-                                logic. Defaults to 90s, except when
+                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
+                                manager configuration file, except when

                                 <varname>Type=oneshot</varname> is
                                 <varname>Type=oneshot</varname> is

-                                used in which case the timeout
+                                used, in which case the timeout

                                 is disabled by default.
                                 </para></listitem>
                         </varlistentry>
                                 is disabled by default.
                                 </para></listitem>
                         </varlistentry>


@@ -544,7 +605,8 @@
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout

-                                logic. Defaults to 90s.
+                                logic. Defaults to <varname>TimeoutStartSec=</varname> from the
+                                manager configuration file.

                                 </para></listitem>
                         </varlistentry>
 
                                 </para></listitem>
                         </varlistentry>
 


@@ -860,12 +922,15 @@
                                 these two options, this rate limiting
                                 may be modified. Use
                                 <varname>StartLimitInterval=</varname>
                                 these two options, this rate limiting
                                 may be modified. Use
                                 <varname>StartLimitInterval=</varname>

-                                to configure the checking interval
-                                (defaults to 10s, set to 0 to disable
+                                to configure the checking interval (defaults to
+                                <varname>DefaultStartLimitInterval=</varname> in
+                                manager configuration file, set to 0 to disable

                                 any kind of rate limiting). Use
                                 <varname>StartLimitBurst=</varname> to
                                 configure how many starts per interval
                                 any kind of rate limiting). Use
                                 <varname>StartLimitBurst=</varname> to
                                 configure how many starts per interval

-                                are allowed (defaults to 5). These
+                                are allowed (defaults to
+                                <varname>DefaultStartLimitBurst=</varname> in
+                                manager configuration file). These

                                 configuration options are particularly
                                 useful in conjunction with
                                 <varname>Restart=</varname>, however
                                 configuration options are particularly
                                 useful in conjunction with
                                 <varname>Restart=</varname>, however


@@ -969,33 +1034,6 @@
                                 range 0-99.</para></listitem>
                         </varlistentry>
 
                                 range 0-99.</para></listitem>
                         </varlistentry>
 

-                        <varlistentry>
-                                <term><varname>FsckPassNo=</varname></term>
-                                <listitem><para>Set the fsck passno
-                                priority to use to order this service
-                                in relation to other file system
-                                checking services. This option is only
-                                necessary to fix ordering in relation
-                                to fsck jobs automatically created for
-                                all <filename>/etc/fstab</filename>
-                                entries with a value in the fs_passno
-                                column > 0. As such it should only be
-                                used as option for fsck
-                                services. 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
-                                same range as
-                                <filename>/etc/fstab</filename>'s
-                                fs_passno column. See
-                                <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-                                for details.</para></listitem>
-                        </varlistentry>
-

                 </variablelist>
         </refsect1>
 
                 </variablelist>
         </refsect1>
 


@@ -1006,7 +1044,7 @@
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>
                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
                   </para>