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
 200                         <varlistentry>
 201                                 <term><option>--all</option></term>
 202
 203                                 <listitem><para>If set makes sure that
 204                                 all symlinks on the specified unit are
 205                                 removed from the configuration
 206                                 directory and its subdirectories, not
 207                                 just those specified in the
 208                                 <literal>[Install]</literal>
 209                                 section.</para></listitem>
 210                         </varlistentry>
 211
 212                         <varlistentry>
 213                                 <term><option>--verbose</option></term>
 214                                 <term><option>-v</option></term>
 215
 216                                 <listitem><para>Show what is done as
 217                                 it is done.</para></listitem>
 218                         </varlistentry>
 219
 220                 </variablelist>
 221
 222                 <para>The following commands are understood:</para>
 223
 224                 <variablelist>
 225                         <varlistentry>
 226                                 <term><command>enable</command></term>
 227
 228                                 <listitem><para>Enable one or more
 229                                 units. This will create a number of
 230                                 symlinks as encoded in the
 231                                 <literal>[Install]</literal> section
 232                                 of a unit file.</para></listitem>
 233                         </varlistentry>
 234
 235                         <varlistentry>
 236                                 <term><command>disable</command></term>
 237
 238                                 <listitem><para>Disable or more
 239                                 units. This will remove a number of
 240                                 symlinks as encoded in the
 241                                 <literal>[Install]</literal> section
 242                                 of a unit file.</para></listitem>
 243                         </varlistentry>
 244
 245                         <varlistentry>
 246                                 <term><command>realize</command></term>
 247
 248                                 <listitem><para>Does not enable or
 249                                 disable any unit. Checks whether any
 250                                 of the units specified are enabled,
 251                                 and then starts/stops/restarts the
 252                                 units accordingly. This will check for
 253                                 the existence of a number of symlinks
 254                                 as encoded in the
 255                                 <literal>[Install]</literal> section
 256                                 of a unit file, and then executes the
 257                                 action normally specified by
 258                                 <option>--realize</option>. If
 259                                 <option>--realize</option> is not
 260                                 specified implies
 261                                 <option>maybe</option> mode. To
 262                                 override this mode specify
 263                                 <option>--realize=</option> in
 264                                 addition to
 265                                 <command>realize</command>.</para></listitem>
 266                         </varlistentry>
 267
 268                         <varlistentry>
 269                                 <term><command>test</command></term>
 270
 271                                 <listitem><para>Does not enable or
 272                                 disable any unit. Checks whether any
 273                                 of the units specified are
 274                                 enabled. This will check for the
 275                                 existence of a number of symlinks as
 276                                 encoded in the
 277                                 <literal>[Install]</literal> section
 278                                 of a unit file, and return with an
 279                                 exit code of 0 if a unit is enabled, 1
 280                                 otherwise.</para></listitem>
 281                         </varlistentry>
 282
 283                 </variablelist>
 284
 285         </refsect1>
 286
 287         <refsect1>
 288                 <title>Exit status</title>
 289
 290                 <para>On success 0 is returned, a non-zero failure
 291                 code otherwise.</para>
 292         </refsect1>
 293
 294         <refsect1>
 295                 <title>See Also</title>
 296                 <para>
 297                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 298                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 299                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 300                 </para>
 301         </refsect1>
 302
 303 </refentry>