unit: introduce %s specifier for the user shell

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index d38a00136651b552ba94b4c513e643a5654f3a2f..4a2e9c3bf93dc07103eb0e1cb55d0732b4b1284f 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -8,16 +8,16 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  under the terms of the GNU Lesser General Public License as published by
+  the Free Software Foundation; either version 2.1 of the License, or

   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   (at your option) any later version.
 
   systemd is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  You should have received a copy of the GNU Lesser General Public License

   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 


@@ -121,8 +121,9 @@
 
                 <para>If a line starts with <option>.include</option>
                 followed by a file name, the specified file will be
 
                 <para>If a line starts with <option>.include</option>
                 followed by a file name, the specified file will be

-                read as if its contents were listed in place of the
-                <option>.include</option> directive.</para>
+                parsed at this point. Make sure that the file that is
+                included has the appropriate section headers before
+                any directives.</para>

 
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory
 
                 <para>Along with a unit file
                 <filename>foo.service</filename> a directory


@@ -180,30 +181,101 @@
                 and no file by that name is found, systemd will look
                 for <filename>getty@.service</filename> and
                 instantiate a service from that configuration file if
                 and no file by that name is found, systemd will look
                 for <filename>getty@.service</filename> and
                 instantiate a service from that configuration file if

-                it is found. To refer to the instance string from
+                it is found.</para>
+
+                <para>To refer to the instance string from

                 within the configuration file you may use the special
                 <literal>%i</literal> specifier in many of the
                 within the configuration file you may use the special
                 <literal>%i</literal> specifier in many of the

-                configuration options. Other specifiers that may be
-                used are <literal>%n</literal>, <literal>%N</literal>,
-                <literal>%p</literal>, <literal>%P</literal>,
-                <literal>%I</literal>, <literal>%f</literal>,
-                <literal>%c</literal>, <literal>%r</literal>,
-                <literal>%R</literal> and <literal>%t</literal> for
-                the full unit name, the unescaped unit name, the
-                prefix name, the unescaped prefix name, the unescaped
-                instance name, the unescaped filename, the control
-                group path of the unit, the root control group path of
-                systemd, and the parent directory of the root control
-                cgroup path of systemd and the runtime socket dir,
-                respectively. The unescaped filename is either the
-                unescaped instance name (if set) with / prepended (if
-                necessary), or the prefix name similarly prepended
-                with /. The prefix name here refers to the string
-                before the @, i.e. "getty" in the example above, where
-                "tty3" is the instance name. The runtime socket
-                directory is either <filename>/run</filename> (for the
-                system manager) or <literal>$XDG_RUNTIME_DIR</literal>
-                (for user managers).</para>
+                configuration options. Other specifiers exist, the
+                full list is:</para>
+
+                <table>
+                  <title>Specifiers available in unit files</title>
+                  <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+                    <colspec colname="spec" />
+                    <colspec colname="mean" />
+                    <colspec colname="detail" />
+                    <thead>
+                      <row>
+                        <entry>Specifier</entry>
+                        <entry>Meaning</entry>
+                        <entry>Details</entry>
+                      </row>
+                    </thead>
+                    <tbody>
+                      <row>
+                        <entry><literal>%n</literal></entry>
+                        <entry>Full unit name</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%N</literal></entry>
+                        <entry>Unescaped full unit name</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%p</literal></entry>
+                        <entry>Prefix name</entry>
+                        <entry>This refers to the string before the @, i.e. "getty" in the example above, where "tty3" is the instance name.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%P</literal></entry>
+                        <entry>Unescaped prefix name</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%i</literal></entry>
+                        <entry>Instance name</entry>
+                        <entry>This is the string between the @ character and the suffix.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%I</literal></entry>
+                        <entry>Unescaped instance name</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%f</literal></entry>
+                        <entry>Unescaped file name</entry>
+                        <entry>This is either the unescaped instance name (if set) with / prepended (if necessary), or the prefix name similarly prepended with /.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%c</literal></entry>
+                        <entry>Control group path of the unit</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%r</literal></entry>
+                        <entry>Root control group path of systemd</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%R</literal></entry>
+                        <entry>Parent directory of the root control group path of systemd</entry>
+                        <entry></entry>
+                      </row>
+                      <row>
+                        <entry><literal>%t</literal></entry>
+                        <entry>Runtime socket dir</entry>
+                        <entry>This is either /run (for the system manager) or $XDG_RUNTIME_DIR (for user managers).</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%u</literal></entry>
+                        <entry>User name</entry>
+                        <entry>This is the name of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%h</literal></entry>
+                        <entry>User home directory</entry>
+                        <entry>This is the home directory of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+                      </row>
+                      <row>
+                        <entry><literal>%s</literal></entry>
+                        <entry>User shell</entry>
+                        <entry>This is the shell of the configured user of the unit, or (if none is set) the user running the systemd instance.</entry>
+                      </row>
+                    </tbody>
+                  </tgroup>
+                </table>

 
                 <para>If a unit file is empty (i.e. has the file size
                 0) or is symlinked to <filename>/dev/null</filename>
 
                 <para>If a unit file is empty (i.e. has the file size
                 0) or is symlinked to <filename>/dev/null</filename>


