← Back to branch summary

~serge-hallyn/ubuntu/quantal/lxc/lxc-fixapi

« back to all changes in this revision

Viewing changes to doc/lxc.conf.5

  • Committer: Package Import Robot
  • Author(s): Serge Hallyn
  • Date: 2012-04-26 15:18:35 UTC
  • mfrom: (3.1.41 sid)
  • Revision ID: package-import@ubuntu.com-20120426151835-3vz6kb4m90gb26js
Tags: 0.8.0~rc1-4ubuntu1
https://launchpad.net/bugs/988918
https://launchpad.net/bugs/981955
* Merge from unstable.  Remaining changes:
  - control:
    - update maintainer
    - Build-Depends: add dh-apparmor and libapparmor-dev
    - lxc Depends: add bridge-utils, dnsmasq-base, iptables, rsync
    - lxc Recommends: add cgroup-lite | cgroup-bin, openssl
    - lxc Suggests: add btrfs-tools, lvm2, qemu-user-static
    - lxc Conflicts: remove (cgroup-bin)
  - Add lxc-start-ephemeral and lxc-wait to debian/local
  - apparmor:
    - add lxc.apparmor, lxc-containers.apparmor,
      lxc-default.apparmor, and new lxc.apparmor.in
  - add debian/lxc.conf (default container creation config file)
  - debian/lxc.install.in:
    * add lxc-start-ephemeral
    * add debian/lxc.conf
    * skip lxc-debconf*
    * skip lxc-ls (Use upstream's)
  - debian/lxc*.install.in: use '*', not @DEB_HOST_MULTIARCH@
  - Use our own completely different lxc.postinst and lxc.postrm
  - remove lxc.templates
  - debian/rules:
    * add DEB_DH_INSTALLINIT_ARGS = --upstart-only
    * don't do debconf stuff
    * add debian/*.apparmor.in to files processed under
      override_dh_auto_clean
    * don't comment out ubuntu or busybox templates
    * do apparmor stuff and install our own lxc-wait under override_dh_install
    * install our upstart scripts in override_dh_installinit
  - add lxc.default, lxc.lxc-net.upstart, lxc.upstart under
    debian/

* patches kept:
  - 0013-lxc-create-use-default-config.patch (needed manual rebase)
  - 0030-ubuntu-template-fail.patch
  - 0031-ubuntu-template-resolvconf.patch
  - 0044-lxc-destroy-rm-autos
  - debian/patches/0045-fix-other-templates
  - debian/patches/0046-lxc-clone-change-hwaddr
  - debian/patches/0047-bindhome-check-shell
  - debian/patches/0049-ubuntu-template-sudo-and-cleanup
  - debian/patches/0050-clone-lvm-sizes
  - debian/patches/0052-ubuntu-bind-user-conflict
  - debian/patches/0053-lxc-start-pin-rootfs
  - debian/patches/0054-ubuntu-debug
  - debian/patches/0055-ubuntu-handle-badgrp
  - debian/patches/0056-dont-watch-utmp
  - debian/patches/0057-update-manpages
  - debian/patches/0058-fixup-ubuntu-cloud
  - debian/patches/0059-reenable-daily-cloudimg
  - debian/patches/0060-lxc-shutdown
  - debian/patches/0061-lxc-start-apparmor
  - debian/patches/0062-templates-relative-paths
  - debian/patches/0063-check-apparmor-enabled
  - debian/patches/0064-apparmor-mount-proc
  - debian/patches/0065-fix-bindhome-relpath
  - debian/patches/0066-confile-typo
  - debian/patches/0067-templates-lxc-profile
  - debian/patches/0068-fix-lxc-config-layout 
  - debian/patches/0069-ubuntu-cloud-fix
  - debian/patches/0070-templates-rmdir-dev-shm
  - debian/patches/0071-ubuntu-cloud-fix-image-extraction
  - debian/patches/0072-lxc-shutdown-help
  - debian/patches/0073-lxc-destroy-waits-before-destroy
  - mark all patches which have been forwarded as such, refresh all
* 0074-lxc-execute-find-init: lxc-init had moved.  Introduce a function in
  lxc-execute to go find it.  Otherwise lxc-execute for any older releases
  will fail.
* 0075-lxc-ls-bash: lxc-ls needs bash, not sh
* add debian/lxc.apparmor.in so DEB_HOST_MULTIARCH can be expanded
* 0076-fix-sprintfs:  - check return values for all sprintfs and snprintfs
  which could overflow (LP: #988918)
* 0077-execute-without-rootfs: let lxc-execute succeed with no rootfs
  (LP: #981955)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/lxc.conf.5
 
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.CONF" "5" "02 March 2012" "" ""
 
7
 
 
8
.SH NAME
 
9
lxc.conf \- linux container configuration file
 
10
.SH "DESCRIPTION"
 
11
.PP
 
12
The linux containers (\fBlxc\fR) are always created
 
13
before being used. This creation defines a set of system
 
14
resources to be virtualized / isolated when a process is using
 
15
the container. By default, the pids, sysv ipc and mount points
 
16
are virtualized and isolated. The other system resources are
 
17
shared across containers, until they are explicitly defined in
 
18
the configuration file. For example, if there is no network
 
19
configuration, the network will be shared between the creator of
 
20
the container and the container itself, but if the network is
 
21
specified, a new network stack is created for the container and
 
22
the container can no longer use the network of its ancestor.
 
23
.PP
 
24
The configuration file defines the different system resources to
 
25
be assigned for the container. At present, the utsname, the
 
26
network, the mount points, the root file system and the control
 
27
groups are supported.
 
28
.PP
 
29
Each option in the configuration file has the form \fBkey
 
30
= value\fR fitting in one line. The '#' character means
 
31
the line is a comment.
 
32
.SS "ARCHITECTURE"
 
33
.PP
 
34
Allows to set the architecture for the container. For example,
 
35
set a 32bits architecture for a container running 32bits
 
36
binaries on a 64bits host. That fix the container scripts
 
37
which rely on the architecture to do some work like
 
38
downloading the packages.
 
39
.TP
 
40
\fB     lxc.arch \fR
 
41
Specify the architecture for the container.
 
42
 
 
43
Valid options are
 
44
\fBx86\fR,
 
45
\fBi686\fR,
 
46
\fBx86_64\fR,
 
47
\fBamd64\fR
 
48
.SS "HOSTNAME"
 
49
.PP
 
50
The utsname section defines the hostname to be set for the
 
51
container. That means the container can set its own hostname
 
52
without changing the one from the system. That makes the
 
53
hostname private for the container.
 
54
.TP
 
55
\fB     lxc.utsname \fR
 
56
specify the hostname for the container
 
57
.SS "NETWORK"
 
58
.PP
 
59
The network section defines how the network is virtualized in
 
60
the container. The network virtualization acts at layer
 
61
two. In order to use the network virtualization, parameters
 
62
must be specified to define the network interfaces of the
 
63
container. Several virtual interfaces can be assigned and used
 
64
in a container even if the system has only one physical
 
65
network interface.
 
66
.TP
 
67
\fB     lxc.network.type \fR
 
68
specify what kind of network virtualization to be used
 
69
for the container. Each time
 
70
a \fBlxc.network.type\fR field is found a new
 
71
round of network configuration begins. In this way,
 
72
several network virtualization types can be specified
 
73
for the same container, as well as assigning several
 
74
network interfaces for one container. The different
 
75
virtualization types can be:
 
76
 
 
77
\fBempty:\fR will create only the loopback
 
78
interface.
 
79
 
 
80
\fBveth:\fR a peer network device is created
 
81
with one side assigned to the container and the other
 
82
side is attached to a bridge specified by
 
83
the \fBlxc.network.link\fR\&. If the bridge is
 
84
not specified, then the veth pair device will be created
 
85
but not attached to any bridge. Otherwise, the bridge
 
86
has to be setup before on the
 
87
system, \fBlxc\fR won't handle any
 
88
configuration outside of the container.  By
 
89
default \fBlxc\fR choose a name for the
 
90
network device belonging to the outside of the
 
91
container, this name is handled
 
92
by \fBlxc\fR, but if you wish to handle
 
93
this name yourself, you can tell \fBlxc\fR
 
94
to set a specific name with
 
95
the \fBlxc.network.veth.pair\fR option.
 
96
 
 
97
\fBvlan:\fR a vlan interface is linked with
 
98
the interface specified by
 
99
the \fBlxc.network.link\fR and assigned to
 
100
the container. The vlan identifier is specified with the
 
101
option \fBlxc.network.vlan.id\fR\&.
 
102
 
 
103
\fBmacvlan:\fR a macvlan interface is linked
 
104
with the interface specified by
 
105
the \fBlxc.network.link\fR and assigned to
 
106
the container.
 
107
\fBlxc.network.macvlan.mode\fR specifies the
 
108
mode the macvlan will use to communicate between
 
109
different macvlan on the same upper device. The accepted
 
110
modes are \fBprivate\fR, the device never
 
111
communicates with any other device on the same upper_dev (default),
 
112
\fBvepa\fR, the new Virtual Ethernet Port
 
113
Aggregator (VEPA) mode, it assumes that the adjacent
 
114
bridge returns all frames where both source and
 
115
destination are local to the macvlan port, i.e. the
 
116
bridge is set up as a reflective relay.  Broadcast
 
117
frames coming in from the upper_dev get flooded to all
 
118
macvlan interfaces in VEPA mode, local frames are not
 
119
delivered locallay, or \fBbridge\fR, it
 
120
provides the behavior of a simple bridge between
 
121
different macvlan interfaces on the same port. Frames
 
122
from one interface to another one get delivered directly
 
123
and are not sent out externally. Broadcast frames get
 
124
flooded to all other bridge ports and to the external
 
125
interface, but when they come back from a reflective
 
126
relay, we don't deliver them again.  Since we know all
 
127
the MAC addresses, the macvlan bridge mode does not
 
128
require learning or STP like the bridge module does.
 
129
 
 
130
\fBphys:\fR an already existing interface
 
131
specified by the \fBlxc.network.link\fR is
 
132
assigned to the container.
 
133
.TP
 
134
\fB     lxc.network.flags \fR
 
135
specify an action to do for the
 
136
network.
 
137
 
 
138
\fBup:\fR activates the interface.
 
139
.TP
 
140
\fB     lxc.network.link \fR
 
141
specify the interface to be used for real network
 
142
traffic.
 
143
.TP
 
144
\fB     lxc.network.name \fR
 
145
the interface name is dynamically allocated, but if
 
146
another name is needed because the configuration files
 
147
being used by the container use a generic name,
 
148
eg. eth0, this option will rename the interface in the
 
149
container.
 
150
.TP
 
151
\fB     lxc.network.hwaddr \fR
 
152
the interface mac address is dynamically allocated by
 
153
default to the virtual interface, but in some cases,
 
154
this is needed to resolve a mac address conflict or to
 
155
always have the same link-local ipv6 address
 
156
.TP
 
157
\fB     lxc.network.ipv4 \fR
 
158
specify the ipv4 address to assign to the virtualized
 
159
interface. Several lines specify several ipv4 addresses.
 
160
The address is in format x.y.z.t/m,
 
161
eg. 192.168.1.123/24. The broadcast address should be
 
162
specified on the same line, right after the ipv4
 
163
address.
 
164
.TP
 
165
\fB     lxc.network.ipv4.gateway \fR
 
166
specify the ipv4 address to use as the gateway inside the
 
167
container. The address is in format x.y.z.t, eg.
 
168
192.168.1.123.
 
169
Can also have the special value \fBauto\fR,
 
170
which means to take the primary address from the bridge
 
171
interface (as specified by the
 
172
\fBlxc.network.link\fR option) and use that as
 
173
the gateway. \fBauto\fR is only available when
 
174
using the \fBveth\fR and
 
175
\fBmacvlan\fR network types.
 
176
.TP
 
177
\fB     lxc.network.ipv6 \fR
 
178
specify the ipv6 address to assign to the virtualized
 
179
interface. Several lines specify several ipv6 addresses.
 
180
The address is in format x::y/m,
 
181
eg. 2003:db8:1:0:214:1234:fe0b:3596/64
 
182
.TP
 
183
\fB     lxc.network.ipv6.gateway \fR
 
184
specify the ipv6 address to use as the gateway inside the
 
185
container. The address is in format x::y,
 
186
eg. 2003:db8:1:0::1
 
187
Can also have the special value \fBauto\fR,
 
188
which means to take the primary address from the bridge
 
189
interface (as specified by the
 
190
\fBlxc.network.link\fR option) and use that as
 
191
the gateway. \fBauto\fR is only available when
 
192
using the \fBveth\fR and
 
193
\fBmacvlan\fR network types.
 
194
.TP
 
195
\fB     lxc.network.script.up \fR
 
196
add a configuration option to specify a script to be
 
197
executed after creating and configuring the network used
 
198
from the host side. The following arguments are passed
 
199
to the script: container name and config section name
 
200
(net) Additional arguments depend on the config section
 
201
employing a script hook; the following are used by the
 
202
network system: execution context (up), network type
 
203
(empty/veth/macvlan/phys), Depending on the network
 
204
type, other arguments may be passed:
 
205
veth/macvlan/phys. And finally (host-sided) device name.
 
206
.SS "NEW PSEUDO TTY INSTANCE (DEVPTS)"
 
207
.PP
 
208
For stricter isolation the container can have its own private
 
209
instance of the pseudo tty.
 
210
.TP
 
211
\fB     lxc.pts \fR
 
212
If set, the container will have a new pseudo tty
 
213
instance, making this private to it. The value specifies
 
214
the maximum number of pseudo ttys allowed for a pts
 
215
instance (this limitation is not implemented yet).
 
216
.SS "CONTAINER SYSTEM CONSOLE"
 
217
.PP
 
218
If the container is configured with a root filesystem and the
 
219
inittab file is setup to use the console, you may want to specify
 
220
where goes the output of this console.
 
221
.TP
 
222
\fB     lxc.console \fR
 
223
Specify a path to a file where the console output will
 
224
be written. The keyword 'none' will simply disable the
 
225
console. This is dangerous once if have a rootfs with a
 
226
console device file where the application can write, the
 
227
messages will fall in the host.
 
228
.SS "CONSOLE THROUGH THE TTYS"
 
229
.PP
 
230
If the container is configured with a root filesystem and the
 
231
inittab file is setup to launch a getty on the ttys. This
 
232
option will specify the number of ttys to be available for the
 
233
container. The number of getty in the inittab file of the
 
234
container should not be greater than the number of ttys
 
235
specified in this configuration file, otherwise the excess
 
236
getty sessions will die and respawn indefinitly giving
 
237
annoying messages on the console.
 
238
.TP
 
239
\fB     lxc.tty \fR
 
240
Specify the number of tty to make available to the
 
241
container.
 
242
.SS "MOUNT POINTS"
 
243
.PP
 
244
The mount points section specifies the different places to be
 
245
mounted. These mount points will be private to the container
 
246
and won't be visible by the processes running outside of the
 
247
container. This is useful to mount /etc, /var or /home for
 
248
examples.
 
249
.TP
 
250
\fB     lxc.mount \fR
 
251
specify a file location in
 
252
the \fIfstab\fR format, containing the
 
253
mount informations. If the rootfs is an image file or a
 
254
device block and the fstab is used to mount a point
 
255
somewhere in this rootfs, the path of the rootfs mount
 
256
point should be prefixed with the
 
257
\fI${libdir}/lxc/rootfs\fR default path or
 
258
the value of \fBlxc.rootfs.mount\fR if
 
259
specified.
 
260
.TP
 
261
\fB     lxc.mount.entry \fR
 
262
specify a mount point corresponding to a line in the
 
263
fstab format.
 
264
.SS "ROOT FILE SYSTEM"
 
265
.PP
 
266
The root file system of the container can be different than that
 
267
of the host system.
 
268
.TP
 
269
\fB     lxc.rootfs \fR
 
270
specify the root file system for the container. It can
 
271
be an image file, a directory or a block device. If not
 
272
specified, the container shares its root file system
 
273
with the host.
 
274
.TP
 
275
\fB     lxc.rootfs.mount \fR
 
276
where to recursively bind \fBlxc.rootfs\fR
 
277
before pivoting.  This is to ensure success of the
 
278
\fBpivot_root\fR(8)
 
279
syscall.  Any directory suffices, the default should
 
280
generally work.
 
281
.TP
 
282
\fB     lxc.pivotdir \fR
 
283
where to pivot the original root file system under
 
284
\fBlxc.rootfs\fR, specified relatively to
 
285
that.  The default is \fImnt\fR\&.
 
286
It is created if necessary, and also removed after
 
287
unmounting everything from it during container setup.
 
288
.SS "CONTROL GROUP"
 
289
.PP
 
290
The control group section contains the configuration for the
 
291
different subsystem. \fBlxc\fR does not check the
 
292
correctness of the subsystem name. This has the disadvantage
 
293
of not detecting configuration errors until the container is
 
294
started, but has the advantage of permitting any future
 
295
subsystem.
 
296
.TP
 
297
\fB     lxc.cgroup.[subsystem name] \fR
 
298
specify the control group value to be set.  The
 
299
subsystem name is the literal name of the control group
 
300
subsystem.  The permitted names and the syntax of their
 
301
values is not dictated by LXC, instead it depends on the
 
302
features of the Linux kernel running at the time the
 
303
container is started,
 
304
eg. \fBlxc.cgroup.cpuset.cpus\fR
 
305
.SS "CAPABILITIES"
 
306
.PP
 
307
The capabilities can be dropped in the container if this one
 
308
is run as root.
 
309
.TP
 
310
\fB     lxc.cap.drop \fR
 
311
Specify the capability to be dropped in the container. A
 
312
single line defining several capabilities with a space
 
313
separation is allowed. The format is the lower case of
 
314
the capability definition without the "CAP_" prefix,
 
315
eg. CAP_SYS_MODULE should be specified as
 
316
sys_module. See
 
317
\fBcapabilities\fR(7),
 
318
.SH "EXAMPLES"
 
319
.PP
 
320
In addition to the few examples given below, you will find
 
321
some other examples of configuration file in /usr/share/doc/lxc/examples
 
322
.SS "NETWORK"
 
323
.PP
 
324
This configuration sets up a container to use a veth pair
 
325
device with one side plugged to a bridge br0 (which has been
 
326
configured before on the system by the administrator). The
 
327
virtual network device visible in the container is renamed to
 
328
eth0.
 
329
 
 
330
.nf
 
331
        lxc.utsname = myhostname
 
332
        lxc.network.type = veth
 
333
        lxc.network.flags = up
 
334
        lxc.network.link = br0
 
335
        lxc.network.name = eth0
 
336
        lxc.network.hwaddr = 4a:49:43:49:79:bf
 
337
        lxc.network.ipv4 = 1.2.3.5/24 1.2.3.255
 
338
        lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 
339
      
 
340
.fi
 
341
.SS "CONTROL GROUP"
 
342
.PP
 
343
This configuration will setup several control groups for
 
344
the application, cpuset.cpus restricts usage of the defined cpu,
 
345
cpus.share prioritize the control group, devices.allow makes
 
346
usable the specified devices.
 
347
 
 
348
.nf
 
349
        lxc.cgroup.cpuset.cpus = 0,1
 
350
        lxc.cgroup.cpu.shares = 1234
 
351
        lxc.cgroup.devices.deny = a
 
352
        lxc.cgroup.devices.allow = c 1:3 rw
 
353
        lxc.cgroup.devices.allow = b 8:0 rw
 
354
      
 
355
.fi
 
356
.SS "COMPLEX CONFIGURATION"
 
357
.PP
 
358
This example show a complex configuration making a complex
 
359
network stack, using the control groups, setting a new hostname,
 
360
mounting some locations and a changing root file system.
 
361
 
 
362
.nf
 
363
        lxc.utsname = complex
 
364
        lxc.network.type = veth
 
365
        lxc.network.flags = up
 
366
        lxc.network.link = br0
 
367
        lxc.network.hwaddr = 4a:49:43:49:79:bf
 
368
        lxc.network.ipv4 = 1.2.3.5/24 1.2.3.255
 
369
        lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 
370
        lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
 
371
        lxc.network.type = macvlan
 
372
        lxc.network.flags = up
 
373
        lxc.network.link = eth0
 
374
        lxc.network.hwaddr = 4a:49:43:49:79:bd
 
375
        lxc.network.ipv4 = 1.2.3.4/24
 
376
        lxc.network.ipv4 = 192.168.10.125/24
 
377
        lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
 
378
        lxc.network.type = phys
 
379
        lxc.network.flags = up
 
380
        lxc.network.link = dummy0
 
381
        lxc.network.hwaddr = 4a:49:43:49:79:ff
 
382
        lxc.network.ipv4 = 1.2.3.6/24
 
383
        lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
 
384
        lxc.cgroup.cpuset.cpus = 0,1
 
385
        lxc.cgroup.cpu.shares = 1234
 
386
        lxc.cgroup.devices.deny = a
 
387
        lxc.cgroup.devices.allow = c 1:3 rw
 
388
        lxc.cgroup.devices.allow = b 8:0 rw
 
389
        lxc.mount = /etc/fstab.complex
 
390
        lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
 
391
        lxc.rootfs = /mnt/rootfs.complex
 
392
        lxc.cap.drop = sys_module mknod setuid net_raw
 
393
        lxc.cap.drop = mac_override
 
394
      
 
395
.fi
 
396
.SH "SEE ALSO"
 
397
.PP
 
398
\fBchroot\fR(1),
 
399
\fBpivot_root\fR(8),
 
400
\fB\fIfstab\fB\fR(5)
 
401
.SH "SEE ALSO"
 
402
.PP
 
403
\fBlxc\fR(1),
 
404
\fBlxc-create\fR(1),
 
405
\fBlxc-destroy\fR(1),
 
406
\fBlxc-start\fR(1),
 
407
\fBlxc-stop\fR(1),
 
408
\fBlxc-execute\fR(1),
 
409
\fBlxc-kill\fR(1),
 
410
\fBlxc-console\fR(1),
 
411
\fBlxc-monitor\fR(1),
 
412
\fBlxc-wait\fR(1),
 
413
\fBlxc-cgroup\fR(1),
 
414
\fBlxc-ls\fR(1),
 
415
\fBlxc-ps\fR(1),
 
416
\fBlxc-info\fR(1),
 
417
\fBlxc-freeze\fR(1),
 
418
\fBlxc-unfreeze\fR(1),
 
419
\fBlxc-attach\fR(1),
 
420
\fBlxc.conf\fR(5)
 
421
.SH "AUTHOR"
 
422
.PP
 
423
Daniel Lezcano <daniel.lezcano@free.fr>