chiark / gitweb /
unit: introduce ConditionFileIsExecutable= and use it where we check for a binary...
[elogind.git] / man / systemd.unit.xml
index 7284524dbbae65b58567efd4da29cf0b1a0de5b0..d38a00136651b552ba94b4c513e643a5654f3a2f 100644 (file)
                 <varname>Wanted=</varname> see below. The preferred
                 way to create symlinks in the
                 <filename>.wants/</filename> directory of a service is
                 <varname>Wanted=</varname> see below. The preferred
                 way to create symlinks in the
                 <filename>.wants/</filename> directory of a service is
-                with the
-                <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                with the <command>enable</command> command of the
+                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 tool which reads information from the [Install]
                 tool which reads information from the [Install]
-                section of unit files. (See below.)</para>
+                section of unit files. (See below.) A similar
+                functionality exists for <varname>Requires=</varname>
+                type dependencies as well, the directory suffix is
+                <filename>.requires/</filename> in this case.</para>
 
                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
 
                 <para>Note that while systemd offers a flexible
                 dependency system between units it is recommended to
                 <literal>%i</literal> specifier in many of the
                 configuration options. Other specifiers that may be
                 used are <literal>%n</literal>, <literal>%N</literal>,
                 <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> and
-                <literal>%I</literal>, for the full unit name, the
-                unescaped unit name, the prefix name, the unescaped
-                prefix name and the unescaped instance name,
-                respectively. The prefix name here refers to the
-                string before the @, i.e. "getty" in the example
-                above, where "tty3" is the instance name.</para>
+                <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>
+
+                <para>If a unit file is empty (i.e. has the file size
+                0) or is symlinked to <filename>/dev/null</filename>
+                its configuration will not be loaded and it appears
+                with a load state of <literal>masked</literal>, and
+                cannot be activated. Use this as an effective way to
+                fully disable a unit, making it impossible to start it
+                even manually.</para>
+
+                <para>The unit file format is covered by the
+                <ulink
+                url="http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise">Interface
+                Stability Promise</ulink>.</para>
         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>
                 dependent on the type of unit:</para>
 
                 <variablelist>
                 dependent on the type of unit:</para>
 
                 <variablelist>
-                        <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.</para>
-                                </listitem>
-                        </varlistentry>
 
                         <varlistentry>
                                 <term><varname>Description=</varname></term>
 
                         <varlistentry>
                                 <term><varname>Description=</varname></term>
                                 services.</para></listitem>
                         </varlistentry>
 
                                 services.</para></listitem>
                         </varlistentry>
 
-
                         <varlistentry>
                                 <term><varname>RequiresOverridable=</varname></term>
 
                         <varlistentry>
                                 <term><varname>RequiresOverridable=</varname></term>
 
                                 details see above.</para></listitem>
                         </varlistentry>
 
                                 details see above.</para></listitem>
                         </varlistentry>
 
+                        <varlistentry>
+                                <term><varname>BindTo=</varname></term>
+
+                                <listitem><para>Configures requirement
+                                dependencies, very similar in style to
+                                <varname>Requires=</varname>, however
+                                in addition to this behaviour it also
+                                declares that this unit is stopped
+                                when any of the units listed suddenly
+                                disappears. Units can suddenly,
+                                unexpectedly disappear if a service
+                                terminates on its own choice, a device
+                                is unplugged or a mount point
+                                unmounted without involvement of
+                                systemd.</para></listitem>
+                        </varlistentry>
+
                         <varlistentry>
                                 <term><varname>Conflicts=</varname></term>
 
                         <varlistentry>
                                 <term><varname>Conflicts=</varname></term>
 
                                 independent of and orthogonal to the
                                 <varname>After=</varname> and
                                 <varname>Before=</varname> ordering
                                 independent of and orthogonal to the
                                 <varname>After=</varname> and
                                 <varname>Before=</varname> ordering
