52N/A

52N/A<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

52N/A

52N/A<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">

52N/A<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">

52N/A]>

52N/A

52N/A<refentry>

52N/A

52N/A <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>

52N/A

52N/A <refmeta>

52N/A <refentrytitle>lxc-attach</refentrytitle>

6N/A <manvolnum>1</manvolnum>

6N/A </refmeta>

6N/A

6N/A <refnamediv>

6N/A <refname>lxc-attach</refname>

15N/A

6N/A <refpurpose>

6N/A start a process inside a running container.

128N/A </refpurpose>

6N/A </refnamediv>

15N/A

6N/A <refsynopsisdiv>

6N/A <cmdsynopsis>

6N/A <command>lxc-attach</command>

6N/A <arg choice="req">-n <replaceable>name</replaceable></arg>

6N/A <arg choice="opt">-a <replaceable>arch</replaceable></arg>

6N/A <arg choice="opt">-e</arg>

6N/A <arg choice="opt">-s <replaceable>namespaces</replaceable></arg>

6N/A <arg choice="opt">-R</arg>

6N/A <arg choice="opt">-- <replaceable>command</replaceable></arg>

6N/A </cmdsynopsis>

6N/A </refsynopsisdiv>

15N/A

6N/A <refsect1>

6N/A <title>Description</title>

6N/A

6N/A <para>

6N/A <command>lxc-attach</command> runs the specified

6N/A <replaceable>command</replaceable> inside the container

6N/A specified by <replaceable>name</replaceable>. The container

6N/A has to be running already.

6N/A </para>

6N/A <para>

6N/A If no <replaceable>command</replaceable> is specified, the

128N/A current default shell of the user running

121N/A <command>lxc-attach</command> will be looked up inside the

128N/A container and executed. This will fail if no such user exists

6N/A inside the container or the container does not have a working

6N/A nsswitch mechanism.

15N/A </para>

15N/A

15N/A </refsect1>

15N/A

15N/A <refsect1>

15N/A

15N/A <title>Options</title>

15N/A

15N/A <variablelist>

15N/A

44N/A <varlistentry>

44N/A <term>

44N/A <option>-a, --arch <replaceable>arch</replaceable></option>

44N/A </term>

44N/A <listitem>

44N/A <para>

6N/A Specify the architecture which the kernel should appear to be

6N/A running as to the command executed. This option will accept the

6N/A same settings as the <option>lxc.arch</option> option in

6N/A container configuration files, see

6N/A <citerefentry>

6N/A <refentrytitle><filename>lxc.conf</filename></refentrytitle>

6N/A <manvolnum>5</manvolnum>

6N/A </citerefentry>. By default, the current archictecture of the

6N/A running container will be used.

6N/A </para>

6N/A </listitem>

6N/A </varlistentry>

6N/A

6N/A <varlistentry>

6N/A <term>

6N/A <option>-e, --elevated-privileges</option>

6N/A </term>

6N/A <listitem>

6N/A <para>

6N/A Do not drop privileges when running

6N/A <replaceable>command</replaceable> inside the container. If

6N/A this option is specified, the new process will

63N/A <emphasis>not</emphasis> be added to the container's cgroup(s)

63N/A and it will not drop its capabilities before executing.

63N/A </para>

63N/A <para>

63N/A <emphasis>Warning:</emphasis> This may leak privileges into the

63N/A container if the command starts subprocesses that remain active

63N/A after the main process that was attached is terminated. The

63N/A (re-)starting of daemons inside the container is problematic,

63N/A especially if the daemon starts a lot of subprocesses such as

63N/A <command>cron</command> or <command>sshd</command>.

63N/A <emphasis>Use with great care.</emphasis>

63N/A </para>

63N/A </listitem>

63N/A </varlistentry>

168N/A

63N/A <varlistentry>

63N/A <term>

63N/A <option>-s, --namespaces <replaceable>namespaces</replaceable></option>

63N/A </term>

63N/A <listitem>

63N/A <para>

63N/A Specify the namespaces to attach to, as a pipe-separated list,

63N/A e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are

63N/A <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,

63N/A <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,

63N/A <replaceable>USER </replaceable> and

63N/A <replaceable>NETWORK</replaceable>. This allows one to change

63N/A the context of the process to e.g. the network namespace of the

63N/A container while retaining the other namespaces as those of the

63N/A host.

63N/A </para>

63N/A <para>

63N/A <emphasis>Important:</emphasis> This option implies

63N/A <option>-e</option>.

63N/A </para>

63N/A </listitem>

63N/A </varlistentry>

131N/A

63N/A <varlistentry>

63N/A <term>

63N/A <option>-R, --remount-sys-proc</option>

6N/A </term>

26N/A <listitem>

6N/A <para>

44N/A When using <option>-s</option> and the mount namespace is not

44N/A included, this flag will cause <command>lxc-attach</command>

44N/A to remount <replaceable>/proc</replaceable> and

44N/A <replaceable>/sys</replaceable> to reflect the current other

