unit: don't show ENOENT configuration file warnings for units that are not essential

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

diff --git a/man/systemd.service.xml b/man/systemd.service.xml
index 8005a51a472150f8a9fce31f50c21ad7148237f2..94a21d3fe3d99c2160611e590c15d70de69a2344 100644 (file)
--- a/man/systemd.service.xml
+++ b/man/systemd.service.xml
@@ -64,24 +64,52 @@
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 for the common options of all unit configuration
                 files. The common configuration items are configured
                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 for the common options of all unit configuration
                 files. The common configuration items are configured

-                in the generic [Unit] and [Install] sections. The
-                service specific configuration options are configured
-                in the [Service] section.</para>
-
-                <para>Additional options are listed in <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+                in the generic <literal>[Unit]</literal> and
+                <literal>[Install]</literal> sections. The service
+                specific configuration options are configured in the
+                <literal>[Service]</literal> section.</para>
+
+                <para>Additional options are listed in
+                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                which define the execution environment the commands
+                are executed in.</para>
+
+                <para>Unless <varname>DefaultDependencies=</varname>
+                is set to <option>false</option>, service units will
+                implicitly have dependencies of type
+                <varname>Requires=</varname> and
+                <varname>After=</varname> on
+                <filename>basic.target</filename> as well as
+                dependencies of type <varname>Conflicts=</varname> and
+                <varname>Before=</varname> on
+                <filename>shutdown.target</filename>. These ensure
+                that normal service units pull in basic system
+                initialization, and are terminated cleanly prior to
+                system shutdown. Only services involved with early
+                boot or late system shutdown should disable this
+                option.</para>
+
+                <para>If a service is requested under a certain name
+                but no unit configuration file is found, systemd looks
+                for a SysV init script by the same name (with the
+                <filename>.service</filename> suffix removed) and
+                dynamically creates a service unit from that
+                script. This is useful for compatibility with
+                SysV.</para>

         </refsect1>
 
         <refsect1>
                 <title>Options</title>
 
         </refsect1>
 
         <refsect1>
                 <title>Options</title>
 

-                <para>Service files must include a [Service] section,
-                which carries information about the service and the
-                process it supervises. A number of options that may be
-                used in this section are shared with other unit
-                types. These options are documented in
+                <para>Service files must include a
+                <literal>[Service]</literal> section, which carries
+                information about the service and the process it
+                supervises. A number of options that may be used in
+                this section are shared with other unit types. These
+                options are documented in

                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The

-                options specific to the [Service] section of service
-                units are the following:</para>
+                options specific to the <literal>[Service]</literal>
+                section of service units are the following:</para>

 
                 <variablelist>
                         <varlistentry>
 
                 <variablelist>
                         <varlistentry>


@@ -140,14 +168,18 @@
 
                                 <para>Behaviour of
                                 <option>dbus</option> is similar to
 
                                 <para>Behaviour of
                                 <option>dbus</option> is similar to

-                                <option>simple</option>, however it
-                                is expected that the daemon acquires a
+                                <option>simple</option>, however it is
+                                expected that the daemon acquires a

                                 name on the D-Bus bus, as configured
                                 by
                                 <varname>BusName=</varname>. systemd
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been
                                 name on the D-Bus bus, as configured
                                 by
                                 <varname>BusName=</varname>. systemd
                                 will proceed starting follow-up units
                                 after the D-Bus bus name has been

-                                acquired.</para>
+                                acquired. Service units with this
+                                option configured implicitly have
+                                dependencies on the
+                                <filename>dbus.target</filename>
+                                unit.</para>

 
                                 <para>Behaviour of
                                 <option>notify</option> is similar to
 
                                 <para>Behaviour of
                                 <option>notify</option> is similar to


@@ -160,10 +192,13 @@
                                 starting follow-up units after this
                                 notification message has been sent. If
                                 this option is used
                                 starting follow-up units after this
                                 notification message has been sent. If
                                 this option is used

-                                <option>NotifyAccess=</option> (see
+                                <varname>NotifyAccess=</varname> (see

                                 below) must be set to open access to
                                 the notification socket provided by
                                 below) must be set to open access to
                                 the notification socket provided by

-                                systemd.</para>
+                                systemd. If
+                                <varname>NotifyAccess=</varname> is not
+                                set, it will be implicitly set to
+                                <option>main</option>.</para>

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


@@ -217,15 +252,36 @@
                                 services. This option may not be
                                 specified more than once. Optionally,
                                 if the absolute file name is prefixed
                                 services. This option may not be
                                 specified more than once. Optionally,
                                 if the absolute file name is prefixed

-                                with @, the second token will be
-                                passed as argv[0] to the executed
-                                process, followed by the further
-                                arguments specified. Unless
-                                <option>Type=forking</option> is set,
-                                the process started via this command
-                                line will be considered the main
-                                process of the
-                                daemon.</para></listitem>
+                                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
+                                first token is prefixed with
+                                <literal>-</literal> an error code of
+                                the command normally considered a
+                                failure is ignored and considered
+                                success. If both <literal>-</literal>
+                                and <literal>@</literal> are used for
+                                the same command the latter must
+                                preceed the latter. Unless
+                                <varname>Type=forking</varname> is
+                                set, the process started via this
+                                command line will be considered the
+                                main process of the daemon. The
+                                command line accepts % specifiers as
+                                described in
+                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. On
+                                top of that basic environment variable
+                                substitution is supported, where
+                                <literal>${FOO}</literal> is replaced
+                                by the string value of the environment
+                                variable of the same name. Also
+                                <literal>$FOO</literal> may appear as
+                                seperate word on the command line in
+                                which case the variable is replaced by
+                                its value split at
+                                whitespaces.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -234,31 +290,58 @@
                                 <listitem><para>Additional commands
                                 that are executed before (resp. after)
                                 the command in
                                 <listitem><para>Additional commands
                                 that are executed before (resp. after)
                                 the command in

