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

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

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

]>

<refentry>

<docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>

<refmeta>

<refentrytitle>lxc-attach</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>lxc-attach</refname>

<refpurpose>

start a process inside a running container.

</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>lxc-attach</command>

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

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

<arg choice="opt">-e</arg>

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

<arg choice="opt">-R</arg>

<arg choice="opt">-- <replaceable>command</replaceable></arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para>

<command>lxc-attach</command> runs the specified

<replaceable>command</replaceable> inside the container

specified by <replaceable>name</replaceable>. The container

has to be running already.

</para>

<para>

If no <replaceable>command</replaceable> is specified, the

current default shell of the user running

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

container and executed. This will fail if no such user exists

inside the container or the container does not have a working

nsswitch mechanism.

</para>

</refsect1>

<refsect1>

<title>Options</title>

<variablelist>

<varlistentry>

<term>

<option>-a, --arch <replaceable>arch</replaceable></option>

</term>

<listitem>

<para>

Specify the architecture which the kernel should appear to be

running as to the command executed. This option will accept the

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

container configuration files, see

<citerefentry>

<refentrytitle><filename>lxc.conf</filename></refentrytitle>

<manvolnum>5</manvolnum>

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

running container will be used.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>-e, --elevated-privileges</option>

</term>

<listitem>

<para>

Do not drop privileges when running

<replaceable>command</replaceable> inside the container. If

this option is specified, the new process will

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

and it will not drop its capabilities before executing.

</para>

<para>

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

container if the command starts subprocesses that remain active

after the main process that was attached is terminated. The

(re-)starting of daemons inside the container is problematic,

especially if the daemon starts a lot of subprocesses such as

<command>cron</command> or <command>sshd</command>.

<emphasis>Use with great care.</emphasis>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>-s, --namespaces <replaceable>namespaces</replaceable></option>

</term>

<listitem>

<para>

Specify the namespaces to attach to, as a pipe-separated list,

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

<replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,

<replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,

<replaceable>USER </replaceable> and

<replaceable>NETWORK</replaceable>. This allows one to change

the context of the process to e.g. the network namespace of the

container while retaining the other namespaces as those of the

host.

</para>

<para>

<emphasis>Important:</emphasis> This option implies

<option>-e</option>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>-R, --remount-sys-proc</option>

</term>

<listitem>

<para>

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

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

to remount <replaceable>/proc</replaceable> and

<replaceable>/sys</replaceable> to reflect the current other

namespace contexts.

</para>

<para>

Please see the <emphasis>Notes</emphasis> section for more

details.

</para>

<para>

This option will be ignored if one tries to attach to the

mount namespace anyway.

</para>

</listitem>

</varlistentry>

</variablelist>

</refsect1>

&commonoptions;

<refsect1>

<title>Examples</title>

<para>

To spawn a new shell running inside an existing container, use

<programlisting>

lxc-attach -n container

</programlisting>

</para>

<para>

To restart the cron service of a running Debian container, use

<programlisting>

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

</programlisting>

</para>

<para>

To deactivate the network link eth1 of a running container that

does not have the NET_ADMIN capability, use either the

<option>-e</option> option to use increased capabilities,

assuming the <command>ip</command> tool is installed:

<programlisting>

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

</programlisting>

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

tools installed on the host outside the container:

<programlisting>

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

</programlisting>

</para>

</refsect1>

<refsect1>

<title>Compatibility</title>

<para>

Attaching completely (including the pid and mount namespaces) to a

container requires a patched kernel, please see the lxc website for

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

used with an unpatched kernel.

</para>

<para>

Nevertheless, it will succeed on an unpatched kernel of version 3.0

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

namespaces that the process is to be attached to to one or more of

<replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>

and <replaceable>UTSNAME</replaceable>.

</para>

<para>

Attaching to user namespaces is currently completely unsupported

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

to do this once once future kernel versions implement this.

</para>

</refsect1>

<refsect1>

<title>Notes</title>

<para>

The Linux <replaceable>/proc</replaceable> and

<replaceable>/sys</replaceable> filesystems contain information

about some quantities that are affected by namespaces, such as

the directories named after process ids in

<replaceable>/proc</replaceable> or the network interface infromation

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

process mounting the pseudo-filesystems determines what information

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

accessing <replaceable>/proc</replaceable> or

<replaceable>/sys</replaceable>.

</para>

<para>

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

the pid namespace of a container, but not its mount namespace

(which will contain the <replaceable>/proc</replaceable> of the

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

will reflect that of the host and not the container. Analogously,

the same issue occurs when reading the contents of

<replaceable>/sys/class/net</replaceable> and attaching to just

the network namespace.

</para>

<para>

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

the option to remount <replaceable>/proc</replaceable> and

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

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

not to interfere with the host's actual filesystem, the mount

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

does) before this is done, esentially giving the process a new

mount namespace, which is identical to the hosts's mount namespace

except for the <replaceable>/proc</replaceable> and

<replaceable>/sys</replaceable> filesystems.

</para>

</refsect1>

<refsect1>

<title>Security</title>

<para>

The <option>-e</option> and <option>-s</option> options should

be used with care, as it may break the isolation of the containers

if used improperly.

</para>

</refsect1>

&seealso;

<refsect1>

<title>Author</title>

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

</refsect1>

</refentry>