mirror of
https://git.proxmox.com/git/mirror_lxc
synced 2025-06-01 21:53:40 +00:00
aa8d013ec5
The package 'docbook-tools' [1] required to format Docbook 3.0 into man pages has been obsoleted a long time ago and can no longer be downloaded from its former homepage. Recent versions of that package -- now called 'docbook2X' --, cannot deal with that old markup format anymore (and don't support the '-w all' command line switch either). To remedy these issues, all SGML files have been updated to Docbook 4.5 so that recent versions of docbook2man can process them. [1] http://sources.redhat.com/docbook-tools/ [2] http://docbook2x.sourceforge.net/ Signed-off-by: Peter Simons <simons@cryp.to> Acked-by: Stéphane Graber <stgraber@ubuntu.com>
306 lines
10 KiB
Plaintext
306 lines
10 KiB
Plaintext
<!--
|
|
|
|
lxc: linux Container library
|
|
|
|
(C) Copyright IBM Corp. 2007, 2008
|
|
|
|
Authors:
|
|
Daniel Lezcano <dlezcano at fr.ibm.com>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
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
|
|
|
|
-->
|
|
|
|
<!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>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:2
|
|
sgml-indent-data:t
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:nil
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|