unit: rename 'banned' load state to 'masked'

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

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index e5d5968ab2227d0711504864ab6d73be38077c02..e59c1a16c4d828d4530b50bcd8322509c168a012 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -189,6 +189,19 @@
                 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>
                 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>

+
+                <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>


@@ -418,8 +431,9 @@
 
                                 <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>


@@ -461,20 +475,43 @@
                         </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>
 


@@ -529,22 +566,23 @@
                                 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>
 
                 </variablelist>
                         </varlistentry>
 
                 </variablelist>