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" "24 November 2009" "Version 0.6.4" ""
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 functionalies
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 where the configuration is
103
persistent. The application will be launched inside this
104
container and it will use the configuration which was previously
105
created or specified in parameter of the command.
107
How to run an application in a container ?
109
Before running an application, you should know what are the
110
resources you want to isolate. The default configuration is to
111
isolate the pids, the sysv ipc and the mount points. If you want
112
to run a simple shell inside a container, a basic configuration
113
is needed, especially if you want to share the rootfs. If you
114
want to run an application like \fBsshd\fR, you
115
should provide a new network stack and a new hostname. If you
116
want to avoid conflicts with some files
117
eg. \fI/var/run/httpd.pid\fR, you should
118
remount \fI/var/run\fR with an empty
119
directory. If you want to avoid the conflicts in all the cases,
120
you can specify a rootfs for the container. The rootfs can be a
121
directory tree, previously bind mounted with the initial rootfs,
122
so you can still use your distro but with your
123
own \fI/etc\fR and \fI/home\fR
125
Here is an example of directory tree
130
[root@lxc sshd]$ tree -d rootfs
156
and the mount points file associated with it:
159
[root@lxc sshd]$ cat fstab
161
/lib /home/root/sshd/rootfs/lib none ro,bind 0 0
162
/bin /home/root/sshd/rootfs/bin none ro,bind 0 0
163
/usr /home/root/sshd/rootfs/usr none ro,bind 0 0
164
/sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0
168
How to run a system in a container ?
170
Running a system inside a container is paradoxically easier
171
than running an application. Why ? Because you don't have to care
172
about the resources to be isolated, everything need to be
173
isolated, the other resources are specified as being isolated but
174
without configuration because the container will set them
175
up. eg. the ipv4 address will be setup by the system container
176
init scripts. Here is an example of the mount points file:
179
[root@lxc debian]$ cat fstab
181
/dev /home/root/debian/rootfs/dev none bind 0 0
182
/dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
185
More information can be added to the container to facilitate the
186
configuration. For example, make accessible from the container
187
the resolv.conf file belonging to the host.
190
/etc/resolv.conf /home/root/debian/rootfs/etc/resolv.conf none bind 0 0
193
.SS "CONTAINER LIFE CYCLE"
195
When the container is created, it contains the configuration
196
information. When a process is launched, the container will be
197
starting and running. When the last process running inside the
198
container exits, the container is stopped.
200
In case of failure when the container is initialized, it will
201
pass through the aborting state.
206
| STOPPED |<---------------
213
| STARTING |--error- |
217
--------- ---------- |
218
| RUNNING | | ABORTING | |
219
--------- ---------- |
225
| STOPPING |<------- |
228
---------------------
232
.SS "VOLATILE CONTAINERS"
234
The container can be directly started with a
235
configuration file in parameter without creating them before.
238
The container is configured through a configuration
239
file, the format of the configuration file is described in
240
\fB\fIlxc.conf\fB\fR(5)
241
.SS "CREATING / DESTROYING THE CONTAINERS"
243
The container is created via the \fBlxc-create\fR
244
command. It takes a container name as parameter and an
245
optional configuration file. 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 "STARTING / STOPPING A CONTAINER"
257
When the container has been created, it is ready to run an
258
application / system. When the application has to be destroyed,
259
the container can be stopped, that will kill all the processes
260
of the container. If the container was not created before
261
starting the application, the container will use the
262
configuration file passed as parameter to the command, otherwise
263
it will use the default isolation.
265
Running an application inside a container is not exactly the
266
same thing as running a system. For this reason, there is two
267
commands to run an application into a container:
270
lxc-execute -n foo [-f config] /bin/bash
271
lxc-start -n foo [/bin/bash]
275
\fBlxc-execute\fR command will run the
276
specified command into a container but it will mount /proc
277
and autocreate/autodestroy the container if it does not
278
exist. It will furthermore create an intermediate
279
process, \fBlxc-init\fR, which is in charge to
280
launch the specified command, that allows to support daemons
281
in the container. In other words, in the
282
container \fBlxc-init\fR has the pid 1 and the
283
first process of the application has the pid 2.
285
\fBlxc-start\fR command will run the specified
286
command into the container doing nothing else than using the
287
configuration specified by \fBlxc-create\fR\&.
288
The pid of the first process is 1. If no command is
289
specified \fBlxc-start\fR will
290
run \fI/sbin/init\fR\&.
292
To summarize, \fBlxc-execute\fR is for running
293
an application and \fBlxc-start\fR is for
296
If the application is no longer responding, inaccessible or is
297
not able to finish by itself, a
298
wild \fBlxc-stop\fR command will kill all the
299
processes in the container without pity.
305
.SS "CONNECT TO AN AVAILABLE TTY"
307
If the container is configured with the ttys, it is possible
308
to access it through them. It is up to the container to
309
provide a set of available tty to be used by the following
310
command. When the tty is lost, it is possible to reconnect it
314
lxc-console -n foo -t 3
317
.SS "FREEZE / UNFREEZE A CONTAINER"
319
Sometime, it is useful to stop all the processes belonging to
320
a container, eg. for job scheduling. The commands:
326
will put all the processes in an uninteruptible state and
332
will resume all the tasks.
334
This feature is enabled if the cgroup freezer is enabled in the
336
.SS "GETTING INFORMATION ABOUT THE CONTAINER"
338
When there are a lot of containers, it is hard to follow
339
what has been created or destroyed, what is running or what are
340
the pids running into a specific container. For this reason, the
341
following commands give this information:
350
\fBlxc-ls\fR lists the containers of the
351
system. The command is a script built on top
352
of \fBls\fR, so it accepts the options of the ls
359
will display the containers list in one column or:
365
will display the containers list and their permissions.
367
\fBlxc-ps\fR will display the pids for a specific
368
container. Like \fBlxc-ls\fR, \fBlxc-ps\fR
369
is built on top of \fBps\fR and accepts the same
373
lxc-ps --name foo --forest
375
will display the processes hierarchy for the processes
376
belonging the 'foo' container.
381
will display all the containers and their processes.
383
\fBlxc-info\fR gives informations for a specific
384
container, at present time, only the state of the container is
387
Here is an example on how the combination of these commands
388
allow to list all the containers and retrieve their state.
391
for i in $(lxc-ls -1); do
396
And displaying all the pids of all the containers:
399
for i in $(lxc-ls -1); do
400
lxc-ps --name $i --forest
405
\fBlxc-netstat\fR display network information for
406
a specific container. This command is built on top of
407
the \fBnetstat\fR command and will accept its
410
The following command will display the socket informations for
414
lxc-netstat -n foo -tano
417
.SS "MONITORING THE CONTAINERS"
419
It is sometime useful to track the states of a container,
420
for example to monitor it or just to wait for a specific
423
\fBlxc-monitor\fR command will monitor one or
424
several containers. The parameter of this command accept a
425
regular expression for example:
428
lxc-monitor -n "foo|bar"
431
will monitor the states of containers named 'foo' and 'bar', and:
437
will monitor all the containers.
439
For a container 'foo' starting, doing some work and exiting,
440
the output will be in the form:
443
'foo' changed state to [STARTING]
444
'foo' changed state to [RUNNING]
445
'foo' changed state to [STOPPING]
446
'foo' changed state to [STOPPED]
450
\fBlxc-wait\fR command will wait for a specific
451
state change and exit. This is useful for scripting to
452
synchronize the launch of a container or the end. The
453
parameter is an ORed combination of different states. The
454
following example shows how to wait for a container if he went
459
# launch lxc-wait in background
460
lxc-wait -n foo -s STOPPED &
463
# this command goes in background
464
lxc-execute -n foo mydaemon &
466
# block until the lxc-wait exits
467
# and lxc-wait exits when the container
470
echo "'foo' is finished"
474
.SS "SETTING THE CONTROL GROUP FOR A CONTAINER"
476
The container is tied with the control groups, when a
477
container is started a control group is created and associated
478
with it. The control group properties can be read and modified
479
when the container is running by using the lxc-cgroup command.
481
\fBlxc-cgroup\fR command is used to set or get a
482
control group subsystem which is associated with a
483
container. The subsystem name is handled by the user, the
484
command won't do any syntax checking on the subsystem name, if
485
the subsystem name does not exists, the command will fail.
489
lxc-cgroup -n foo cpuset.cpus
492
will display the content of this subsystem.
495
lxc-cgroup -n foo cpu.shares 512
498
will set the subsystem to the specified value.
501
The \fBlxc\fR is still in development, so the
502
command syntax and the API can change. The version 1.0.0 will be
508
\fBlxc-destroy\fR(1),
511
\fBlxc-execute\fR(1),
512
\fBlxc-console\fR(1),
513
\fBlxc-monitor\fR(1),
520
\fBlxc-unfreeze\fR(1),
524
Daniel Lezcano <daniel.lezcano@free.fr>
added
removed
doc/lxc.7