@@ -237,6 +309,23 @@
                                 name.</para></listitem>
                         </varlistentry>
 
                                 name.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>Documentation=</varname></term>
+                                <listitem><para>A space separated list
+                                of URIs referencing documentation for
+                                this unit or its
+                                configuration. Accepted are only URIs
+                                of the types
+                                <literal>http://</literal>,
+                                <literal>https://</literal>,
+                                <literal>file:</literal>,
+                                <literal>info:</literal>,
+                                <literal>man:</literal>. For more
+                                information about the syntax of these
+                                URIs see
+                                <citerefentry><refentrytitle>uri</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>Requires=</varname></term>
 
                         <varlistentry>
                                 <term><varname>Requires=</varname></term>
 


@@ -336,7 +425,7 @@
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>

-                                <term><varname>BindTo=</varname></term>
+                                <term><varname>BindsTo=</varname></term>

 
                                 <listitem><para>Configures requirement
                                 dependencies, very similar in style to
 
                                 <listitem><para>Configures requirement
                                 dependencies, very similar in style to


@@ -452,6 +541,34 @@
                                 state.</para></listitem>
                         </varlistentry>
 
                                 state.</para></listitem>
                         </varlistentry>
 

+                        <varlistentry>
+                                <term><varname>PropagatesReloadTo=</varname></term>
+                                <term><varname>ReloadPropagatedFrom=</varname></term>
+
+                                <listitem><para>Lists one or more
+                                units where reload requests on the
+                                unit will be propagated to/on the
+                                other unit will be propagated
+                                from. Issuing a reload request on a
+                                unit will automatically also enqueue a
+                                reload request on all units that the
+                                reload request shall be propagated to
+                                via these two
+                                settings.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>RequiresMountsFor=</varname></term>
+
+                                <listitem><para>Takes a space
+                                separated list of paths. Automatically
+                                adds dependencies of type
+                                <varname>Requires=</varname> and
+                                <varname>After=</varname> for all
+                                mount units required to access the
+                                specified path.</para></listitem>
+                        </varlistentry>
+

                         <varlistentry>
                                 <term><varname>OnFailureIsolate=</varname></term>
 
                         <varlistentry>
                                 <term><varname>OnFailureIsolate=</varname></term>
 


@@ -609,11 +726,15 @@
                                 <term><varname>ConditionPathExists=</varname></term>
                                 <term><varname>ConditionPathExistsGlob=</varname></term>
                                 <term><varname>ConditionPathIsDirectory=</varname></term>
                                 <term><varname>ConditionPathExists=</varname></term>
                                 <term><varname>ConditionPathExistsGlob=</varname></term>
                                 <term><varname>ConditionPathIsDirectory=</varname></term>

+                                <term><varname>ConditionPathIsSymbolicLink=</varname></term>
+                                <term><varname>ConditionPathIsMountPoint=</varname></term>
+                                <term><varname>ConditionPathIsReadWrite=</varname></term>

                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>
                                 <term><varname>ConditionSecurity=</varname></term>
                                 <term><varname>ConditionDirectoryNotEmpty=</varname></term>
                                 <term><varname>ConditionFileIsExecutable=</varname></term>
                                 <term><varname>ConditionKernelCommandLine=</varname></term>
                                 <term><varname>ConditionVirtualization=</varname></term>
                                 <term><varname>ConditionSecurity=</varname></term>

