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