doc/lxc-autostart.sgml.in

   1 <!--
   2
   3 lxc-autostart
   4
   5 (C) Copyright 2013 Canonical Ltd.
   6
   7 Authors:
   8 Stéphane Graber <stgraber@ubuntu.com>
   9
  10 This library is free software; you can redistribute it and/or
  11 modify it under the terms of the GNU Lesser General Public
  12 License as published by the Free Software Foundation; either
  13 version 2.1 of the License, or (at your option) any later version.
  14
  15 This library is distributed in the hope that it will be useful,
  16 but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  18 Lesser General Public License for more details.
  19
  20 You should have received a copy of the GNU Lesser General Public
  21 License along with this library; if not, write to the Free Software
  22 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  23
  24 -->
  25
  26 <!DOCTYPE refentry PUBLIC @docdtd@ [
  27     <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
  28     <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  29 ]>
  30
  31 <refentry>
  32     <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  33     <refmeta>
  34         <refentrytitle>lxc-autostart</refentrytitle>
  35         <manvolnum>1</manvolnum>
  36     </refmeta>
  37
  38     <refnamediv>
  39         <refname>lxc-autostart</refname>
  40
  41         <refpurpose>
  42             start/stop/kill auto-started containers
  43         </refpurpose>
  44     </refnamediv>
  45
  46     <refsynopsisdiv>
  47         <cmdsynopsis>
  48             <command>lxc-autostart</command>
  49             <arg choice="opt">-k</arg>
  50             <arg choice="opt">-L</arg>
  51             <arg choice="opt">-r</arg>
  52             <arg choice="opt">-s</arg>
  53             <arg choice="opt">-a</arg>
  54             <arg choice="opt">-A</arg>
  55             <arg choice="opt">-g <replaceable>groups</replaceable></arg>
  56             <arg choice="opt">-t <replaceable>timeout</replaceable></arg>
  57         </cmdsynopsis>
  58     </refsynopsisdiv>
  59
  60     <refsect1>
  61         <title>Description</title>
  62
  63         <para>
  64             <command>lxc-autostart</command> processes containers
  65             with lxc.start.auto set. It lets the user start, shutdown,
  66             kill, restart containers in the right order, waiting the
  67             right time. Supports filtering by lxc.group or just run
  68             against all defined containers. It can also be used by
  69             external tools in list mode where no action will be performed
  70             and the list of affected containers (and if relevant, delays)
  71             will be shown.
  72         </para>
  73
  74         <para>
  75             The <optional>-r</optional>, <optional>-s</optional>
  76             and <optional>-k</optional> options specify the action to perform.
  77             If none is specified, then the containers will be started.
  78             <optional>-a</optional> and <optional>-g</optional> are used to
  79             specify which containers will be affected. By default only
  80             containers without a lxc.group set will be affected.
  81             <optional>-t TIMEOUT</optional> specifies the maximum amount
  82             of time to wait for the container to complete the shutdown
  83             or reboot.
  84         </para>
  85     </refsect1>
  86
  87     <refsect1>
  88         <title>Options</title>
  89         <variablelist>
  90             <varlistentry>
  91                 <term>
  92                     <option>-r,--reboot </option>
  93                 </term>
  94                 <listitem>
  95                     <para>
  96                         Request a reboot of the container.
  97                     </para>
  98                 </listitem>
  99             </varlistentry>
 100
 101             <varlistentry>
 102                 <term>
 103                     <option>-s,--shutdown </option>
 104                 </term>
 105                 <listitem>
 106                     <para>
 107                         Request a clean shutdown. If a
 108                         <optional>-t timeout</optional> greater than 0 is
 109                         given and the container has not shut down within
 110                         this period, it will be killed as with the
 111                         <optional>-k kill</optional> option.
 112                     </para>
 113                 </listitem>
 114             </varlistentry>
 115
 116             <varlistentry>
 117                 <term>
 118                     <option>-k,--kill </option>
 119                 </term>
 120                 <listitem>
 121                     <para>
 122                         Rather than requesting a clean shutdown of the
 123                         container, explicitly kill all tasks in the container.
 124                     </para>
 125                 </listitem>
 126             </varlistentry>
 127
 128             <varlistentry>
 129                 <term>
 130                     <option>-L,--list </option>
 131                 </term>
 132                 <listitem>
 133                     <para>
 134                         Rather than performing the action, just print
 135                         the container name and wait delays until starting the next container.
 136                     </para>
 137                 </listitem>
 138             </varlistentry>
 139
 140             <varlistentry>
 141                 <term>
 142                     <option>-t,--timeout <replaceable>TIMEOUT</replaceable></option>
 143                 </term>
 144                 <listitem>
 145                     <para>
 146                         Wait TIMEOUT seconds before hard-stopping the container.
 147                     </para>
 148                 </listitem>
 149             </varlistentry>
 150
 151             <varlistentry>
 152                 <term>
 153                     <option>-g,--group <replaceable>GROUP</replaceable></option>
 154                 </term>
 155                 <listitem>
 156                     <para>
 157                         Comma separated list of groups to select
 158                         (defaults to those without a lxc.group - the NULL group).
 159                         This option may be specified multiple times
 160                         and the arguments concatenated.  The NULL or
 161                         empty group may be specified as a leading comma,
 162                         trailing comma, embedded double comma, or empty
 163                         argument where the NULL group should be processed.
 164                         Groups are processed in the order specified on the
 165                         command line.  Multiple invocations of the -g option
 166                         may be freely intermixed with the comma separated
 167                         lists and will be combined in specified order.
 168                     </para>
 169                 </listitem>
 170             </varlistentry>
 171
 172             <varlistentry>
 173                 <term>
 174                     <option>-a,--all</option>
 175                 </term>
 176                 <listitem>
 177                     <para>
 178                         Ignore lxc.group and select all auto-started containers.
 179                     </para>
 180                 </listitem>
 181             </varlistentry>
 182
 183             <varlistentry>
 184                 <term>
 185                     <option>-A,--ignore-auto</option>
 186                 </term>
 187                 <listitem>
 188                     <para>
 189                         Ignore the lxc.start.auto flag. Combined with
 190                         -a, will select all containers on the system.
 191                     </para>
 192                 </listitem>
 193             </varlistentry>
 194         </variablelist>
 195     </refsect1>
 196
 197     <refsect1>
 198         <title>Autostart and System Boot</title>
 199
 200         <para>
 201             The <command>lxc-autostart</command> command is used as part of the
 202             LXC system service, when enabled to run on host system at bootup and at
 203             shutdown.  It's used to select which containers to start in what order
 204             and how much to delay between each startup when the host system boots.
 205         </para>
 206
 207         <para>
 208             Each container can be part of any number of groups or no group at all.
 209             Two groups are special. One is the NULL group, i.e. the container does
 210             not belong to any group. The other group is the "onboot" group.
 211         </para>
 212
 213         <para>
 214             When the system boots with the LXC service enabled, it will first
 215             attempt to boot any containers with lxc.start.auto == 1 that is a member
 216             of the "onboot" group. The startup will be in order of lxc.start.order.
 217             If an lxc.start.delay has been specified, that delay will be honored
 218             before attempting to start the next container to give the current
 219             container time to begin initialization and reduce overloading the host
 220             system. After starting the members of the "onboot" group, the LXC system
 221             will proceed to boot containers with lxc.start.auto == 1 which are not
 222             members of any group (the NULL group) and proceed as with the onboot
 223             group.
 224         </para>
 225     </refsect1>
 226
 227     <refsect1>
 228         <title>Startup Group Examples</title>
 229         <variablelist>
 230             <varlistentry>
 231                 <term>
 232                     <option>-g "onboot,"</option>
 233                 </term>
 234                 <listitem>
 235                     <para>
 236                         Start the "onboot" group first then the NULL group.
 237                     </para>
 238                     <para>
 239                         This is the equivalent of: <option>-g onboot -g ""</option>.
 240                     </para>
 241                 </listitem>
 242             </varlistentry>
 243             <varlistentry>
 244                 <term>
 245                     <option>-g "dns,web,,onboot"</option>
 246                 </term>
 247                 <listitem>
 248                     <para>
 249                         Starts the "dns" group first, the "web" group second, then
 250                         the NULL group followed by the "onboot" group.
 251                     </para>
 252                     <para>
 253                         This is the equivalent of: <option>-g dns,web -g ,onboot</option> or <option>-g dns -g web -g "" -g onboot</option>.
 254                     </para>
 255                 </listitem>
 256             </varlistentry>
 257         </variablelist>
 258     </refsect1>
 259
 260     &seealso;
 261
 262     <refsect1>
 263         <title>Author</title>
 264         <para>Stéphane Graber <email>stgraber@ubuntu.com</email></para>
 265     </refsect1>
 266 </refentry>
 267
 268 <!-- Keep this comment at the end of the file
 269 Local variables:
 270 mode: sgml
 271 sgml-omittag:t
 272 sgml-shorttag:t
 273 sgml-minimize-attributes:nil
 274 sgml-always-quote-attributes:t
 275 sgml-indent-step:2
 276 sgml-indent-data:t
 277 sgml-parent-document:nil
 278 sgml-default-dtd-file:nil
 279 sgml-exposed-tags:nil
 280 sgml-local-catalogs:nil
 281 sgml-local-ecat-files:nil
 282 End:
 283 -->