1186N/A

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

1186N/A

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

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

1281N/A]>

1330N/A

1330N/A<refentry>

1330N/A

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

1330N/A

1330N/A <refmeta>

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

1186N/A <manvolnum>1</manvolnum>

1186N/A </refmeta>

1186N/A

1186N/A <refnamediv>

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

1281N/A

1281N/A <refpurpose>

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

1186N/A </refpurpose>

1186N/A </refnamediv>

1186N/A

1281N/A <refsynopsisdiv>

1281N/A <cmdsynopsis>

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

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

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

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

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

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

1186N/A <arg choice="opt">--keep-env</arg>

1281N/A <arg choice="opt">--clear-env</arg>

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

1281N/A </cmdsynopsis>

1186N/A </refsynopsisdiv>

1186N/A

1186N/A <refsect1>

1281N/A <title>Description</title>

1281N/A

1281N/A <para>

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

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

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

1186N/A has to be running already.

1186N/A </para>

1281N/A <para>

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

1281N/A current default shell of the user running

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

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

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

1281N/A nsswitch mechanism.

1281N/A </para>

1281N/A

1281N/A </refsect1>

1281N/A

1186N/A <refsect1>

1186N/A

1186N/A <title>Options</title>

1281N/A

1281N/A <variablelist>

1281N/A

1281N/A <varlistentry>

1281N/A <term>

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

1281N/A </term>

1281N/A <listitem>

1281N/A <para>

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

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

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

1281N/A container configuration files, see

1281N/A <citerefentry>

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

1281N/A <manvolnum>5</manvolnum>

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

1281N/A running container will be used.

1281N/A </para>

1186N/A </listitem>

1281N/A </varlistentry>

1186N/A

1281N/A <varlistentry>

1281N/A <term>

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

1281N/A </term>

1186N/A <listitem>

1281N/A <para>

1281N/A Do not drop privileges when running

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

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

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

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

1281N/A </para>

1186N/A <para>

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

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

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

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

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

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

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

1186N/A </para>

1186N/A </listitem>

1186N/A </varlistentry>

1186N/A

1186N/A <varlistentry>

1186N/A <term>

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

1186N/A </term>

1186N/A <listitem>

1186N/A <para>

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

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

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

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

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

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

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

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

1186N/A host.

1186N/A </para>

1186N/A <para>

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

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

849N/A </para>

1281N/A </listitem>

1186N/A </varlistentry>

1281N/A

1281N/A <varlistentry>

1186N/A <term>

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

1281N/A </term>

1186N/A <listitem>

1186N/A <para>

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

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

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

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

1281N/A namespace contexts.

1186N/A </para>

1281N/A <para>

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

1186N/A details.

1186N/A </para>

1186N/A <para>

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

1186N/A mount namespace anyway.

1186N/A </para>

1278N/A </listitem>

1278N/A </varlistentry>

1278N/A

1186N/A <varlistentry>

1281N/A <term>

1186N/A <option>--keep-env</option>

1186N/A </term>

1281N/A <listitem>

1186N/A <para>

1186N/A Keep the current environment for attached programs. This is

1186N/A the current default behaviour (as of version 0.9), but is

1186N/A is likely to change in the future, since this may leak

1186N/A undesirable information into the container. If you rely on

1186N/A the environment being available for the attached program,

1186N/A please use this option to be future-proof. In addition to

1186N/A current environment variables, container=lxc will be set.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>

<option>--clear-env</option>

</term>

<listitem>

<para>

Clear the environment before attaching, so no undesired

environment variables leak into the container. The variable

container=lxc will be the only environment with which the

attached program starts.

</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>