44N/A namespace contexts.

44N/A </para>

44N/A <para>

44N/A Please see the <emphasis>Notes</emphasis> section for more

44N/A details.

44N/A </para>

44N/A <para>

44N/A This option will be ignored if one tries to attach to the

44N/A mount namespace anyway.

44N/A </para>

44N/A </listitem>

44N/A </varlistentry>

44N/A

44N/A </variablelist>

44N/A

44N/A </refsect1>

44N/A

44N/A &commonoptions;

44N/A

44N/A <refsect1>

44N/A <title>Examples</title>

44N/A <para>

44N/A To spawn a new shell running inside an existing container, use

44N/A <programlisting>

44N/A lxc-attach -n container

44N/A </programlisting>

44N/A </para>

44N/A <para>

44N/A To restart the cron service of a running Debian container, use

44N/A <programlisting>

6N/A lxc-attach -n container -- /etc/init.d/cron restart

6N/A </programlisting>

6N/A </para>

6N/A <para>

6N/A To deactivate the network link eth1 of a running container that

6N/A does not have the NET_ADMIN capability, use either the

6N/A <option>-e</option> option to use increased capabilities,

6N/A assuming the <command>ip</command> tool is installed:

6N/A <programlisting>

15N/A lxc-attach -n container -e -- /sbin/ip link delete eth1

15N/A </programlisting>

15N/A Or, alternatively, use the <option>-s</option> to use the

15N/A tools installed on the host outside the container:

15N/A <programlisting>

44N/A lxc-attach -n container -s NETWORK -- /sbin/ip link delete eth1

44N/A </programlisting>

44N/A </para>

44N/A </refsect1>

44N/A

44N/A <refsect1>

44N/A <title>Compatibility</title>

44N/A <para>

15N/A Attaching completely (including the pid and mount namespaces) to a

15N/A container requires a patched kernel, please see the lxc website for

15N/A details. <command>lxc-attach</command> will fail in that case if

15N/A used with an unpatched kernel.

15N/A </para>

15N/A <para>

15N/A Nevertheless, it will succeed on an unpatched kernel of version 3.0

15N/A or higher if the <option>-s</option> option is used to restrict the

15N/A namespaces that the process is to be attached to to one or more of

15N/A <replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>

15N/A and <replaceable>UTSNAME</replaceable>.

15N/A </para>

15N/A <para>

15N/A Attaching to user namespaces is currently completely unsupported

15N/A by the kernel. <command>lxc-attach</command> should however be able

15N/A to do this once once future kernel versions implement this.

15N/A </para>

15N/A </refsect1>

15N/A

15N/A <refsect1>

15N/A <title>Notes</title>

15N/A <para>

15N/A The Linux <replaceable>/proc</replaceable> and

15N/A <replaceable>/sys</replaceable> filesystems contain information

15N/A about some quantities that are affected by namespaces, such as

15N/A the directories named after process ids in

15N/A <replaceable>/proc</replaceable> or the network interface infromation

15N/A in <replaceable>/sys/class/net</replaceable>. The namespace of the

15N/A process mounting the pseudo-filesystems determines what information

15N/A is shown, <emphasis>not</emphasis> the namespace of the process

6N/A accessing <replaceable>/proc</replaceable> or

6N/A <replaceable>/sys</replaceable>.

6N/A </para>

6N/A <para>

6N/A If one uses the <option>-s</option> option to only attach to

6N/A the pid namespace of a container, but not its mount namespace

6N/A (which will contain the <replaceable>/proc</replaceable> of the

6N/A container and not the host), the contents of <option>/proc</option>

6N/A will reflect that of the host and not the container. Analogously,

6N/A the same issue occurs when reading the contents of

6N/A <replaceable>/sys/class/net</replaceable> and attaching to just

6N/A the network namespace.

6N/A </para>

6N/A <para>

6N/A To work around this problem, the <option>-R</option> flag provides

6N/A the option to remount <replaceable>/proc</replaceable> and

6N/A <replaceable>/sys</replaceable> in order for them to reflect the

6N/A network/pid namespace context of the attached process. In order

6N/A not to interfere with the host's actual filesystem, the mount

6N/A namespace will be unshared (like <command>lxc-unshare</command>

6N/A does) before this is done, esentially giving the process a new

6N/A mount namespace, which is identical to the hosts's mount namespace

6N/A except for the <replaceable>/proc</replaceable> and

121N/A <replaceable>/sys</replaceable> filesystems.

6N/A </para>

6N/A </refsect1>

6N/A

6N/A <refsect1>

6N/A <title>Security</title>

6N/A <para>

6N/A The <option>-e</option> and <option>-s</option> options should

6N/A be used with care, as it may break the isolation of the containers

6N/A if used improperly.

63N/A </para>

63N/A </refsect1>

63N/A

63N/A &seealso;

63N/A

63N/A <refsect1>

63N/A <title>Author</title>

63N/A <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>

63N/A </refsect1>

6N/A

63N/A</refentry>

164N/A

63N/A