-                                dependencies.</para></listitem>
+                                dependencies.</para>
+
+                                <para>If a unit A that conflicts with
+                                a unit B is scheduled to be started at
+                                the same time as B, the transaction
+                                will either fail (in case both are
+                                required part of the transaction) or
+                                be modified to be fixed (in case one
+                                or both jobs are not a required part
+                                of the transaction). In the latter
+                                case the job that is not the required
+                                will be removed, or in case both are
+                                not required the unit that conflicts
+                                will be started and the unit that is
+                                conflicted is
+                                stopped.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>
 
                                 <listitem><para>Lists one or more
                                 units that are activated when this
 
                                 <listitem><para>Lists one or more
                                 units that are activated when this
-                                unit fails (i.e. enters maintenance
-                                state).</para></listitem>
+                                unit enters the
+                                '<literal>failed</literal>'
+                                state.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><varname>RecursiveStop=</varname></term>
+                                <term><varname>OnFailureIsolate=</varname></term>
 
                                 <listitem><para>Takes a boolean
 
                                 <listitem><para>Takes a boolean
-                                argument. If <option>true</option> and
-                                the unit stops without being requested
-                                by the user, all units
-                                depending on it will be stopped as
-                                well. (e.g. if a service exits or
-                                crashes on its own behalf, units using
-                                it will be stopped) Note that normally
-                                if a unit stops without a user request,
-                                units depending on it will not be
-                                terminated. Only if the user requested
-                                shutdown of a unit, all units depending
-                                on that unit will be shut down as well
-                                and at the same time. Defaults to
+                                argument. If <option>true</option> the
+                                unit listed in
+                                <varname>OnFailure=</varname> will be
+                                enqueued in isolation mode, i.e. all
+                                units that are not its dependency will
+                                be stopped. If this is set only a
+                                single unit may be listed in
+                                <varname>OnFailure=</varname>. Defaults
+                                to
                                 <option>false</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>false</option>.</para></listitem>
                         </varlistentry>
 
+                        <varlistentry>
+                                <term><varname>IgnoreOnIsolate=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option>
+                                this unit will not be stopped when
+                                isolating another unit. Defaults to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>IgnoreOnSnapshot=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option>
+                                this unit will not be included in
+                                snapshots. Defaults to
+                                <option>true</option> for device and
+                                snapshot units, <option>false</option>
+                                for the others.</para></listitem>
+                        </varlistentry>
+
                         <varlistentry>
                                 <term><varname>StopWhenUnneeded=</varname></term>
 
                         <varlistentry>
                                 <term><varname>StopWhenUnneeded=</varname></term>
 
                         </varlistentry>
 
                         <varlistentry>
                         </varlistentry>
 
                         <varlistentry>
-                                <term><varname>OnlyByDependency=</varname></term>
+                                <term><varname>RefuseManualStart=</varname></term>
+                                <term><varname>RefuseManualStop=</varname></term>
 
                                 <listitem><para>Takes a boolean
                                 argument. If <option>true</option>
                                 this unit can only be activated
 
                                 <listitem><para>Takes a boolean
                                 argument. If <option>true</option>
                                 this unit can only be activated
-                                indirectly. In this case explicit
-                                start-up requested by the user is
-                                denied, however if it is started as a
+                                (resp. deactivated) indirectly. In
+                                this case explicit start-up
+                                (resp. termination) requested by the
+                                user is denied, however if it is
+                                started (resp. stopped) as a
                                 dependency of another unit, start-up
                                 dependency of another unit, start-up
