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 <!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
  29 ]>
  30
  31 <refentry>
  32
  33   <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
  34
  35   <refmeta>
  36     <refentrytitle>lxc.conf</refentrytitle>
  37     <manvolnum>5</manvolnum>
  38   </refmeta>
  39
  40   <refnamediv>
  41     <refname>lxc.conf</refname>
  42
  43     <refpurpose>
  44       linux container configuration file
  45     </refpurpose>
  46   </refnamediv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para>
  52       The linux containers (<command>lxc</command>) are always created
  53       before being used. This creation defines a set of system
  54       resources to be virtualized / isolated when a process is using
  55       the container. By default, the pids, sysv ipc and mount points
  56       are virtualized and isolated. The other system resources are
  57       shared across containers, until they are explicitly defined in
  58       the configuration file. For example, if there is no network
  59       configuration, the network will be shared between the creator of
  60       the container and the container itself, but if the network is
  61       specified, a new network stack is created for the container and
  62       the container can no longer use the network of its ancestor.
  63     </para>
  64
  65     <para>
  66       The configuration file defines the different system resources to
  67       be assigned for the container. At present, the utsname, the
  68       network, the mount points, the root file system and the control
  69       groups are supported.
  70     </para>
  71
  72     <para>
  73       Each option in the configuration file has the form <command>key
  74       = value</command> fitting in one line. The '#' character means
  75       the line is a comment.
  76     </para>
  77
  78     <refsect2>
  79       <title>Hostname</title>
  80       <para>
  81         The utsname section defines the hostname to be set for the
  82         container. That means the container can set its own hostname
  83         without changing the one from the system. That makes the
  84         hostname private for the container.
  85       </para>
  86       <variablelist>
  87         <varlistentry>
  88           <term>
  89             <option>lxc.utsname</option>
  90           </term>
  91           <listitem>
  92             <para>
  93               specify the hostname for the container
  94             </para>
  95           </listitem>
  96         </varlistentry>
  97       </variablelist>
  98     </refsect2>
  99
 100     <refsect2>
 101       <title>Network</title>
 102       <para>
 103         The network section defines how the network is virtualized in
 104         the container. The network virtualization acts at layer
 105         two. In order to use the network virtualization, parameters
 106         must be specified to define the network interfaces of the
 107         container. Several virtual interfaces can be assigned and used
 108         in a container even if the system has only one physical
 109         network interface.
 110       </para>
 111       <variablelist>
 112         <varlistentry>
 113           <term>
 114             <option>lxc.network.type</option>
 115           </term>
 116           <listitem>
 117             <para>
 118               specify what kind of network virtualization to be used
 119               for the container. Each time
 120               a <option>lxc.network.type</option> field is found a new
 121               round of network configuration begins. In this way,
 122               several network virtualization types can be specified
 123               for the same container, as well as assigning several
 124               network interfaces for one container. The different
 125               virtualization types can be:
 126             </para>
 127
 128             <para>
 129               <option>empty:</option> will create only the loopback
 130               interface.
 131             </para>
 132
 133             <para>
 134               <option>veth:</option> a peer network device is created
 135               with one side assigned to the container and the other
 136               side is attached to a bridge specified by
 137               the <option>lxc.network.link</option>. If the bridge is
 138               not specified, then the veth pair device will be created
 139               but not attached to any bridge. Otherwise, the bridge
 140               has to be setup before on the
 141               system, <command>lxc</command> won't handle any
 142               configuration outside of the container.  By
 143               default <command>lxc</command> choose a name for the
 144               network device belonging to the outside of the
 145               container, this name is handled
 146               by <command>lxc</command>, but if you wish to handle
 147               this name yourself, you can tell <command>lxc</command>
 148               to set a specific name with
 149               the <option>lxc.network.veth.pair</option> option.
 150             </para>
 151
 152             <para>
 153               <option>vlan:</option> a vlan interface is linked with
 154               the interface specified by
 155               the <option>lxc.network.link</option> and assigned to
 156               the container. The vlan identifier is specified with the
 157               option <option>lxc.network.vlan.id</option>.
 158             </para>
 159
 160             <para>
 161               <option>macvlan:</option> a macvlan interface is linked
 162               with the interface specified by
 163               the <option>lxc.network.link</option> and assigned to
 164               the container.
 165               <option>lxc.network.macvlan.mode</option> specifies the
 166               mode the macvlan will use to communicate between
 167               different macvlan on the same upper device. The accepted
 168               modes are <option>private</option>, the device never
 169               communicates with any other device on the same upper_dev (default),
 170               <option>vepa</option>, the new Virtual Ethernet Port
 171               Aggregator (VEPA) mode, it assumes that the adjacent
 172               bridge returns all frames where both source and
 173               destination are local to the macvlan port, i.e. the
 174               bridge is set up as a reflective relay.  Broadcast
 175               frames coming in from the upper_dev get flooded to all
 176               macvlan interfaces in VEPA mode, local frames are not
 177               delivered locallay, or <option>bridge</option>, it
 178               provides the behavior of a simple bridge between
 179               different macvlan interfaces on the same port. Frames
 180               from one interface to another one get delivered directly
 181               and are not sent out externally. Broadcast frames get
 182               flooded to all other bridge ports and to the external
 183               interface, but when they come back from a reflective
 184               relay, we don't deliver them again.  Since we know all
 185               the MAC addresses, the macvlan bridge mode does not
 186               require learning or STP like the bridge module does.
 187             </para>
 188
 189             <para>
 190               <option>phys:</option> an already existing interface
 191               specified by the <option>lxc.network.link</option> is
 192               assigned to the container.
 193             </para>
 194           </listitem>
 195           </varlistentry>
 196
 197         <varlistentry>
 198           <term>
 199             <option>lxc.network.flags</option>
 200           </term>
 201           <listitem>
 202             <para>
 203               specify an action to do for the
 204               network.
 205             </para>
 206
 207             <para><option>up:</option> activates the interface.
 208             </para>
 209           </listitem>
 210         </varlistentry>
 211
 212         <varlistentry>
 213           <term>
 214             <option>lxc.network.link</option>
 215           </term>
 216           <listitem>
 217             <para>
 218               specify the interface to be used for real network
 219               traffic.
 220             </para>
 221           </listitem>
 222         </varlistentry>
 223
 224         <varlistentry>
 225           <term>
 226             <option>lxc.network.name</option>
 227           </term>
 228           <listitem>
 229             <para>
 230               the interface name is dynamically allocated, but if
 231               another name is needed because the configuration files
 232               being used by the container use a generic name,
 233               eg. eth0, this option will rename the interface in the
 234               container.
 235             </para>
 236           </listitem>
 237         </varlistentry>
 238
 239         <varlistentry>
 240           <term>
 241             <option>lxc.network.hwaddr</option>
 242           </term>
 243           <listitem>
 244             <para>
 245               the interface mac address is dynamically allocated by
 246               default to the virtual interface, but in some cases,
 247               this is needed to resolve a mac address conflict or to
 248               always have the same link-local ipv6 address
 249             </para>
 250           </listitem>
 251         </varlistentry>
 252
 253         <varlistentry>
 254           <term>
 255             <option>lxc.network.ipv4</option>
 256           </term>
 257           <listitem>
 258             <para>
 259               specify the ipv4 address to assign to the virtualized
 260               interface. Several lines specify several ipv4 addresses.
 261               The address is in format x.y.z.t/m,
 262               eg. 192.168.1.123/24.
 263             </para>
 264           </listitem>
 265         </varlistentry>
 266
 267         <varlistentry>
 268           <term>
 269             <option>lxc.network.ipv6</option>
 270           </term>
 271           <listitem>
 272             <para>
 273               specify the ipv6 address to assign to the virtualized
 274               interface. Several lines specify several ipv6 addresses.
 275               The address is in format x::y/m,
 276               eg. 2003:db8:1:0:214:1234:fe0b:3596/64
 277             </para>
 278           </listitem>
 279         </varlistentry>
 280
 281       </variablelist>
 282
 283     </refsect2>
 284
 285     <refsect2>
 286       <title>New pseudo tty instance (devpts)</title>
 287       <para>
 288         For stricter isolation the container can have its own private
 289         instance of the pseudo tty.
 290       </para>
 291       <variablelist>
 292         <varlistentry>
 293           <term>
 294             <option>lxc.pts</option>
 295           </term>
 296           <listitem>
 297             <para>
 298               If set, the container will have a new pseudo tty
 299               instance, making this private to it. The value specifies
 300               the maximum number of pseudo ttys allowed for a pts
 301               instance (this limitation is not implemented yet).
 302             </para>
 303           </listitem>
 304         </varlistentry>
 305       </variablelist>
 306     </refsect2>
 307
 308     <refsect2>
 309       <title>Console through the ttys</title>
 310       <para>
 311         If the container is configured with a root filesystem and the
 312         inittab file is setup to launch a getty on the ttys. This
 313         option will specify the number of ttys to be available for the
 314         container. The number of getty in the inittab file of the
 315         container should not be greater than the number of ttys
 316         specified in this configuration file, otherwise the excess
 317         getty sessions will die and respawn indefinitly giving
 318         annoying messages on the console.
 319       </para>
 320       <variablelist>
 321         <varlistentry>
 322           <term>
 323             <option>lxc.tty</option>
 324           </term>
 325           <listitem>
 326             <para>
 327               Specify the number of tty to make available to the
 328               container.
 329             </para>
 330           </listitem>
 331         </varlistentry>
 332       </variablelist>
 333     </refsect2>
 334
 335     <refsect2>
 336       <title>Mount points</title>
 337       <para>
 338         The mount points section specifies the different places to be
 339         mounted. These mount points will be private to the container
 340         and won't be visible by the processes running outside of the
 341         container. This is useful to mount /etc, /var or /home for
 342         examples.
 343       </para>
 344       <variablelist>
 345         <varlistentry>
 346           <term>
 347             <option>lxc.mount</option>
 348           </term>
 349           <listitem>
 350             <para>
 351               specify a file location in
 352               the <filename>fstab</filename> format, containing the
 353               mount informations.
 354             </para>
 355           </listitem>
 356         </varlistentry>
 357
 358         <varlistentry>
 359           <term>
 360             <option>lxc.mount.entry</option>
 361           </term>
 362           <listitem>
 363             <para>
 364               specify a mount point corresponding to a line in the
 365               fstab format.
 366             </para>
 367           </listitem>
 368         </varlistentry>
 369
 370       </variablelist>
 371     </refsect2>
 372
 373     <refsect2>
 374       <title>Root file system</title>
 375       <para>
 376         The root file system is the location where the container will
 377         chroot.
 378       </para>
 379       <variablelist>
 380         <varlistentry>
 381           <term>
 382             <option>lxc.rootfs</option>
 383           </term>
 384           <listitem>
 385             <para>
 386               specify a file location containing the new file tree for
 387               a root file system.
 388             </para>
 389           </listitem>
 390         </varlistentry>
 391       </variablelist>
 392     </refsect2>
 393
 394     <refsect2>
 395       <title>Control group</title>
 396       <para>
 397         The control group section contains the configuration for the
 398         different subsystem. <command>lxc</command> does not check the
 399         correctness of the subsystem name. This has the disadvantage
 400         of not detecting configuration errors until the container is
 401         started, but has the advantage of permitting any future
 402         subsystem.
 403       </para>
 404       <variablelist>
 405         <varlistentry>
 406           <term>
 407             <option>lxc.cgroup.[subsystem name]</option>
 408           </term>
 409           <listitem>
 410             <para>
 411               specify the control group value to be set.  The
 412               subsystem name is the literal name of the control group
 413               subsystem.  The permitted names and the syntax of their
 414               values is not dictated by LXC, instead it depends on the
 415               features of the Linux kernel running at the time the
 416               container is started,
 417               eg. <option>lxc.cgroup.cpuset.cpus</option>
 418             </para>
 419           </listitem>
 420         </varlistentry>
 421       </variablelist>
 422     </refsect2>
 423
 424     <refsect2>
 425       <title>Capabilities</title>
 426       <para>
 427         The capabilities can be dropped in the container if this one
 428         is run as root.
 429       </para>
 430       <variablelist>
 431         <varlistentry>
 432           <term>
 433             <option>lxc.cap.drop</option>
 434           </term>
 435           <listitem>
 436             <para>
 437               Specify the capability to be dropped in the container. A
 438               single line defining several capabilities with a space
 439               separation is allowed. The format is the lower case of
 440               the capability definition without the "CAP_" prefix,
 441               eg. CAP_SYS_MODULE should be specified as
 442               sys_module. See
 443               <citerefentry>
 444                 <refentrytitle><command>capabilities</command></refentrytitle>
 445                 <manvolnum>7</manvolnum>
 446               </citerefentry>,
 447             </para>
 448           </listitem>
 449         </varlistentry>
 450       </variablelist>
 451     </refsect2>
 452
 453   </refsect1>
 454
 455   <refsect1>
 456     <title>Examples</title>
 457       <para>
 458         In addition to the few examples given below, you will find
 459         some other examples of configuration file in @DOCDIR@/examples
 460       </para>
 461     <refsect2>
 462       <title>Network</title>
 463       <para>This configuration sets up a container to use a veth pair
 464         device with one side plugged to a bridge br0 (which has been
 465         configured before on the system by the administrator). The
 466         virtual network device visible in the container is renamed to
 467         eth0.</para>
 468       <programlisting>
 469         lxc.utsname = myhostname
 470         lxc.network.type = veth
 471         lxc.network.flags = up
 472         lxc.network.link = br0
 473         lxc.network.name = eth0
 474         lxc.network.hwaddr = 4a:49:43:49:79:bf
 475         lxc.network.ipv4 = 1.2.3.5/24
 476         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 477       </programlisting>
 478     </refsect2>
 479
 480     <refsect2>
 481       <title>Control group</title>
 482       <para>This configuration will setup several control groups for
 483       the application, cpuset.cpus restricts usage of the defined cpu,
 484       cpus.share prioritize the control group, devices.allow makes
 485       usable the specified devices.</para>
 486       <programlisting>
 487         lxc.cgroup.cpuset.cpus = 0,1
 488         lxc.cgroup.cpu.shares = 1234
 489         lxc.cgroup.devices.deny = a
 490         lxc.cgroup.devices.allow = c 1:3 rw
 491         lxc.cgroup.devices.allow = b 8:0 rw
 492       </programlisting>
 493     </refsect2>
 494
 495     <refsect2>
 496       <title>Complex configuration</title>
 497       <para>This example show a complex configuration making a complex
 498       network stack, using the control groups, setting a new hostname,
 499       mounting some locations and a changing root file system.</para>
 500       <programlisting>
 501         lxc.utsname = complex
 502         lxc.network.type = veth
 503         lxc.network.flags = up
 504         lxc.network.link = br0
 505         lxc.network.hwaddr = 4a:49:43:49:79:bf
 506         lxc.network.ipv4 = 1.2.3.5/24
 507         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 508         lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
 509         lxc.network.type = macvlan
 510         lxc.network.flags = up
 511         lxc.network.link = eth0
 512         lxc.network.hwaddr = 4a:49:43:49:79:bd
 513         lxc.network.ipv4 = 1.2.3.4/24
 514         lxc.network.ipv4 = 192.168.10.125/24
 515         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
 516         lxc.network.type = phys
 517         lxc.network.flags = up
 518         lxc.network.link = dummy0
 519         lxc.network.hwaddr = 4a:49:43:49:79:ff
 520         lxc.network.ipv4 = 1.2.3.6/24
 521         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
 522         lxc.cgroup.cpuset.cpus = 0,1
 523         lxc.cgroup.cpu.shares = 1234
 524         lxc.cgroup.devices.deny = a
 525         lxc.cgroup.devices.allow = c 1:3 rw
 526         lxc.cgroup.devices.allow = b 8:0 rw
 527         lxc.mount = /etc/fstab.complex
 528         lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
 529         lxc.rootfs = /mnt/rootfs.complex
 530         lxc.cap.drop = sys_module mknod setuid net_raw
 531         lxc.cap.drop = mac_override
 532       </programlisting>
 533     </refsect2>
 534
 535   </refsect1>
 536
 537   <refsect1>
 538     <title>See Also</title>
 539     <simpara>
 540       <citerefentry>
 541         <refentrytitle><command>chroot</command></refentrytitle>
 542         <manvolnum>1</manvolnum>
 543       </citerefentry>,
 544
 545       <citerefentry>
 546         <refentrytitle><command>pivot_root</command></refentrytitle>
 547         <manvolnum>8</manvolnum>
 548       </citerefentry>,
 549
 550       <citerefentry>
 551         <refentrytitle><filename>fstab</filename></refentrytitle>
 552         <manvolnum>5</manvolnum>
 553       </citerefentry>
 554
 555     </simpara>
 556   </refsect1>
 557
 558   &seealso;
 559
 560   <refsect1>
 561     <title>Author</title>
 562     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
 563   </refsect1>
 564
 565 </refentry>
 566
 567 <!-- Keep this comment at the end of the file
 568 Local variables:
 569 mode: sgml
 570 sgml-omittag:t
 571 sgml-shorttag:t
 572 sgml-minimize-attributes:nil
 573 sgml-always-quote-attributes:t
 574 sgml-indent-step:2
 575 sgml-indent-data:t
 576 sgml-parent-document:nil
 577 sgml-default-dtd-file:nil
 578 sgml-exposed-tags:nil
 579 sgml-local-catalogs:nil
 580 sgml-local-ecat-files:nil
 581 End:
 582 -->