X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=blobdiff_plain;f=man%2Fsystemd-install.xml;h=03ed0c7449caad2fa2d1a253548b118dec3f7101;hp=9881e9819e29bc22b540abce5af3d5cb0bad9f22;hb=ad780f1991d81c8013cc345488b9a035bf30aae7;hpb=359957ee23e8dad97f6c75969d7ecfe4d3c4369f

diff --git a/man/systemd-install.xml b/man/systemd-install.xml
index 9881e9819..03ed0c744 100644
--- a/man/systemd-install.xml
+++ b/man/systemd-install.xml
@@ -21,7 +21,7 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
-<refentry id="systemd">
+<refentry id="systemd-install">
 
         <refentryinfo>
                 <title>systemd-install</title>
@@ -50,13 +50,16 @@
 
         <refsynopsisdiv>
                 <cmdsynopsis>
-                        <command>systemd-install <arg choice="opt" rep="repeat">options</arg> <option>enable</option> <arg choice="opt" rep="repeat">name</arg></command>
+                        <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">enable</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
                 </cmdsynopsis>
                 <cmdsynopsis>
-                        <command>systemd-install <arg choice="opt" rep="repeat">options</arg> <option>disable</option> <arg choice="opt" rep="repeat">name</arg></command>
+                        <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">disable</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
                 </cmdsynopsis>
                 <cmdsynopsis>
-                        <command>systemd-install <arg choice="opt" rep="repeat">options</arg> <option>test</option> <arg choice="opt" rep="repeat">name</arg></command>
+                        <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">realize</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
+                </cmdsynopsis>
+                <cmdsynopsis>
+                        <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">test</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
                 </cmdsynopsis>
         </refsynopsisdiv>
 
@@ -65,20 +68,48 @@
 
                 <para><command>systemd-install</command> enables or
                 disables systemd units, or checks whether they are
-                enabled.</para>
+                enabled, according to the installation suggestions
+                included in the unit files.</para>
+
+                <para>This command is useful to apply or undo the
+                installation instructions encoded in the <literal>[Install]</literal>
+                section of unit files. See
+                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                for more information.</para>
+
+                <para>Enabling units (as with <command>systemd-install
+                enable</command>) should not be confused with
+                activating units (as with <command>systemctl
+                start</command>). The former simply installs the unit
+                files in the configuration tree, but does not start
+                them. The latter equals starting them, but does not
+                necessarily require them to be enabled.</para>
+
+                <para>Note that while
+                <command>systemd-install</command> is the recommended
+                tool to create or remove symlinks in the systemd
+                configuration directory the administrator can also
+                create links there manually, which is particularly
+                useful to use configurations that deviate from the
+                installation suggestions included in the unit
+                files.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
 
                 <para>The following options are understood:</para>
 
                 <variablelist>
                         <varlistentry>
-                                <term>--help</term>
+                                <term><option>--help</option></term>
 
                                 <listitem><para>Prints a short help
                                 text and exits.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term>--force</term>
+                                <term><option>--force</option></term>
 
                                 <listitem><para>Enable/disable a
                                 service even if it conflicts
@@ -89,14 +120,14 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term>--system</term>
+                                <term><option>--system</option></term>
 
                                 <listitem><para>Enable/disable a
                                 system service.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term>--session</term>
+                                <term><option>--session</option></term>
 
                                 <listitem><para>Enable/disable a
                                 session service for the calling
@@ -104,45 +135,130 @@
                         </varlistentry>
 
                         <varlistentry>
-                                <term>--global</term>
+                                <term><option>--global</option></term>
 
                                 <listitem><para>Enable/disable a
                                 session service for all
                                 users.</para></listitem>
                         </varlistentry>
