You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+
+<!DOCTYPE refentry PUBLIC @docdtd@ [
<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
<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="req">-n, --name <replaceable>name</replaceable></arg>
+ <arg choice="opt">-f, --rcfile <replaceable>config_file</replaceable></arg>
+ <arg choice="opt">-a, --arch <replaceable>arch</replaceable></arg>
+ <arg choice="opt">-e, --elevated-privileges <replaceable>privileges</replaceable></arg>
+ <arg choice="opt">-s, --namespaces <replaceable>namespaces</replaceable></arg>
+ <arg choice="opt">-R, --remount-sys-proc</arg>
<arg choice="opt">--keep-env</arg>
<arg choice="opt">--clear-env</arg>
+ <arg choice="opt">-v, --set-var <replaceable>variable</replaceable></arg>
+ <arg choice="opt">--keep-var <replaceable>variable</replaceable></arg>
+ <arg choice="opt">-u, --uid <replaceable>uid</replaceable></arg>
+ <arg choice="opt">-g, --gid <replaceable>gid</replaceable></arg>
<arg choice="opt">-- <replaceable>command</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
inside the container or the container does not have a working
nsswitch mechanism.
</para>
+ <para>
+ Previous versions of <command>lxc-attach</command> simply attached to the
+ specified namespaces of a container and ran a shell or the specified command
+ without first allocating a pseudo terminal. This made them vulnerable to
+ input faking via a TIOCSTI <command>ioctl</command> call after switching
+ between userspace execution contexts with different privilege levels. Newer
+ versions of <command>lxc-attach</command> will try to allocate a pseudo
+ terminal file descriptor pair on the host and attach any standard file
+ descriptors which refer to a terminal to the container side of the pseudo
+ terminal before executing a shell or command. Note, that if none of the
+ standard file descriptors refer to a terminal <command>lxc-attach</command>
+ will not try to allocate a pseudo terminal. Instead it will simply attach
+ to the containers namespaces and run a shell or the specified command.
+ </para>
</refsect1>
<variablelist>
+ <varlistentry>
+ <term>
+ <option>-f, --rcfile <replaceable>config_file</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Specify the configuration file to configure the virtualization
+ and isolation functionalities for the container.
+ </para>
+ <para>
+ This configuration file if present will be used even if there is
+ already a configuration file present in the previously created
+ container (via lxc-create).
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<option>-a, --arch <replaceable>arch</replaceable></option>
<citerefentry>
<refentrytitle><filename>lxc.conf</filename></refentrytitle>
<manvolnum>5</manvolnum>
- </citerefentry>. By default, the current archictecture of the
+ </citerefentry>. By default, the current architecture of the
running container will be used.
</para>
</listitem>
<varlistentry>
<term>
- <option>-e, --elevated-privileges</option>
+ <option>
+ -e, --elevated-privileges <replaceable>privileges</replaceable>
+ </option>
</term>
<listitem>
<para>
<emphasis>not</emphasis> be added to the container's cgroup(s)
and it will not drop its capabilities before executing.
</para>
+ <para>
+ You may specify privileges, in case you do not want to elevate all of
+ them, as a pipe-separated list, e.g.
+ <replaceable>CGROUP|LSM</replaceable>. Allowed values are
+ <replaceable>CGROUP</replaceable>, <replaceable>CAP</replaceable> and
+ <replaceable>LSM</replaceable> representing cgroup, capabilities and
+ restriction privileges respectively. (The pipe symbol needs to be escaped,
+ e.g. <replaceable>CGROUP\|LSM</replaceable> or quoted, e.g.
+ <replaceable>"CGROUP|LSM"</replaceable>.)
+ </para>
<para>
<emphasis>Warning:</emphasis> This may leak privileges into the
container if the command starts subprocesses that remain active
<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.
+ host. (The pipe symbol needs to be escaped, e.g.
+ <replaceable>MOUNT\|PID</replaceable> or quoted, e.g.
+ <replaceable>"MOUNT|PID"</replaceable>.)
</para>
<para>
<emphasis>Important:</emphasis> This option implies
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>-v, --set-var <replaceable>variable</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Set an additional environment variable that is seen by the
+ attached program in the container. It is specified in the
+ form of "VAR=VALUE", and can be specified multiple times.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--keep-var <replaceable>variable</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Keep a specified environment variable. It can only be
+ specified in conjunction
+ with <replaceable>--clear-env</replaceable>, and can be
+ specified multiple times.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--u, --uid <replaceable>uid</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Executes the <replaceable>command</replaceable> with user ID
+ <replaceable>uid</replaceable> inside the container.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--g, --gid <replaceable>gid</replaceable></option>
+ </term>
+ <listitem>
+ <para>
+ Executes the <replaceable>command</replaceable> with group ID
+ <replaceable>gid</replaceable> inside the container.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</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
+ container requires a kernel of version 3.8 or higher, or 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.
+ used with an unpatched kernel of version 3.7 and prior.
</para>
<para>
Nevertheless, it will succeed on an unpatched kernel of version 3.0
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.
+ Attaching to user namespaces is supported by kernel 3.8 or higher
+ with enabling user namespace.
</para>
</refsect1>
<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
+ <replaceable>/proc</replaceable> or the network interface information
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
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
+ does) before this is done, essentially 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>
+ <para>
+ Previous versions of <command>lxc-attach</command> suffered a bug whereby
+ a user could attach to a containers namespace without being placed in a
+ writeable cgroup for some critical subsystems. Newer versions of
+ <command>lxc-attach</command> will check whether a user is in a writeable
+ cgroup for those critical subsystems. <command>lxc-attach</command> might
+ thus fail unexpectedly for some users (E.g. on systems where an
+ unprivileged user is not placed in a writeable cgroup in critical
+ subsystems on login.). However, this behavior is correct and more secure.
+ </para>
</refsect1>
<refsect1>
projects / mirror_lxc.git / blobdiff