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