3 lxc: linux Container library
5 (C) Copyright IBM Corp. 2007, 2008
8 Daniel Lezcano <daniel.lezcano at free.fr>
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 <!DOCTYPE refentry PUBLIC @docdtd@ [
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.
51 <command>lxc-attach</command>
52 <arg choice="req">-n <replaceable>name</replaceable></arg>
53 <arg choice="opt">-a <replaceable>arch</replaceable></arg>
54 <arg choice="opt">-e</arg>
55 <arg choice="opt">-s <replaceable>namespaces</replaceable></arg>
56 <arg choice="opt">-R</arg>
57 <arg choice="opt">--keep-env</arg>
58 <arg choice="opt">--clear-env</arg>
59 <arg choice="opt">-- <replaceable>command</replaceable></arg>
64 <title>Description</title>
67 <command>lxc-attach</command> runs the specified
68 <replaceable>command</replaceable> inside the container
69 specified by <replaceable>name</replaceable>. The container
70 has to be running already.
73 If no <replaceable>command</replaceable> is specified, the
74 current default shell of the user running
75 <command>lxc-attach</command> will be looked up inside the
76 container and executed. This will fail if no such user exists
77 inside the container or the container does not have a working
85 <title>Options</title>
91 <option>-a, --arch <replaceable>arch</replaceable></option>
95 Specify the architecture which the kernel should appear to be
96 running as to the command executed. This option will accept the
97 same settings as the <option>lxc.arch</option> option in
98 container configuration files, see
100 <refentrytitle><filename>lxc.conf</filename></refentrytitle>
101 <manvolnum>5</manvolnum>
102 </citerefentry>. By default, the current archictecture of the
103 running container will be used.
110 <option>-e, --elevated-privileges</option>
114 Do not drop privileges when running
115 <replaceable>command</replaceable> inside the container. If
116 this option is specified, the new process will
117 <emphasis>not</emphasis> be added to the container's cgroup(s)
118 and it will not drop its capabilities before executing.
121 <emphasis>Warning:</emphasis> This may leak privileges into the
122 container if the command starts subprocesses that remain active
123 after the main process that was attached is terminated. The
124 (re-)starting of daemons inside the container is problematic,
125 especially if the daemon starts a lot of subprocesses such as
126 <command>cron</command> or <command>sshd</command>.
127 <emphasis>Use with great care.</emphasis>
134 <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
138 Specify the namespaces to attach to, as a pipe-separated list,
139 e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
140 <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
141 <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
142 <replaceable>USER </replaceable> and
143 <replaceable>NETWORK</replaceable>. This allows one to change
144 the context of the process to e.g. the network namespace of the
145 container while retaining the other namespaces as those of the
149 <emphasis>Important:</emphasis> This option implies
157 <option>-R, --remount-sys-proc</option>
161 When using <option>-s</option> and the mount namespace is not
162 included, this flag will cause <command>lxc-attach</command>
163 to remount <replaceable>/proc</replaceable> and
164 <replaceable>/sys</replaceable> to reflect the current other
168 Please see the <emphasis>Notes</emphasis> section for more
172 This option will be ignored if one tries to attach to the
173 mount namespace anyway.
180 <option>--keep-env</option>
184 Keep the current environment for attached programs. This is
185 the current default behaviour (as of version 0.9), but is
186 is likely to change in the future, since this may leak
187 undesirable information into the container. If you rely on
188 the environment being available for the attached program,
189 please use this option to be future-proof. In addition to
190 current environment variables, container=lxc will be set.
197 <option>--clear-env</option>
201 Clear the environment before attaching, so no undesired
202 environment variables leak into the container. The variable
203 container=lxc will be the only environment with which the
204 attached program starts.
216 <title>Examples</title>
218 To spawn a new shell running inside an existing container, use
220 lxc-attach -n container
224 To restart the cron service of a running Debian container, use
226 lxc-attach -n container -- /etc/init.d/cron restart
230 To deactivate the network link eth1 of a running container that
231 does not have the NET_ADMIN capability, use either the
232 <option>-e</option> option to use increased capabilities,
233 assuming the <command>ip</command> tool is installed:
235 lxc-attach -n container -e -- /sbin/ip link delete eth1
237 Or, alternatively, use the <option>-s</option> to use the
238 tools installed on the host outside the container:
240 lxc-attach -n container -s NETWORK -- /sbin/ip link delete eth1
246 <title>Compatibility</title>
248 Attaching completely (including the pid and mount namespaces) to a
249 container requires a patched kernel, please see the lxc website for
250 details. <command>lxc-attach</command> will fail in that case if
251 used with an unpatched kernel.
254 Nevertheless, it will succeed on an unpatched kernel of version 3.0
255 or higher if the <option>-s</option> option is used to restrict the
256 namespaces that the process is to be attached to to one or more of
257 <replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>
258 and <replaceable>UTSNAME</replaceable>.
261 Attaching to user namespaces is currently completely unsupported
262 by the kernel. <command>lxc-attach</command> should however be able
263 to do this once once future kernel versions implement this.
270 The Linux <replaceable>/proc</replaceable> and
271 <replaceable>/sys</replaceable> filesystems contain information
272 about some quantities that are affected by namespaces, such as
273 the directories named after process ids in
274 <replaceable>/proc</replaceable> or the network interface infromation
275 in <replaceable>/sys/class/net</replaceable>. The namespace of the
276 process mounting the pseudo-filesystems determines what information
277 is shown, <emphasis>not</emphasis> the namespace of the process
278 accessing <replaceable>/proc</replaceable> or
279 <replaceable>/sys</replaceable>.
282 If one uses the <option>-s</option> option to only attach to
283 the pid namespace of a container, but not its mount namespace
284 (which will contain the <replaceable>/proc</replaceable> of the
285 container and not the host), the contents of <option>/proc</option>
286 will reflect that of the host and not the container. Analogously,
287 the same issue occurs when reading the contents of
288 <replaceable>/sys/class/net</replaceable> and attaching to just
289 the network namespace.
292 To work around this problem, the <option>-R</option> flag provides
293 the option to remount <replaceable>/proc</replaceable> and
294 <replaceable>/sys</replaceable> in order for them to reflect the
295 network/pid namespace context of the attached process. In order
296 not to interfere with the host's actual filesystem, the mount
297 namespace will be unshared (like <command>lxc-unshare</command>
298 does) before this is done, esentially giving the process a new
299 mount namespace, which is identical to the hosts's mount namespace
300 except for the <replaceable>/proc</replaceable> and
301 <replaceable>/sys</replaceable> filesystems.
306 <title>Security</title>
308 The <option>-e</option> and <option>-s</option> options should
309 be used with care, as it may break the isolation of the containers
317 <title>Author</title>
318 <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
323 <!-- Keep this comment at the end of the file
328 sgml-minimize-attributes:nil
329 sgml-always-quote-attributes:t
332 sgml-parent-document:nil
333 sgml-default-dtd-file:nil
334 sgml-exposed-tags:nil
335 sgml-local-catalogs:nil
336 sgml-local-ecat-files:nil