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