]>
Commit | Line | Data |
---|---|---|
8a67a2b2 | 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 | ||
341a091c | 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 | ||
b0a33c1e | 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 | ||
8a67a2b2 | 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> | |
998dc19a | 356 | <option>lxc.cgroup.[subsystem name]</option> |
8a67a2b2 | 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 | --> |