« back to all changes in this revision
Viewing changes to doc/lxc.conf.sgml.in
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Guido Trotter
- Date: 2009-04-29 17:49:13 UTC
- Revision ID: james.westby@ubuntu.com-20090429174913-jvahs1ykizqtodje
Tags: upstream-0.6.2
Import upstream version 0.6.2
- files added:
- config
- doc
- etc
- scripts
- src
- src/lxc
- test
added
removed
doc/lxc.conf.sgml.in
1
<!--
2
3
lxc: linux Container library
4
5
(C) Copyright IBM Corp. 2007, 2008
6
7
Authors:
8
Daniel Lezcano <dlezcano at fr.ibm.com>
9
10
This library is free software; you can redistribute it and/or
11
modify it under the terms of the GNU Lesser General Public
12
License as published by the Free Software Foundation; either
13
version 2.1 of the License, or (at your option) any later version.
14
15
This library is distributed in the hope that it will be useful,
16
but WITHOUT ANY WARRANTY; without even the implied warranty of
17
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18
Lesser General Public License for more details.
19
20
You should have received a copy of the GNU Lesser General Public
21
License along with this library; if not, write to the Free Software
22
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
23
24
-->
25
26
<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
27
28
<refentry>
29
30
<docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
31
32
<refmeta>
33
<refentrytitle>lxc.conf</refentrytitle>
34
<manvolnum>5</manvolnum>
35
</refmeta>
36
37
<refnamediv>
38
<refname>lxc.conf</refname>
39
40
<refpurpose>
41
linux container configuration file
42
</refpurpose>
43
</refnamediv>
44
45
<refsect1>
46
<title>Description</title>
47
48
<para>
49
The linux containers (<command>lxc</command>) are always created
50
before being used. This creation defines a set of system
51
resources to be virtualized / isolated when a process is using
52
the container. By default, the pids, sysv ipc and mount points
53
are virtualized and isolated. The other system resources are
54
shared across containers, until they are explicitly defined in
55
the configuration file. For example, if there is no network
56
configuration, the network will be shared between the creator of
57
the container and the container itself, but if the network is
58
specified, a new network stack is created for the container and
59
the container can no longer use the network of its ancestor.
60
</para>
61
62
<para>
63
The configuration file defines the different system resources to
64
be assigned for the container. At present, the utsname, the
65
network, the mount points, the root file system and the control
66
groups are supported.
67
</para>
68
69
<para>
70
Each option in the configuration file has the form <command>key
71
= value</command> fitting in one line. The '#' caracter means
72
the line is a comment.
73
</para>
74
75
<refsect2>
76
<title>Hostname</title>
77
<para>
78
The utsname section defines the hostname to be set for the
79
container. That means the container can set its own hostname
80
without changing the one from the system. That makes the
81
hostname private for the container.
82
</para>
83
<variablelist>
84
<varlistentry>
85
<term>
86
<option>lxc.utsname</option>
87
</term>
88
<listitem>
89
<para>
90
specify the hostname for the container
91
</para>
92
</listitem>
93
</varlistentry>
94
</variablelist>
95
</refsect2>
96
97
<refsect2>
98
<title>Network</title>
99
<para>
100
The network section defines how the network is virtualized in
101
the container. The network virtualization acts at the layer
102
two, so in order to use the network, a few information should
103
be specified to define the network interfaces to be used by
104
the container. Several virtual interfaces can be assigned and
105
used in a container either if the system has only one physical
106
network interface.
107
</para>
108
<variablelist>
109
<varlistentry>
110
<term>
111
<option>lxc.network.type</option>
112
</term>
113
<listitem>
114
<para>
115
specify what kind of network virtualization to be used
116
for the container. Each time
117
a <option>lxc.network.type</option> field is found a new
118
round of network configuration begins. By this way
119
several network virtualization can be specified for the
120
same container, as well as assigning several network
121
interfaces for one container. The different
122
virtualization types can be:
123
</para>
124
125
<para>
126
<option>empty:</option> a new network stack is created
127
for the container, but it will not contain any network
128
interface.
129
</para>
130
131
<para>
132
<option>veth:</option> a new network stack is created, a
133
peer network device is created with one side assigned to
134
the container and the other side attached to a bridge
135
specified by the <option>lxc.network.link</option>. The
136
bridge has to be setup before on the
137
system, <command>lxc</command> won't handle
138
configuration outside of the container.
139
</para>
140
141
<para>
142
<option>macvlan:</option> a new network stack is
143
created, a macvlan interface is linked with the
144
interface specified by
145
the <option>lxc.network.link</option> and assigned to
146
the container.
147
</para>
148
149
<para>
150
<option>phys:</option> a new network stack is created
151
and the interface specified by
152
the <option>lxc.network.link</option> is assigned to the
153
container.
154
</para>
155
</listitem>
156
</varlistentry>
157
158
<varlistentry>
159
<term>
160
<option>lxc.network.flags</option>
161
</term>
162
<listitem>
163
<para>
164
specify an action to do for the
165
network.
166
</para>
167
168
<para><option>up:</option> activates the interface.
169
</para>
170
</listitem>
171
</varlistentry>
172
173
<varlistentry>
174
<term>
175
<option>lxc.network.link</option>
176
</term>
177
<listitem>
178
<para>
179
specify the interface to be used for real network
180
traffic.
181
</para>
182
</listitem>
183
</varlistentry>
184
185
<varlistentry>
186
<term>
187
<option>lxc.network.name</option>
188
</term>
189
<listitem>
190
<para>
191
the interface name is dynamically allocated, but if an
192
other name is needed because the configuration files
193
being used by the container use a generic name,
194
eg. eth0, this option will rename the interface in the
195
container.
196
</para>
197
</listitem>
198
</varlistentry>
199
200
<varlistentry>
201
<term>
202
<option>lxc.network.hwaddr</option>
203
</term>
204
<listitem>
205
<para>
206
the interface mac address is dynamically allocated by
207
default to the virtual interface, but in some case, this
208
is needed to resolve a mac address conflict or to have
209
always the same link-locak ipv6 address.
210
</para>
211
</listitem>
212
</varlistentry>
213
214
<varlistentry>
215
<term>
216
<option>lxc.network.ipv4</option>
217
</term>
218
<listitem>
219
<para>
220
specify the ipv4 address to assign to the virtualized
221
interface. Several lines specify several ipv4 addresses.
222
The address is in format x.y.z.t/m,
223
eg. 192.168.1.123/24.
224
</para>
225
</listitem>
226
</varlistentry>
227
228
<varlistentry>
229
<term>
230
<option>lxc.network.ipv6</option>
231
</term>
232
<listitem>
233
<para>
234
specify the ipv6 address to assign to the virtualized
235
interface. Several lines specify several ipv6 addresses.
236
The address is in format x::y/m,
237
eg. 2003:db8:1:0:214:1234:fe0b:3596/64
238
</para>
239
</listitem>
240
</varlistentry>
241
242
</variablelist>
243
244
</refsect2>
245
246
<refsect2>
247
<title>New pseudo tty instance (devpts)</title>
248
<para>
249
For stricter isolation the container can have its own private
250
instance of the pseudo tty.
251
</para>
252
<variablelist>
253
<varlistentry>
254
<term>
255
<option>lxc.pts</option>
256
</term>
257
<listitem>
258
<para>
259
Specify the container should have a new pseudo tty
260
instance making this private to it. The value specified
261
is ignored for but it is preferable to specify a
262
consistent value representing the maximum number of
263
pseudo tty allowed for pts instance either if it is
264
ignored for now.
265
</para>
266
</listitem>
267
</varlistentry>
268
</variablelist>
269
</refsect2>
270
271
<refsect2>
272
<title>Console through the ttys</title>
273
<para>
274
If the container is configured with a root filesystem and the
275
inittab file is setup to launch a getty on the ttys. This
276
option will specify the number of ttys to be available for the
277
container. The number of getty in the inittab file of the
278
container and the number of tty specified in this
279
configuration file should be equal, otherwise the getty will
280
die and respawn indefinitly giving annoying messages on the
281
console.
282
</para>
283
<variablelist>
284
<varlistentry>
285
<term>
286
<option>lxc.tty</option>
287
</term>
288
<listitem>
289
<para>
290
Specify the number of tty to make available to the
291
container.
292
</para>
293
</listitem>
294
</varlistentry>
295
</variablelist>
296
</refsect2>
297
298
<refsect2>
299
<title>Mount points</title>
300
<para>
301
The mount points section specifies the different places to be
302
mounted. These mount points will be private to the container
303
and won't be visible by the processes running outside of the
304
container. This is useful to mount /etc, /var or /home for
305
examples.
306
</para>
307
<variablelist>
308
<varlistentry>
309
<term>
310
<option>lxc.mount</option>
311
</term>
312
<listitem>
313
<para>
314
specify a file location in
315
the <filename>fstab</filename> format, containing the
316
mount informations.
317
</para>
318
</listitem>
319
</varlistentry>
320
</variablelist>
321
</refsect2>
322
323
<refsect2>
324
<title>Root file system</title>
325
<para>
326
The root file system is the location where the container will
327
chroot.
328
</para>
329
<variablelist>
330
<varlistentry>
331
<term>
332
<option>lxc.rootfs</option>
333
</term>
334
<listitem>
335
<para>
336
specify a file location containing the new file tree for
337
a root file system.
338
</para>
339
</listitem>
340
</varlistentry>
341
</variablelist>
342
</refsect2>
343
344
<refsect2>
345
<title>Control group</title>
346
<para>
347
The control group section contains the configuration for the
348
different subsystem. <command>lxc</command> does not check the
349
correctness of the subsystem name. This has the inconvenient
350
to have the error being detected at runtime, but the advantage
351
to support any future subsystem.
352
</para>
353
<variablelist>
354
<varlistentry>
355
<term>
356
<option>lxc.cgroup.[subsystem name]</option>
357
</term>
358
<listitem>
359
<para>
360
specify the control group value to be set. This field is
361
the identifier to tell the following keyword is the
362
literal name of the control group subsystem,
363
eg. <option>lxc.cgroup.cpuset.cpus</option>
364
</para>
365
</listitem>
366
</varlistentry>
367
</variablelist>
368
</refsect2>
369
370
</refsect1>
371
372
<refsect1>
373
<title>Examples</title>
374
<refsect2>
375
<title>Network</title>
376
<para>This configuration sets up a container to use a veth pair
377
device with one side plugged to a bridge br0 (which has been
378
configured before on the system by the administrator). The
379
virtual network device visible in the container is renamed to
380
eth0.</para>
381
382
<variablelist>
383
384
<varlistentry>
385
<term>lxc.utsname = myhostname</term>
386
<listitem><para></para></listitem>
387
</varlistentry>
388
389
<varlistentry>
390
<term>lxc.network.type = veth</term>
391
<listitem><para></para></listitem>
392
</varlistentry>
393
394
<varlistentry>
395
<term>lxc.network.flags = up</term>
396
<listitem><para></para></listitem>
397
</varlistentry>
398
399
<varlistentry>
400
<term>lxc.network.link = br0</term>
401
<listitem><para></para></listitem>
402
</varlistentry>
403
404
<varlistentry>
405
<term>lxc.network.name = eth0</term>
406
<listitem><para></para></listitem>
407
</varlistentry>
408
409
<varlistentry>
410
<term>lxc.network.hwaddr = 4a:49:43:49:79:bf</term>
411
<listitem><para></para></listitem>
412
</varlistentry>
413
414
<varlistentry>
415
<term>lxc.network.ipv4 = 1.2.3.5/24</term>
416
<listitem><para></para></listitem>
417
</varlistentry>
418
419
<varlistentry>
420
<term>lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597</term>
421
<listitem><para></para></listitem>
422
</varlistentry>
423
424
</variablelist>
425
426
</refsect2>
427
428
<refsect2>
429
<title>Control group</title>
430
<para>This configuration will setup several control groups for
431
the application, cpuset.cpus restricts usage of the defined cpu,
432
cpus.share prioritize the control group, devices.allow makes
433
usable the specified devices.</para>
434
435
<variablelist>
436
<varlistentry>
437
<term>lxc.cgroup.cpuset.cpus = 0,1</term>
438
<listitem><para></para></listitem>
439
</varlistentry>
440
441
<varlistentry>
442
<term>lxc.cgroup.cpu.shares = 1234</term>
443
<listitem><para></para></listitem>
444
</varlistentry>
445
446
<varlistentry>
447
<term>lxc.cgroup.devices.deny = a</term>
448
<listitem><para></para></listitem>
449
</varlistentry>
450
451
<varlistentry>
452
<term>lxc.cgroup.devices.allow = c 1:3 rw</term>
453
<listitem><para></para></listitem>
454
</varlistentry>
455
456
<varlistentry>
457
<term>lxc.cgroup.devices.allow = b 8:0 rw</term>
458
<listitem><para></para></listitem>
459
</varlistentry>
460
</variablelist>
461
462
</refsect2>
463
464
<refsect2>
465
<title>Complex configuration</title>
466
<para>This example show a complex configuration making a complex
467
network stack, using the control groups, setting a new hostname,
468
mounting some locations and a changing the root file
469
system.</para>
470
471
<variablelist>
472
<varlistentry>
473
<term>lxc.utsname = complex</term>
474
<listitem><para></para></listitem>
475
</varlistentry>
476
<varlistentry>
477
<term>lxc.network.type = veth</term>
478
<listitem><para></para></listitem>
479
</varlistentry>
480
<varlistentry>
481
<term>lxc.network.flags = up</term>
482
<listitem><para></para></listitem>
483
</varlistentry>
484
<varlistentry>
485
<term>lxc.network.link = br0</term>
486
<listitem><para></para></listitem>
487
</varlistentry>
488
<varlistentry>
489
<term>lxc.network.hwaddr = 4a:49:43:49:79:bf</term>
490
<listitem><para></para></listitem>
491
</varlistentry>
492
<varlistentry>
493
<term>lxc.network.ipv4 = 1.2.3.5/24</term>
494
<listitem><para></para></listitem>
495
</varlistentry>
496
<varlistentry>
497
<term>lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597</term>
498
<listitem><para></para></listitem>
499
</varlistentry>
500
<varlistentry>
501
<term>lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588</term>
502
<listitem><para></para></listitem>
503
</varlistentry>
504
<varlistentry>
505
<term>lxc.network.type = macvlan</term>
506
<listitem><para></para></listitem>
507
</varlistentry>
508
<varlistentry>
509
<term>lxc.network.flags = up</term>
510
<listitem><para></para></listitem>
511
</varlistentry>
512
<varlistentry>
513
<term>lxc.network.link = eth0</term>
514
<listitem><para></para></listitem>
515
</varlistentry>
516
<varlistentry>
517
<term>lxc.network.hwaddr = 4a:49:43:49:79:bd</term>
518
<listitem><para></para></listitem>
519
</varlistentry>
520
<varlistentry>
521
<term>lxc.network.ipv4 = 1.2.3.4/24</term>
522
<listitem><para></para></listitem>
523
</varlistentry>
524
<varlistentry>
525
<term>lxc.network.ipv4 = 192.168.10.125/24</term>
526
<listitem><para></para></listitem>
527
</varlistentry>
528
<varlistentry>
529
<term>lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596</term>
530
<listitem><para></para></listitem>
531
</varlistentry>
532
<varlistentry>
533
<term>lxc.network.type = phys</term>
534
<listitem><para></para></listitem>
535
</varlistentry>
536
<varlistentry>
537
<term>lxc.network.flags = up</term>
538
<listitem><para></para></listitem>
539
</varlistentry>
540
<varlistentry>
541
<term>lxc.network.link = dummy0</term>
542
<listitem><para></para></listitem>
543
</varlistentry>
544
<varlistentry>
545
<term>lxc.network.hwaddr = 4a:49:43:49:79:ff</term>
546
<listitem><para></para></listitem>
547
</varlistentry>
548
<varlistentry>
549
<term>lxc.network.ipv4 = 1.2.3.6/24</term>
550
<listitem><para></para></listitem>
551
</varlistentry>
552
<varlistentry>
553
<term>lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297</term>
554
<listitem><para></para></listitem>
555
</varlistentry>
556
<varlistentry>
557
<term>lxc.cgroup.cpuset.cpus = 0,1</term>
558
<listitem><para></para></listitem>
559
</varlistentry>
560
<varlistentry>
561
<term>lxc.cgroup.cpu.shares = 1234</term>
562
<listitem><para></para></listitem>
563
</varlistentry>
564
<varlistentry>
565
<term>lxc.cgroup.devices.deny = a</term>
566
<listitem><para></para></listitem>
567
</varlistentry>
568
<varlistentry>
569
<term>lxc.cgroup.devices.allow = c 1:3 rw</term>
570
<listitem><para></para></listitem>
571
</varlistentry>
572
<varlistentry>
573
<term>lxc.cgroup.devices.allow = b 8:0 rw</term>
574
<listitem><para></para></listitem>
575
</varlistentry>
576
<varlistentry>
577
<term>lxc.mount = /etc/fstab.complex</term>
578
<listitem><para></para></listitem>
579
</varlistentry>
580
<varlistentry>
581
<term>lxc.rootfs = /mnt/rootfs.complex</term>
582
<listitem><para></para></listitem>
583
</varlistentry>
584
</variablelist>
585
</refsect2>
586
587
</refsect1>
588
589
<refsect1>
590
<title>See Also</title>
591
<simpara>
592
<citerefentry>
593
<refentrytitle><command>lxc-create</command></refentrytitle>
594
<manvolnum>1</manvolnum>
595
</citerefentry>,
596
597
<citerefentry>
598
<refentrytitle><command>lxc-execute</command></refentrytitle>
599
<manvolnum>1</manvolnum>
600
</citerefentry>,
601
602
<citerefentry>
603
<refentrytitle><command>chroot</command></refentrytitle>
604
<manvolnum>1</manvolnum>
605
</citerefentry>,
606
607
<citerefentry>
608
<refentrytitle><command>pivot_root</command></refentrytitle>
609
<manvolnum>8</manvolnum>
610
</citerefentry>,
611
612
<citerefentry>
613
<refentrytitle><filename>fstab</filename></refentrytitle>
614
<manvolnum>5</manvolnum>
615
</citerefentry>
616
617
</simpara>
618
</refsect1>
619
620
<refsect1>
621
<title>Author</title>
622
<para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
623
</refsect1>
624
625
</refentry>
626
627
<!-- Keep this comment at the end of the file
628
Local variables:
629
mode: sgml
630
sgml-omittag:t
631
sgml-shorttag:t
632
sgml-minimize-attributes:nil
633
sgml-always-quote-attributes:t
634
sgml-indent-step:2
635
sgml-indent-data:t
636
sgml-parent-document:nil
637
sgml-default-dtd-file:nil
638
sgml-exposed-tags:nil
639
sgml-local-catalogs:nil
640
sgml-local-ecat-files:nil
641
End:
642
-->
Loggerhead is a web-based interface for Breezy
Version: 2.0.1