+                                <term><varname>ConditionCapability=</varname></term>

                                 <term><varname>ConditionNull=</varname></term>
 
                                 <listitem><para>Before starting a unit
                                 <term><varname>ConditionNull=</varname></term>
 
                                 <listitem><para>Before starting a unit


@@ -623,7 +744,7 @@
                                 a file existence condition can be
                                 checked before a unit is started. If
                                 the specified absolute path name does
                                 a file existence condition can be
                                 checked before a unit is started. If
                                 the specified absolute path name does

-                                not exist startup of a unit will not
+                                not exist, startup of a unit will not

                                 actually happen, however the unit is
                                 still useful for ordering purposes in
                                 this case. The condition is checked at
                                 actually happen, however the unit is
                                 still useful for ordering purposes in
                                 this case. The condition is checked at


@@ -633,10 +754,11 @@
                                 <varname>ConditionPathExists=</varname>
                                 is prefixed with an exclamation mark
                                 (!), the test is negated, and the unit
                                 <varname>ConditionPathExists=</varname>
                                 is prefixed with an exclamation mark
                                 (!), the test is negated, and the unit

-                                only started if the path does not
-                                exist. <varname>ConditionPathExistsGlob=</varname>
-                                work in a similar way, but checks for
-                                the existance of at least one file or
+                                is only started if the path does not
+                                exist.
+                                <varname>ConditionPathExistsGlob=</varname>
+                                works in a similar way, but checks for
+                                the existence of at least one file or

                                 directory matching the specified
                                 globbing
                                 pattern. <varname>ConditionPathIsDirectory=</varname>
                                 directory matching the specified
                                 globbing
                                 pattern. <varname>ConditionPathIsDirectory=</varname>


@@ -644,7 +766,23 @@
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path
                                 exists and is a
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path
                                 exists and is a

-                                directory. <varname>ConditionFileIsExecutable=</varname>
+                                directory. <varname>ConditionPathIsSymbolicLink=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a symbolic
+                                link. <varname>ConditionPathIsMountPoint=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a mount
+                                point. <varname>ConditionPathIsReadWrite=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether the underlying
+                                file system is read and writable
+                                (i.e. not mounted
+                                read-only). <varname>ConditionFileIsExecutable=</varname>

                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path
                                 is similar to
                                 <varname>ConditionPathExists=</varname>
                                 but verifies whether a certain path


@@ -677,16 +815,27 @@
                                 whether it is a specific
                                 implementation. Takes either boolean
                                 value to check if being executed in
                                 whether it is a specific
                                 implementation. Takes either boolean
                                 value to check if being executed in

-                                any virtual environment or one of the
+                                any virtualized environment, or one of
+                                <varname>vm</varname> and
+                                <varname>container</varname> to test
+                                against a specific type of
+                                virtualization solution, or one of

                                 <varname>qemu</varname>,
                                 <varname>kvm</varname>,
                                 <varname>vmware</varname>,
                                 <varname>microsoft</varname>,
                                 <varname>oracle</varname>,
                                 <varname>xen</varname>,
                                 <varname>qemu</varname>,
                                 <varname>kvm</varname>,
                                 <varname>vmware</varname>,
                                 <varname>microsoft</varname>,
                                 <varname>oracle</varname>,
                                 <varname>xen</varname>,

-                                <varname>pidns</varname>,
-                                <varname>openvz</varname> to test
-                                against a specific implementation. The
+                                <varname>bochs</varname>,
+                                <varname>chroot</varname>,
+                                <varname>openvz</varname>,
+                                <varname>lxc</varname>,
+                                <varname>lxc-libvirt</varname>,
+                                <varname>systemd-nspawn</varname> to
+                                test against a specific
+                                implementation. If multiple
+                                virtualization technologies are nested
+                                only the innermost is considered. The

                                 test may be negated by prepending an
                                 exclamation mark.
                                 <varname>ConditionSecurity=</varname>
                                 test may be negated by prepending an
                                 exclamation mark.
                                 <varname>ConditionSecurity=</varname>


@@ -695,7 +844,19 @@
                                 system.  Currently the only recognized
                                 value is <varname>selinux</varname>.
                                 The test may be negated by prepending
                                 system.  Currently the only recognized
                                 value is <varname>selinux</varname>.
                                 The test may be negated by prepending

