| 1 |
<!-- SPDX-License-Identifier: LGPL-2.1+ --> |
| 2 |
|
| 3 |
<!DOCTYPE refentry PUBLIC @docdtd@ [ |
| 4 |
|
| 5 |
<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml"> |
| 6 |
]> |
| 7 |
|
| 8 |
<refentry> |
| 9 |
|
| 10 |
<docinfo> |
| 11 |
<date>@LXC_GENERATE_DATE@</date> |
| 12 |
</docinfo> |
| 13 |
|
| 14 |
|
| 15 |
<refmeta> |
| 16 |
<refentrytitle>lxc</refentrytitle> |
| 17 |
<manvolnum>7</manvolnum> |
| 18 |
<refmiscinfo> |
| 19 |
Version @PACKAGE_VERSION@ |
| 20 |
</refmiscinfo> |
| 21 |
</refmeta> |
| 22 |
|
| 23 |
<refnamediv> |
| 24 |
<refname>lxc</refname> |
| 25 |
|
| 26 |
<refpurpose> |
| 27 |
linux containers |
| 28 |
</refpurpose> |
| 29 |
</refnamediv> |
| 30 |
|
| 31 |
<refsect1> |
| 32 |
<title>Overview</title> |
| 33 |
<para> |
| 34 |
The container technology is actively being pushed into the mainstream |
| 35 |
Linux kernel. It provides resource management through control groups and |
| 36 |
resource isolation via namespaces. |
| 37 |
</para> |
| 38 |
|
| 39 |
<para> |
| 40 |
<command>lxc</command>, aims to use these new functionalities to provide a |
| 41 |
userspace container object which provides full resource isolation and |
| 42 |
resource control for an applications or a full system. |
| 43 |
</para> |
| 44 |
|
| 45 |
<para> |
| 46 |
<command>lxc</command> is small enough to easily manage a container with |
| 47 |
simple command lines and complete enough to be used for other purposes. |
| 48 |
</para> |
| 49 |
</refsect1> |
| 50 |
|
| 51 |
<refsect1> |
| 52 |
<title>Requirements</title> |
| 53 |
<para> |
| 54 |
The kernel version >= 3.10 shipped with the distros, will work with |
| 55 |
<command>lxc</command>, this one will have less functionalities but enough |
| 56 |
to be interesting. |
| 57 |
</para> |
| 58 |
|
| 59 |
<para> |
| 60 |
<command>lxc</command> relies on a set of functionalities provided by the |
| 61 |
kernel. The helper script <command>lxc-checkconfig</command> will give |
| 62 |
you information about your kernel configuration, required, and missing |
| 63 |
features. |
| 64 |
</para> |
| 65 |
</refsect1> |
| 66 |
|
| 67 |
<refsect1> |
| 68 |
<title>Functional specification</title> |
| 69 |
<para> |
| 70 |
A container is an object isolating some resources of the host, for the |
| 71 |
application or system running in it. |
| 72 |
</para> |
| 73 |
<para> |
| 74 |
The application / system will be launched inside a container specified by |
| 75 |
a configuration that is either initially created or passed as a parameter |
| 76 |
of the commands. |
| 77 |
</para> |
| 78 |
|
| 79 |
<para>How to run an application in a container</para> |
| 80 |
<para> |
| 81 |
Before running an application, you should know what are the resources you |
| 82 |
want to isolate. The default configuration is to isolate PIDs, the sysv |
| 83 |
IPC and mount points. If you want to run a simple shell inside a |
| 84 |
container, a basic configuration is needed, especially if you want to |
| 85 |
share the rootfs. If you want to run an application like |
| 86 |
<command>sshd</command>, you should provide a new network stack and a new |
| 87 |
hostname. If you want to avoid conflicts with some files eg. |
| 88 |
<filename>/var/run/httpd.pid</filename>, you should remount |
| 89 |
<filename>/var/run</filename> with an empty directory. If you want to |
| 90 |
avoid the conflicts in all the cases, you can specify a rootfs for the |
| 91 |
container. The rootfs can be a directory tree, previously bind mounted |
| 92 |
with the initial rootfs, so you can still use your distro but with your |
| 93 |
own <filename>/etc</filename> and <filename>/home</filename> |
| 94 |
</para> |
| 95 |
<para> |
| 96 |
Here is an example of directory tree |
| 97 |
for <command>sshd</command>: |
| 98 |
<programlisting> |
| 99 |
[root@lxc sshd]$ tree -d rootfs |
| 100 |
|
| 101 |
rootfs |
| 102 |
|-- bin |
| 103 |
|-- dev |
| 104 |
| |-- pts |
| 105 |
| `-- shm |
| 106 |
| `-- network |
| 107 |
|-- etc |
| 108 |
| `-- ssh |
| 109 |
|-- lib |
| 110 |
|-- proc |
| 111 |
|-- root |
| 112 |
|-- sbin |
| 113 |
|-- sys |
| 114 |
|-- usr |
| 115 |
`-- var |
| 116 |
|-- empty |
| 117 |
| `-- sshd |
| 118 |
|-- lib |
| 119 |
| `-- empty |
| 120 |
| `-- sshd |
| 121 |
`-- run |
| 122 |
`-- sshd |
| 123 |
</programlisting> |
| 124 |
|
| 125 |
and the mount points file associated with it: |
| 126 |
<programlisting> |
| 127 |
[root@lxc sshd]$ cat fstab |
| 128 |
|
| 129 |
/lib /home/root/sshd/rootfs/lib none ro,bind 0 0 |
| 130 |
/bin /home/root/sshd/rootfs/bin none ro,bind 0 0 |
| 131 |
/usr /home/root/sshd/rootfs/usr none ro,bind 0 0 |
| 132 |
/sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0 |
| 133 |
</programlisting> |
| 134 |
</para> |
| 135 |
|
| 136 |
<para>How to run a system in a container</para> |
| 137 |
|
| 138 |
<para> |
| 139 |
Running a system inside a container is paradoxically easier |
| 140 |
than running an application. Why? Because you don't have to care |
| 141 |
about the resources to be isolated, everything needs to be |
| 142 |
isolated, the other resources are specified as being isolated but |
| 143 |
without configuration because the container will set them |
| 144 |
up. eg. the ipv4 address will be setup by the system container |
| 145 |
init scripts. Here is an example of the mount points file: |
| 146 |
</para> |
| 147 |
|
| 148 |
<programlisting> |
| 149 |
[root@lxc debian]$ cat fstab |
| 150 |
|
| 151 |
/dev /home/root/debian/rootfs/dev none bind 0 0 |
| 152 |
/dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0 |
| 153 |
</programlisting> |
| 154 |
|
| 155 |
<refsect2> |
| 156 |
<title>Container life cycle</title> |
| 157 |
<para> |
| 158 |
When the container is created, it contains the configuration |
| 159 |
information. When a process is launched, the container will be starting |
| 160 |
and running. When the last process running inside the container exits, |
| 161 |
the container is stopped. |
| 162 |
</para> |
| 163 |
<para> |
| 164 |
In case of failure when the container is initialized, it will pass |
| 165 |
through the aborting state. |
| 166 |
</para> |
| 167 |
|
| 168 |
<programlisting> |
| 169 |
<![CDATA[ |
| 170 |
--------- |
| 171 |
| STOPPED |<--------------- |
| 172 |
--------- | |
| 173 |
| | |
| 174 |
start | |
| 175 |
| | |
| 176 |
V | |
| 177 |
---------- | |
| 178 |
| STARTING |--error- | |
| 179 |
---------- | | |
| 180 |
| | | |
| 181 |
V V | |
| 182 |
--------- ---------- | |
| 183 |
| RUNNING | | ABORTING | | |
| 184 |
--------- ---------- | |
| 185 |
| | | |
| 186 |
no process | | |
| 187 |
| | | |
| 188 |
V | | |
| 189 |
---------- | | |
| 190 |
| STOPPING |<------- | |
| 191 |
---------- | |
| 192 |
| | |
| 193 |
--------------------- |
| 194 |
]]> |
| 195 |
</programlisting> |
| 196 |
</refsect2> |
| 197 |
|
| 198 |
<refsect2> |
| 199 |
<title>Configuration</title> |
| 200 |
<para>The container is configured through a configuration |
| 201 |
file, the format of the configuration file is described in |
| 202 |
<citerefentry> |
| 203 |
<refentrytitle><filename>lxc.conf</filename></refentrytitle> |
| 204 |
<manvolnum>5</manvolnum> |
| 205 |
</citerefentry> |
| 206 |
</para> |
| 207 |
</refsect2> |
| 208 |
|
| 209 |
<refsect2> |
| 210 |
<title>Unprivileged containers</title> |
| 211 |
<para> |
| 212 |
Unprivileged LXC containers run without root host-level privileges in a |
| 213 |
user namespace, mapping container UID 0 to a non-root host ID, which |
| 214 |
strictly limits the accessible devices and filesystems of the |
| 215 |
container. In order to mount a rootfs in an unprivileged container, the |
| 216 |
mapped host user must have execute permissions for all directories |
| 217 |
along the path to and including the rootfs. Additionally, all files and |
| 218 |
directories under the rootfs must be owned by the correct user ID and |
| 219 |
group ID. The correct user ID and group ID are the host IDs mapped to |
| 220 |
the container root(UID 0) in lxc.idmap. |
| 221 |
</para> |
| 222 |
</refsect2> |
| 223 |
|
| 224 |
<refsect2> |
| 225 |
<title>Creating / Destroying containers</title> |
| 226 |
<para> |
| 227 |
A persistent container object can be created via the |
| 228 |
<command>lxc-create</command> command. It takes a container name as |
| 229 |
parameter and optional configuration file and template. The name is |
| 230 |
used by the different commands to refer to this container. The |
| 231 |
<command>lxc-destroy</command> command will destroy the container |
| 232 |
object. |
| 233 |
<programlisting> |
| 234 |
lxc-create -n foo |
| 235 |
lxc-destroy -n foo |
| 236 |
</programlisting> |
| 237 |
</para> |
| 238 |
</refsect2> |
| 239 |
|
| 240 |
<refsect2> |
| 241 |
<title>Volatile container</title> |
| 242 |
<para> |
| 243 |
It is not mandatory to create a container object before starting it. |
| 244 |
The container can be directly started with a configuration file as |
| 245 |
parameter. |
| 246 |
</para> |
| 247 |
</refsect2> |
| 248 |
|
| 249 |
<refsect2> |
| 250 |
<title>Starting / Stopping container</title> |
| 251 |
<para> |
| 252 |
When the container has been created, it is ready to run an application / |
| 253 |
system. This is the purpose of the <command>lxc-execute</command> and |
| 254 |
<command>lxc-start</command> commands. If the container was not created |
| 255 |
before starting the application, the container will use the |
| 256 |
configuration file passed as parameter to the command, and if there is |
| 257 |
no such parameter either, then it will use a default isolation. If the |
| 258 |
application ended, the container will be stopped, but if needed the |
| 259 |
<command>lxc-stop</command> command can be used to stop the container. |
| 260 |
</para> |
| 261 |
|
| 262 |
<para> |
| 263 |
Running an application inside a container is not exactly the same thing |
| 264 |
as running a system. For this reason, there are two different commands |
| 265 |
to run an application into a container: |
| 266 |
<programlisting> |
| 267 |
lxc-execute -n foo [-f config] /bin/bash |
| 268 |
lxc-start -n foo [-f config] [/bin/bash] |
| 269 |
</programlisting> |
| 270 |
</para> |
| 271 |
|
| 272 |
<para> |
| 273 |
The <command>lxc-execute</command> command will run the specified command |
| 274 |
into a container via an intermediate process, |
| 275 |
<command>lxc-init</command>. |
| 276 |
This lxc-init after launching the specified command, will wait for its |
| 277 |
end and all other reparented processes. (to support daemons in the |
| 278 |
container). In other words, in the container, |
| 279 |
<command>lxc-init</command> has PID 1 and the first process of the |
| 280 |
application has PID 2. |
| 281 |
</para> |
| 282 |
|
| 283 |
<para> |
| 284 |
The <command>lxc-start</command> command will directly run the specified |
| 285 |
command in the container. The PID of the first process is 1. If no |
| 286 |
command is specified <command>lxc-start</command> will run the command |
| 287 |
defined in lxc.init.cmd or if not set, <filename>/sbin/init</filename> . |
| 288 |
</para> |
| 289 |
|
| 290 |
<para> |
| 291 |
To summarize, <command>lxc-execute</command> is for running an |
| 292 |
application and <command>lxc-start</command> is better suited for |
| 293 |
running a system. |
| 294 |
</para> |
| 295 |
|
| 296 |
<para> |
| 297 |
If the application is no longer responding, is inaccessible or is not |
| 298 |
able to finish by itself, a wild <command>lxc-stop</command> command |
| 299 |
will kill all the processes in the container without pity. |
| 300 |
<programlisting> |
| 301 |
lxc-stop -n foo -k |
| 302 |
</programlisting> |
| 303 |
</para> |
| 304 |
</refsect2> |
| 305 |
|
| 306 |
<refsect2> |
| 307 |
<title>Connect to an available tty</title> |
| 308 |
<para> |
| 309 |
If the container is configured with ttys, it is possible to access it |
| 310 |
through them. It is up to the container to provide a set of available |
| 311 |
ttys to be used by the following command. When the tty is lost, it is |
| 312 |
possible to reconnect to it without login again. |
| 313 |
<programlisting> |
| 314 |
lxc-console -n foo -t 3 |
| 315 |
</programlisting> |
| 316 |
</para> |
| 317 |
</refsect2> |
| 318 |
|
| 319 |
<refsect2> |
| 320 |
<title>Freeze / Unfreeze container</title> |
| 321 |
<para> |
| 322 |
Sometime, it is useful to stop all the processes belonging to |
| 323 |
a container, eg. for job scheduling. The commands: |
| 324 |
<programlisting> |
| 325 |
lxc-freeze -n foo |
| 326 |
</programlisting> |
| 327 |
|
| 328 |
will put all the processes in an uninteruptible state and |
| 329 |
|
| 330 |
<programlisting> |
| 331 |
lxc-unfreeze -n foo |
| 332 |
</programlisting> |
| 333 |
|
| 334 |
will resume them. |
| 335 |
</para> |
| 336 |
|
| 337 |
<para> |
| 338 |
This feature is enabled if the freezer cgroup v1 controller is enabled |
| 339 |
in the kernel. |
| 340 |
</para> |
| 341 |
</refsect2> |
| 342 |
|
| 343 |
<refsect2> |
| 344 |
<title>Getting information about container</title> |
| 345 |
<para> |
| 346 |
When there are a lot of containers, it is hard to follow what has been |
| 347 |
created or destroyed, what is running or what are the PIDs running in a |
| 348 |
specific container. For this reason, the following commands may be useful: |
| 349 |
<programlisting> |
| 350 |
lxc-ls -f |
| 351 |
lxc-info -n foo |
| 352 |
</programlisting> |
| 353 |
</para> |
| 354 |
<para> |
| 355 |
<command>lxc-ls</command> lists containers. |
| 356 |
</para> |
| 357 |
|
| 358 |
<para> |
| 359 |
<command>lxc-info</command> gives information for a specific container. |
| 360 |
</para> |
| 361 |
|
| 362 |
<para> |
| 363 |
Here is an example on how the combination of these commands |
| 364 |
allows one to list all the containers and retrieve their state. |
| 365 |
<programlisting> |
| 366 |
for i in $(lxc-ls -1); do |
| 367 |
lxc-info -n $i |
| 368 |
done |
| 369 |
</programlisting> |
| 370 |
</para> |
| 371 |
</refsect2> |
| 372 |
|
| 373 |
<refsect2> |
| 374 |
<title>Monitoring container</title> |
| 375 |
<para> |
| 376 |
It is sometime useful to track the states of a container, for example to |
| 377 |
monitor it or just to wait for a specific state in a script. |
| 378 |
</para> |
| 379 |
|
| 380 |
<para> |
| 381 |
<command>lxc-monitor</command> command will monitor one or several |
| 382 |
containers. The parameter of this command accepts a regular expression |
| 383 |
for example: |
| 384 |
<programlisting> |
| 385 |
lxc-monitor -n "foo|bar" |
| 386 |
</programlisting> |
| 387 |
will monitor the states of containers named 'foo' and 'bar', and: |
| 388 |
<programlisting> |
| 389 |
lxc-monitor -n ".*" |
| 390 |
</programlisting> |
| 391 |
will monitor all the containers. |
| 392 |
</para> |
| 393 |
<para> |
| 394 |
For a container 'foo' starting, doing some work and exiting, |
| 395 |
the output will be in the form: |
| 396 |
<programlisting> |
| 397 |
'foo' changed state to [STARTING] |
| 398 |
'foo' changed state to [RUNNING] |
| 399 |
'foo' changed state to [STOPPING] |
| 400 |
'foo' changed state to [STOPPED] |
| 401 |
</programlisting> |
| 402 |
</para> |
| 403 |
<para> |
| 404 |
<command>lxc-wait</command> command will wait for a specific |
| 405 |
state change and exit. This is useful for scripting to |
| 406 |
synchronize the launch of a container or the end. The |
| 407 |
parameter is an ORed combination of different states. The |
| 408 |
following example shows how to wait for a container if it successfully |
| 409 |
started as a daemon. |
| 410 |
|
| 411 |
<programlisting> |
| 412 |
<![CDATA[ |
| 413 |
# launch lxc-wait in background |
| 414 |
lxc-wait -n foo -s STOPPED & |
| 415 |
LXC_WAIT_PID=$! |
| 416 |
|
| 417 |
# this command goes in background |
| 418 |
lxc-execute -n foo mydaemon & |
| 419 |
|
| 420 |
# block until the lxc-wait exits |
| 421 |
# and lxc-wait exits when the container |
| 422 |
# is STOPPED |
| 423 |
wait $LXC_WAIT_PID |
| 424 |
echo "'foo' is finished" |
| 425 |
]]> |
| 426 |
</programlisting> |
| 427 |
</para> |
| 428 |
</refsect2> |
| 429 |
|
| 430 |
<refsect2> |
| 431 |
<title>cgroup settings for containers</title> |
| 432 |
<para> |
| 433 |
The container is tied with the control groups, when a container is |
| 434 |
started a control group is created and associated with it. The control |
| 435 |
group properties can be read and modified when the container is running |
| 436 |
by using the lxc-cgroup command. |
| 437 |
</para> |
| 438 |
<para> |
| 439 |
<command>lxc-cgroup</command> command is used to set or get a |
| 440 |
control group subsystem which is associated with a |
| 441 |
container. The subsystem name is handled by the user, the |
| 442 |
command won't do any syntax checking on the subsystem name, if |
| 443 |
the subsystem name does not exists, the command will fail. |
| 444 |
</para> |
| 445 |
<para> |
| 446 |
<programlisting> |
| 447 |
lxc-cgroup -n foo cpuset.cpus |
| 448 |
</programlisting> |
| 449 |
will display the content of this subsystem. |
| 450 |
<programlisting> |
| 451 |
lxc-cgroup -n foo cpu.shares 512 |
| 452 |
</programlisting> |
| 453 |
will set the subsystem to the specified value. |
| 454 |
</para> |
| 455 |
</refsect2> |
| 456 |
</refsect1> |
| 457 |
|
| 458 |
&seealso; |
| 459 |
|
| 460 |
</refentry> |
| 461 |
|
| 462 |
<!-- Keep this comment at the end of the file Local variables: mode: |
| 463 |
sgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil |
| 464 |
sgml-always-quote-attributes:t sgml-indent-step:2 sgml-indent-data:t |
| 465 |
sgml-parent-document:nil sgml-default-dtd-file:nil |
| 466 |
sgml-exposed-tags:nil sgml-local-catalogs:nil |
| 467 |
sgml-local-ecat-files:nil End: --> |