1
.\" This manpage has been automatically generated by docbook2man
2
.\" from a DocBook document. This tool can be found at:
3
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
4
.\" Please send any bug reports, improvements, comments, patches,
5
.\" etc. to Steve Cheng <steve@ggi-project.org>.
6
.TH "LXC" "7" "02 March 2012" "Version 0.8.0-rc1" ""
9
lxc \- linux containers
12
You are in a hurry, and you don't want to read this man page. Ok,
13
without warranty, here are the commands to launch a shell inside
14
a container with a predefined configuration template, it may
16
\fB/usr/bin/lxc-execute -n foo -f
17
/usr/share/doc/lxc/examples/lxc-macvlan.conf /bin/bash\fR
20
The container technology is actively being pushed into the
21
mainstream linux kernel. It provides the resource management
22
through the control groups aka process containers and resource
23
isolation through the namespaces.
25
The linux containers, \fBlxc\fR, aims to use these
26
new functionalities to provide an userspace container object
27
which provides full resource isolation and resource control for
28
an applications or a system.
30
The first objective of this project is to make the life easier
31
for the kernel developers involved in the containers project and
32
especially to continue working on the Checkpoint/Restart new
33
features. The \fBlxc\fR is small enough to easily
34
manage a container with simple command lines and complete enough
35
to be used for other purposes.
38
The \fBlxc\fR relies on a set of functionalities
39
provided by the kernel which needs to be active. Depending of
40
the missing functionalities the \fBlxc\fR will
41
work with a restricted number of functionalities or will simply
44
The following list gives the kernel features to be enabled in
45
the kernel to have the full features container:
49
* Control Group support
50
-> Namespace cgroup subsystem
51
-> Freezer cgroup subsystem
53
-> Simple CPU accounting cgroup subsystem
55
-> Memory resource controllers for Control Groups
57
-> Basis for grouping tasks (Control Groups)
66
-> Support multiple instances of devpts
67
* Network device support
69
-> Virtual ethernet pair device
72
-> 802.1d Ethernet Bridging
74
-> File POSIX Capabilities
78
The kernel version >= 2.6.27 shipped with the distros, will
79
work with \fBlxc\fR, this one will have less
80
functionalities but enough to be interesting.
81
With the kernel 2.6.29, \fBlxc\fR is fully
83
The helper script \fBlxc-checkconfig\fR will give
84
you information about your kernel configuration.
86
Before using the \fBlxc\fR, your system should be
87
configured with the file capabilities, otherwise you will need
88
to run the \fBlxc\fR commands as root.
90
The control group can be mounted anywhere, eg:
91
\fBmount -t cgroup cgroup /cgroup\fR\&.
92
If you want to dedicate a specific cgroup mount point
93
for \fBlxc\fR, that is to have different cgroups
94
mounted at different places with different options but
95
let \fBlxc\fR to use one location, you can bind
96
the mount point with the \fBlxc\fR name, eg:
97
\fBmount -t cgroup lxc /cgroup4lxc\fR or
98
\fBmount -t cgroup -ons,cpuset,freezer,devices
100
.SH "FUNCTIONAL SPECIFICATION"
102
A container is an object isolating some resources of the host,
103
for the application or system running in it.
105
The application / system will be launched inside a
106
container specified by a configuration that is either
107
initially created or passed as parameter of the starting commands.
109
How to run an application in a container ?
111
Before running an application, you should know what are the
112
resources you want to isolate. The default configuration is to
113
isolate the pids, the sysv ipc and the mount points. If you want
114
to run a simple shell inside a container, a basic configuration
115
is needed, especially if you want to share the rootfs. If you
116
want to run an application like \fBsshd\fR, you
117
should provide a new network stack and a new hostname. If you
118
want to avoid conflicts with some files
119
eg. \fI/var/run/httpd.pid\fR, you should
120
remount \fI/var/run\fR with an empty
121
directory. If you want to avoid the conflicts in all the cases,
122
you can specify a rootfs for the container. The rootfs can be a
123
directory tree, previously bind mounted with the initial rootfs,
124
so you can still use your distro but with your
125
own \fI/etc\fR and \fI/home\fR
127
Here is an example of directory tree
132
[root@lxc sshd]$ tree -d rootfs
158
and the mount points file associated with it:
161
[root@lxc sshd]$ cat fstab
163
/lib /home/root/sshd/rootfs/lib none ro,bind 0 0
164
/bin /home/root/sshd/rootfs/bin none ro,bind 0 0
165
/usr /home/root/sshd/rootfs/usr none ro,bind 0 0
166
/sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0
170
How to run a system in a container ?
172
Running a system inside a container is paradoxically easier
173
than running an application. Why ? Because you don't have to care
174
about the resources to be isolated, everything need to be
175
isolated, the other resources are specified as being isolated but
176
without configuration because the container will set them
177
up. eg. the ipv4 address will be setup by the system container
178
init scripts. Here is an example of the mount points file:
181
[root@lxc debian]$ cat fstab
183
/dev /home/root/debian/rootfs/dev none bind 0 0
184
/dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
187
More information can be added to the container to facilitate the
188
configuration. For example, make accessible from the container
189
the resolv.conf file belonging to the host.
192
/etc/resolv.conf /home/root/debian/rootfs/etc/resolv.conf none bind 0 0
195
.SS "CONTAINER LIFE CYCLE"
197
When the container is created, it contains the configuration
198
information. When a process is launched, the container will be
199
starting and running. When the last process running inside the
200
container exits, the container is stopped.
202
In case of failure when the container is initialized, it will
203
pass through the aborting state.
208
| STOPPED |<---------------
215
| STARTING |--error- |
219
--------- ---------- |
220
| RUNNING | | ABORTING | |
221
--------- ---------- |
227
| STOPPING |<------- |
230
---------------------
236
The container is configured through a configuration
237
file, the format of the configuration file is described in
238
\fB\fIlxc.conf\fB\fR(5)
239
.SS "CREATING / DESTROYING CONTAINER (PERSISTENT CONTAINER)"
241
A persistent container object can be
242
created via the \fBlxc-create\fR
243
command. It takes a container name as parameter and
244
optional configuration file and template.
245
The name is used by the different
246
commands to refer to this
247
container. The \fBlxc-destroy\fR command will
248
destroy the container object.
255
.SS "VOLATILE CONTAINER"
257
It is not mandatory to create a container object
259
The container can be directly started with a
260
configuration file as parameter.
261
.SS "STARTING / STOPPING CONTAINER"
263
When the container has been created, it is ready to run an
264
application / system.
265
This is the purpose of the \fBlxc-execute\fR and
266
\fBlxc-start\fR commands.
267
If the container was not created before
268
starting the application, the container will use the
269
configuration file passed as parameter to the command,
270
and if there is no such parameter either, then
271
it will use a default isolation.
272
If the application is ended, the container will be stopped also,
273
but if needed the \fBlxc-stop\fR command can
274
be used to kill the still running application.
276
Running an application inside a container is not exactly the
277
same thing as running a system. For this reason, there are two
278
different commands to run an application into a container:
281
lxc-execute -n foo [-f config] /bin/bash
282
lxc-start -n foo [-f config] [/bin/bash]
286
\fBlxc-execute\fR command will run the
287
specified command into the container via an intermediate
288
process, \fBlxc-init\fR\&.
289
This lxc-init after launching the specified command,
290
will wait for its end and all other reparented processes.
291
(that allows to support daemons in the container).
292
In other words, in the
293
container, \fBlxc-init\fR has the pid 1 and the
294
first process of the application has the pid 2.
296
\fBlxc-start\fR command will run directly the specified
297
command into the container.
298
The pid of the first process is 1. If no command is
299
specified \fBlxc-start\fR will
300
run \fI/sbin/init\fR\&.
302
To summarize, \fBlxc-execute\fR is for running
303
an application and \fBlxc-start\fR is better suited for
306
If the application is no longer responding, is inaccessible or is
307
not able to finish by itself, a
308
wild \fBlxc-stop\fR command will kill all the
309
processes in the container without pity.
315
.SS "CONNECT TO AN AVAILABLE TTY"
317
If the container is configured with the ttys, it is possible
318
to access it through them. It is up to the container to
319
provide a set of available tty to be used by the following
320
command. When the tty is lost, it is possible to reconnect it
324
lxc-console -n foo -t 3
327
.SS "FREEZE / UNFREEZE CONTAINER"
329
Sometime, it is useful to stop all the processes belonging to
330
a container, eg. for job scheduling. The commands:
336
will put all the processes in an uninteruptible state and
344
This feature is enabled if the cgroup freezer is enabled in the
346
.SS "GETTING INFORMATION ABOUT CONTAINER"
348
When there are a lot of containers, it is hard to follow
349
what has been created or destroyed, what is running or what are
350
the pids running into a specific container. For this reason, the
351
following commands may be usefull:
360
\fBlxc-ls\fR lists the containers of the
361
system. The command is a script built on top
362
of \fBls\fR, so it accepts the options of the ls
369
will display the containers list in one column or:
375
will display the containers list and their permissions.
377
\fBlxc-ps\fR will display the pids for a specific
378
container. Like \fBlxc-ls\fR, \fBlxc-ps\fR
379
is built on top of \fBps\fR and accepts the same
383
lxc-ps --name foo --forest
385
will display the processes hierarchy for the processes
386
belonging the 'foo' container.
391
will display all the containers and their processes.
393
\fBlxc-info\fR gives informations for a specific
394
container, at present time, only the state of the container is
397
Here is an example on how the combination of these commands
398
allow to list all the containers and retrieve their state.
401
for i in $(lxc-ls -1); do
406
And displaying all the pids of all the containers:
409
for i in $(lxc-ls -1); do
410
lxc-ps --name $i --forest
415
\fBlxc-netstat\fR display network information for
416
a specific container. This command is built on top of
417
the \fBnetstat\fR command and will accept its
420
The following command will display the socket informations for
424
lxc-netstat -n foo -tano
427
.SS "MONITORING CONTAINER"
429
It is sometime useful to track the states of a container,
430
for example to monitor it or just to wait for a specific
433
\fBlxc-monitor\fR command will monitor one or
434
several containers. The parameter of this command accept a
435
regular expression for example:
438
lxc-monitor -n "foo|bar"
441
will monitor the states of containers named 'foo' and 'bar', and:
447
will monitor all the containers.
449
For a container 'foo' starting, doing some work and exiting,
450
the output will be in the form:
453
\&'foo' changed state to [STARTING]
454
\&'foo' changed state to [RUNNING]
455
\&'foo' changed state to [STOPPING]
456
\&'foo' changed state to [STOPPED]
460
\fBlxc-wait\fR command will wait for a specific
461
state change and exit. This is useful for scripting to
462
synchronize the launch of a container or the end. The
463
parameter is an ORed combination of different states. The
464
following example shows how to wait for a container if he went
469
# launch lxc-wait in background
470
lxc-wait -n foo -s STOPPED &
473
# this command goes in background
474
lxc-execute -n foo mydaemon &
476
# block until the lxc-wait exits
477
# and lxc-wait exits when the container
480
echo "'foo' is finished"
484
.SS "SETTING THE CONTROL GROUP FOR CONTAINER"
486
The container is tied with the control groups, when a
487
container is started a control group is created and associated
488
with it. The control group properties can be read and modified
489
when the container is running by using the lxc-cgroup command.
491
\fBlxc-cgroup\fR command is used to set or get a
492
control group subsystem which is associated with a
493
container. The subsystem name is handled by the user, the
494
command won't do any syntax checking on the subsystem name, if
495
the subsystem name does not exists, the command will fail.
499
lxc-cgroup -n foo cpuset.cpus
502
will display the content of this subsystem.
505
lxc-cgroup -n foo cpu.shares 512
508
will set the subsystem to the specified value.
511
The \fBlxc\fR is still in development, so the
512
command syntax and the API can change. The version 1.0.0 will be
518
\fBlxc-destroy\fR(1),
521
\fBlxc-execute\fR(1),
523
\fBlxc-console\fR(1),
524
\fBlxc-monitor\fR(1),
531
\fBlxc-unfreeze\fR(1),
536
Daniel Lezcano <daniel.lezcano@free.fr>
added
removed
doc/lxc.7
