| 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 |
--> |