-                                will succeed. This is mostly a safety
-                                feature to ensure that the user does
-                                not accidentally activate units that are
-                                not intended to be activated
-                                explicitly. This option defaults to
+                                (resp. termination) will succeed. This
+                                is mostly a safety feature to ensure
+                                that the user does not accidentally
+                                activate units that are not intended
+                                to be activated explicitly, and not
+                                accidentally deactivate units that are
+                                not intended to be deactivated.
+                                These options default to
+                                <option>false</option>.</para></listitem>
+                        </varlistentry>
+
+                        <varlistentry>
+                                <term><varname>AllowIsolate=</varname></term>
+
+                                <listitem><para>Takes a boolean
+                                argument. If <option>true</option>
+                                this unit may be used with the
+                                <command>systemctl isolate</command>
+                                command. Otherwise this will be
+                                refused. It probably is a good idea to
+                                leave this disabled except for target
+                                units that shall be used similar to
+                                runlevels in SysV init systems, just
+                                as a precaution to avoid unusable
+                                system states. This option defaults to
                                 <option>false</option>.</para></listitem>
                         </varlistentry>
 
                                 <option>false</option>.</para></listitem>
                         </varlistentry>
 
                                 ones.</para></listitem>
                         </varlistentry>
 
                                 ones.</para></listitem>
                         </varlistentry>
 
-                        <varlistentry>
-                                <term><varname>IgnoreDependencyFailure=</varname></term>
-
-                                <listitem><para>Takes a boolean
-                                argument. If <option>true</option> and
-                                a requirement dependency of this unit
-                                fails to start up this unit will be
-                                started nonetheless, ignoring that
-                                failure. If <option>false</option>
-                                (the default) and a dependency unit
-                                fails the unit will immediately fail
-                                too and the job is removed.</para></listitem>
-                        </varlistentry>
-
                         <varlistentry>
                                 <term><varname>JobTimeoutSec=</varname></term>
 
                         <varlistentry>
                                 <term><varname>JobTimeoutSec=</varname></term>
 
                                 time. If this time limit is reached
                                 the job will be cancelled, the unit
                                 however will not change state or even
                                 time. If this time limit is reached
                                 the job will be cancelled, the unit
                                 however will not change state or even
-                                enter maintenance mode. This value
-                                defaults to 0 (job timeouts disabled),
-                                except for device units. NB: this
-                                timeout is independent from any
-                                unit-specific timeout (for example,
-                                the timeout set with
+                                enter the '<literal>failed</literal>'
+                                mode. This value defaults to 0 (job
+                                timeouts disabled), except for device
+                                units. NB: this timeout is independent
+                                from any unit-specific timeout (for
+                                example, the timeout set with
                                 <varname>Timeout=</varname> in service
                                 <varname>Timeout=</varname> in service
-                                units) as the job timeout has no effect
-                                on the unit itself, only on the job
-                                that might be pending for it. Or in
-                                other words: unit-specific timeouts
+                                units) as the job timeout has no
+                                effect on the unit itself, only on the
+                                job that might be pending for it. Or
+                                in other words: unit-specific timeouts
                                 are useful to abort unit state
                                 changes, and revert them. The job
                                 timeout set with this option however
                                 are useful to abort unit state
                                 changes, and revert them. The job
                                 timeout set with this option however
-                                is useful to abort only the job waiting
-                                for the unit state to change.</para></listitem>
+                                is useful to abort only the job
+                                waiting for the unit state to
+                                change.</para></listitem>
                         </varlistentry>
 
                         </varlistentry>
 