-                                an exclamation mark. Finally,
+                                an exclamation
+                                mark. <varname>ConditionCapability=</varname>
+                                may be used to check whether the given
+                                capability exists in the capability
+                                bounding set of the service manager
+                                (i.e. this does not check whether
+                                capability is actually available in
+                                the permitted or effective sets, see
+                                <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+                                for details). Pass a capability name
+                                such as <literal>CAP_MKNOD</literal>,
+                                possibly prefixed with an exclamation
+                                mark to negate the check. Finally,

                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition
                                 check value to the unit. It takes a
                                 <varname>ConditionNull=</varname> may
                                 be used to add a constant condition
                                 check value to the unit. It takes a


@@ -717,36 +878,23 @@
                                 prefix an argument with the pipe
                                 symbol and an exclamation mark the
                                 pipe symbol must be passed first, the
                                 prefix an argument with the pipe
                                 symbol and an exclamation mark the
                                 pipe symbol must be passed first, the

-                                exclamation second.</para></listitem>
+                                exclamation second. Except for
+                                <varname>ConditionPathIsSymbolicLink=</varname>,
+                                all path checks follow
+                                symlinks.</para></listitem>

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

-                                <term><varname>Names=</varname></term>
-
-                                <listitem><para>Additional names for
-                                this unit. The names listed here must
-                                have the same suffix (i.e. type) as
-                                the unit file name. This option may be
-                                specified more than once, in which
-                                case all listed names are used. Note
-                                that this option is different from the
-                                <varname>Alias=</varname> option from
-                                the [Install] section mentioned
-                                below. See below for details. Note
-                                that in almost all cases this option
-                                is not what you want. A symlink alias
-                                in the file system is generally
-                                preferable since it can be used as
-                                lookup key. If a unit with a symlinked
-                                alias name is not loaded and needs to
-                                be it is easily found via the
-                                symlink. However, if a unit with an
-                                alias name configured with this
-                                setting is not loaded it will not be
-                                discovered. This settings' only use is
-                                in conjunction with service
-                                instances.</para>
-                                </listitem>
+                                <term><varname>SourcePath=</varname></term>
+                                <listitem><para>A path to a
+                                configuration file this unit has been
+                                generated from. This is primarily
+                                useful for implementation of generator
+                                tools that convert configuration from
+                                an external configuration file format
+                                into native unit files. Thus
+                                functionality should not be used in
+                                normal units.</para></listitem>

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


@@ -774,37 +922,16 @@
                                 time,
                                 <command>systemctl enable</command>
                                 will create symlinks from these names
                                 time,
                                 <command>systemctl enable</command>
                                 will create symlinks from these names

-                                to the unit file name. Note that this
-                                is different from the
-                                <varname>Names=</varname> option from
-                                the [Unit] section mentioned above:
-                                The names from
-                                <varname>Names=</varname> apply
-                                unconditionally if the unit is
-                                loaded. The names from
-                                <varname>Alias=</varname> apply only
-                                if the unit has actually been
-                                installed with the
-                                <command>systemctl enable</command>
-                                command.  Also, if systemd searches for a
-                                unit, it will discover symlinked alias
-                                names as configured with
-                                <varname>Alias=</varname>, but not
-                                names configured with
-                                <varname>Names=</varname> only. It is
-                                a common pattern to list a name in
-                                both options. In this case, a unit
-                                will be active under all names if
-                                installed, but also if not installed
-                                but requested explicitly under its
-                                main name.</para></listitem>
+                                to the unit file name.</para></listitem>

                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>WantedBy=</varname></term>
                         </varlistentry>
 
                         <varlistentry>
                                 <term><varname>WantedBy=</varname></term>

+                                <term><varname>RequiredBy=</varname></term>

 
                                 <listitem><para>Installs a symlink in
                                 the <filename>.wants/</filename>
 
                                 <listitem><para>Installs a symlink in
                                 the <filename>.wants/</filename>

+                                resp. <filename>.requires/</filename>

                                 subdirectory for a unit. This has the
                                 effect that when the listed unit name
                                 is activated the unit listing it is
                                 subdirectory for a unit. This has the
                                 effect that when the listed unit name
                                 is activated the unit listing it is


@@ -849,7 +976,8 @@
                         <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

-                        <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>systemd.snapshot</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry>

                 </para>
         </refsect1>
 
                 </para>
         </refsect1>