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 "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  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. The broadcast address should be
 295               specified on the same line, right after the ipv4
 296               address.
 297             </para>
 298           </listitem>
 299         </varlistentry>
 300
 301         <varlistentry>
 302           <term>
 303             <option>lxc.network.ipv4.gateway</option>
 304           </term>
 305           <listitem>
 306             <para>
 307               specify the ipv4 address to use as the gateway inside the
 308               container. The address is in format x.y.z.t, eg.
 309               192.168.1.123.
 310
 311               Can also have the special value <option>auto</option>,
 312               which means to take the primary address from the bridge
 313               interface (as specified by the
 314               <option>lxc.network.link</option> option) and use that as
 315               the gateway. <option>auto</option> is only available when
 316               using the <option>veth</option> and
 317               <option>macvlan</option> network types.
 318             </para>
 319           </listitem>
 320         </varlistentry>
 321
 322
 323         <varlistentry>
 324           <term>
 325             <option>lxc.network.ipv6</option>
 326           </term>
 327           <listitem>
 328             <para>
 329               specify the ipv6 address to assign to the virtualized
 330               interface. Several lines specify several ipv6 addresses.
 331               The address is in format x::y/m,
 332               eg. 2003:db8:1:0:214:1234:fe0b:3596/64
 333             </para>
 334           </listitem>
 335         </varlistentry>
 336
 337         <varlistentry>
 338           <term>
 339             <option>lxc.network.ipv6.gateway</option>
 340           </term>
 341           <listitem>
 342             <para>
 343               specify the ipv6 address to use as the gateway inside the
 344               container. The address is in format x::y,
 345               eg. 2003:db8:1:0::1
 346
 347               Can also have the special value <option>auto</option>,
 348               which means to take the primary address from the bridge
 349               interface (as specified by the
 350               <option>lxc.network.link</option> option) and use that as
 351               the gateway. <option>auto</option> is only available when
 352               using the <option>veth</option> and
 353               <option>macvlan</option> network types.
 354             </para>
 355           </listitem>
 356         </varlistentry>
 357
 358         <varlistentry>
 359           <term>
 360             <option>lxc.network.script.up</option>
 361           </term>
 362           <listitem>
 363             <para>
 364               add a configuration option to specify a script to be
 365               executed after creating and configuring the network used
 366               from the host side. The following arguments are passed
 367               to the script: container name and config section name
 368               (net) Additional arguments depend on the config section
 369               employing a script hook; the following are used by the
 370               network system: execution context (up), network type
 371               (empty/veth/macvlan/phys), Depending on the network
 372               type, other arguments may be passed:
 373               veth/macvlan/phys. And finally (host-sided) device name.
 374             </para>
 375           </listitem>
 376         </varlistentry>
 377
 378         <varlistentry>
 379           <term>
 380             <option>lxc.network.script.down</option>
 381           </term>
 382           <listitem>
 383             <para>
 384               add a configuration option to specify a script to be
 385               executed before destroying the network used from the
 386               host side. The following arguments are passed to the
 387               script: container name and config section name (net)
 388               Additional arguments depend on the config section
 389               employing a script hook; the following are used by the
 390               network system: execution context (down), network type
 391               (empty/veth/macvlan/phys), Depending on the network
 392               type, other arguments may be passed:
 393               veth/macvlan/phys. And finally (host-sided) device name.
 394             </para>
 395           </listitem>
 396         </varlistentry>
 397       </variablelist>
 398     </refsect2>
 399
 400     <refsect2>
 401       <title>New pseudo tty instance (devpts)</title>
 402       <para>
 403         For stricter isolation the container can have its own private
 404         instance of the pseudo tty.
 405       </para>
 406       <variablelist>
 407         <varlistentry>
 408           <term>
 409             <option>lxc.pts</option>
 410           </term>
 411           <listitem>
 412             <para>
 413               If set, the container will have a new pseudo tty
 414               instance, making this private to it. The value specifies
 415               the maximum number of pseudo ttys allowed for a pts
 416               instance (this limitation is not implemented yet).
 417             </para>
 418           </listitem>
 419         </varlistentry>
 420       </variablelist>
 421     </refsect2>
 422
 423     <refsect2>
 424       <title>Container system console</title>
 425       <para>
 426         If the container is configured with a root filesystem and the
 427         inittab file is setup to use the console, you may want to specify
 428         where goes the output of this console.
 429       </para>
 430       <variablelist>
 431         <varlistentry>
 432           <term>
 433             <option>lxc.console</option>
 434           </term>
 435           <listitem>
 436             <para>
 437               Specify a path to a file where the console output will
 438               be written. The keyword 'none' will simply disable the
 439               console. This is dangerous once if have a rootfs with a
 440               console device file where the application can write, the
 441               messages will fall in the host.
 442             </para>
 443           </listitem>
 444         </varlistentry>
 445       </variablelist>
 446     </refsect2>
 447
 448     <refsect2>
 449       <title>Console through the ttys</title>
 450       <para>
 451         If the container is configured with a root filesystem and the
 452         inittab file is setup to launch a getty on the ttys. This
 453         option will specify the number of ttys to be available for the
 454         container. The number of getty in the inittab file of the
 455         container should not be greater than the number of ttys
 456         specified in this configuration file, otherwise the excess
 457         getty sessions will die and respawn indefinitly giving
 458         annoying messages on the console.
 459       </para>
 460       <variablelist>
 461         <varlistentry>
 462           <term>
 463             <option>lxc.tty</option>
 464           </term>
 465           <listitem>
 466             <para>
 467               Specify the number of tty to make available to the
 468               container.
 469             </para>
 470           </listitem>
 471         </varlistentry>
 472       </variablelist>
 473     </refsect2>
 474
 475     <refsect2>
 476       <title>Console devices location</title>
 477       <para>
 478         LXC consoles are provided through Unix98 PTYs created on the
 479         host and bind-mounted over the expected devices in the container.
 480         By default, they are bind-mounted over <filename>/dev/console</filename>
 481         and <filename>/dev/ttyN</filename>.  This can prevent package upgrades
 482         in the guest.  Therefore you can specify a directory location (under
 483         <filename>/dev</filename> under which LXC will create the files and
 484         bind-mount over them.  These will then be symbolically linked to
 485         <filename>/dev/console</filename> and <filename>/dev/ttyN</filename>.
 486         A package upgrade can then succeed as it is able to remove and replace
 487         the symbolic links.
 488       </para>
 489       <variablelist>
 490         <varlistentry>
 491           <term>
 492             <option>lxc.devttydir</option>
 493           </term>
 494           <listitem>
 495             <para>
 496               Specify a directory under <filename>/dev</filename>
 497               under which to create the container console devices.
 498             </para>
 499           </listitem>
 500         </varlistentry>
 501       </variablelist>
 502     </refsect2>
 503
 504     <refsect2>
 505       <title>/dev directory</title>
 506       <para>
 507         By default, lxc does nothing with the container's
 508         <filename>/dev</filename>.  This allows the container's
 509         <filename>/dev</filename> to be set up as needed in the container
 510         rootfs.  If lxc.autodev is set to 1, then after mounting the container's
 511         rootfs LXC will mount a fresh tmpfs under <filename>/dev</filename>
 512         (limited to 100k) and fill in a minimal set of initial devices.
 513         This is generally required when starting a container containing
 514         a "systemd" based "init" but may be optional at other times.  Addional
 515         devices in the containers /dev directory may be created through the
 516         use of the <option>lxc.hook.autodev</option> hook.
 517       </para>
 518       <variablelist>
 519         <varlistentry>
 520           <term>
 521             <option>lxc.autodev</option>
 522           </term>
 523           <listitem>
 524             <para>
 525               Set this to 1 to have LXC mount and populate a minimal
 526               <filename>/dev</filename> when starting the container.
 527             </para>
 528           </listitem>
 529         </varlistentry>
 530       </variablelist>
 531     </refsect2>
 532
 533     <refsect2>
 534       <title>Mount points</title>
 535       <para>
 536         The mount points section specifies the different places to be
 537         mounted. These mount points will be private to the container
 538         and won't be visible by the processes running outside of the
 539         container. This is useful to mount /etc, /var or /home for
 540         examples.
 541       </para>
 542       <variablelist>
 543         <varlistentry>
 544           <term>
 545             <option>lxc.mount</option>
 546           </term>
 547           <listitem>
 548             <para>
 549               specify a file location in
 550               the <filename>fstab</filename> format, containing the
 551               mount informations. If the rootfs is an image file or a
 552               device block and the fstab is used to mount a point
 553               somewhere in this rootfs, the path of the rootfs mount
 554               point should be prefixed with the
 555               <filename>@LXCROOTFSMOUNT@</filename> default path or
 556               the value of <option>lxc.rootfs.mount</option> if
 557               specified.
 558             </para>
 559           </listitem>
 560         </varlistentry>
 561
 562         <varlistentry>
 563           <term>
 564             <option>lxc.mount.entry</option>
 565           </term>
 566           <listitem>
 567             <para>
 568               specify a mount point corresponding to a line in the
 569               fstab format.
 570             </para>
 571           </listitem>
 572         </varlistentry>
 573
 574       </variablelist>
 575     </refsect2>
 576
 577     <refsect2>
 578       <title>Root file system</title>
 579       <para>
 580         The root file system of the container can be different than that
 581         of the host system.
 582       </para>
 583       <variablelist>
 584         <varlistentry>
 585           <term>
 586             <option>lxc.rootfs</option>
 587           </term>
 588           <listitem>
 589             <para>
 590               specify the root file system for the container. It can
 591               be an image file, a directory or a block device. If not
 592               specified, the container shares its root file system
 593               with the host.
 594             </para>
 595           </listitem>
 596         </varlistentry>
 597
 598         <varlistentry>
 599           <term>
 600             <option>lxc.rootfs.mount</option>
 601           </term>
 602           <listitem>
 603             <para>
 604               where to recursively bind <option>lxc.rootfs</option>
 605               before pivoting.  This is to ensure success of the
 606               <citerefentry>
 607                 <refentrytitle><command>pivot_root</command></refentrytitle>
 608                 <manvolnum>8</manvolnum>
 609               </citerefentry>
 610               syscall.  Any directory suffices, the default should
 611               generally work.
 612             </para>
 613           </listitem>
 614         </varlistentry>
 615
 616         <varlistentry>
 617           <term>
 618             <option>lxc.pivotdir</option>
 619           </term>
 620           <listitem>
 621             <para>
 622               where to pivot the original root file system under
 623               <option>lxc.rootfs</option>, specified relatively to
 624               that.  The default is <filename>mnt</filename>.
 625               It is created if necessary, and also removed after
 626               unmounting everything from it during container setup.
 627             </para>
 628           </listitem>
 629         </varlistentry>
 630       </variablelist>
 631     </refsect2>
 632
 633     <refsect2>
 634       <title>Control group</title>
 635       <para>
 636         The control group section contains the configuration for the
 637         different subsystem. <command>lxc</command> does not check the
 638         correctness of the subsystem name. This has the disadvantage
 639         of not detecting configuration errors until the container is
 640         started, but has the advantage of permitting any future
 641         subsystem.
 642       </para>
 643       <variablelist>
 644         <varlistentry>
 645           <term>
 646             <option>lxc.cgroup.[subsystem name]</option>
 647           </term>
 648           <listitem>
 649             <para>
 650               specify the control group value to be set.  The
 651               subsystem name is the literal name of the control group
 652               subsystem.  The permitted names and the syntax of their
 653               values is not dictated by LXC, instead it depends on the
 654               features of the Linux kernel running at the time the
 655               container is started,
 656               eg. <option>lxc.cgroup.cpuset.cpus</option>
 657             </para>
 658           </listitem>
 659         </varlistentry>
 660       </variablelist>
 661     </refsect2>
 662
 663     <refsect2>
 664       <title>Capabilities</title>
 665       <para>
 666         The capabilities can be dropped in the container if this one
 667         is run as root.
 668       </para>
 669       <variablelist>
 670         <varlistentry>
 671           <term>
 672             <option>lxc.cap.drop</option>
 673           </term>
 674           <listitem>
 675             <para>
 676               Specify the capability to be dropped in the container. A
 677               single line defining several capabilities with a space
 678               separation is allowed. The format is the lower case of
 679               the capability definition without the "CAP_" prefix,
 680               eg. CAP_SYS_MODULE should be specified as
 681               sys_module. See
 682               <citerefentry>
 683                 <refentrytitle><command>capabilities</command></refentrytitle>
 684                 <manvolnum>7</manvolnum>
 685               </citerefentry>,
 686             </para>
 687           </listitem>
 688         </varlistentry>
 689       </variablelist>
 690     </refsect2>
 691
 692     <refsect2>
 693       <title>UID mappings</title>
 694       <para>
 695         A container can be started in a private user namespace with
 696         user and group id mappings.  For instance, you can map userid
 697         0 in the container to userid 200000 on the host.  The root
 698         user in the container will be privileged in the container,
 699         but unprivileged on the host.  Normally a system container
 700         will want a range of ids, so you would map, for instance,
 701         user and group ids 0 through 20,000 in the container to the
 702         ids 200,000 through 220,000.
 703       </para>
 704       <variablelist>
 705         <varlistentry>
 706           <term>
 707             <option>lxc.id_map</option>
 708           </term>
 709           <listitem>
 710             <para>
 711               Four values must be provided.  First a character, either
 712               'u', or 'g', to specify whether user or group ids are
 713               being mapped.  Next is the first userid as seen in the
 714               user namespace of the container.  Next is the userid as
 715               seen on the host.  Finally, a range indicating the number
 716               of consecutive ids to map.
 717              </para>
 718           </listitem>
 719         </varlistentry>
 720       </variablelist>
 721     </refsect2>
 722
 723     <refsect2>
 724       <title>Startup hooks</title>
 725       <para>
 726         Startup hooks are programs or scripts which can be executed
 727         at various times in a container's lifetime.
 728       </para>
 729       <variablelist>
 730         <varlistentry>
 731           <term>
 732             <option>lxc.hook.pre-start</option>
 733           </term>
 734           <listitem>
 735             <para>
 736               A hook to be run in the host's namespace before the
 737               container ttys, consoles, or mounts are up.
 738             </para>
 739           </listitem>
 740         </varlistentry>
 741       </variablelist>
 742       <variablelist>
 743         <varlistentry>
 744           <term>
 745             <option>lxc.hook.pre-mount</option>
 746           </term>
 747           <listitem>
 748             <para>
 749               A hook to be run in the container's fs namespace but before
 750               the rootfs has been set up.  This allows for manipulation
 751               of the rootfs, i.e. to mount an encrypted filesystem.  Mounts
 752               done in this hook will not be reflected on the host (apart from
 753               mounts propagation), so they will be automatically cleaned up
 754               when the container shuts down.
 755             </para>
 756           </listitem>
 757         </varlistentry>
 758       </variablelist>
 759       <variablelist>
 760         <varlistentry>
 761           <term>
 762             <option>lxc.hook.mount</option>
 763           </term>
 764           <listitem>
 765             <para>
 766               A hook to be run in the container's namespace after
 767               mounting has been done, but before the pivot_root.
 768             </para>
 769           </listitem>
 770         </varlistentry>
 771       </variablelist>
 772       <variablelist>
 773         <varlistentry>
 774           <term>
 775             <option>lxc.hook.autodev</option>
 776           </term>
 777           <listitem>
 778             <para>
 779               A hook to be run in the container's namespace after
 780               mounting has been done and after any mount hooks have
 781               run, but before the pivot_root, if
 782               <option>lxc.autodev</option> == 1.
 783               The purpose of this hook is to assist in populating the
 784               /dev directory of the container when using the autodev
 785               option for systemd based containers.  The container's /dev
 786               directory is relative to the
 787               ${<option>LXC_ROOTFS_MOUNT</option>} environment
 788               variable available when the hook is run.
 789             </para>
 790           </listitem>
 791         </varlistentry>
 792       </variablelist>
 793       <variablelist>
 794         <varlistentry>
 795           <term>
 796             <option>lxc.hook.start</option>
 797           </term>
 798           <listitem>
 799             <para>
 800               A hook to be run in the container's namespace immediately
 801               before executing the container's init.  This requires the
 802               program to be available in the container.
 803             </para>
 804           </listitem>
 805         </varlistentry>
 806       </variablelist>
 807       <variablelist>
 808         <varlistentry>
 809           <term>
 810             <option>lxc.hook.post-stop</option>
 811           </term>
 812           <listitem>
 813             <para>
 814               A hook to be run in the host's namespace after the
 815               container has been shut down.
 816             </para>
 817           </listitem>
 818         </varlistentry>
 819       </variablelist>
 820     </refsect2>
 821
 822     <refsect2>
 823       <title>Startup hooks Environment Variables</title>
 824       <para>
 825         A number of environment variables are made available to the startup
 826         hooks to provide configuration information and assist in the
 827         functioning of the hooks.  Not all variables are valid in all
 828         contexts.  In particular, all paths are relative to the host system
 829         and, as such, not valid during the <option>lxc.hook.start</option> hook.
 830       </para>
 831       <variablelist>
 832         <varlistentry>
 833           <term>
 834             <option>LXC_NAME</option>
 835           </term>
 836           <listitem>
 837             <para>
 838               The LXC name of the container.  Useful for logging messages
 839               in commmon log environments.  [<option>-n</option>]
 840             </para>
 841           </listitem>
 842         </varlistentry>
 843       </variablelist>
 844       <variablelist>
 845         <varlistentry>
 846           <term>
 847             <option>LXC_CONFIG_FILE</option>
 848           </term>
 849           <listitem>
 850             <para>
 851               Host relative path to the container configuration file.  This
 852               gives the container to reference the original, top level,
 853               configuration file for the container in order to locate any
 854               addotional configuration information not otherwise made
 855               available.  [<option>-f</option>]
 856             </para>
 857           </listitem>
 858         </varlistentry>
 859       </variablelist>
 860       <variablelist>
 861         <varlistentry>
 862           <term>
 863             <option>LXC_CONSOLE</option>
 864           </term>
 865           <listitem>
 866             <para>
 867               The path to the console output of the container if not NULL.
 868               [<option>-c</option>] [<option>lxc.console</option>]
 869             </para>
 870           </listitem>
 871         </varlistentry>
 872       </variablelist>
 873       <variablelist>
 874         <varlistentry>
 875           <term>
 876             <option>LXC_CONSOLE_LOGPATH</option>
 877           </term>
 878           <listitem>
 879             <para>
 880               The path to the console log output of the container if not NULL.
 881               [<option>-L</option>]
 882             </para>
 883           </listitem>
 884         </varlistentry>
 885       </variablelist>
 886       <variablelist>
 887         <varlistentry>
 888           <term>
 889             <option>LXC_ROOTFS_MOUNT</option>
 890           </term>
 891           <listitem>
 892             <para>
 893               The mount location to which the container is initially bound.
 894               This will be the host relative path to the container rootfs
 895               for the container instance being started and is where changes
 896               should be made for that instance.
 897               [<option>lxc.rootfs.mount</option>]
 898             </para>
 899           </listitem>
 900         </varlistentry>
 901       </variablelist>
 902       <variablelist>
 903         <varlistentry>
 904           <term>
 905             <option>LXC_ROOTFS_PATH</option>
 906           </term>
 907           <listitem>
 908             <para>
 909               The host relative path to the container root which has been
 910               mounted to the rootfs.mount location.
 911               [<option>lxc.rootfs</option>]
 912             </para>
 913           </listitem>
 914         </varlistentry>
 915       </variablelist>
 916
 917     </refsect2>
 918
 919   </refsect1>
 920
 921   <refsect1>
 922     <title>Examples</title>
 923       <para>
 924         In addition to the few examples given below, you will find
 925         some other examples of configuration file in @DOCDIR@/examples
 926       </para>
 927     <refsect2>
 928       <title>Network</title>
 929       <para>This configuration sets up a container to use a veth pair
 930         device with one side plugged to a bridge br0 (which has been
 931         configured before on the system by the administrator). The
 932         virtual network device visible in the container is renamed to
 933         eth0.</para>
 934       <programlisting>
 935         lxc.utsname = myhostname
 936         lxc.network.type = veth
 937         lxc.network.flags = up
 938         lxc.network.link = br0
 939         lxc.network.name = eth0
 940         lxc.network.hwaddr = 4a:49:43:49:79:bf
 941         lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
 942         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 943       </programlisting>
 944     </refsect2>
 945
 946     <refsect2>
 947       <title>UID/GID mapping</title>
 948       <para>This configuration will map both user and group ids in the
 949         range 0-9999 in the container to the ids 100000-109999 on the host.
 950       </para>
 951       <programlisting>
 952         lxc.id_map = u 0 100000 10000
 953         lxc.id_map = g 0 100000 10000
 954       </programlisting>
 955     </refsect2>
 956
 957     <refsect2>
 958       <title>Control group</title>
 959       <para>This configuration will setup several control groups for
 960       the application, cpuset.cpus restricts usage of the defined cpu,
 961       cpus.share prioritize the control group, devices.allow makes
 962       usable the specified devices.</para>
 963       <programlisting>
 964         lxc.cgroup.cpuset.cpus = 0,1
 965         lxc.cgroup.cpu.shares = 1234
 966         lxc.cgroup.devices.deny = a
 967         lxc.cgroup.devices.allow = c 1:3 rw
 968         lxc.cgroup.devices.allow = b 8:0 rw
 969       </programlisting>
 970     </refsect2>
 971
 972     <refsect2>
 973       <title>Complex configuration</title>
 974       <para>This example show a complex configuration making a complex
 975       network stack, using the control groups, setting a new hostname,
 976       mounting some locations and a changing root file system.</para>
 977       <programlisting>
 978         lxc.utsname = complex
 979         lxc.network.type = veth
 980         lxc.network.flags = up
 981         lxc.network.link = br0
 982         lxc.network.hwaddr = 4a:49:43:49:79:bf
 983         lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
 984         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
 985         lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
 986         lxc.network.type = macvlan
 987         lxc.network.flags = up
 988         lxc.network.link = eth0
 989         lxc.network.hwaddr = 4a:49:43:49:79:bd
 990         lxc.network.ipv4 = 10.2.3.4/24
 991         lxc.network.ipv4 = 192.168.10.125/24
 992         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
 993         lxc.network.type = phys
 994         lxc.network.flags = up
 995         lxc.network.link = dummy0
 996         lxc.network.hwaddr = 4a:49:43:49:79:ff
 997         lxc.network.ipv4 = 10.2.3.6/24
 998         lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
 999         lxc.cgroup.cpuset.cpus = 0,1
1000         lxc.cgroup.cpu.shares = 1234
1001         lxc.cgroup.devices.deny = a
1002         lxc.cgroup.devices.allow = c 1:3 rw
1003         lxc.cgroup.devices.allow = b 8:0 rw
1004         lxc.mount = /etc/fstab.complex
1005         lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
1006         lxc.rootfs = /mnt/rootfs.complex
1007         lxc.cap.drop = sys_module mknod setuid net_raw
1008         lxc.cap.drop = mac_override
1009       </programlisting>
1010     </refsect2>
1011
1012   </refsect1>
1013
1014   <refsect1>
1015     <title>See Also</title>
1016     <simpara>
1017       <citerefentry>
1018         <refentrytitle><command>chroot</command></refentrytitle>
1019         <manvolnum>1</manvolnum>
1020       </citerefentry>,
1021
1022       <citerefentry>
1023         <refentrytitle><command>pivot_root</command></refentrytitle>
1024         <manvolnum>8</manvolnum>
1025       </citerefentry>,
1026
1027       <citerefentry>
1028         <refentrytitle><filename>fstab</filename></refentrytitle>
1029         <manvolnum>5</manvolnum>
1030       </citerefentry>
1031
1032     </simpara>
1033   </refsect1>
1034
1035   &seealso;
1036
1037   <refsect1>
1038     <title>Author</title>
1039     <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
1040   </refsect1>
1041
1042 </refentry>
1043
1044 <!-- Keep this comment at the end of the file
1045 Local variables:
1046 mode: sgml
1047 sgml-omittag:t
1048 sgml-shorttag:t
1049 sgml-minimize-attributes:nil
1050 sgml-always-quote-attributes:t
1051 sgml-indent-step:2
1052 sgml-indent-data:t
1053 sgml-parent-document:nil
1054 sgml-default-dtd-file:nil
1055 sgml-exposed-tags:nil
1056 sgml-local-catalogs:nil
1057 sgml-local-ecat-files:nil
1058 End:
1059 -->