« back to all changes in this revision
Viewing changes to doc/lxc.conf.5
- browse files at revision 1.1.10
- compare with another revision
- compare with revision 1.1.10
- download diff
- download tarball
- view history from revision 1.1.10
- Committer: Stéphane Graber
- Date: 2011-08-11 18:43:51 UTC
- mto: (3.1.15 sid)
- mto: This revision was merged to the branch mainline in revision 30.
- Revision ID: stgraber@ubuntu.com-20110811184351-xa4c5v0ct5ud45d0
Tags: upstream-0.7.5
Import upstream version 0.7.5
- files added:
- src/lxc/lxc-clone.in
- files removed:
- doc/lxc-cgroup.1
- files modified:
- ChangeLog
added
removed
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" "20 May 2011" "" ""
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.ipv6 \fR
166
specify the ipv6 address to assign to the virtualized
167
interface. Several lines specify several ipv6 addresses.
168
The address is in format x::y/m,
169
eg. 2003:db8:1:0:214:1234:fe0b:3596/64
170
.TP
171
\fB lxc.network.script.up \fR
172
add a configuration option to specify a script to be
173
executed after creating and configuring the network used
174
from the host side. The following arguments are passed
175
to the script: container name and config section name
176
(net) Additional arguments depend on the config section
177
employing a script hook; the following are used by the
178
network system: execution context (up), network type
179
(empty/veth/macvlan/phys), Depending on the network
180
type, other arguments may be passed:
181
veth/macvlan/phys. And finally (host-sided) device name.
182
.SS "NEW PSEUDO TTY INSTANCE (DEVPTS)"
183
.PP
184
For stricter isolation the container can have its own private
185
instance of the pseudo tty.
186
.TP
187
\fB lxc.pts \fR
188
If set, the container will have a new pseudo tty
189
instance, making this private to it. The value specifies
190
the maximum number of pseudo ttys allowed for a pts
191
instance (this limitation is not implemented yet).
192
.SS "CONTAINER SYSTEM CONSOLE"
193
.PP
194
If the container is configured with a root filesystem and the
195
inittab file is setup to use the console, you may want to specify
196
where goes the output of this console.
197
.TP
198
\fB lxc.console \fR
199
Specify a path to a file where the console output will
200
be written.
201
.SS "CONSOLE THROUGH THE TTYS"
202
.PP
203
If the container is configured with a root filesystem and the
204
inittab file is setup to launch a getty on the ttys. This
205
option will specify the number of ttys to be available for the
206
container. The number of getty in the inittab file of the
207
container should not be greater than the number of ttys
208
specified in this configuration file, otherwise the excess
209
getty sessions will die and respawn indefinitly giving
210
annoying messages on the console.
211
.TP
212
\fB lxc.tty \fR
213
Specify the number of tty to make available to the
214
container.
215
.SS "MOUNT POINTS"
216
.PP
217
The mount points section specifies the different places to be
218
mounted. These mount points will be private to the container
219
and won't be visible by the processes running outside of the
220
container. This is useful to mount /etc, /var or /home for
221
examples.
222
.TP
223
\fB lxc.mount \fR
224
specify a file location in
225
the \fIfstab\fR format, containing the
226
mount informations. If the rootfs is an image file or a
227
device block and the fstab is used to mount a point
228
somewhere in this rootfs, the path of the rootfs mount
229
point should be prefixed with the
230
\fI/usr/lib64/lxc/rootfs\fR default path or
231
the value of \fBlxc.rootfs.mount\fR if
232
specified.
233
.TP
234
\fB lxc.mount.entry \fR
235
specify a mount point corresponding to a line in the
236
fstab format.
237
.SS "ROOT FILE SYSTEM"
238
.PP
239
The root file system of the container can be different than that
240
of the host system.
241
.TP
242
\fB lxc.rootfs \fR
243
specify the root file system for the container. It can
244
be an image file, a directory or a block device. If not
245
specified, the container shares its root file system
246
with the host.
247
.TP
248
\fB lxc.rootfs.mount \fR
249
where to recursively bind \fBlxc.rootfs\fR
250
before pivoting. This is to ensure success of the
251
\fBpivot_root\fR(8)
252
syscall. Any directory suffices, the default should
253
generally work.
254
.TP
255
\fB lxc.pivotdir \fR
256
where to pivot the original root file system under
257
\fBlxc.rootfs\fR, specified relatively to
258
that. The default is \fImnt\fR\&.
259
It is created if necessary, and also removed after
260
unmounting everything from it during container setup.
261
.SS "CONTROL GROUP"
262
.PP
263
The control group section contains the configuration for the
264
different subsystem. \fBlxc\fR does not check the
265
correctness of the subsystem name. This has the disadvantage
266
of not detecting configuration errors until the container is
267
started, but has the advantage of permitting any future
268
subsystem.
269
.TP
270
\fB lxc.cgroup.[subsystem name] \fR
271
specify the control group value to be set. The
272
subsystem name is the literal name of the control group
273
subsystem. The permitted names and the syntax of their
274
values is not dictated by LXC, instead it depends on the
275
features of the Linux kernel running at the time the
276
container is started,
277
eg. \fBlxc.cgroup.cpuset.cpus\fR
278
.SS "CAPABILITIES"
279
.PP
280
The capabilities can be dropped in the container if this one
281
is run as root.
282
.TP
283
\fB lxc.cap.drop \fR
284
Specify the capability to be dropped in the container. A
285
single line defining several capabilities with a space
286
separation is allowed. The format is the lower case of
287
the capability definition without the "CAP_" prefix,
288
eg. CAP_SYS_MODULE should be specified as
289
sys_module. See
290
\fBcapabilities\fR(7),
291
.SH "EXAMPLES"
292
.PP
293
In addition to the few examples given below, you will find
294
some other examples of configuration file in /usr/share/doc/lxc/examples
295
.SS "NETWORK"
296
.PP
297
This configuration sets up a container to use a veth pair
298
device with one side plugged to a bridge br0 (which has been
299
configured before on the system by the administrator). The
300
virtual network device visible in the container is renamed to
301
eth0.
302
303
.nf
304
lxc.utsname = myhostname
305
lxc.network.type = veth
306
lxc.network.flags = up
307
lxc.network.link = br0
308
lxc.network.name = eth0
309
lxc.network.hwaddr = 4a:49:43:49:79:bf
310
lxc.network.ipv4 = 1.2.3.5/24 1.2.3.255
311
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
312
313
.fi
314
.SS "CONTROL GROUP"
315
.PP
316
This configuration will setup several control groups for
317
the application, cpuset.cpus restricts usage of the defined cpu,
318
cpus.share prioritize the control group, devices.allow makes
319
usable the specified devices.
320
321
.nf
322
lxc.cgroup.cpuset.cpus = 0,1
323
lxc.cgroup.cpu.shares = 1234
324
lxc.cgroup.devices.deny = a
325
lxc.cgroup.devices.allow = c 1:3 rw
326
lxc.cgroup.devices.allow = b 8:0 rw
327
328
.fi
329
.SS "COMPLEX CONFIGURATION"
330
.PP
331
This example show a complex configuration making a complex
332
network stack, using the control groups, setting a new hostname,
333
mounting some locations and a changing root file system.
334
335
.nf
336
lxc.utsname = complex
337
lxc.network.type = veth
338
lxc.network.flags = up
339
lxc.network.link = br0
340
lxc.network.hwaddr = 4a:49:43:49:79:bf
341
lxc.network.ipv4 = 1.2.3.5/24 1.2.3.255
342
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
343
lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
344
lxc.network.type = macvlan
345
lxc.network.flags = up
346
lxc.network.link = eth0
347
lxc.network.hwaddr = 4a:49:43:49:79:bd
348
lxc.network.ipv4 = 1.2.3.4/24
349
lxc.network.ipv4 = 192.168.10.125/24
350
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
351
lxc.network.type = phys
352
lxc.network.flags = up
353
lxc.network.link = dummy0
354
lxc.network.hwaddr = 4a:49:43:49:79:ff
355
lxc.network.ipv4 = 1.2.3.6/24
356
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
357
lxc.cgroup.cpuset.cpus = 0,1
358
lxc.cgroup.cpu.shares = 1234
359
lxc.cgroup.devices.deny = a
360
lxc.cgroup.devices.allow = c 1:3 rw
361
lxc.cgroup.devices.allow = b 8:0 rw
362
lxc.mount = /etc/fstab.complex
363
lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
364
lxc.rootfs = /mnt/rootfs.complex
365
lxc.cap.drop = sys_module mknod setuid net_raw
366
lxc.cap.drop = mac_override
367
368
.fi
369
.SH "SEE ALSO"
370
.PP
371
\fBchroot\fR(1),
372
\fBpivot_root\fR(8),
373
\fB\fIfstab\fB\fR(5)
374
.SH "SEE ALSO"
375
.PP
376
\fBlxc\fR(1),
377
\fBlxc-create\fR(1),
378
\fBlxc-destroy\fR(1),
379
\fBlxc-start\fR(1),
380
\fBlxc-stop\fR(1),
381
\fBlxc-execute\fR(1),
382
\fBlxc-kill\fR(1),
383
\fBlxc-console\fR(1),
384
\fBlxc-monitor\fR(1),
385
\fBlxc-wait\fR(1),
386
\fBlxc-cgroup\fR(1),
387
\fBlxc-ls\fR(1),
388
\fBlxc-ps\fR(1),
389
\fBlxc-info\fR(1),
390
\fBlxc-freeze\fR(1),
391
\fBlxc-unfreeze\fR(1),
392
\fBlxc.conf\fR(5)
393
.SH "AUTHOR"
394
.PP
395
Daniel Lezcano <daniel.lezcano@free.fr>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1