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