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