-                                <varname>ExecStart=</varname>. If
-                                specified more than once, all commands
-                                are executed one after the other,
-                                serially. Use of these settings is
-                                optional.</para></listitem>
+                                <varname>ExecStart=</varname>. Multiple
+                                command lines may be concatenated in a
+                                single directive, by seperating them
+                                by semicolons (these semicolons must
+                                be passed as seperate words). In that
+                                case, the commands are executed one
+                                after the other,
+                                serially. Alternatively, these
+                                directives may be specified more than
+                                once whith the same effect. However,
+                                the latter syntax is not recommended
+                                for compatibility with parsers
+                                suitable for XDG
+                                <filename>.desktop</filename> files.
+                                Use of these settings is
+                                optional. Specifier and environment
+                                variable substitution is
+                                supported.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>ExecReload=</varname></term>
                                 <listitem><para>Commands to execute to
                                 trigger a configuration reload in the
                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>ExecReload=</varname></term>
                                 <listitem><para>Commands to execute to
                                 trigger a configuration reload in the

-                                service. If used more than once, all
-                                commands are executed one after the
-                                other, serially. Use of this setting is optional.
-                                </para></listitem>
+                                service. This argument takes multiple
+                                command lines, following the same
+                                scheme as pointed out for
+                                <varname>ExecStartPre=</varname>
+                                above. Use of this setting is
+                                optional. Specifier and environment
+                                variable substitution is supported
+                                here following the same scheme as for
+                                <varname>ExecStart=</varname>. One
+                                special environment variable is set:
+                                if known <literal>$MAINPID</literal> is
+                                set to the main process of the
+                                daemon, and may be used for command
+                                lines like the following:
+                                <command>/bin/kill -HUP
+                                $(MAINPID)</command>.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>ExecStop=</varname></term>
                                 <listitem><para>Commands to execute to
                                 stop the service started via
                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>ExecStop=</varname></term>
                                 <listitem><para>Commands to execute to
                                 stop the service started via

-                                <varname>ExecStart=</varname>. If used
-                                more than once, all commands are
-                                executed one after the other,
-                                serially. Use of this setting is
+                                <varname>ExecStart=</varname>. This
+                                argument takes multiple command lines,
+                                following the same scheme as pointed
+                                out for
+                                <varname>ExecStartPre=</varname>
+                                above. Use of this setting is

                                 optional. All processes remaining for
                                 a service after the commands
                                 configured in this option are run are
                                 optional. All processes remaining for
                                 a service after the commands
                                 configured in this option are run are


@@ -267,7 +350,11 @@
                                 (see below). If this option is not
                                 specified the process is terminated
                                 right-away when service stop is
                                 (see below). If this option is not
                                 specified the process is terminated
                                 right-away when service stop is

-                                requested.</para></listitem>
+                                requested. Specifier and environment
+                                variable substitution is supported
+                                (including
+                                <literal>$(MAINPID)</literal>, see
+                                above).</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -276,11 +363,15 @@
                                 that are executed after the service
                                 was stopped using the commands
                                 configured in
                                 that are executed after the service
                                 was stopped using the commands
                                 configured in

-                                <varname>ExecStop=</varname>. If
-                                specified more than once, all commands
-                                are executed one after the other,
-                                serially. Use of these settings is
-                                optional.</para></listitem>
+                                <varname>ExecStop=</varname>. This
+                                argument takes multiple command lines,
+                                following the same scheme as pointed
+                                out for
+                                <varname>ExecStartPre</varname>. Use
+                                of these settings is
+                                optional. Specifier and environment
+                                variable substitution is
+                                supported.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>


@@ -309,7 +400,7 @@
                                 forcibly via SIGTERM, and after
                                 another delay of this time with
                                 SIGKILL. (See
                                 forcibly via SIGTERM, and after
                                 another delay of this time with
                                 SIGKILL. (See

-                                <option>KillMode=</option>
+                                <varname>KillMode=</varname>

                                 below.) Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout
                                 below.) Takes a unit-less value in seconds, or a
                                 time span value such as "5min
                                 20s". Pass 0 to disable the timeout


@@ -447,7 +538,7 @@
                                 <para>Processes will first be
                                 terminated via SIGTERM. If then after
                                 a delay (configured via the
                                 <para>Processes will first be
                                 terminated via SIGTERM. If then after
                                 a delay (configured via the

-                                <option>TimeoutSec=</option> option)
+                                <varname>TimeoutSec=</varname> option)

                                 processes still remain, the
                                 termination request is repeated with
                                 the SIGKILL signal. See
                                 processes still remain, the
                                 termination request is repeated with
                                 the SIGKILL signal. See


@@ -502,7 +593,7 @@
         <refsect1>
                   <title>See Also</title>
                   <para>
         <refsect1>
                   <title>See Also</title>
                   <para>

-                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</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>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>