lxc-attach.sgml.in revision 4d69b2939ce09fbe624636dc01734a542e050ef9
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulingerlxc: linux Container library
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger(C) Copyright IBM Corp. 2007, 2008
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerDaniel Lezcano <daniel.lezcano at free.fr>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerThis library is free software; you can redistribute it and/or
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulingermodify it under the terms of the GNU Lesser General Public
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerLicense as published by the Free Software Foundation; either
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulingerversion 2.1 of the License, or (at your option) any later version.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerThis library is distributed in the hope that it will be useful,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulingerbut WITHOUT ANY WARRANTY; without even the implied warranty of
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerLesser General Public License for more details.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerYou should have received a copy of the GNU Lesser General Public
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerLicense along with this library; if not, write to the Free Software
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof TulingerFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger start a process inside a running container.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </refpurpose>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </refnamediv>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <refsynopsisdiv>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <cmdsynopsis>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <arg choice="req">-n <replaceable>name</replaceable></arg>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <arg choice="opt">-a <replaceable>arch</replaceable></arg>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <arg choice="opt">-s <replaceable>namespaces</replaceable></arg>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <arg choice="opt">-- <replaceable>command</replaceable></arg>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </cmdsynopsis>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </refsynopsisdiv>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <command>lxc-attach</command> runs the specified
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>command</replaceable> inside the container
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger specified by <replaceable>name</replaceable>. The container
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger has to be running already.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger If no <replaceable>command</replaceable> is specified, the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger current default shell of the user running
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <command>lxc-attach</command> will be looked up inside the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger container and executed. This will fail if no such user exists
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger inside the container or the container does not have a working
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger nsswitch mechanism.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <variablelist>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <option>-a, --arch <replaceable>arch</replaceable></option>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger Specify the architecture which the kernel should appear to be
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger running as to the command executed. This option will accept the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger same settings as the <option>lxc.arch</option> option in
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger container configuration files, see
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <citerefentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <refentrytitle><filename>lxc.conf</filename></refentrytitle>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </citerefentry>. By default, the current archictecture of the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger running container will be used.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger -e, --elevated-privileges <replaceable>privileges</replaceable>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger Do not drop privileges when running
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>command</replaceable> inside the container. If
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger this option is specified, the new process will
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <emphasis>not</emphasis> be added to the container's cgroup(s)
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger and it will not drop its capabilities before executing.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger You may specify privileges, in case you do not want to elevate all of
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger them, as a pipe-separated list, e.g.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>CGROUP|LSM</replaceable>. Allowed values are
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>CGROUP</replaceable>, <replaceable>CAP</replaceable> and
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>LSM</replaceable> representing cgroup, capabilities and
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger restriction privileges respectively.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <emphasis>Warning:</emphasis> This may leak privileges into the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger container if the command starts subprocesses that remain active
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger after the main process that was attached is terminated. The
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger (re-)starting of daemons inside the container is problematic,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger especially if the daemon starts a lot of subprocesses such as
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <command>cron</command> or <command>sshd</command>.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger Specify the namespaces to attach to, as a pipe-separated list,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>NETWORK</replaceable>. This allows one to change
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger the context of the process to e.g. the network namespace of the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger container while retaining the other namespaces as those of the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <emphasis>Important:</emphasis> This option implies
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger When using <option>-s</option> and the mount namespace is not
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger included, this flag will cause <command>lxc-attach</command>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger to remount <replaceable>/proc</replaceable> and
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <replaceable>/sys</replaceable> to reflect the current other
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger namespace contexts.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger Please see the <emphasis>Notes</emphasis> section for more
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger This option will be ignored if one tries to attach to the
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger mount namespace anyway.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger <varlistentry>
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger Keep the current environment for attached programs. This is
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger the current default behaviour (as of version 0.9), but is
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger is likely to change in the future, since this may leak
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger undesirable information into the container. If you rely on
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger the environment being available for the attached program,
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger please use this option to be future-proof. In addition to
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger current environment variables, container=lxc will be set.
d470e59c0405a31b7e5f194bd9b705e91b12bf0aKryštof Tulinger </varlistentry>