+                        <varlistentry>
+                                <term><varname>ConditionPathExists=</varname></term>
+                                <term><varname>ConditionPathExistsGlob=</varname></term>
+                                <term><varname>ConditionPathIsDirectory=</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>ConditionNull=</varname></term>
+
+                                <listitem><para>Before starting a unit
+                                verify that the specified condition is
+                                true. With
+                                <varname>ConditionPathExists=</varname>
+                                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
+                                actually happen, however the unit is
+                                still useful for ordering purposes in
+                                this case. The condition is checked at
+                                the time the queued start job is to be
+                                executed. If the absolute path name
+                                passed to
+                                <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
+                                directory matching the specified
+                                globbing
+                                pattern. <varname>ConditionPathIsDirectory=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a
+                                directory. <varname>ConditionFileIsExecutable=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists, is a regular file and marked
+                                executable.
+                                <varname>ConditionDirectoryNotEmpty=</varname>
+                                is similar to
+                                <varname>ConditionPathExists=</varname>
+                                but verifies whether a certain path
+                                exists and is a non-empty
+                                directory. Similarly
+                                <varname>ConditionKernelCommandLine=</varname>
+                                may be used to check whether a
+                                specific kernel command line option is
+                                set (or if prefixed with the
+                                exclamation mark unset). The argument
+                                must either be a single word, or an
+                                assignment (i.e. two words, separated
+                                by the equality sign). In the former
+                                case the kernel command line is
+                                searched for the word appearing as is,
+                                or as left hand side of an
+                                assignment. In the latter case the
+                                exact assignment is looked for with
+                                right and left hand side
+                                matching. <varname>ConditionVirtualization=</varname>
+                                may be used to check whether the
+                                system is executed in a virtualized
+                                environment and optionally test
+                                whether it is a specific
+                                implementation. Takes either boolean
+                                value to check if being executed in
+                                any virtual environment or one of the
+                                <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
+                                test may be negated by prepending an
+                                exclamation mark.
+                                <varname>ConditionSecurity=</varname>
+                                may be used to check whether the given
+                                security module is enabled on the
+                                system.  Currently the only recognized
+                                value is <varname>selinux</varname>.
+                                The test may be negated by prepending
+                                an exclamation mark. Finally,
+                                <varname>ConditionNull=</varname> may
+                                be used to add a constant condition
+                                check value to the unit. It takes a
+                                boolean argument. If set to
+                                <varname>false</varname> the condition
+                                will always fail, otherwise
+                                succeed. If multiple conditions are
+                                specified the unit will be executed if
+                                all of them apply (i.e. a logical AND
+                                is applied). Condition checks can be
+                                prefixed with a pipe symbol (|) in
+                                which case a condition becomes a
+                                triggering condition. If at least one
+                                triggering condition is defined for a
+                                unit then the unit will be executed if
+                                at least one of the triggering
+                                conditions apply and all of the
+                                non-triggering conditions. If you
+                                prefix an argument with the pipe
+                                symbol and an exclamation mark the
+                                pipe symbol must be passed first, the
+                                exclamation second.</para></listitem>
+                        </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>
+                        </varlistentry>
                 </variablelist>
 
                 <para>Unit file may include a [Install] section, which
                 </variablelist>
 
                 <para>Unit file may include a [Install] section, which
                 section is not interpreted by
                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 during runtime. It is used exclusively by the
                 section is not interpreted by
                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 during runtime. It is used exclusively by the
-                <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                <command>enable</command> and
+                <command>disable</command> commands of the
+                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                 tool during installation of a unit:</para>
 
                 <variablelist>
                 tool during installation of a unit:</para>
 
                 <variablelist>
                                 more than once, in which case all
                                 listed names are used. At installation
                                 time,
                                 more than once, in which case all
                                 listed names are used. At installation
                                 time,
-                                <command>systemd-install</command>
+                                <command>systemctl enable</command>
                                 will create symlinks from these names
                                 to the unit file name. Note that this
                                 is different from the
                                 will create symlinks from these names
                                 to the unit file name. Note that this
                                 is different from the
                                 <varname>Alias=</varname> apply only
                                 if the unit has actually been
                                 installed with the
                                 <varname>Alias=</varname> apply only
                                 if the unit has actually been
                                 installed with the
-                                <command>systemd-install</command>
-                                tool.  Also, if systemd searches for a
+                                <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
                                 unit, it will discover symlinked alias
                                 names as configured with
                                 <varname>Alias=</varname>, but not
                                 installed. If the user requests
                                 installation of a unit with this
                                 option configured,
                                 installed. If the user requests
                                 installation of a unit with this
                                 option configured,
-                                <command>systemd-install</command>
+                                <command>systemctl enable</command>
                                 will automatically install units
                                 listed in this option as
                                 well.</para></listitem>
                                 will automatically install units
                                 listed in this option as
                                 well.</para></listitem>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,