+
+                        <varlistentry>
+                                <term><option>--realize[=MODE]</option></term>
+
+                                <listitem><para>After
+                                enabling/disabling stop/restart/stop
+                                the unit and reload manager
+                                configuration. Optionally, takes one
+                                of <option>no</option>,
+                                <option>reload</option>,
+                                <option>minimal</option>,
+                                <option>maybe</option> or
+                                <option>yes</option>. If
+                                <option>no</option> is passed the
+                                manager will not reload its
+                                configuration and no service will be
+                                started or stopped after
+                                enabling/disabling of the unit
+                                files. If <option>reload</option> is
+                                passed the daemon configuration is
+                                reloaded but the unit otherwise not
+                                started/stopped/restarted. If
+                                <option>minimal</option> is passed and
+                                a unit is being enabled it will also
+                                be restarted should it already be
+                                running. If a unit is being disabled
+                                it will be stopped should it be
+                                running. In either case the daemon
+                                configuration is
+                                reloaded. <option>maybe</option> is
+                                similar to this, but the unit will
+                                also be started if it is being enabled
+                                and any of the units listed in
+                                <varname>WantedBy=</varname> in the
+                                <literal>[Install]</literal> section
+                                of the unit file is already
+                                activated. Finally
+                                <option>yes</option> starts the unit
+                                unconditionally after enabling. This
+                                setting defaults to
+                                <option>no</option>. If
+                                <option>--realize</option> is
+                                specifieed but the mode value is
+                                omitted defaults to
+                                <option>maybe</option>. This option
+                                has no effect when
+                                <option>--global</option> or
+                                <command>test</command> is used, or
+                                when systemd is not running or the
+                                command is executed in a
+                                <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+                                environment. This option is implied if
+                                the <command>realize</command> command
+                                is used.</para></listitem>
+                        </varlistentry>
                 </variablelist>
 
-                <para>The following verbs are understood:</para>
+                <para>The following commands are understood:</para>
 
                 <variablelist>
                         <varlistentry>
-                                <term>enable</term>
+                                <term><command>enable</command></term>
 
-                                <listitem><para>Enable a unit. This
-                                will create a number of symlinks as
-                                encoded in the [Install] section of a
-                                unit file.</para></listitem>
+                                <listitem><para>Enable one or more
+                                units. This will create a number of
+                                symlinks as encoded in the
+                                <literal>[Install]</literal> section
+                                of a unit file.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term>disable</term>
+                                <term><command>disable</command></term>
+
+                                <listitem><para>Disable or more
+                                units. This will remove a number of
+                                symlinks as encoded in the
+                                <literal>[Install]</literal> section
+                                of a unit file.</para></listitem>
+                        </varlistentry>
 
-                                <listitem><para>Disable a unit. This
-                                will removed a number of symlinks as
-                                encoded in the [Install] section of a
-                                unit file.</para></listitem>
+                        <varlistentry>
+                                <term><command>realize</command></term>
+
+                                <listitem><para>Does not enable or
+                                disable any unit. Checks whether any
+                                of the units specified are enabled,
+                                and then starts/stops/restarts the
+                                units accordingly. This will check for
+                                the existence of a number of symlinks
+                                as encoded in the
+                                <literal>[Install]</literal> section
+                                of a unit file, and then executes the
+                                action normally specified by
+                                <option>--realize</option>. If
+                                <option>--realize</option> is not
+                                specified implies
+                                <option>maybe</option> mode. To
+                                override this mode specify
+                                <option>--realize=</option> in
+                                addition to
+                                <command>realize</command>.</para></listitem>
                         </varlistentry>
 
                         <varlistentry>
-                                <term>test</term>
-
-                                <listitem><para>Checks whether any of
-                                the units specified are
-                                installed. This will check for the
-                                existance of a number of symlinks as
-                                encoded in the [Install] section of a
-                                unit file.</para></listitem>
+                                <term><command>test</command></term>
+
+                                <listitem><para>Does not enable or
+                                disable any unit. Checks whether any
+                                of the units specified are
+                                enabled. This will check for the
+                                existence of a number of symlinks as
+                                encoded in the
+                                <literal>[Install]</literal> section
+                                of a unit file, and return with an
+                                exit code of 0 if a unit is enabled, 1
+                                otherwise.</para></listitem>
                         </varlistentry>
+
                 </variablelist>
 
         </refsect1>
@@ -157,6 +273,7 @@
         <refsect1>
                 <title>See Also</title>
                 <para>
+                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>