doc/lxc-attach.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
  27 <!DOCTYPE refentry PUBLIC @docdtd@ [
  28
  29 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
  30 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  31 ]>
  32
  33 <refentry>
  34
  35   <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  36
  37   <refmeta>
  38     <refentrytitle>lxc-attach</refentrytitle>
  39     <manvolnum>1</manvolnum>
  40   </refmeta>
  41
  42   <refnamediv>
  43     <refname>lxc-attach</refname>
  44
  45     <refpurpose>
  46       start a process inside a running container.
  47     </refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <cmdsynopsis>
  52       <command>lxc-attach</command>
  53       <arg choice="req">-n <replaceable>name</replaceable></arg>
  54       <arg choice="opt">-a <replaceable>arch</replaceable></arg>
  55       <arg choice="opt">-e</arg>
  56       <arg choice="opt">-s <replaceable>namespaces</replaceable></arg>
  57       <arg choice="opt">-R</arg>
  58       <arg choice="opt">--keep-env</arg>
  59       <arg choice="opt">--clear-env</arg>
  60       <arg choice="opt">-- <replaceable>command</replaceable></arg>
  61     </cmdsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para>
  68       <command>lxc-attach</command> runs the specified
  69       <replaceable>command</replaceable> inside the container
  70       specified by <replaceable>name</replaceable>. The container
  71       has to be running already.
  72     </para>
  73     <para>
  74       If no <replaceable>command</replaceable> is specified, the
  75       current default shell of the user running
  76       <command>lxc-attach</command> will be looked up inside the
  77       container and executed. This will fail if no such user exists
  78       inside the container or the container does not have a working
  79       nsswitch mechanism.
  80     </para>
  81
  82   </refsect1>
  83
  84   <refsect1>
  85
  86     <title>Options</title>
  87
  88     <variablelist>
  89
  90       <varlistentry>
  91         <term>
  92           <option>-a, --arch <replaceable>arch</replaceable></option>
  93         </term>
  94         <listitem>
  95           <para>
  96             Specify the architecture which the kernel should appear to be
  97             running as to the command executed. This option will accept the
  98             same settings as the <option>lxc.arch</option> option in
  99             container configuration files, see
 100             <citerefentry>
 101               <refentrytitle><filename>lxc.conf</filename></refentrytitle>
 102               <manvolnum>5</manvolnum>
 103             </citerefentry>. By default, the current archictecture of the
 104             running container will be used.
 105           </para>
 106         </listitem>
 107       </varlistentry>
 108
 109       <varlistentry>
 110         <term>
 111           <option>
 112       -e, --elevated-privileges <replaceable>privileges</replaceable>
 113     </option>
 114         </term>
 115         <listitem>
 116           <para>
 117             Do not drop privileges when running
 118             <replaceable>command</replaceable> inside the container. If
 119             this option is specified, the new process will
 120             <emphasis>not</emphasis> be added to the container's cgroup(s)
 121             and it will not drop its capabilities before executing.
 122           </para>
 123     <para>
 124       You may specify privileges, in case you do not want to elevate all of
 125       them, as a pipe-separated list, e.g.
 126       <replaceable>CGROUP|LSM</replaceable>. Allowed values are
 127       <replaceable>CGROUP</replaceable>, <replaceable>CAP</replaceable> and
 128       <replaceable>LSM</replaceable> representing cgroup, capabilities and
 129       restriction privileges respectively.
 130     </para>
 131           <para>
 132             <emphasis>Warning:</emphasis> This may leak privileges into the
 133             container if the command starts subprocesses that remain active
 134             after the main process that was attached is terminated. The
 135             (re-)starting of daemons inside the container is problematic,
 136             especially if the daemon starts a lot of subprocesses such as
 137             <command>cron</command> or <command>sshd</command>.
 138             <emphasis>Use with great care.</emphasis>
 139           </para>
 140         </listitem>
 141       </varlistentry>
 142
 143       <varlistentry>
 144         <term>
 145           <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
 146         </term>
 147         <listitem>
 148           <para>
 149             Specify the namespaces to attach to, as a pipe-separated list,
 150             e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
 151             <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
 152             <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
 153             <replaceable>USER </replaceable> and
 154             <replaceable>NETWORK</replaceable>. This allows one to change
 155             the context of the process to e.g. the network namespace of the
 156             container while retaining the other namespaces as those of the
 157             host.
 158           </para>
 159           <para>
 160             <emphasis>Important:</emphasis> This option implies
 161             <option>-e</option>.
 162           </para>
 163         </listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term>
 168           <option>-R, --remount-sys-proc</option>
 169         </term>
 170         <listitem>
 171           <para>
 172             When using <option>-s</option> and the mount namespace is not
 173             included, this flag will cause <command>lxc-attach</command>
 174             to remount <replaceable>/proc</replaceable> and
 175             <replaceable>/sys</replaceable> to reflect the current other
 176             namespace contexts.
 177           </para>
 178           <para>
 179             Please see the <emphasis>Notes</emphasis> section for more
 180             details.
 181           </para>
 182           <para>
 183             This option will be ignored if one tries to attach to the
 184             mount namespace anyway.
 185           </para>
 186         </listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term>
 191           <option>--keep-env</option>
 192         </term>
 193         <listitem>
 194           <para>
 195             Keep the current environment for attached programs. This is
 196             the current default behaviour (as of version 0.9), but is
 197             is likely to change in the future, since this may leak
 198             undesirable information into the container. If you rely on
 199             the environment being available for the attached program,
 200             please use this option to be future-proof. In addition to
 201             current environment variables, container=lxc will be set.
 202           </para>
 203         </listitem>
 204       </varlistentry>
 205
 206       <varlistentry>
 207         <term>
 208           <option>--clear-env</option>
 209         </term>
 210         <listitem>
 211           <para>
 212             Clear the environment before attaching, so no undesired
 213             environment variables leak into the container. The variable
 214             container=lxc will be the only environment with which the
 215             attached program starts.
 216           </para>
 217         </listitem>
 218       </varlistentry>
 219
 220      </variablelist>
 221
 222   </refsect1>
 223
 224   &commonoptions;
 225
 226   <refsect1>
 227     <title>Examples</title>
 228       <para>
 229         To spawn a new shell running inside an existing container, use
 230         <programlisting>
 231           lxc-attach -n container
 232         </programlisting>
 233       </para>
 234       <para>
 235         To restart the cron service of a running Debian container, use
 236         <programlisting>
 237           lxc-attach -n container -- /etc/init.d/cron restart
 238         </programlisting>
 239       </para>
 240       <para>
 241         To deactivate the network link eth1 of a running container that
 242         does not have the NET_ADMIN capability, use either the
 243         <option>-e</option> option to use increased capabilities,
 244         assuming the <command>ip</command> tool is installed:
 245         <programlisting>
 246           lxc-attach -n container -e -- /sbin/ip link delete eth1
 247         </programlisting>
 248         Or, alternatively, use the <option>-s</option> to use the
 249         tools installed on the host outside the container:
 250         <programlisting>
 251           lxc-attach -n container -s NETWORK -- /sbin/ip link delete eth1
 252         </programlisting>
 253       </para>
 254   </refsect1>
 255
 256   <refsect1>
 257     <title>Compatibility</title>
 258     <para>
 259       Attaching completely (including the pid and mount namespaces) to a
 260       container requires a kernel of version 3.8 or higher, or a
 261       patched kernel, please see the lxc website for
 262       details. <command>lxc-attach</command> will fail in that case if
 263       used with an unpatched kernel of version 3.7 and prior.
 264     </para>
 265     <para>
 266       Nevertheless, it will succeed on an unpatched kernel of version 3.0
 267       or higher if the <option>-s</option> option is used to restrict the
 268       namespaces that the process is to be attached to to one or more of
 269       <replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>
 270       and <replaceable>UTSNAME</replaceable>.
 271     </para>
 272     <para>
 273       Attaching to user namespaces is supported by kernel 3.8 or higher
 274       with enabling user namespace.
 275     </para>
 276   </refsect1>
 277
 278   <refsect1>
 279     <title>Notes</title>
 280     <para>
 281       The Linux <replaceable>/proc</replaceable> and
 282       <replaceable>/sys</replaceable> filesystems contain information
 283       about some quantities that are affected by namespaces, such as
 284       the directories named after process ids in
 285       <replaceable>/proc</replaceable> or the network interface information
 286       in <replaceable>/sys/class/net</replaceable>. The namespace of the
 287       process mounting the pseudo-filesystems determines what information
 288       is shown, <emphasis>not</emphasis> the namespace of the process
 289       accessing <replaceable>/proc</replaceable> or
 290       <replaceable>/sys</replaceable>.
 291     </para>
 292     <para>
 293       If one uses the <option>-s</option> option to only attach to
 294       the pid namespace of a container, but not its mount namespace
 295       (which will contain the <replaceable>/proc</replaceable> of the
 296       container and not the host), the contents of <option>/proc</option>
 297       will reflect that of the host and not the container. Analogously,
 298       the same issue occurs when reading the contents of
 299       <replaceable>/sys/class/net</replaceable> and attaching to just
 300       the network namespace.
 301     </para>
 302     <para>
 303       To work around this problem, the <option>-R</option> flag provides
 304       the option to remount <replaceable>/proc</replaceable> and
 305       <replaceable>/sys</replaceable> in order for them to reflect the
 306       network/pid namespace context of the attached process. In order
 307       not to interfere with the host's actual filesystem, the mount
 308       namespace will be unshared (like <command>lxc-unshare</command>
 309       does) before this is done, esentially giving the process a new
 310       mount namespace, which is identical to the hosts's mount namespace
 311       except for the <replaceable>/proc</replaceable> and
 312       <replaceable>/sys</replaceable> filesystems.
 313     </para>
 314   </refsect1>
 315
 316   <refsect1>
 317     <title>Security</title>
 318     <para>
 319       The <option>-e</option> and <option>-s</option> options should
 320       be used with care, as it may break the isolation of the containers
 321       if used improperly.
 322     </para>
 323   </refsect1>
 324
 325   &seealso;
 326
 327   <refsect1>
 328     <title>Author</title>
 329     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 330   </refsect1>
 331
 332 </refentry>
 333
 334 <!-- Keep this comment at the end of the file
 335 Local variables:
 336 mode: sgml
 337 sgml-omittag:t
 338 sgml-shorttag:t
 339 sgml-minimize-attributes:nil
 340 sgml-always-quote-attributes:t
 341 sgml-indent-step:2
 342 sgml-indent-data:t
 343 sgml-parent-document:nil
 344 sgml-default-dtd-file:nil
 345 sgml-exposed-tags:nil
 346 sgml-local-catalogs:nil
 347 sgml-local-ecat-files:nil
 348 End:
 349 -->