3
lxc: linux Container library
5
(C) Copyright IBM Corp. 2007, 2008
8
Daniel Lezcano <dlezcano at fr.ibm.com>
10
This library is free software; you can redistribute it and/or
11
modify it under the terms of the GNU Lesser General Public
12
License as published by the Free Software Foundation; either
13
version 2.1 of the License, or (at your option) any later version.
15
This library is distributed in the hope that it will be useful,
16
but WITHOUT ANY WARRANTY; without even the implied warranty of
17
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18
Lesser General Public License for more details.
20
You should have received a copy of the GNU Lesser General Public
21
License along with this library; if not, write to the Free Software
22
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
26
<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
28
<!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
29
<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
34
<docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
37
<refentrytitle>lxc-attach</refentrytitle>
38
<manvolnum>1</manvolnum>
42
<refname>lxc-attach</refname>
45
start a process inside a running container.
50
<cmdsynopsis><command>lxc-attach <replaceable>-n
51
name</replaceable> <optional>-a
52
arch</optional> <optional>-e</optional> <optional>-s
54
<optional>-- command</optional></command></cmdsynopsis>
58
<title>Description</title>
61
<command>lxc-attach</command> runs the specified
62
<replaceable>command</replaceable> inside the container
63
specified by <replaceable>name</replaceable>. The container
64
has to be running already.
67
If no <replaceable>command</replaceable> is specified, the
68
current default shell of the user running
69
<command>lxc-attach</command> will be looked up inside the
70
container and executed. This will fail if no such user exists
71
inside the container or the container does not have a working
79
<title>Options</title>
85
<option>-a, --arch <replaceable>arch</replaceable></option>
89
Specify the architecture which the kernel should appear to be
90
running as to the command executed. This option will accept the
91
same settings as the <option>lxc.arch</option> option in
92
container configuration files, see
94
<refentrytitle><filename>lxc.conf</filename></refentrytitle>
95
<manvolnum>5</manvolnum>
96
</citerefentry>. By default, the current archictecture of the
97
running container will be used.
104
<option>-e, --elevated-privileges</option>
108
Do not drop privileges when running
109
<replaceable>command</replaceable> inside the container. If
110
this option is specified, the new process will
111
<emphasis>not</emphasis> be added to the container's cgroup(s)
112
and it will not drop its capabilities before executing.
115
<emphasis>Warning:</emphasis> This may leak privileges into the
116
container if the command starts subprocesses that remain active
117
after the main process that was attached is terminated. The
118
(re-)starting of daemons inside the container is problematic,
119
especially if the daemon starts a lot of subprocesses such as
120
<command>cron</command> or <command>sshd</command>.
121
<emphasis>Use with great care.</emphasis>
128
<option>-s, --namespaces <replaceable>namespaces</replaceable></option>
132
Specify the namespaces to attach to, as a pipe-separated liste,
133
e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
134
<replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
135
<replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
136
<replaceable>USER </replaceable> and
137
<replaceable>NETWORK</replaceable>. This allows one to change
138
the context of the process to e.g. the network namespace of the
139
container while retaining the other namespaces as those of the
143
<emphasis>Important:</emphasis> This option implies
156
<title>Examples</title>
158
To spawn a new shell running inside an existing container, use
160
lxc-attach -n container
164
To restart the cron service of a running Debian container, use
166
lxc-attach -n container -- /etc/init.d/cron restart
170
To deactivate the network link eth1 of a running container that
171
does not have the NET_ADMIN capability, use either the
172
<option>-e</option> option to use increased capabilities,
173
assuming the <command>ip</command> tool is installed:
175
lxc-attach -n container -e -- /sbin/ip link delete eth1
177
Or, alternatively, use the <option>-s</option> to use the
178
tools installed on the host outside the container:
180
lxc-attach -n container -s NETWORK -- /sbin/ip link delete eth1
186
<title>Compatibility</title>
188
Attaching completely (including the pid and mount namespaces) to a
189
container requires a patched kernel, please see the lxc website for
190
details. <command>lxc-attach</command> will fail in that case if
191
used with an unpatched kernel.
194
Nevertheless, it will succeed on an unpatched kernel of version 3.0
195
or higher if the <option>-s</option> option is used to restrict the
196
namespaces that the process is to be attached to to one or more of
197
<replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>
198
and <replaceable>UTSNAME</replaceable>.
201
Attaching to user namespaces is currently completely unsupported
202
by the kernel. User namespaces will be skipped (but will not cause
203
<command>lxc-attach</command> to fail) unless used with a future
204
version of the kernel that supports this.
211
The Linux <replaceable>/proc</replaceable> and
212
<replaceable>/sys</replaceable> filesystems contain information
213
about some quantities that are affected by namespaces, such as
214
the directories named after process ids in
215
<replaceable>/proc</replaceable> or the network interface infromation
216
in <replaceable>/sys/class/net</replaceable>. The namespace of the
217
process mounting the pseudo-filesystems determines what information
218
is shown, <emphasis>not</emphasis> the namespace of the process
219
accessing <replaceable>/proc</replaceable> or
220
<replaceable>/sys</replaceable>.
223
If one uses the <option>-s</option> option to only attach to
224
the pid namespace of a container, but not its mount namespace
225
(which will contain the <replaceable>/proc</replaceable> of the
226
container and not the host), the contents of <option>/proc</option>
227
will reflect that of the host and not the container. Analogously,
228
the same issue occurs when reading the contents of
229
<replaceable>/sys/class/net</replaceable> and attaching to just
230
the network namespace.
233
A workaround is to use <command>lxc-unshare</command> to unshare
234
the mount namespace after using <command>lxc-attach</command> with
235
<replaceable>-s PID</replaceable> and/or <replaceable>-s
236
NETWORK</replaceable> and then unmount and then mount again both
237
pseudo-filesystems within that new mount namespace, before
238
executing a program/script that relies on this information to be
244
<title>Security</title>
246
The <option>-e</option> and <option>-s</option> options should
247
be used with care, as it may break the isolation of the containers
255
<title>Author</title>
256
<para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
261
<!-- Keep this comment at the end of the file
266
sgml-minimize-attributes:nil
267
sgml-always-quote-attributes:t
270
sgml-parent-document:nil
271
sgml-default-dtd-file:nil
272
sgml-exposed-tags:nil
273
sgml-local-catalogs:nil
274
sgml-local-ecat-files:nil
added
removed
.pc/0105-lxc-attach-add-R-option/doc/lxc-attach.sgml.in
