doc/lxc-start.sgml.in

   1 <!--
   2
   3 lxc: linux Container library
   4
   5 (C) Copyright IBM Corp. 2007, 2008
   6
   7 Authors:
   8 Daniel Lezcano <daniel.lezcano at free.fr>
   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
  28 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
  29 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  30 ]>
  31
  32 <refentry>
  33
  34   <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  35
  36   <refmeta>
  37     <refentrytitle>lxc-start</refentrytitle>
  38     <manvolnum>1</manvolnum>
  39   </refmeta>
  40
  41   <refnamediv>
  42     <refname>lxc-start</refname>
  43
  44     <refpurpose>
  45       run an application inside a container.
  46     </refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <cmdsynopsis>
  51       <command>lxc-start</command>
  52       <arg choice="req">-n <replaceable>name</replaceable></arg>
  53       <arg choice="opt">-f <replaceable>config_file</replaceable></arg>
  54       <arg choice="opt">-c <replaceable>console_device</replaceable></arg>
  55       <arg choice="opt">-L <replaceable>console_logfile</replaceable></arg>
  56       <arg choice="opt">-d</arg>
  57       <arg choice="opt">-F</arg>
  58       <arg choice="opt">-p <replaceable>pid_file</replaceable></arg>
  59       <arg choice="opt">-s KEY=VAL</arg>
  60       <arg choice="opt">-C</arg>
  61       <arg choice="opt">--share-[net|ipc|uts] <replaceable>name|pid</replaceable></arg>
  62       <arg choice="opt">command</arg>
  63     </cmdsynopsis>
  64   </refsynopsisdiv>
  65
  66   <refsect1>
  67     <title>Description</title>
  68
  69     <para>
  70       <command>lxc-start</command> runs the specified
  71       <replaceable>command</replaceable> inside the container
  72       specified by <replaceable>name</replaceable>.
  73     </para>
  74     <para>
  75       It will setup the container
  76       according to the configuration previously defined with the
  77       lxc-create command or with the configuration file parameter.
  78       If no configuration is
  79       defined, the default isolation is used.
  80     </para>
  81     <para>
  82       If no command is specified, <command>lxc-start</command> will
  83       use the command defined in lxc.init.cmd or if not set, the default
  84       <command>"/sbin/init"</command> command to run a system
  85       container.
  86     </para>
  87
  88   </refsect1>
  89
  90   <refsect1>
  91
  92     <title>Options</title>
  93
  94     <variablelist>
  95
  96       <varlistentry>
  97         <term>
  98           <option>-d, --daemon</option>
  99         </term>
 100         <listitem>
 101           <para>
 102             Run the container as a daemon. As the container has no
 103             more tty, if an error occurs nothing will be displayed,
 104             the log file can be used to check the error. (This is the default mode)
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term>
 111           <option>-F, --foreground</option>
 112         </term>
 113         <listitem>
 114           <para>
 115             Run the container in the foreground. In this mode, the container
 116             console will be attached to the current tty and signals will be routed
 117             directly to the container.
 118           </para>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term>
 124           <option>-p, --pidfile <replaceable>pid_file</replaceable></option>
 125         </term>
 126         <listitem>
 127           <para>
 128             Create a file with the process id.
 129           </para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term>
 135           <option>-f, --rcfile <replaceable>config_file</replaceable></option>
 136         </term>
 137         <listitem>
 138           <para>
 139             Specify the configuration file to configure the virtualization
 140             and isolation functionalities for the container.
 141           </para>
 142           <para>
 143            This configuration file if present will be used even if there is
 144            already a configuration file present in the previously created
 145            container (via lxc-create).
 146           </para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term>
 152           <option>-c,
 153           --console <replaceable>console_device</replaceable></option>
 154         </term>
 155         <listitem>
 156           <para>
 157             Specify a device to use for the container's console, for example
 158             /dev/tty8. If this option is not specified the current terminal
 159             will be used unless <option>-d</option> is specified.
 160           </para>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term>
 166           <option>-L,
 167           --console-log <replaceable>console_logfile</replaceable></option>
 168         </term>
 169         <listitem>
 170           <para>
 171             Specify a file to log the container's console output to.
 172           </para>
 173         </listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term>
 178           <option>-s, --define <replaceable>KEY=VAL</replaceable></option>
 179         </term>
 180         <listitem>
 181           <para>
 182             Assign value <replaceable>VAL</replaceable> to configuration
 183             variable <replaceable>KEY</replaceable>. This overrides any
 184             assignment done in <replaceable>config_file</replaceable>.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term>
 191           <option>-C,
 192           --close-all-fds</option>
 193         </term>
 194         <listitem>
 195           <para>
 196           If any file descriptors are inherited, close them.  If this option
 197           is not specified, then <command>lxc-start</command> will exit with
 198           failure instead. Note: <replaceable>--daemon</replaceable> implies
 199           <replaceable>--close-all-fds</replaceable>.
 200           </para>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term>
 206           <option>--share-net <replaceable>name|pid</replaceable></option>
 207         </term>
 208         <listitem>
 209           <para>
 210             Inherit a network namespace from
 211             a <replaceable>name</replaceable> container or
 212             a <replaceable>pid</replaceable>. The network namespace
 213             will continue to be managed by the original owner. The
 214             network configuration of the starting container is ignored
 215             and the up/down scripts won't be executed.
 216           </para>
 217         </listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term>
 222           <option>--share-ipc <replaceable>name|pid</replaceable></option>
 223         </term>
 224         <listitem>
 225           <para>
 226             Inherit an IPC namespace from
 227             a <replaceable>name</replaceable> container or
 228             a <replaceable>pid</replaceable>.
 229           </para>
 230         </listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term>
 235           <option>--share-uts <replaceable>name|pid</replaceable></option>
 236         </term>
 237         <listitem>
 238           <para>
 239             Inherit a UTS namespace from
 240             a <replaceable>name</replaceable> container or
 241             a <replaceable>pid</replaceable>. The starting LXC will
 242             not set the hostname, but the container OS may do it
 243             anyway.
 244           </para>
 245         </listitem>
 246       </varlistentry>
 247
 248     </variablelist>
 249
 250   </refsect1>
 251
 252   &commonoptions;
 253
 254   <refsect1>
 255     <title>Diagnostic</title>
 256
 257     <variablelist>
 258
 259       <varlistentry>
 260         <term>The container is busy</term>
 261         <listitem>
 262           <para>
 263             The specified container is already running an
 264             application. You should stop it before reuse this
 265             container or create a new one.
 266           </para>
 267         </listitem>
 268       </varlistentry>
 269
 270     </variablelist>
 271
 272   </refsect1>
 273
 274   &seealso;
 275
 276   <refsect1>
 277     <title>Author</title>
 278     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 279   </refsect1>
 280
 281 </refentry>
 282
 283 <!-- Keep this comment at the end of the file
 284 Local variables:
 285 mode: sgml
 286 sgml-omittag:t
 287 sgml-shorttag:t
 288 sgml-minimize-attributes:nil
 289 sgml-always-quote-attributes:t
 290 sgml-indent-step:2
 291 sgml-indent-data:t
 292 sgml-parent-document:nil
 293 sgml-default-dtd-file:nil
 294 sgml-exposed-tags:nil
 295 sgml-local-catalogs:nil
 296 sgml-local-ecat-files:nil
 297 End:
 298 -->