Debian Codegraph @

doc/lxc-attach.sgml.in

raw
1 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
2
3 <!DOCTYPE refentry PUBLIC @docdtd@ [
4
5 <!ENTITY commonoptions SYSTEM "@builddir@/common_options.sgml">
6 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
7 ]>
8
9 <refentry>
10
11 <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
12
13 <refmeta>
14 <refentrytitle>lxc-attach</refentrytitle>
15 <manvolnum>1</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>lxc-attach</refname>
20
21 <refpurpose>
22 start a process inside a running container.
23 </refpurpose>
24 </refnamediv>
25
26 <refsynopsisdiv>
27 <cmdsynopsis>
28 <command>lxc-attach</command>
29 <arg choice="req">-n, --name <replaceable>name</replaceable></arg>
30 <arg choice="opt">-f, --rcfile <replaceable>config_file</replaceable></arg>
31 <arg choice="opt">-a, --arch <replaceable>arch</replaceable></arg>
32 <arg choice="opt">-e, --elevated-privileges <replaceable>privileges</replaceable></arg>
33 <arg choice="opt">-s, --namespaces <replaceable>namespaces</replaceable></arg>
34 <arg choice="opt">-R, --remount-sys-proc</arg>
35 <arg choice="opt">--keep-env</arg>
36 <arg choice="opt">--clear-env</arg>
37 <arg choice="opt">-v, --set-var <replaceable>variable</replaceable></arg>
38 <arg choice="opt">--keep-var <replaceable>variable</replaceable></arg>
39 <arg choice="opt">-u, --uid <replaceable>uid</replaceable></arg>
40 <arg choice="opt">-g, --gid <replaceable>gid</replaceable></arg>
41 <arg choice="opt">-- <replaceable>command</replaceable></arg>
42 </cmdsynopsis>
43 </refsynopsisdiv>
44
45 <refsect1>
46 <title>Description</title>
47
48 <para>
49 <command>lxc-attach</command> runs the specified
50 <replaceable>command</replaceable> inside the container
51 specified by <replaceable>name</replaceable>. The container
52 has to be running already.
53 </para>
54 <para>
55 If no <replaceable>command</replaceable> is specified, the
56 current default shell of the user running
57 <command>lxc-attach</command> will be looked up inside the
58 container and executed. This will fail if no such user exists
59 inside the container or the container does not have a working
60 nsswitch mechanism.
61 </para>
62 <para>
63 Previous versions of <command>lxc-attach</command> simply attached to the
64 specified namespaces of a container and ran a shell or the specified command
65 without first allocating a pseudo terminal. This made them vulnerable to
66 input faking via a TIOCSTI <command>ioctl</command> call after switching
67 between userspace execution contexts with different privilege levels. Newer
68 versions of <command>lxc-attach</command> will try to allocate a pseudo
69 terminal file descriptor pair on the host and attach any standard file
70 descriptors which refer to a terminal to the container side of the pseudo
71 terminal before executing a shell or command. Note, that if none of the
72 standard file descriptors refer to a terminal <command>lxc-attach</command>
73 will not try to allocate a pseudo terminal. Instead it will simply attach
74 to the containers namespaces and run a shell or the specified command.
75 </para>
76
77 </refsect1>
78
79 <refsect1>
80
81 <title>Options</title>
82
83 <variablelist>
84
85 <varlistentry>
86 <term>
87 <option>-f, --rcfile <replaceable>config_file</replaceable></option>
88 </term>
89 <listitem>
90 <para>
91 Specify the configuration file to configure the virtualization
92 and isolation functionalities for the container.
93 </para>
94 <para>
95 This configuration file if present will be used even if there is
96 already a configuration file present in the previously created
97 container (via lxc-create).
98 </para>
99 </listitem>
100 </varlistentry>
101
102 <varlistentry>
103 <term>
104 <option>-a, --arch <replaceable>arch</replaceable></option>
105 </term>
106 <listitem>
107 <para>
108 Specify the architecture which the kernel should appear to be
109 running as to the command executed. This option will accept the
110 same settings as the <option>lxc.arch</option> option in
111 container configuration files, see
112 <citerefentry>
113 <refentrytitle><filename>lxc.conf</filename></refentrytitle>
114 <manvolnum>5</manvolnum>
115 </citerefentry>. By default, the current architecture of the
116 running container will be used.
117 </para>
118 </listitem>
119 </varlistentry>
120
121 <varlistentry>
122 <term>
123 <option>
124 -e, --elevated-privileges <replaceable>privileges</replaceable>
125 </option>
126 </term>
127 <listitem>
128 <para>
129 Do not drop privileges when running
130 <replaceable>command</replaceable> inside the container. If
131 this option is specified, the new process will
132 <emphasis>not</emphasis> be added to the container's cgroup(s)
133 and it will not drop its capabilities before executing.
134 </para>
135 <para>
136 You may specify privileges, in case you do not want to elevate all of
137 them, as a pipe-separated list, e.g.
138 <replaceable>CGROUP|LSM</replaceable>. Allowed values are
139 <replaceable>CGROUP</replaceable>, <replaceable>CAP</replaceable> and
140 <replaceable>LSM</replaceable> representing cgroup, capabilities and
141 restriction privileges respectively. (The pipe symbol needs to be escaped,
142 e.g. <replaceable>CGROUP\|LSM</replaceable> or quoted, e.g.
143 <replaceable>"CGROUP|LSM"</replaceable>.)
144 </para>
145 <para>
146 <emphasis>Warning:</emphasis> This may leak privileges into the
147 container if the command starts subprocesses that remain active
148 after the main process that was attached is terminated. The
149 (re-)starting of daemons inside the container is problematic,
150 especially if the daemon starts a lot of subprocesses such as
151 <command>cron</command> or <command>sshd</command>.
152 <emphasis>Use with great care.</emphasis>
153 </para>
154 </listitem>
155 </varlistentry>
156
157 <varlistentry>
158 <term>
159 <option>-s, --namespaces <replaceable>namespaces</replaceable></option>
160 </term>
161 <listitem>
162 <para>
163 Specify the namespaces to attach to, as a pipe-separated list,
164 e.g. <replaceable>NETWORK|IPC</replaceable>. Allowed values are
165 <replaceable>MOUNT</replaceable>, <replaceable>PID</replaceable>,
166 <replaceable>UTSNAME</replaceable>, <replaceable>IPC</replaceable>,
167 <replaceable>USER </replaceable> and
168 <replaceable>NETWORK</replaceable>. This allows one to change
169 the context of the process to e.g. the network namespace of the
170 container while retaining the other namespaces as those of the
171 host. (The pipe symbol needs to be escaped, e.g.
172 <replaceable>MOUNT\|PID</replaceable> or quoted, e.g.
173 <replaceable>"MOUNT|PID"</replaceable>.)
174 </para>
175 <para>
176 <emphasis>Important:</emphasis> This option implies
177 <option>-e</option>.
178 </para>
179 </listitem>
180 </varlistentry>
181
182 <varlistentry>
183 <term>
184 <option>-R, --remount-sys-proc</option>
185 </term>
186 <listitem>
187 <para>
188 When using <option>-s</option> and the mount namespace is not
189 included, this flag will cause <command>lxc-attach</command>
190 to remount <replaceable>/proc</replaceable> and
191 <replaceable>/sys</replaceable> to reflect the current other
192 namespace contexts.
193 </para>
194 <para>
195 Please see the <emphasis>Notes</emphasis> section for more
196 details.
197 </para>
198 <para>
199 This option will be ignored if one tries to attach to the
200 mount namespace anyway.
201 </para>
202 </listitem>
203 </varlistentry>
204
205 <varlistentry>
206 <term>
207 <option>--keep-env</option>
208 </term>
209 <listitem>
210 <para>
211 Keep the current environment for attached programs. This is
212 the current default behaviour (as of version 0.9), but is
213 is likely to change in the future, since this may leak
214 undesirable information into the container. If you rely on
215 the environment being available for the attached program,
216 please use this option to be future-proof. In addition to
217 current environment variables, container=lxc will be set.
218 </para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term>
224 <option>--clear-env</option>
225 </term>
226 <listitem>
227 <para>
228 Clear the environment before attaching, so no undesired
229 environment variables leak into the container. The variable
230 container=lxc will be the only environment with which the
231 attached program starts.
232 </para>
233 </listitem>
234 </varlistentry>
235
236 <varlistentry>
237 <term>
238 <option>-v, --set-var <replaceable>variable</replaceable></option>
239 </term>
240 <listitem>
241 <para>
242 Set an additional environment variable that is seen by the
243 attached program in the container. It is specified in the
244 form of "VAR=VALUE", and can be specified multiple times.
245 </para>
246 </listitem>
247 </varlistentry>
248
249 <varlistentry>
250 <term>
251 <option>--keep-var <replaceable>variable</replaceable></option>
252 </term>
253 <listitem>
254 <para>
255 Keep a specified environment variable. It can only be
256 specified in conjunction
257 with <replaceable>--clear-env</replaceable>, and can be
258 specified multiple times.
259 </para>
260 </listitem>
261 </varlistentry>
262
263 <varlistentry>
264 <term>
265 <option>-u, --uid <replaceable>uid</replaceable></option>
266 </term>
267 <listitem>
268 <para>
269 Executes the <replaceable>command</replaceable> with user ID (use numerical value)
270 <replaceable>uid</replaceable> inside the container.
271 </para>
272 </listitem>
273 </varlistentry>
274
275 <varlistentry>
276 <term>
277 <option>--g, --gid <replaceable>gid</replaceable></option>
278 </term>
279 <listitem>
280 <para>
281 Executes the <replaceable>command</replaceable> with group ID (use numerical value)
282 <replaceable>gid</replaceable> inside the container.
283 </para>
284 </listitem>
285 </varlistentry>
286
287 </variablelist>
288
289 </refsect1>
290
291 &commonoptions;
292
293 <refsect1>
294 <title>Examples</title>
295 <para>
296 To spawn a new shell running inside an existing container, use
297 <programlisting>
298 lxc-attach -n container
299 </programlisting>
300 </para>
301 <para>
302 To restart the cron service of a running Debian container, use
303 <programlisting>
304 lxc-attach -n container -- /etc/init.d/cron restart
305 </programlisting>
306 </para>
307 <para>
308 To deactivate the network link eth1 of a running container that
309 does not have the NET_ADMIN capability, use either the
310 <option>-e</option> option to use increased capabilities,
311 assuming the <command>ip</command> tool is installed:
312 <programlisting>
313 lxc-attach -n container -e -- /sbin/ip link delete eth1
314 </programlisting>
315 Or, alternatively, use the <option>-s</option> to use the
316 tools installed on the host outside the container:
317 <programlisting>
318 lxc-attach -n container -s NETWORK -- /sbin/ip link delete eth1
319 </programlisting>
320 </para>
321 </refsect1>
322
323 <refsect1>
324 <title>Compatibility</title>
325 <para>
326 Attaching completely (including the pid and mount namespaces) to a
327 container requires a kernel of version 3.8 or higher, or a
328 patched kernel, please see the lxc website for
329 details. <command>lxc-attach</command> will fail in that case if
330 used with an unpatched kernel of version 3.7 and prior.
331 </para>
332 <para>
333 Nevertheless, it will succeed on an unpatched kernel of version 3.0
334 or higher if the <option>-s</option> option is used to restrict the
335 namespaces that the process is to be attached to to one or more of
336 <replaceable>NETWORK</replaceable>, <replaceable>IPC</replaceable>
337 and <replaceable>UTSNAME</replaceable>.
338 </para>
339 <para>
340 Attaching to user namespaces is supported by kernel 3.8 or higher
341 with enabling user namespace.
342 </para>
343 </refsect1>
344
345 <refsect1>
346 <title>Notes</title>
347 <para>
348 The Linux <replaceable>/proc</replaceable> and
349 <replaceable>/sys</replaceable> filesystems contain information
350 about some quantities that are affected by namespaces, such as
351 the directories named after process ids in
352 <replaceable>/proc</replaceable> or the network interface information
353 in <replaceable>/sys/class/net</replaceable>. The namespace of the
354 process mounting the pseudo-filesystems determines what information
355 is shown, <emphasis>not</emphasis> the namespace of the process
356 accessing <replaceable>/proc</replaceable> or
357 <replaceable>/sys</replaceable>.
358 </para>
359 <para>
360 If one uses the <option>-s</option> option to only attach to
361 the pid namespace of a container, but not its mount namespace
362 (which will contain the <replaceable>/proc</replaceable> of the
363 container and not the host), the contents of <option>/proc</option>
364 will reflect that of the host and not the container. Analogously,
365 the same issue occurs when reading the contents of
366 <replaceable>/sys/class/net</replaceable> and attaching to just
367 the network namespace.
368 </para>
369 <para>
370 To work around this problem, the <option>-R</option> flag provides
371 the option to remount <replaceable>/proc</replaceable> and
372 <replaceable>/sys</replaceable> in order for them to reflect the
373 network/pid namespace context of the attached process. In order
374 not to interfere with the host's actual filesystem, the mount
375 namespace will be unshared (like <command>lxc-unshare</command>
376 does) before this is done, essentially giving the process a new
377 mount namespace, which is identical to the hosts's mount namespace
378 except for the <replaceable>/proc</replaceable> and
379 <replaceable>/sys</replaceable> filesystems.
380 </para>
381 <para>
382 Previous versions of <command>lxc-attach</command> suffered a bug whereby
383 a user could attach to a containers namespace without being placed in a
384 writeable cgroup for some critical subsystems. Newer versions of
385 <command>lxc-attach</command> will check whether a user is in a writeable
386 cgroup for those critical subsystems. <command>lxc-attach</command> might
387 thus fail unexpectedly for some users (E.g. on systems where an
388 unprivileged user is not placed in a writeable cgroup in critical
389 subsystems on login.). However, this behavior is correct and more secure.
390 </para>
391 </refsect1>
392
393 <refsect1>
394 <title>Security</title>
395 <para>
396 The <option>-e</option> and <option>-s</option> options should
397 be used with care, as it may break the isolation of the containers
398 if used improperly.
399 </para>
400 </refsect1>
401
402 &seealso;
403
404 </refentry>
405
406 <!-- Keep this comment at the end of the file
407 Local variables:
408 mode: sgml
409 sgml-omittag:t
410 sgml-shorttag:t
411 sgml-minimize-attributes:nil
412 sgml-always-quote-attributes:t
413 sgml-indent-step:2
414 sgml-indent-data:t
415 sgml-parent-document:nil
416 sgml-default-dtd-file:nil
417 sgml-exposed-tags:nil
418 sgml-local-catalogs:nil
419 sgml-local-ecat-files:nil
420 End:
421 -->