doc/lxc-execute.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-execute</refentrytitle>
  38     <manvolnum>1</manvolnum>
  39   </refmeta>
  40
  41   <refnamediv>
  42     <refname>lxc-execute</refname>
  43
  44     <refpurpose>
  45       run an application inside a container.
  46     </refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <cmdsynopsis>
  51       <command>lxc-execute</command>
  52       <arg choice="req">-n <replaceable>name</replaceable></arg>
  53       <arg choice="opt">-d</arg>
  54       <arg choice="opt">-f <replaceable>config_file</replaceable></arg>
  55       <arg choice="opt">-s KEY=VAL</arg>
  56       <arg choice="opt">-- <replaceable>command</replaceable></arg>
  57     </cmdsynopsis>
  58   </refsynopsisdiv>
  59
  60   <refsect1>
  61     <title>Description</title>
  62
  63     <para>
  64       <command>lxc-execute</command> runs the specified
  65       <replaceable>command</replaceable> inside the container
  66       specified by <replaceable>name</replaceable>.
  67     </para>
  68     <para>
  69       It will setup the container
  70       according to the configuration previously defined with the
  71       lxc-create command or with the configuration file parameter.
  72       If no configuration is
  73       defined, the default isolation is used.
  74     </para>
  75     <para>
  76       This command is mainly used when you want to quickly launch an
  77       application in an isolated environment.
  78     </para>
  79     <para>
  80       <command>lxc-execute</command> command will run the
  81       specified command into the container via an intermediate
  82       process, <command>lxc-init</command>.
  83       This lxc-init after launching  the specified command,
  84       will wait for its end and all other reparented processes.
  85       (to support daemons in the container).
  86       In other words, in the
  87       container, <command>lxc-init</command> has the pid 1 and the
  88       first process of the application has the pid 2.
  89      </para>
  90      <para>
  91       The above <command>lxc-init</command> is designed to forward received
  92       signals to the started command.
  93      </para>
  94   </refsect1>
  95
  96   <refsect1>
  97     <title>Options</title>
  98     <variablelist>
  99
 100       <varlistentry>
 101         <term>
 102           <option>-f, --rcfile <replaceable>config_file</replaceable></option>
 103         </term>
 104         <listitem>
 105           <para>
 106             Specify the configuration file to configure the virtualization
 107             and isolation functionalities for the container.
 108           </para>
 109           <para>
 110            This configuration file if present will be used even if there is
 111            already a configuration file present in the previously created
 112            container (via lxc-create).
 113           </para>
 114         </listitem>
 115       </varlistentry>
 116       <varlistentry>
 117         <term>
 118           <option>-s, --define <replaceable>KEY=VAL</replaceable></option>
 119         </term>
 120         <listitem>
 121           <para>
 122             Assign value <replaceable>VAL</replaceable> to configuration
 123             variable <replaceable>KEY</replaceable>. This overrides any
 124             assignment done in <replaceable>config_file</replaceable>.
 125           </para>
 126         </listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term>
 131           <option>-d, --daemon</option>
 132         </term>
 133         <listitem>
 134           <para>
 135             Run the container as a daemon. As the container has no
 136             more tty, if an error occurs nothing will be displayed,
 137             the log file can be used to check the error.
 138           </para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--</option></term>
 144         <listitem>
 145           <para>
 146             Signal the end of options and disables further option
 147             processing. Any arguments after the -- are treated as
 148             arguments to <replaceable>command</replaceable>.
 149           </para>
 150           <para>
 151             This option is useful when you want specify options
 152             to <replaceable>command</replaceable> and don't want
 153             <command>lxc-execute</command> to interpret them.
 154           </para>
 155         </listitem>
 156       </varlistentry>
 157
 158     </variablelist>
 159
 160   </refsect1>
 161
 162   &commonoptions;
 163
 164   <refsect1>
 165     <title>Diagnostic</title>
 166
 167     <variablelist>
 168
 169       <varlistentry>
 170         <term>The container is busy</term>
 171         <listitem>
 172           <para>
 173             The specified container is already running an
 174             application. You should stop it before reuse this
 175             container or create a new one.
 176           </para>
 177         </listitem>
 178       </varlistentry>
 179
 180     </variablelist>
 181
 182   </refsect1>
 183
 184   &seealso;
 185
 186   <refsect1>
 187     <title>Author</title>
 188     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 189   </refsect1>
 190
 191 </refentry>
 192
 193 <!-- Keep this comment at the end of the file
 194 Local variables:
 195 mode: sgml
 196 sgml-omittag:t
 197 sgml-shorttag:t
 198 sgml-minimize-attributes:nil
 199 sgml-always-quote-attributes:t
 200 sgml-indent-step:2
 201 sgml-indent-data:t
 202 sgml-parent-document:nil
 203 sgml-default-dtd-file:nil
 204 sgml-exposed-tags:nil
 205 sgml-local-catalogs:nil
 206 sgml-local-ecat-files:nil
 207 End:
 208 -->