man/systemd-install.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU General Public License as published by
  12   the Free Software Foundation; either version 2 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-install">
  25
  26         <refentryinfo>
  27                 <title>systemd-install</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd-install</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd-install</refname>
  47                 <refpurpose>Enable or disable a systemd unit
  48                 definition file</refpurpose>
  49         </refnamediv>
  50
  51         <refsynopsisdiv>
  52                 <cmdsynopsis>
  53                         <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">enable</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
  54                 </cmdsynopsis>
  55                 <cmdsynopsis>
  56                         <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">disable</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
  57                 </cmdsynopsis>
  58                 <cmdsynopsis>
  59                         <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">realize</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
  60                 </cmdsynopsis>
  61                 <cmdsynopsis>
  62                         <command>systemd-install <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="plain">test</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
  63                 </cmdsynopsis>
  64         </refsynopsisdiv>
  65
  66         <refsect1>
  67                 <title>Description</title>
  68
  69                 <para><command>systemd-install</command> enables or
  70                 disables systemd units, or checks whether they are
  71                 enabled, according to the installation suggestions
  72                 included in the unit files.</para>
  73
  74                 <para>This command is useful to apply or undo the
  75                 installation instructions encoded in the <literal>[Install]</literal>
  76                 section of unit files. See
  77                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  78                 for more information.</para>
  79
  80                 <para>Enabling units (as with <command>systemd-install
  81                 enable</command>) should not be confused with
  82                 activating units (as with <command>systemctl
  83                 start</command>). The former simply installs the unit
  84                 files in the configuration tree, but does not start
  85                 them. The latter equals starting them, but does not
  86                 necessarily require them to be enabled.</para>
  87
  88                 <para>Note that while
  89                 <command>systemd-install</command> is the recommended
  90                 tool to create or remove symlinks in the systemd
  91                 configuration directory the administrator can also
  92                 create links there manually, which is particularly
  93                 useful to use configurations that deviate from the
  94                 installation suggestions included in the unit
  95                 files.</para>
  96         </refsect1>
  97
  98         <refsect1>
  99                 <title>Options</title>
 100
 101                 <para>The following options are understood:</para>
 102
 103                 <variablelist>
 104                         <varlistentry>
 105                                 <term><option>--help</option></term>
 106
 107                                 <listitem><para>Prints a short help
 108                                 text and exits.</para></listitem>
 109                         </varlistentry>
 110
 111                         <varlistentry>
 112                                 <term><option>--force</option></term>
 113
 114                                 <listitem><para>Enable/disable a
 115                                 service even if it conflicts
 116                                 with/contradicts another service. This
 117                                 might have the effect of disabling
 118                                 another service that was
 119                                 enabled.</para></listitem>
 120                         </varlistentry>
 121
 122                         <varlistentry>
 123                                 <term><option>--system</option></term>
 124
 125                                 <listitem><para>Enable/disable a
 126                                 system service.</para></listitem>
 127                         </varlistentry>
 128
 129                         <varlistentry>
 130                                 <term><option>--session</option></term>
 131
 132                                 <listitem><para>Enable/disable a
 133                                 session service for the calling
 134                                 user.</para></listitem>
 135                         </varlistentry>
 136
 137                         <varlistentry>
 138                                 <term><option>--global</option></term>
 139
 140                                 <listitem><para>Enable/disable a
 141                                 session service for all
 142                                 users.</para></listitem>
 143                         </varlistentry>
 144
 145                         <varlistentry>
 146                                 <term><option>--realize[=MODE]</option></term>
 147
 148                                 <listitem><para>After
 149                                 enabling/disabling stop/restart/stop
 150                                 the unit and reload manager
 151                                 configuration. Optionally, takes one
 152                                 of <option>no</option>,
 153                                 <option>reload</option>,
 154                                 <option>minimal</option>,
 155                                 <option>maybe</option> or
 156                                 <option>yes</option>. If
 157                                 <option>no</option> is passed the
 158                                 manager will not reload its
 159                                 configuration and no service will be
 160                                 started or stopped after
 161                                 enabling/disabling of the unit
 162                                 files. If <option>reload</option> is
 163                                 passed the daemon configuration is
 164                                 reloaded but the unit otherwise not
 165                                 started/stopped/restarted. If
 166                                 <option>minimal</option> is passed and
 167                                 a unit is being enabled it will also
 168                                 be restarted should it already be
 169                                 running. If a unit is being disabled
 170                                 it will be stopped should it be
 171                                 running. In either case the daemon
 172                                 configuration is
 173                                 reloaded. <option>maybe</option> is
 174                                 similar to this, but the unit will
 175                                 also be started if it is being enabled
 176                                 and any of the units listed in
 177                                 <varname>WantedBy=</varname> in the
 178                                 <literal>[Install]</literal> section
 179                                 of the unit file is already
 180                                 activated. Finally
 181                                 <option>yes</option> starts the unit
 182                                 unconditionally after enabling. This
 183                                 setting defaults to
 184                                 <option>no</option>. If
 185                                 <option>--realize</option> is
 186                                 specifieed but the mode value is
 187                                 omitted defaults to
 188                                 <option>maybe</option>. This option
 189                                 has no effect when
 190                                 <option>--global</option> or
 191                                 <command>test</command> is used, or
 192                                 when systemd is not running or the
 193                                 command is executed in a
 194                                 <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 195                                 environment. This option is implied if
 196                                 the <command>realize</command> command
 197                                 is used.</para></listitem>
 198                         </varlistentry>
 199                 </variablelist>
 200
 201                 <para>The following commands are understood:</para>
 202
 203                 <variablelist>
 204                         <varlistentry>
 205                                 <term><command>enable</command></term>
 206
 207                                 <listitem><para>Enable one or more
 208                                 units. This will create a number of
 209                                 symlinks as encoded in the
 210                                 <literal>[Install]</literal> section
 211                                 of a unit file.</para></listitem>
 212                         </varlistentry>
 213
 214                         <varlistentry>
 215                                 <term><command>disable</command></term>
 216
 217                                 <listitem><para>Disable or more
 218                                 units. This will remove a number of
 219                                 symlinks as encoded in the
 220                                 <literal>[Install]</literal> section
 221                                 of a unit file.</para></listitem>
 222                         </varlistentry>
 223
 224                         <varlistentry>
 225                                 <term><command>realize</command></term>
 226
 227                                 <listitem><para>Does not enable or
 228                                 disable any unit. Checks whether any
 229                                 of the units specified are enabled,
 230                                 and then starts/stops/restarts the
 231                                 units accordingly. This will check for
 232                                 the existence of a number of symlinks
 233                                 as encoded in the
 234                                 <literal>[Install]</literal> section
 235                                 of a unit file, and then executes the
 236                                 action normally specified by
 237                                 <option>--realize</option>. If
 238                                 <option>--realize</option> is not
 239                                 specified implies
 240                                 <option>maybe</option> mode. To
 241                                 override this mode specify
 242                                 <option>--realize=</option> in
 243                                 addition to
 244                                 <command>realize</command>.</para></listitem>
 245                         </varlistentry>
 246
 247                         <varlistentry>
 248                                 <term><command>test</command></term>
 249
 250                                 <listitem><para>Does not enable or
 251                                 disable any unit. Checks whether any
 252                                 of the units specified are
 253                                 enabled. This will check for the
 254                                 existence of a number of symlinks as
 255                                 encoded in the
 256                                 <literal>[Install]</literal> section
 257                                 of a unit file, and return with an
 258                                 exit code of 0 if a unit is enabled, 1
 259                                 otherwise.</para></listitem>
 260                         </varlistentry>
 261
 262                 </variablelist>
 263
 264         </refsect1>
 265
 266         <refsect1>
 267                 <title>Exit status</title>
 268
 269                 <para>On success 0 is returned, a non-zero failure
 270                 code otherwise.</para>
 271         </refsect1>
 272
 273         <refsect1>
 274                 <title>See Also</title>
 275                 <para>
 276                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 277                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 278                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 279                 </para>
 280         </refsect1>
 281
 282 </refentry>