[lxc-devel] [PATCH] doc: Try to clear some confusion about lxc.conf

Serge Hallyn serge.hallyn at ubuntu.com
Thu Jan 23 03:09:03 UTC 2014


Quoting Stéphane Graber (stgraber at ubuntu.com):
> Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>

Acked-by: Serge E. Hallyn <serge.hallyn at ubuntu.com>

But, should we have a lxc.conf(5) which just says see also
lxc.system.conf(5) or lxc.container.conf(5)?  We have old email
threads pointing to lxc.conf(5)...

> ---
>  configure.ac                   |    2 +
>  doc/Makefile.am                |    5 +-
>  doc/lxc.conf                   |   36 -
>  doc/lxc.conf.sgml.in           | 1475 ++------------------------------------
>  doc/lxc.container.conf         |   36 +
>  doc/lxc.container.conf.sgml.in | 1543 ++++++++++++++++++++++++++++++++++++++++
>  doc/lxc.system.conf            |   20 +
>  doc/lxc.system.conf.sgml.in    |  206 ++++++
>  8 files changed, 1854 insertions(+), 1469 deletions(-)
>  delete mode 100644 doc/lxc.conf
>  create mode 100644 doc/lxc.container.conf
>  create mode 100644 doc/lxc.container.conf.sgml.in
>  create mode 100644 doc/lxc.system.conf
>  create mode 100644 doc/lxc.system.conf.sgml.in
> 
> diff --git a/configure.ac b/configure.ac
> index 73facf3..736625f 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -608,6 +608,8 @@ AC_CONFIG_FILES([
>  	doc/lxc-wait.sgml
>  
>  	doc/lxc.conf.sgml
> +	doc/lxc.container.conf.sgml
> +	doc/lxc.system.conf.sgml
>  	doc/lxc-usernet.sgml
>  	doc/lxc.sgml
>  	doc/common_options.sgml
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index e848717..9ddf53f 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -10,7 +10,8 @@ SUBDIRS += api
>  endif
>  
>  EXTRA_DIST = \
> -	lxc.conf \
> +	lxc.container.conf \
> +	lxc.system.conf \
>  	FAQ.txt
>  
>  if ENABLE_DOCBOOK
> @@ -37,6 +38,8 @@ man_MANS = \
>  	lxc-wait.1 \
>  	\
>  	lxc.conf.5 \
> +	lxc.container.conf.5 \
> +	lxc.system.conf.5 \
>  	lxc-usernet.5 \
>  	\
>  	lxc.7
> diff --git a/doc/lxc.conf b/doc/lxc.conf
> deleted file mode 100644
> index 4e2491b..0000000
> --- a/doc/lxc.conf
> +++ /dev/null
> @@ -1,36 +0,0 @@
> -# the fstab mount file
> -lxc.mount = ./fstab
> -
> -# the hostname to be set into the container
> -lxc.utsname = virtnode
> -
> -# The network has several of kind of configuration:
> -#
> -#  * veth    : the network will use the veth virtual device, the specified
> -#              link must be a bridge
> -#  * macvlan : the network will use the macvlan device, the specified link
> -#              should be an existing interface, usually it is eth0
> -#  * phys    : the network will use a physical network device, the specified
> -#              link should be an existing interface
> -lxc.network.type = macvlan
> -
> -# specify the flags to be used for the network, actually only <up> is allowed
> -# which mean the network should be set up when created. If the network is set
> -# up, the loopback is automatically set up too.
> -lxc.network.flags = up
> -
> -# specify the physical network device which will communicate with the
> -# outside world
> -lxc.network.link = eth0
> -
> -# NIC ethernet mac address
> -lxc.network.hwaddr = 4a:49:43:49:79:bd
> -
> -# specify the ipv4 address of the container. Several lines are allowed and
> -# will mean several addresses will be assigned to the interface
> -lxc.network.ipv4 = 1.2.3.5/24
> -
> -# specify the ipv6 address of the container. Several lines are allowed and
> -# will mean several addresses will be assigned to the interface
> -lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
> -
> diff --git a/doc/lxc.conf.sgml.in b/doc/lxc.conf.sgml.in
> index 897738f..19f11c2 100644
> --- a/doc/lxc.conf.sgml.in
> +++ b/doc/lxc.conf.sgml.in
> @@ -2,10 +2,10 @@
>  
>  lxc: linux Container library
>  
> -(C) Copyright IBM Corp. 2007, 2008
> +(C) Copyright Canonical Ltd. 2014
>  
>  Authors:
> -Daniel Lezcano <daniel.lezcano at free.fr>
> +Stéphane Graber <stgraber at ubuntu.com>
>  
>  This library is free software; you can redistribute it and/or
>  modify it under the terms of the GNU Lesser General Public
> @@ -41,7 +41,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>      <refname>lxc.conf</refname>
>  
>      <refpurpose>
> -      linux container configuration file
> +      Configuration files for LXC.
>      </refpurpose>
>    </refnamediv>
>  
> @@ -49,1480 +49,91 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
>      <title>Description</title>
>  
>      <para>
> -      The linux containers (<command>lxc</command>) are always created
> -      before being used. This creation defines a set of system
> -      resources to be virtualized / isolated when a process is using
> -      the container. By default, the pids, sysv ipc and mount points
> -      are virtualized and isolated. The other system resources are
> -      shared across containers, until they are explicitly defined in
> -      the configuration file. For example, if there is no network
> -      configuration, the network will be shared between the creator of
> -      the container and the container itself, but if the network is
> -      specified, a new network stack is created for the container and
> -      the container can no longer use the network of its ancestor.
> +      LXC configuration is split in two parts. Container configuration
> +      and system configuration.
>      </para>
>  
> -    <para>
> -      The configuration file defines the different system resources to
> -      be assigned for the container. At present, the utsname, the
> -      network, the mount points, the root file system, the user namespace,
> -      and the control groups are supported.
> -    </para>
> -
> -    <para>
> -      Each option in the configuration file has the form <command>key
> -      = value</command> fitting in one line. The '#' character means
> -      the line is a comment.
> -    </para>
> -
> -    <refsect2>
> -      <title>Configuration</title>
> -      <para>
> -	In order to ease administration of multiple related containers, it
> -	is possible to have a container configuration file cause another
> -	file to be loaded.  For instance, network configuration
> -	can be defined in one common file which is included by multiple
> -	containers.  Then, if the containers are moved to another host,
> -	only one file may need to be updated.
> -      </para>
> -
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.include</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the file to be included.  The included file must be
> -	      in the same valid lxc configuration file format.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Architecture</title>
> -      <para>
> -	Allows one to set the architecture for the container. For example,
> -	set a 32bits architecture for a container running 32bits
> -	binaries on a 64bits host. This fixes the container scripts
> -	which rely on the architecture to do some work like
> -	downloading the packages.
> -      </para>
> -
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.arch</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the architecture for the container.
> -	    </para>
> -	    <para>
> -	      Valid options are
> -	      <option>x86</option>,
> -	      <option>i686</option>,
> -	      <option>x86_64</option>,
> -	      <option>amd64</option>
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Hostname</title>
> -      <para>
> -	The utsname section defines the hostname to be set for the
> -	container. That means the container can set its own hostname
> -	without changing the one from the system. That makes the
> -	hostname private for the container.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.utsname</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the hostname for the container
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Halt signal</title>
> -      <para>
> -    Allows one to specify signal name or number, sent by lxc-stop to the
> -    container's init process to cleanly shutdown the container. Different
> -    init systems could use different signals to perform clean shutdown
> -    sequence. This option allows the signal to be specified in kill(1)
> -    fashion, e.g. SIGPWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The
> -    default signal is SIGPWR.
> -      </para>
> -      <variablelist>
> -    <varlistentry>
> -      <term>
> -        <option>lxc.haltsignal</option>
> -      </term>
> -      <listitem>
> -        <para>
> -          specify the signal used to halt the container
> -        </para>
> -      </listitem>
> -    </varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Stop signal</title>
> -      <para>
> -    Allows one to specify signal name or number, sent by lxc-stop to forcibly
> -    shutdown the container. This option allows signal to be specified in
> -    kill(1) fashion, e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number.
> -    The default signal is SIGKILL.
> -      </para>
> -      <variablelist>
> -    <varlistentry>
> -      <term>
> -        <option>lxc.stopsignal</option>
> -      </term>
> -      <listitem>
> -        <para>
> -          specify the signal used to stop the container
> -        </para>
> -      </listitem>
> -    </varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Network</title>
> -      <para>
> -	The network section defines how the network is virtualized in
> -	the container. The network virtualization acts at layer
> -	two. In order to use the network virtualization, parameters
> -	must be specified to define the network interfaces of the
> -	container. Several virtual interfaces can be assigned and used
> -	in a container even if the system has only one physical
> -	network interface.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.type</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify what kind of network virtualization to be used
> -	      for the container. Each time
> -	      a <option>lxc.network.type</option> field is found a new
> -	      round of network configuration begins. In this way,
> -	      several network virtualization types can be specified
> -	      for the same container, as well as assigning several
> -	      network interfaces for one container. The different
> -	      virtualization types can be:
> -	    </para>
> -
> -	    <para>
> -	      <option>none:</option> will cause the container to share
> -	      the host's network namespace.  This means the host
> -	      network devices are usable in the container.  It also
> -	      means that if both the container and host have upstart as
> -	      init, 'halt' in a container (for instance) will shut down the
> -	      host.
> -	    </para>
> -
> -	    <para>
> -	      <option>empty:</option> will create only the loopback
> -	      interface.
> -	    </para>
> -
> -	    <para>
> -	      <option>veth:</option> a peer network device is created
> -	      with one side assigned to the container and the other
> -	      side is attached to a bridge specified by
> -	      the <option>lxc.network.link</option>. If the bridge is
> -	      not specified, then the veth pair device will be created
> -	      but not attached to any bridge. Otherwise, the bridge
> -	      has to be setup before on the
> -	      system, <command>lxc</command> won't handle any
> -	      configuration outside of the container.  By
> -	      default <command>lxc</command> choose a name for the
> -	      network device belonging to the outside of the
> -	      container, this name is handled
> -	      by <command>lxc</command>, but if you wish to handle
> -	      this name yourself, you can tell <command>lxc</command>
> -	      to set a specific name with
> -	      the <option>lxc.network.veth.pair</option> option.
> -	    </para>
> -
> -	    <para>
> -	      <option>vlan:</option> a vlan interface is linked with
> -	      the interface specified by
> -	      the <option>lxc.network.link</option> and assigned to
> -	      the container. The vlan identifier is specified with the
> -	      option <option>lxc.network.vlan.id</option>.
> -	    </para>
> -
> -	    <para>
> -	      <option>macvlan:</option> a macvlan interface is linked
> -	      with the interface specified by
> -	      the <option>lxc.network.link</option> and assigned to
> -	      the container.
> -	      <option>lxc.network.macvlan.mode</option> specifies the
> -	      mode the macvlan will use to communicate between
> -	      different macvlan on the same upper device. The accepted
> -	      modes are <option>private</option>, the device never
> -	      communicates with any other device on the same upper_dev (default),
> -	      <option>vepa</option>, the new Virtual Ethernet Port
> -	      Aggregator (VEPA) mode, it assumes that the adjacent
> -	      bridge returns all frames where both source and
> -	      destination are local to the macvlan port, i.e. the
> -	      bridge is set up as a reflective relay.  Broadcast
> -	      frames coming in from the upper_dev get flooded to all
> -	      macvlan interfaces in VEPA mode, local frames are not
> -	      delivered locally, or <option>bridge</option>, it
> -	      provides the behavior of a simple bridge between
> -	      different macvlan interfaces on the same port. Frames
> -	      from one interface to another one get delivered directly
> -	      and are not sent out externally. Broadcast frames get
> -	      flooded to all other bridge ports and to the external
> -	      interface, but when they come back from a reflective
> -	      relay, we don't deliver them again.  Since we know all
> -	      the MAC addresses, the macvlan bridge mode does not
> -	      require learning or STP like the bridge module does.
> -	    </para>
> -
> -	    <para>
> -	      <option>phys:</option> an already existing interface
> -	      specified by the <option>lxc.network.link</option> is
> -	      assigned to the container.
> -	    </para>
> -	  </listitem>
> -	  </varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.flags</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify an action to do for the
> -	      network.
> -	    </para>
> -
> -	    <para><option>up:</option> activates the interface.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.link</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the interface to be used for real network
> -	      traffic.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.mtu</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the maximum transfer unit for this interface.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.name</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      the interface name is dynamically allocated, but if
> -	      another name is needed because the configuration files
> -	      being used by the container use a generic name,
> -	      eg. eth0, this option will rename the interface in the
> -	      container.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.hwaddr</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      the interface mac address is dynamically allocated by
> -	      default to the virtual interface, but in some cases,
> -	      this is needed to resolve a mac address conflict or to
> -	      always have the same link-local ipv6 address.
> -	      Any "x" in address will be replaced by random value,
> -	      this allows setting hwaddr templates.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.ipv4</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the ipv4 address to assign to the virtualized
> -	      interface. Several lines specify several ipv4 addresses.
> -	      The address is in format x.y.z.t/m,
> -	      eg. 192.168.1.123/24. The broadcast address should be
> -	      specified on the same line, right after the ipv4
> -	      address.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.ipv4.gateway</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the ipv4 address to use as the gateway inside the
> -	      container. The address is in format x.y.z.t, eg.
> -	      192.168.1.123.
> -
> -	      Can also have the special value <option>auto</option>,
> -	      which means to take the primary address from the bridge
> -	      interface (as specified by the
> -	      <option>lxc.network.link</option> option) and use that as
> -	      the gateway. <option>auto</option> is only available when
> -	      using the <option>veth</option> and
> -	      <option>macvlan</option> network types.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.ipv6</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the ipv6 address to assign to the virtualized
> -	      interface. Several lines specify several ipv6 addresses.
> -	      The address is in format x::y/m,
> -	      eg. 2003:db8:1:0:214:1234:fe0b:3596/64
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.ipv6.gateway</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the ipv6 address to use as the gateway inside the
> -	      container. The address is in format x::y,
> -	      eg. 2003:db8:1:0::1
> -
> -	      Can also have the special value <option>auto</option>,
> -	      which means to take the primary address from the bridge
> -	      interface (as specified by the
> -	      <option>lxc.network.link</option> option) and use that as
> -	      the gateway. <option>auto</option> is only available when
> -	      using the <option>veth</option> and
> -	      <option>macvlan</option> network types.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.script.up</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      add a configuration option to specify a script to be
> -	      executed after creating and configuring the network used
> -	      from the host side. The following arguments are passed
> -	      to the script: container name and config section name
> -	      (net) Additional arguments depend on the config section
> -	      employing a script hook; the following are used by the
> -	      network system: execution context (up), network type
> -	      (empty/veth/macvlan/phys), Depending on the network
> -	      type, other arguments may be passed:
> -	      veth/macvlan/phys. And finally (host-sided) device name.
> -	    </para>
> -	    <para>
> -	      Standard output from the script is logged at debug level.
> -	      Standard error is not logged, but can be captured by the
> -	      hook redirecting its standard error to standard output.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.network.script.down</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      add a configuration option to specify a script to be
> -	      executed before destroying the network used from the
> -	      host side. The following arguments are passed to the
> -	      script: container name and config section name (net)
> -	      Additional arguments depend on the config section
> -	      employing a script hook; the following are used by the
> -	      network system: execution context (down), network type
> -	      (empty/veth/macvlan/phys), Depending on the network
> -	      type, other arguments may be passed:
> -	      veth/macvlan/phys. And finally (host-sided) device name.
> -	    </para>
> -	    <para>
> -	      Standard output from the script is logged at debug level.
> -	      Standard error is not logged, but can be captured by the
> -	      hook redirecting its standard error to standard output.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>New pseudo tty instance (devpts)</title>
> -      <para>
> -	For stricter isolation the container can have its own private
> -	instance of the pseudo tty.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.pts</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      If set, the container will have a new pseudo tty
> -	      instance, making this private to it. The value specifies
> -              the maximum number of pseudo ttys allowed for a pts
> -              instance (this limitation is not implemented yet).
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Container system console</title>
> -      <para>
> -	If the container is configured with a root filesystem and the
> -	inittab file is setup to use the console, you may want to specify
> -	where the output of this console goes.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.console</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify a path to a file where the console output will
> -	      be written. The keyword 'none' will simply disable the
> -	      console. This is dangerous once if have a rootfs with a
> -	      console device file where the application can write, the
> -	      messages will fall in the host.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Console through the ttys</title>
> -      <para>
> -	This option is useful if the container is configured with a root
> -	filesystem and the inittab file is setup to launch a getty on the
> -	ttys. The option specifies the number of ttys to be available for
> -	the container. The number of gettys in the inittab file of the
> -	container should not be greater than the number of ttys	specified
> -	in this option, otherwise the excess getty sessions will die and
> -	respawn indefinitely giving annoying messages on the console or in
> -	<filename>/var/log/messages</filename>.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.tty</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the number of tty to make available to the
> -	      container.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Console devices location</title>
> -      <para>
> -        LXC consoles are provided through Unix98 PTYs created on the
> -	host and bind-mounted over the expected devices in the container.
> -	By default, they are bind-mounted over <filename>/dev/console</filename>
> -	and <filename>/dev/ttyN</filename>.  This can prevent package upgrades
> -	in the guest.  Therefore you can specify a directory location (under
> -	<filename>/dev</filename> under which LXC will create the files and
> -	bind-mount over them.  These will then be symbolically linked to
> -	<filename>/dev/console</filename> and <filename>/dev/ttyN</filename>.
> -	A package upgrade can then succeed as it is able to remove and replace
> -	the symbolic links.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.devttydir</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify a directory under <filename>/dev</filename>
> -	      under which to create the container console devices.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
>      <refsect2>
> -      <title>/dev directory</title>
> +      <title>Container configuration</title>
>        <para>
> -	By default, lxc does nothing with the container's
> -	<filename>/dev</filename>.  This allows the container's
> -	<filename>/dev</filename> to be set up as needed in the container
> -	rootfs.  If lxc.autodev is set to 1, then after mounting the container's
> -	rootfs LXC will mount a fresh tmpfs under <filename>/dev</filename>
> -	(limited to 100k) and fill in a minimal set of initial devices.
> -        This is generally required when starting a container containing
> -        a "systemd" based "init" but may be optional at other times.  Additional
> -        devices in the containers /dev directory may be created through the
> -        use of the <option>lxc.hook.autodev</option> hook.
> +          The container configuration is held in the
> +          <filename>config</filename> stored in the container's
> +          directory.
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.autodev</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Set this to 1 to have LXC mount and populate a minimal
> -	      <filename>/dev</filename> when starting the container.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Enable kmsg symlink</title>
> -      <para>
> -      Enable creating /dev/kmsg as symlink to /dev/console.  This defaults to 1.
> -      </para>
> -      <variablelist>
> -    <varlistentry>
> -      <term>
> -        <option>lxc.kmsg</option>
> -      </term>
> -      <listitem>
> -        <para>
> -          Set this to 0 to disable /dev/kmsg symlinking.
> -        </para>
> -      </listitem>
> -    </varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Mount points</title>
> -      <para>
> -	The mount points section specifies the different places to be
> -	mounted. These mount points will be private to the container
> -	and won't be visible by the processes running outside of the
> -	container. This is useful to mount /etc, /var or /home for
> -	examples.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.mount</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify a file location in
> -	      the <filename>fstab</filename> format, containing the
> -	      mount information. If the rootfs is an image file or a
> -	      block device and the fstab is used to mount a point
> -	      somewhere in this rootfs, the path of the rootfs mount
> -	      point should be prefixed with the
> -	      <filename>@LXCROOTFSMOUNT@</filename> default path or
> -	      the value of <option>lxc.rootfs.mount</option> if
> -	      specified. Note that when mounting a filesystem from an
> -	      image file or block device the third field (fs_vfstype)
> -	      cannot be auto as with
> -              <citerefentry>
> -		<refentrytitle>mount</refentrytitle>
> -                <manvolnum>8</manvolnum>
> -              </citerefentry>
> -              but must be explicitly specified.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.mount.entry</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify a mount point corresponding to a line in the
> -	      fstab format.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.mount.auto</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify which standard kernel file systems should be
> -	      automatically mounted. This may dramatically simplify
> -	      the configuration. The file systems are:
> -	    </para>
> -	    <itemizedlist>
> -	      <listitem>
> -	        <para>
> -	          <option>proc:mixed</option> (or <option>proc</option>):
> -	          mount <filename>/proc</filename> as read-write, but
> -	          remount <filename>/proc/sys</filename> and
> -	          <filename>/proc/sysrq-trigger</filename> read-only
> -	          for security / container isolation purposes.
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>proc:rw</option>: mount
> -	          <filename>/proc</filename> as read-write
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>sys:ro</option> (or <option>sys</option>):
> -	          mount <filename>/sys</filename> as read-only
> -	          for security / container isolation purposes.
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>sys:rw</option>: mount
> -	          <filename>/sys</filename> as read-write
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup:mixed</option> (or
> -	          <option>cgroup</option>):
> -	          mount a tmpfs to <filename>/sys/fs/cgroup</filename>,
> -	          create directories for all hierarchies to which
> -	          the container is added, create subdirectories
> -	          there with the name of the cgroup, and bind-mount
> -	          the container's own cgroup into that directory.
> -	          The container will be able to write to its own
> -	          cgroup directory, but not the parents, since they
> -	          will be remounted read-only
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup:ro</option>: similar to
> -	          <option>cgroup:mixed</option>, but everything will
> -	        be mounted read-only.
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup:rw</option>: similar to
> -	          <option>cgroup:mixed</option>, but everything will
> -	          be mounted read-write. Note that the paths leading
> -	          up to the container's own cgroup will be writable,
> -	          but will not be a cgroup filesystem but just part
> -	          of the tmpfs of <filename>/sys/fs/cgroup</filename>
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup-full:mixed</option> (or
> -	          <option>cgroup-full</option>):
> -	          mount a tmpfs to <filename>/sys/fs/cgroup</filename>,
> -	          create directories for all hierarchies to which
> -	          the container is added, bind-mount the hierarchies
> -	          from the host to the container and make everything
> -	          read-only except the container's own cgroup. Note
> -	          that compared to <option>cgroup</option>, where
> -	          all paths leading up to the container's own cgroup
> -	          are just simple directories in the underlying
> -	          tmpfs, here
> -	          <filename>/sys/fs/cgroup/$hierarchy</filename>
> -	          will contain the host's full cgroup hierarchy,
> -	          albeit read-only outside the container's own cgroup.
> -	          This may leak quite a bit of information into the
> -	          container.
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup-full:ro</option>: similar to
> -	          <option>cgroup-full:mixed</option>, but everything
> -	          will be mounted read-only.
> -	        </para>
> -	      </listitem>
> -	      <listitem>
> -	        <para>
> -	          <option>cgroup-full:rw</option>: similar to
> -	          <option>cgroup-full:mixed</option>, but everything
> -	          will be mounted read-write. Note that in this case,
> -	          the container may escape its own cgroup. (Note also
> -	          that if the container has CAP_SYS_ADMIN support
> -	          and can mount the cgroup filesystem itself, it may
> -	          do so anyway.)
> -	        </para>
> -	      </listitem>
> -	    </itemizedlist>
> -	    <para>
> -	      Examples:
> -	    </para>
> -	    <programlisting>
> -	      lxc.mount.auto = proc sys cgroup
> -	      lxc.mount.auto = proc:rw sys:rw cgroup-full:rw
> -	    </programlisting>
> -	  </listitem>
> -	</varlistentry>
> -
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Root file system</title>
> -      <para>
> -	The root file system of the container can be different than that
> -	of the host system.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.rootfs</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the root file system for the container. It can
> -	      be an image file, a directory or a block device. If not
> -	      specified, the container shares its root file system
> -	      with the host.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.rootfs.mount</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      where to recursively bind <option>lxc.rootfs</option>
> -	      before pivoting.  This is to ensure success of the
> -	      <citerefentry>
> -		<refentrytitle><command>pivot_root</command></refentrytitle>
> -		<manvolnum>8</manvolnum>
> -	      </citerefentry>
> -	      syscall.  Any directory suffices, the default should
> -	      generally work.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.pivotdir</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      where to pivot the original root file system under
> -	      <option>lxc.rootfs</option>, specified relatively to
> -	      that.  The default is <filename>mnt</filename>.
> -	      It is created if necessary, and also removed after
> -	      unmounting everything from it during container setup.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Control group</title>
> -      <para>
> -	The control group section contains the configuration for the
> -	different subsystem. <command>lxc</command> does not check the
> -	correctness of the subsystem name. This has the disadvantage
> -	of not detecting configuration errors until the container is
> -	started, but has the advantage of permitting any future
> -	subsystem.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.cgroup.[subsystem name]</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      specify the control group value to be set.  The
> -	      subsystem name is the literal name of the control group
> -	      subsystem.  The permitted names and the syntax of their
> -	      values is not dictated by LXC, instead it depends on the
> -	      features of the Linux kernel running at the time the
> -	      container is started,
> -	      eg. <option>lxc.cgroup.cpuset.cpus</option>
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Capabilities</title>
> -      <para>
> -	The capabilities can be dropped in the container if this one
> -	is run as root.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.cap.drop</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the capability to be dropped in the container. A
> -	      single line defining several capabilities with a space
> -	      separation is allowed. The format is the lower case of
> -	      the capability definition without the "CAP_" prefix,
> -	      eg. CAP_SYS_MODULE should be specified as
> -	      sys_module. See
> -	      <citerefentry>
> -		<refentrytitle><command>capabilities</command></refentrytitle>
> -		<manvolnum>7</manvolnum>
> -	      </citerefentry>,
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.cap.keep</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the capability to be kept in the container. All other
> -	      capabilities will be dropped.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Apparmor profile</title>
> -      <para>
> -	If lxc was compiled and installed with apparmor support, and the host
> -	system has apparmor enabled, then the apparmor profile under which the
> -	container should be run can be specified in the container
> -	configuration.  The default is <command>lxc-container-default</command>.
> -      </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.aa_profile</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the apparmor profile under which the container should
> -	      be run.  To specify that the container should be unconfined,
> -	      use
> -	    </para>
> -	      <programlisting>lxc.aa_profile = unconfined</programlisting>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
>  
> -    <refsect2>
> -      <title>SELinux context</title>
>        <para>
> -	If lxc was compiled and installed with SELinux support, and the host
> -	system has SELinux enabled, then the SELinux context under which the
> -	container should be run can be specified in the container
> -	configuration.  The default is <command>unconfined_t</command>,
> -	which means that lxc will not attempt to change contexts.
> +          A basic configuration is generated at container creation time
> +          with the default's recommended for the chosen template as well
> +          as extra default keys coming from the
> +          <filename>default.conf</filename> file.
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.se_context</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify the SELinux context under which the container should
> -	      be run or <command>unconfined_t</command>. For example
> -	    </para>
> -	    <programlisting>lxc.se_context = unconfined_u:unconfined_r:lxc_t:s0-s0:c0.c1023</programlisting>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
>  
> -    <refsect2>
> -      <title>Seccomp configuration</title>
>        <para>
> -        A container can be started with a reduced set of available
> -	system calls by loading a seccomp profile at startup.  The
> -	seccomp configuration file should begin with a version number
> -	(which currently must be 1) on the first line, a policy type
> -	(which must be 'whitelist') on the second line, followed by a
> -	list of allowed system call numbers, one per line.
> +          That <filename>default.conf</filename> file is either located
> +          at <filename>@LXC_DEFAULT_CONFIG@</filename> or for
> +          unprivileged containers at
> +          <filename>~/.config/lxc/default.conf</filename>.
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.seccomp</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Specify a file containing the seccomp configuration to
> -	      load before the container starts.
> -	     </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
>  
> -    <refsect2>
> -      <title>UID mappings</title>
>        <para>
> -        A container can be started in a private user namespace with
> -	user and group id mappings.  For instance, you can map userid
> -	0 in the container to userid 200000 on the host.  The root
> -	user in the container will be privileged in the container,
> -	but unprivileged on the host.  Normally a system container
> -	will want a range of ids, so you would map, for instance,
> -	user and group ids 0 through 20,000 in the container to the
> -	ids 200,000 through 220,000.
> +          Details about the syntax of this file can be found in:
> +          <citerefentry>
> +            <refentrytitle><command>lxc.container.conf</command></refentrytitle>
> +            <manvolnum>5</manvolnum>
> +          </citerefentry>
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.id_map</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Four values must be provided.  First a character, either
> -	      'u', or 'g', to specify whether user or group ids are
> -	      being mapped.  Next is the first userid as seen in the
> -	      user namespace of the container.  Next is the userid as
> -	      seen on the host.  Finally, a range indicating the number
> -	      of consecutive ids to map.
> -	     </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
>      </refsect2>
>  
>      <refsect2>
> -      <title>Container hooks</title>
> -      <para>
> -        Container hooks are programs or scripts which can be executed
> -	at various times in a container's lifetime.
> -      </para>
> -      <para>
> -        When a container hook is executed, information is passed both
> -	as command line arguments and through environment variables.
> -	The arguments are:
> -	<itemizedlist>
> -	  <listitem><para> Container name. </para></listitem>
> -	  <listitem><para> Section (always 'lxc'). </para></listitem>
> -	  <listitem><para> The hook type (i.e. 'clone' or 'pre-mount'). </para></listitem>
> -	  <listitem><para> Additional arguments In the
> -	  case of the clone hook, any extra arguments passed to
> -	  lxc-clone will appear as further arguments to the hook. </para></listitem>
> -	</itemizedlist>
> -	The following environment variables are set:
> -	<itemizedlist>
> -	  <listitem><para> LXC_NAME: is the container's name. </para></listitem>
> -	  <listitem><para> LXC_ROOTFS_MOUNT: the path to the mounted root filesystem. </para></listitem>
> -	  <listitem><para> LXC_CONFIG_FILE: the path to the container configuration file. </para></listitem>
> -	  <listitem><para> LXC_SRC_NAME: in the case of the clone hook, this is the original container's name. </para></listitem>
> -	  <listitem><para> LXC_ROOTFS_PATH: this is the lxc.rootfs entry for the container.  Note this is likely not where the mounted rootfs is to be found, use LXC_ROOTFS_MOUNT for that. </para></listitem>
> -	</itemizedlist>
> -      </para>
> +      <title>System configuration</title>
>        <para>
> -        Standard output from the hooks is logged at debug level.
> -        Standard error is not logged, but can be captured by the
> -        hook redirecting its standard error to standard output.
> +          The system configuration is located at
> +          <filename>@LXC_GLOBAL_CONF@</filename> or
> +          <filename>~/.config/lxc/lxc.conf</filename> for unprivileged
> +          containers.
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.pre-start</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the host's namespace before the
> -	      container ttys, consoles, or mounts are up.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.pre-mount</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the container's fs namespace but before
> -	      the rootfs has been set up.  This allows for manipulation
> -	      of the rootfs, i.e. to mount an encrypted filesystem.  Mounts
> -	      done in this hook will not be reflected on the host (apart from
> -	      mounts propagation), so they will be automatically cleaned up
> -	      when the container shuts down.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.mount</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the container's namespace after
> -	      mounting has been done, but before the pivot_root.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.autodev</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the container's namespace after
> -	      mounting has been done and after any mount hooks have
> -	      run, but before the pivot_root, if
> -	      <option>lxc.autodev</option> == 1.
> -	      The purpose of this hook is to assist in populating the
> -	      /dev directory of the container when using the autodev
> -	      option for systemd based containers.  The container's /dev
> -	      directory is relative to the
> -	      ${<option>LXC_ROOTFS_MOUNT</option>} environment
> -	      variable available when the hook is run.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.start</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the container's namespace immediately
> -	      before executing the container's init.  This requires the
> -	      program to be available in the container.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.post-stop</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run in the host's namespace after the
> -	      container has been shut down.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.hook.clone</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      A hook to be run when the container is cloned to a new one.
> -	      See <citerefentry><refentrytitle><command>lxc-clone</command></refentrytitle>
> -	      <manvolnum>1</manvolnum></citerefentry> for more information.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
>  
> -    <refsect2>
> -      <title>Container hooks Environment Variables</title>
>        <para>
> -        A number of environment variables are made available to the startup
> -        hooks to provide configuration information and assist in the
> -        functioning of the hooks.  Not all variables are valid in all
> -        contexts.  In particular, all paths are relative to the host system
> -        and, as such, not valid during the <option>lxc.hook.start</option> hook.
> +          This configuration file is used to set values such as default
> +          lookup paths and storage backend settings for LXC.
>        </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_NAME</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      The LXC name of the container.  Useful for logging messages
> -	      in common log environments.  [<option>-n</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_CONFIG_FILE</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      Host relative path to the container configuration file.  This
> -	      gives the container to reference the original, top level,
> -	      configuration file for the container in order to locate any
> -	      additional configuration information not otherwise made
> -	      available.  [<option>-f</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_CONSOLE</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      The path to the console output of the container if not NULL.
> -	      [<option>-c</option>] [<option>lxc.console</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_CONSOLE_LOGPATH</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      The path to the console log output of the container if not NULL.
> -	      [<option>-L</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_ROOTFS_MOUNT</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      The mount location to which the container is initially bound.
> -	      This will be the host relative path to the container rootfs
> -	      for the container instance being started and is where changes
> -	      should be made for that instance.
> -	      [<option>lxc.rootfs.mount</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>LXC_ROOTFS_PATH</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	      The host relative path to the container root which has been
> -	      mounted to the rootfs.mount location.
> -	      [<option>lxc.rootfs</option>]
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -
> -    </refsect2>
> -    <refsect2>
> -    <title>Logging</title>
> -    <para>
> -      Logging can be configured on a per-container basis.  By default,
> -      depending upon how the lxc package was compiled, container startup
> -      is logged only at the ERROR level, and logged to a file named after
> -      the container (with '.log' appended) either under the container path,
> -      or under @LOGPATH at .
> -    </para>
> -    <para>
> -      Both the default log level and the log file can be specified in the
> -      container configuration file, overriding the default behavior.  Note
> -      that the configuration file entries can in turn be overridden by the
> -      command line options to <command>lxc-start</command>.
> -    </para>
> -      <variablelist>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.loglevel</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	    The level at which to log.  The log level is an integer in
> -	    the range of 0..8 inclusive, where a lower number means more
> -	    verbose debugging.  In particular 0 = trace, 1 = debug, 2 =
> -	    info, 3 = notice, 4 = warn, 5 = error, 6 = critical, 7 =
> -	    alert, and 8 = fatal.  If unspecified, the level defaults
> -	    to 5 (error), so that only errors and above are logged.
> -	    </para>
> -	    <para>
> -	    Note that when a script (such as either a hook script or a
> -	    network interface up or down script) is called, the script's
> -	    standard output is logged at level 1, debug.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -	<varlistentry>
> -	  <term>
> -	    <option>lxc.logfile</option>
> -	  </term>
> -	  <listitem>
> -	    <para>
> -	    The file to which logging info should be written.
> -	    </para>
> -	  </listitem>
> -	</varlistentry>
> -      </variablelist>
> -    </refsect2>
> -
> -    <refsect2>
> -    <title>Autostart</title>
> -    <para>
> -        The autostart options support marking which containers should be
> -        auto-started and in what order. These options may be used by LXC tools
> -        directly or by external tooling provided by the distributions.
> -    </para>
> -
> -    <variablelist>
> -        <varlistentry>
> -          <term>
> -            <option>lxc.start.auto</option>
> -          </term>
> -          <listitem>
> -            <para>
> -              Whether the container should be auto-started.
> -              Valid values are 0 (off) and 1 (on).
> -            </para>
> -          </listitem>
> -        </varlistentry>
> -        <varlistentry>
> -          <term>
> -            <option>lxc.start.delay</option>
> -          </term>
> -          <listitem>
> -            <para>
> -              How long to wait (in seconds) after the container is
> -              started before starting the next one.
> -            </para>
> -          </listitem>
> -        </varlistentry>
> -        <varlistentry>
> -          <term>
> -            <option>lxc.start.order</option>
> -          </term>
> -          <listitem>
> -            <para>
> -              An integer used to sort the containers when auto-starting
> -              a series of containers at once.
> -            </para>
> -          </listitem>
> -        </varlistentry>
> -        <varlistentry>
> -          <term>
> -            <option>lxc.group</option>
> -          </term>
> -          <listitem>
> -            <para>
> -              A multi-value key (can be used multiple times) to put the
> -              container in a container group. Those groups can then be
> -              used (amongst other things) to start a series of related
> -              containers.
> -            </para>
> -          </listitem>
> -        </varlistentry>
> -      </variablelist>
> -    </refsect2>
> -  </refsect1>
>  
> -  <refsect1>
> -    <title>Examples</title>
>        <para>
> -	In addition to the few examples given below, you will find
> -	some other examples of configuration file in @DOCDIR@/examples
> -      </para>
> -    <refsect2>
> -      <title>Network</title>
> -      <para>This configuration sets up a container to use a veth pair
> -	device with one side plugged to a bridge br0 (which has been
> -	configured before on the system by the administrator). The
> -	virtual network device visible in the container is renamed to
> -	eth0.</para>
> -      <programlisting>
> -	lxc.utsname = myhostname
> -	lxc.network.type = veth
> -	lxc.network.flags = up
> -	lxc.network.link = br0
> -	lxc.network.name = eth0
> -	lxc.network.hwaddr = 4a:49:43:49:79:bf
> -	lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
> -	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
> -      </programlisting>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>UID/GID mapping</title>
> -      <para>This configuration will map both user and group ids in the
> -        range 0-9999 in the container to the ids 100000-109999 on the host.
> +          Details about the syntax of this file can be found in:
> +          <citerefentry>
> +            <refentrytitle><command>lxc.system.conf</command></refentrytitle>
> +            <manvolnum>5</manvolnum>
> +          </citerefentry>
>        </para>
> -      <programlisting>
> -	lxc.id_map = u 0 100000 10000
> -	lxc.id_map = g 0 100000 10000
> -      </programlisting>
> -    </refsect2>
> -
> -    <refsect2>
> -      <title>Control group</title>
> -      <para>This configuration will setup several control groups for
> -      the application, cpuset.cpus restricts usage of the defined cpu,
> -      cpus.share prioritize the control group, devices.allow makes
> -      usable the specified devices.</para>
> -      <programlisting>
> -	lxc.cgroup.cpuset.cpus = 0,1
> -	lxc.cgroup.cpu.shares = 1234
> -	lxc.cgroup.devices.deny = a
> -	lxc.cgroup.devices.allow = c 1:3 rw
> -	lxc.cgroup.devices.allow = b 8:0 rw
> -      </programlisting>
>      </refsect2>
> -
> -    <refsect2>
> -      <title>Complex configuration</title>
> -      <para>This example show a complex configuration making a complex
> -      network stack, using the control groups, setting a new hostname,
> -      mounting some locations and a changing root file system.</para>
> -      <programlisting>
> -	lxc.utsname = complex
> -	lxc.network.type = veth
> -	lxc.network.flags = up
> -	lxc.network.link = br0
> -	lxc.network.hwaddr = 4a:49:43:49:79:bf
> -	lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
> -	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
> -	lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
> -	lxc.network.type = macvlan
> -	lxc.network.flags = up
> -	lxc.network.link = eth0
> -	lxc.network.hwaddr = 4a:49:43:49:79:bd
> -	lxc.network.ipv4 = 10.2.3.4/24
> -	lxc.network.ipv4 = 192.168.10.125/24
> -	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
> -	lxc.network.type = phys
> -	lxc.network.flags = up
> -	lxc.network.link = dummy0
> -	lxc.network.hwaddr = 4a:49:43:49:79:ff
> -	lxc.network.ipv4 = 10.2.3.6/24
> -	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
> -	lxc.cgroup.cpuset.cpus = 0,1
> -	lxc.cgroup.cpu.shares = 1234
> -	lxc.cgroup.devices.deny = a
> -	lxc.cgroup.devices.allow = c 1:3 rw
> -	lxc.cgroup.devices.allow = b 8:0 rw
> -	lxc.mount = /etc/fstab.complex
> -	lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
> -	lxc.rootfs = /mnt/rootfs.complex
> -	lxc.cap.drop = sys_module mknod setuid net_raw
> -	lxc.cap.drop = mac_override
> -      </programlisting>
> -    </refsect2>
> -
>    </refsect1>
>  
>    <refsect1>
>      <title>See Also</title>
>      <simpara>
>        <citerefentry>
> -	<refentrytitle><command>chroot</command></refentrytitle>
> -	<manvolnum>1</manvolnum>
> +        <refentrytitle><command>lxc</command></refentrytitle>
> +        <manvolnum>1</manvolnum>
>        </citerefentry>,
> -
>        <citerefentry>
> -	<refentrytitle><command>pivot_root</command></refentrytitle>
> -	<manvolnum>8</manvolnum>
> +        <refentrytitle><command>lxc.container.conf</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
>        </citerefentry>,
> -
>        <citerefentry>
> -	<refentrytitle><filename>fstab</filename></refentrytitle>
> -	<manvolnum>5</manvolnum>
> +        <refentrytitle><command>lxc.system.conf</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
>        </citerefentry>,
> -
>        <citerefentry>
> -	<refentrytitle><filename>capabilities</filename></refentrytitle>
> -	<manvolnum>7</manvolnum>
> +        <refentrytitle><command>lxc-usernet</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
>        </citerefentry>
>      </simpara>
>    </refsect1>
>  
> -  &seealso;
> -
>    <refsect1>
>      <title>Author</title>
> -    <para>Daniel Lezcano <email>daniel.lezcano at free.fr</email></para>
> +    <para>Stéphane Graber <email>stgraber at ubuntu.com</email></para>
>    </refsect1>
> -
>  </refentry>
>  
>  <!-- Keep this comment at the end of the file
> diff --git a/doc/lxc.container.conf b/doc/lxc.container.conf
> new file mode 100644
> index 0000000..4e2491b
> --- /dev/null
> +++ b/doc/lxc.container.conf
> @@ -0,0 +1,36 @@
> +# the fstab mount file
> +lxc.mount = ./fstab
> +
> +# the hostname to be set into the container
> +lxc.utsname = virtnode
> +
> +# The network has several of kind of configuration:
> +#
> +#  * veth    : the network will use the veth virtual device, the specified
> +#              link must be a bridge
> +#  * macvlan : the network will use the macvlan device, the specified link
> +#              should be an existing interface, usually it is eth0
> +#  * phys    : the network will use a physical network device, the specified
> +#              link should be an existing interface
> +lxc.network.type = macvlan
> +
> +# specify the flags to be used for the network, actually only <up> is allowed
> +# which mean the network should be set up when created. If the network is set
> +# up, the loopback is automatically set up too.
> +lxc.network.flags = up
> +
> +# specify the physical network device which will communicate with the
> +# outside world
> +lxc.network.link = eth0
> +
> +# NIC ethernet mac address
> +lxc.network.hwaddr = 4a:49:43:49:79:bd
> +
> +# specify the ipv4 address of the container. Several lines are allowed and
> +# will mean several addresses will be assigned to the interface
> +lxc.network.ipv4 = 1.2.3.5/24
> +
> +# specify the ipv6 address of the container. Several lines are allowed and
> +# will mean several addresses will be assigned to the interface
> +lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
> +
> diff --git a/doc/lxc.container.conf.sgml.in b/doc/lxc.container.conf.sgml.in
> new file mode 100644
> index 0000000..aee5451
> --- /dev/null
> +++ b/doc/lxc.container.conf.sgml.in
> @@ -0,0 +1,1543 @@
> +<!--
> +
> +lxc: linux Container library
> +
> +(C) Copyright IBM Corp. 2007, 2008
> +
> +Authors:
> +Daniel Lezcano <daniel.lezcano at free.fr>
> +
> +This library is free software; you can redistribute it and/or
> +modify it under the terms of the GNU Lesser General Public
> +License as published by the Free Software Foundation; either
> +version 2.1 of the License, or (at your option) any later version.
> +
> +This library is distributed in the hope that it will be useful,
> +but WITHOUT ANY WARRANTY; without even the implied warranty of
> +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +Lesser General Public License for more details.
> +
> +You should have received a copy of the GNU Lesser General Public
> +License along with this library; if not, write to the Free Software
> +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> +
> +-->
> +
> +<!DOCTYPE refentry PUBLIC @docdtd@ [
> +
> +<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
> +]>
> +
> +<refentry>
> +
> +  <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
> +
> +  <refmeta>
> +    <refentrytitle>lxc.container.conf</refentrytitle>
> +    <manvolnum>5</manvolnum>
> +  </refmeta>
> +
> +  <refnamediv>
> +    <refname>lxc.container.conf</refname>
> +
> +    <refpurpose>
> +      LXC container configuration file
> +    </refpurpose>
> +  </refnamediv>
> +
> +  <refsect1>
> +    <title>Description</title>
> +
> +    <para>
> +      The linux containers (<command>lxc</command>) are always created
> +      before being used. This creation defines a set of system
> +      resources to be virtualized / isolated when a process is using
> +      the container. By default, the pids, sysv ipc and mount points
> +      are virtualized and isolated. The other system resources are
> +      shared across containers, until they are explicitly defined in
> +      the configuration file. For example, if there is no network
> +      configuration, the network will be shared between the creator of
> +      the container and the container itself, but if the network is
> +      specified, a new network stack is created for the container and
> +      the container can no longer use the network of its ancestor.
> +    </para>
> +
> +    <para>
> +      The configuration file defines the different system resources to
> +      be assigned for the container. At present, the utsname, the
> +      network, the mount points, the root file system, the user namespace,
> +      and the control groups are supported.
> +    </para>
> +
> +    <para>
> +      Each option in the configuration file has the form <command>key
> +      = value</command> fitting in one line. The '#' character means
> +      the line is a comment.
> +    </para>
> +
> +    <refsect2>
> +      <title>Configuration</title>
> +      <para>
> +	In order to ease administration of multiple related containers, it
> +	is possible to have a container configuration file cause another
> +	file to be loaded.  For instance, network configuration
> +	can be defined in one common file which is included by multiple
> +	containers.  Then, if the containers are moved to another host,
> +	only one file may need to be updated.
> +      </para>
> +
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.include</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the file to be included.  The included file must be
> +	      in the same valid lxc configuration file format.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Architecture</title>
> +      <para>
> +	Allows one to set the architecture for the container. For example,
> +	set a 32bits architecture for a container running 32bits
> +	binaries on a 64bits host. This fixes the container scripts
> +	which rely on the architecture to do some work like
> +	downloading the packages.
> +      </para>
> +
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.arch</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the architecture for the container.
> +	    </para>
> +	    <para>
> +	      Valid options are
> +	      <option>x86</option>,
> +	      <option>i686</option>,
> +	      <option>x86_64</option>,
> +	      <option>amd64</option>
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Hostname</title>
> +      <para>
> +	The utsname section defines the hostname to be set for the
> +	container. That means the container can set its own hostname
> +	without changing the one from the system. That makes the
> +	hostname private for the container.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.utsname</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the hostname for the container
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Halt signal</title>
> +      <para>
> +    Allows one to specify signal name or number, sent by lxc-stop to the
> +    container's init process to cleanly shutdown the container. Different
> +    init systems could use different signals to perform clean shutdown
> +    sequence. This option allows the signal to be specified in kill(1)
> +    fashion, e.g. SIGPWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The
> +    default signal is SIGPWR.
> +      </para>
> +      <variablelist>
> +    <varlistentry>
> +      <term>
> +        <option>lxc.haltsignal</option>
> +      </term>
> +      <listitem>
> +        <para>
> +          specify the signal used to halt the container
> +        </para>
> +      </listitem>
> +    </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Stop signal</title>
> +      <para>
> +    Allows one to specify signal name or number, sent by lxc-stop to forcibly
> +    shutdown the container. This option allows signal to be specified in
> +    kill(1) fashion, e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number.
> +    The default signal is SIGKILL.
> +      </para>
> +      <variablelist>
> +    <varlistentry>
> +      <term>
> +        <option>lxc.stopsignal</option>
> +      </term>
> +      <listitem>
> +        <para>
> +          specify the signal used to stop the container
> +        </para>
> +      </listitem>
> +    </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Network</title>
> +      <para>
> +	The network section defines how the network is virtualized in
> +	the container. The network virtualization acts at layer
> +	two. In order to use the network virtualization, parameters
> +	must be specified to define the network interfaces of the
> +	container. Several virtual interfaces can be assigned and used
> +	in a container even if the system has only one physical
> +	network interface.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.type</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify what kind of network virtualization to be used
> +	      for the container. Each time
> +	      a <option>lxc.network.type</option> field is found a new
> +	      round of network configuration begins. In this way,
> +	      several network virtualization types can be specified
> +	      for the same container, as well as assigning several
> +	      network interfaces for one container. The different
> +	      virtualization types can be:
> +	    </para>
> +
> +	    <para>
> +	      <option>none:</option> will cause the container to share
> +	      the host's network namespace.  This means the host
> +	      network devices are usable in the container.  It also
> +	      means that if both the container and host have upstart as
> +	      init, 'halt' in a container (for instance) will shut down the
> +	      host.
> +	    </para>
> +
> +	    <para>
> +	      <option>empty:</option> will create only the loopback
> +	      interface.
> +	    </para>
> +
> +	    <para>
> +	      <option>veth:</option> a peer network device is created
> +	      with one side assigned to the container and the other
> +	      side is attached to a bridge specified by
> +	      the <option>lxc.network.link</option>. If the bridge is
> +	      not specified, then the veth pair device will be created
> +	      but not attached to any bridge. Otherwise, the bridge
> +	      has to be setup before on the
> +	      system, <command>lxc</command> won't handle any
> +	      configuration outside of the container.  By
> +	      default <command>lxc</command> choose a name for the
> +	      network device belonging to the outside of the
> +	      container, this name is handled
> +	      by <command>lxc</command>, but if you wish to handle
> +	      this name yourself, you can tell <command>lxc</command>
> +	      to set a specific name with
> +	      the <option>lxc.network.veth.pair</option> option.
> +	    </para>
> +
> +	    <para>
> +	      <option>vlan:</option> a vlan interface is linked with
> +	      the interface specified by
> +	      the <option>lxc.network.link</option> and assigned to
> +	      the container. The vlan identifier is specified with the
> +	      option <option>lxc.network.vlan.id</option>.
> +	    </para>
> +
> +	    <para>
> +	      <option>macvlan:</option> a macvlan interface is linked
> +	      with the interface specified by
> +	      the <option>lxc.network.link</option> and assigned to
> +	      the container.
> +	      <option>lxc.network.macvlan.mode</option> specifies the
> +	      mode the macvlan will use to communicate between
> +	      different macvlan on the same upper device. The accepted
> +	      modes are <option>private</option>, the device never
> +	      communicates with any other device on the same upper_dev (default),
> +	      <option>vepa</option>, the new Virtual Ethernet Port
> +	      Aggregator (VEPA) mode, it assumes that the adjacent
> +	      bridge returns all frames where both source and
> +	      destination are local to the macvlan port, i.e. the
> +	      bridge is set up as a reflective relay.  Broadcast
> +	      frames coming in from the upper_dev get flooded to all
> +	      macvlan interfaces in VEPA mode, local frames are not
> +	      delivered locally, or <option>bridge</option>, it
> +	      provides the behavior of a simple bridge between
> +	      different macvlan interfaces on the same port. Frames
> +	      from one interface to another one get delivered directly
> +	      and are not sent out externally. Broadcast frames get
> +	      flooded to all other bridge ports and to the external
> +	      interface, but when they come back from a reflective
> +	      relay, we don't deliver them again.  Since we know all
> +	      the MAC addresses, the macvlan bridge mode does not
> +	      require learning or STP like the bridge module does.
> +	    </para>
> +
> +	    <para>
> +	      <option>phys:</option> an already existing interface
> +	      specified by the <option>lxc.network.link</option> is
> +	      assigned to the container.
> +	    </para>
> +	  </listitem>
> +	  </varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.flags</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify an action to do for the
> +	      network.
> +	    </para>
> +
> +	    <para><option>up:</option> activates the interface.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.link</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the interface to be used for real network
> +	      traffic.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.mtu</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the maximum transfer unit for this interface.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.name</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      the interface name is dynamically allocated, but if
> +	      another name is needed because the configuration files
> +	      being used by the container use a generic name,
> +	      eg. eth0, this option will rename the interface in the
> +	      container.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.hwaddr</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      the interface mac address is dynamically allocated by
> +	      default to the virtual interface, but in some cases,
> +	      this is needed to resolve a mac address conflict or to
> +	      always have the same link-local ipv6 address.
> +	      Any "x" in address will be replaced by random value,
> +	      this allows setting hwaddr templates.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.ipv4</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the ipv4 address to assign to the virtualized
> +	      interface. Several lines specify several ipv4 addresses.
> +	      The address is in format x.y.z.t/m,
> +	      eg. 192.168.1.123/24. The broadcast address should be
> +	      specified on the same line, right after the ipv4
> +	      address.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.ipv4.gateway</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the ipv4 address to use as the gateway inside the
> +	      container. The address is in format x.y.z.t, eg.
> +	      192.168.1.123.
> +
> +	      Can also have the special value <option>auto</option>,
> +	      which means to take the primary address from the bridge
> +	      interface (as specified by the
> +	      <option>lxc.network.link</option> option) and use that as
> +	      the gateway. <option>auto</option> is only available when
> +	      using the <option>veth</option> and
> +	      <option>macvlan</option> network types.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.ipv6</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the ipv6 address to assign to the virtualized
> +	      interface. Several lines specify several ipv6 addresses.
> +	      The address is in format x::y/m,
> +	      eg. 2003:db8:1:0:214:1234:fe0b:3596/64
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.ipv6.gateway</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the ipv6 address to use as the gateway inside the
> +	      container. The address is in format x::y,
> +	      eg. 2003:db8:1:0::1
> +
> +	      Can also have the special value <option>auto</option>,
> +	      which means to take the primary address from the bridge
> +	      interface (as specified by the
> +	      <option>lxc.network.link</option> option) and use that as
> +	      the gateway. <option>auto</option> is only available when
> +	      using the <option>veth</option> and
> +	      <option>macvlan</option> network types.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.script.up</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      add a configuration option to specify a script to be
> +	      executed after creating and configuring the network used
> +	      from the host side. The following arguments are passed
> +	      to the script: container name and config section name
> +	      (net) Additional arguments depend on the config section
> +	      employing a script hook; the following are used by the
> +	      network system: execution context (up), network type
> +	      (empty/veth/macvlan/phys), Depending on the network
> +	      type, other arguments may be passed:
> +	      veth/macvlan/phys. And finally (host-sided) device name.
> +	    </para>
> +	    <para>
> +	      Standard output from the script is logged at debug level.
> +	      Standard error is not logged, but can be captured by the
> +	      hook redirecting its standard error to standard output.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.network.script.down</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      add a configuration option to specify a script to be
> +	      executed before destroying the network used from the
> +	      host side. The following arguments are passed to the
> +	      script: container name and config section name (net)
> +	      Additional arguments depend on the config section
> +	      employing a script hook; the following are used by the
> +	      network system: execution context (down), network type
> +	      (empty/veth/macvlan/phys), Depending on the network
> +	      type, other arguments may be passed:
> +	      veth/macvlan/phys. And finally (host-sided) device name.
> +	    </para>
> +	    <para>
> +	      Standard output from the script is logged at debug level.
> +	      Standard error is not logged, but can be captured by the
> +	      hook redirecting its standard error to standard output.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>New pseudo tty instance (devpts)</title>
> +      <para>
> +	For stricter isolation the container can have its own private
> +	instance of the pseudo tty.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.pts</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      If set, the container will have a new pseudo tty
> +	      instance, making this private to it. The value specifies
> +              the maximum number of pseudo ttys allowed for a pts
> +              instance (this limitation is not implemented yet).
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Container system console</title>
> +      <para>
> +	If the container is configured with a root filesystem and the
> +	inittab file is setup to use the console, you may want to specify
> +	where the output of this console goes.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.console</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify a path to a file where the console output will
> +	      be written. The keyword 'none' will simply disable the
> +	      console. This is dangerous once if have a rootfs with a
> +	      console device file where the application can write, the
> +	      messages will fall in the host.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Console through the ttys</title>
> +      <para>
> +	This option is useful if the container is configured with a root
> +	filesystem and the inittab file is setup to launch a getty on the
> +	ttys. The option specifies the number of ttys to be available for
> +	the container. The number of gettys in the inittab file of the
> +	container should not be greater than the number of ttys	specified
> +	in this option, otherwise the excess getty sessions will die and
> +	respawn indefinitely giving annoying messages on the console or in
> +	<filename>/var/log/messages</filename>.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.tty</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the number of tty to make available to the
> +	      container.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Console devices location</title>
> +      <para>
> +        LXC consoles are provided through Unix98 PTYs created on the
> +	host and bind-mounted over the expected devices in the container.
> +	By default, they are bind-mounted over <filename>/dev/console</filename>
> +	and <filename>/dev/ttyN</filename>.  This can prevent package upgrades
> +	in the guest.  Therefore you can specify a directory location (under
> +	<filename>/dev</filename> under which LXC will create the files and
> +	bind-mount over them.  These will then be symbolically linked to
> +	<filename>/dev/console</filename> and <filename>/dev/ttyN</filename>.
> +	A package upgrade can then succeed as it is able to remove and replace
> +	the symbolic links.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.devttydir</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify a directory under <filename>/dev</filename>
> +	      under which to create the container console devices.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>/dev directory</title>
> +      <para>
> +	By default, lxc does nothing with the container's
> +	<filename>/dev</filename>.  This allows the container's
> +	<filename>/dev</filename> to be set up as needed in the container
> +	rootfs.  If lxc.autodev is set to 1, then after mounting the container's
> +	rootfs LXC will mount a fresh tmpfs under <filename>/dev</filename>
> +	(limited to 100k) and fill in a minimal set of initial devices.
> +        This is generally required when starting a container containing
> +        a "systemd" based "init" but may be optional at other times.  Additional
> +        devices in the containers /dev directory may be created through the
> +        use of the <option>lxc.hook.autodev</option> hook.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.autodev</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Set this to 1 to have LXC mount and populate a minimal
> +	      <filename>/dev</filename> when starting the container.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Enable kmsg symlink</title>
> +      <para>
> +      Enable creating /dev/kmsg as symlink to /dev/console.  This defaults to 1.
> +      </para>
> +      <variablelist>
> +    <varlistentry>
> +      <term>
> +        <option>lxc.kmsg</option>
> +      </term>
> +      <listitem>
> +        <para>
> +          Set this to 0 to disable /dev/kmsg symlinking.
> +        </para>
> +      </listitem>
> +    </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Mount points</title>
> +      <para>
> +	The mount points section specifies the different places to be
> +	mounted. These mount points will be private to the container
> +	and won't be visible by the processes running outside of the
> +	container. This is useful to mount /etc, /var or /home for
> +	examples.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.mount</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify a file location in
> +	      the <filename>fstab</filename> format, containing the
> +	      mount information. If the rootfs is an image file or a
> +	      block device and the fstab is used to mount a point
> +	      somewhere in this rootfs, the path of the rootfs mount
> +	      point should be prefixed with the
> +	      <filename>@LXCROOTFSMOUNT@</filename> default path or
> +	      the value of <option>lxc.rootfs.mount</option> if
> +	      specified. Note that when mounting a filesystem from an
> +	      image file or block device the third field (fs_vfstype)
> +	      cannot be auto as with
> +              <citerefentry>
> +		<refentrytitle>mount</refentrytitle>
> +                <manvolnum>8</manvolnum>
> +              </citerefentry>
> +              but must be explicitly specified.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.mount.entry</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify a mount point corresponding to a line in the
> +	      fstab format.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.mount.auto</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify which standard kernel file systems should be
> +	      automatically mounted. This may dramatically simplify
> +	      the configuration. The file systems are:
> +	    </para>
> +	    <itemizedlist>
> +	      <listitem>
> +	        <para>
> +	          <option>proc:mixed</option> (or <option>proc</option>):
> +	          mount <filename>/proc</filename> as read-write, but
> +	          remount <filename>/proc/sys</filename> and
> +	          <filename>/proc/sysrq-trigger</filename> read-only
> +	          for security / container isolation purposes.
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>proc:rw</option>: mount
> +	          <filename>/proc</filename> as read-write
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>sys:ro</option> (or <option>sys</option>):
> +	          mount <filename>/sys</filename> as read-only
> +	          for security / container isolation purposes.
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>sys:rw</option>: mount
> +	          <filename>/sys</filename> as read-write
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup:mixed</option> (or
> +	          <option>cgroup</option>):
> +	          mount a tmpfs to <filename>/sys/fs/cgroup</filename>,
> +	          create directories for all hierarchies to which
> +	          the container is added, create subdirectories
> +	          there with the name of the cgroup, and bind-mount
> +	          the container's own cgroup into that directory.
> +	          The container will be able to write to its own
> +	          cgroup directory, but not the parents, since they
> +	          will be remounted read-only
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup:ro</option>: similar to
> +	          <option>cgroup:mixed</option>, but everything will
> +	        be mounted read-only.
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup:rw</option>: similar to
> +	          <option>cgroup:mixed</option>, but everything will
> +	          be mounted read-write. Note that the paths leading
> +	          up to the container's own cgroup will be writable,
> +	          but will not be a cgroup filesystem but just part
> +	          of the tmpfs of <filename>/sys/fs/cgroup</filename>
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup-full:mixed</option> (or
> +	          <option>cgroup-full</option>):
> +	          mount a tmpfs to <filename>/sys/fs/cgroup</filename>,
> +	          create directories for all hierarchies to which
> +	          the container is added, bind-mount the hierarchies
> +	          from the host to the container and make everything
> +	          read-only except the container's own cgroup. Note
> +	          that compared to <option>cgroup</option>, where
> +	          all paths leading up to the container's own cgroup
> +	          are just simple directories in the underlying
> +	          tmpfs, here
> +	          <filename>/sys/fs/cgroup/$hierarchy</filename>
> +	          will contain the host's full cgroup hierarchy,
> +	          albeit read-only outside the container's own cgroup.
> +	          This may leak quite a bit of information into the
> +	          container.
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup-full:ro</option>: similar to
> +	          <option>cgroup-full:mixed</option>, but everything
> +	          will be mounted read-only.
> +	        </para>
> +	      </listitem>
> +	      <listitem>
> +	        <para>
> +	          <option>cgroup-full:rw</option>: similar to
> +	          <option>cgroup-full:mixed</option>, but everything
> +	          will be mounted read-write. Note that in this case,
> +	          the container may escape its own cgroup. (Note also
> +	          that if the container has CAP_SYS_ADMIN support
> +	          and can mount the cgroup filesystem itself, it may
> +	          do so anyway.)
> +	        </para>
> +	      </listitem>
> +	    </itemizedlist>
> +	    <para>
> +	      Examples:
> +	    </para>
> +	    <programlisting>
> +	      lxc.mount.auto = proc sys cgroup
> +	      lxc.mount.auto = proc:rw sys:rw cgroup-full:rw
> +	    </programlisting>
> +	  </listitem>
> +	</varlistentry>
> +
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Root file system</title>
> +      <para>
> +	The root file system of the container can be different than that
> +	of the host system.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.rootfs</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the root file system for the container. It can
> +	      be an image file, a directory or a block device. If not
> +	      specified, the container shares its root file system
> +	      with the host.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.rootfs.mount</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      where to recursively bind <option>lxc.rootfs</option>
> +	      before pivoting.  This is to ensure success of the
> +	      <citerefentry>
> +		<refentrytitle><command>pivot_root</command></refentrytitle>
> +		<manvolnum>8</manvolnum>
> +	      </citerefentry>
> +	      syscall.  Any directory suffices, the default should
> +	      generally work.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.pivotdir</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      where to pivot the original root file system under
> +	      <option>lxc.rootfs</option>, specified relatively to
> +	      that.  The default is <filename>mnt</filename>.
> +	      It is created if necessary, and also removed after
> +	      unmounting everything from it during container setup.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Control group</title>
> +      <para>
> +	The control group section contains the configuration for the
> +	different subsystem. <command>lxc</command> does not check the
> +	correctness of the subsystem name. This has the disadvantage
> +	of not detecting configuration errors until the container is
> +	started, but has the advantage of permitting any future
> +	subsystem.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.cgroup.[subsystem name]</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      specify the control group value to be set.  The
> +	      subsystem name is the literal name of the control group
> +	      subsystem.  The permitted names and the syntax of their
> +	      values is not dictated by LXC, instead it depends on the
> +	      features of the Linux kernel running at the time the
> +	      container is started,
> +	      eg. <option>lxc.cgroup.cpuset.cpus</option>
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Capabilities</title>
> +      <para>
> +	The capabilities can be dropped in the container if this one
> +	is run as root.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.cap.drop</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the capability to be dropped in the container. A
> +	      single line defining several capabilities with a space
> +	      separation is allowed. The format is the lower case of
> +	      the capability definition without the "CAP_" prefix,
> +	      eg. CAP_SYS_MODULE should be specified as
> +	      sys_module. See
> +	      <citerefentry>
> +		<refentrytitle><command>capabilities</command></refentrytitle>
> +		<manvolnum>7</manvolnum>
> +	      </citerefentry>,
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.cap.keep</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the capability to be kept in the container. All other
> +	      capabilities will be dropped.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Apparmor profile</title>
> +      <para>
> +	If lxc was compiled and installed with apparmor support, and the host
> +	system has apparmor enabled, then the apparmor profile under which the
> +	container should be run can be specified in the container
> +	configuration.  The default is <command>lxc-container-default</command>.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.aa_profile</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the apparmor profile under which the container should
> +	      be run.  To specify that the container should be unconfined,
> +	      use
> +	    </para>
> +	      <programlisting>lxc.aa_profile = unconfined</programlisting>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>SELinux context</title>
> +      <para>
> +	If lxc was compiled and installed with SELinux support, and the host
> +	system has SELinux enabled, then the SELinux context under which the
> +	container should be run can be specified in the container
> +	configuration.  The default is <command>unconfined_t</command>,
> +	which means that lxc will not attempt to change contexts.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.se_context</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify the SELinux context under which the container should
> +	      be run or <command>unconfined_t</command>. For example
> +	    </para>
> +	    <programlisting>lxc.se_context = unconfined_u:unconfined_r:lxc_t:s0-s0:c0.c1023</programlisting>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Seccomp configuration</title>
> +      <para>
> +        A container can be started with a reduced set of available
> +	system calls by loading a seccomp profile at startup.  The
> +	seccomp configuration file should begin with a version number
> +	(which currently must be 1) on the first line, a policy type
> +	(which must be 'whitelist') on the second line, followed by a
> +	list of allowed system call numbers, one per line.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.seccomp</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Specify a file containing the seccomp configuration to
> +	      load before the container starts.
> +	     </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>UID mappings</title>
> +      <para>
> +        A container can be started in a private user namespace with
> +	user and group id mappings.  For instance, you can map userid
> +	0 in the container to userid 200000 on the host.  The root
> +	user in the container will be privileged in the container,
> +	but unprivileged on the host.  Normally a system container
> +	will want a range of ids, so you would map, for instance,
> +	user and group ids 0 through 20,000 in the container to the
> +	ids 200,000 through 220,000.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.id_map</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Four values must be provided.  First a character, either
> +	      'u', or 'g', to specify whether user or group ids are
> +	      being mapped.  Next is the first userid as seen in the
> +	      user namespace of the container.  Next is the userid as
> +	      seen on the host.  Finally, a range indicating the number
> +	      of consecutive ids to map.
> +	     </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Container hooks</title>
> +      <para>
> +        Container hooks are programs or scripts which can be executed
> +	at various times in a container's lifetime.
> +      </para>
> +      <para>
> +        When a container hook is executed, information is passed both
> +	as command line arguments and through environment variables.
> +	The arguments are:
> +	<itemizedlist>
> +	  <listitem><para> Container name. </para></listitem>
> +	  <listitem><para> Section (always 'lxc'). </para></listitem>
> +	  <listitem><para> The hook type (i.e. 'clone' or 'pre-mount'). </para></listitem>
> +	  <listitem><para> Additional arguments In the
> +	  case of the clone hook, any extra arguments passed to
> +	  lxc-clone will appear as further arguments to the hook. </para></listitem>
> +	</itemizedlist>
> +	The following environment variables are set:
> +	<itemizedlist>
> +	  <listitem><para> LXC_NAME: is the container's name. </para></listitem>
> +	  <listitem><para> LXC_ROOTFS_MOUNT: the path to the mounted root filesystem. </para></listitem>
> +	  <listitem><para> LXC_CONFIG_FILE: the path to the container configuration file. </para></listitem>
> +	  <listitem><para> LXC_SRC_NAME: in the case of the clone hook, this is the original container's name. </para></listitem>
> +	  <listitem><para> LXC_ROOTFS_PATH: this is the lxc.rootfs entry for the container.  Note this is likely not where the mounted rootfs is to be found, use LXC_ROOTFS_MOUNT for that. </para></listitem>
> +	</itemizedlist>
> +      </para>
> +      <para>
> +        Standard output from the hooks is logged at debug level.
> +        Standard error is not logged, but can be captured by the
> +        hook redirecting its standard error to standard output.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.pre-start</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the host's namespace before the
> +	      container ttys, consoles, or mounts are up.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.pre-mount</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the container's fs namespace but before
> +	      the rootfs has been set up.  This allows for manipulation
> +	      of the rootfs, i.e. to mount an encrypted filesystem.  Mounts
> +	      done in this hook will not be reflected on the host (apart from
> +	      mounts propagation), so they will be automatically cleaned up
> +	      when the container shuts down.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.mount</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the container's namespace after
> +	      mounting has been done, but before the pivot_root.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.autodev</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the container's namespace after
> +	      mounting has been done and after any mount hooks have
> +	      run, but before the pivot_root, if
> +	      <option>lxc.autodev</option> == 1.
> +	      The purpose of this hook is to assist in populating the
> +	      /dev directory of the container when using the autodev
> +	      option for systemd based containers.  The container's /dev
> +	      directory is relative to the
> +	      ${<option>LXC_ROOTFS_MOUNT</option>} environment
> +	      variable available when the hook is run.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.start</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the container's namespace immediately
> +	      before executing the container's init.  This requires the
> +	      program to be available in the container.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.post-stop</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run in the host's namespace after the
> +	      container has been shut down.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.hook.clone</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      A hook to be run when the container is cloned to a new one.
> +	      See <citerefentry><refentrytitle><command>lxc-clone</command></refentrytitle>
> +	      <manvolnum>1</manvolnum></citerefentry> for more information.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Container hooks Environment Variables</title>
> +      <para>
> +        A number of environment variables are made available to the startup
> +        hooks to provide configuration information and assist in the
> +        functioning of the hooks.  Not all variables are valid in all
> +        contexts.  In particular, all paths are relative to the host system
> +        and, as such, not valid during the <option>lxc.hook.start</option> hook.
> +      </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_NAME</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      The LXC name of the container.  Useful for logging messages
> +	      in common log environments.  [<option>-n</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_CONFIG_FILE</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      Host relative path to the container configuration file.  This
> +	      gives the container to reference the original, top level,
> +	      configuration file for the container in order to locate any
> +	      additional configuration information not otherwise made
> +	      available.  [<option>-f</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_CONSOLE</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      The path to the console output of the container if not NULL.
> +	      [<option>-c</option>] [<option>lxc.console</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_CONSOLE_LOGPATH</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      The path to the console log output of the container if not NULL.
> +	      [<option>-L</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_ROOTFS_MOUNT</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      The mount location to which the container is initially bound.
> +	      This will be the host relative path to the container rootfs
> +	      for the container instance being started and is where changes
> +	      should be made for that instance.
> +	      [<option>lxc.rootfs.mount</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>LXC_ROOTFS_PATH</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	      The host relative path to the container root which has been
> +	      mounted to the rootfs.mount location.
> +	      [<option>lxc.rootfs</option>]
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +
> +    </refsect2>
> +    <refsect2>
> +    <title>Logging</title>
> +    <para>
> +      Logging can be configured on a per-container basis.  By default,
> +      depending upon how the lxc package was compiled, container startup
> +      is logged only at the ERROR level, and logged to a file named after
> +      the container (with '.log' appended) either under the container path,
> +      or under @LOGPATH at .
> +    </para>
> +    <para>
> +      Both the default log level and the log file can be specified in the
> +      container configuration file, overriding the default behavior.  Note
> +      that the configuration file entries can in turn be overridden by the
> +      command line options to <command>lxc-start</command>.
> +    </para>
> +      <variablelist>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.loglevel</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	    The level at which to log.  The log level is an integer in
> +	    the range of 0..8 inclusive, where a lower number means more
> +	    verbose debugging.  In particular 0 = trace, 1 = debug, 2 =
> +	    info, 3 = notice, 4 = warn, 5 = error, 6 = critical, 7 =
> +	    alert, and 8 = fatal.  If unspecified, the level defaults
> +	    to 5 (error), so that only errors and above are logged.
> +	    </para>
> +	    <para>
> +	    Note that when a script (such as either a hook script or a
> +	    network interface up or down script) is called, the script's
> +	    standard output is logged at level 1, debug.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +	<varlistentry>
> +	  <term>
> +	    <option>lxc.logfile</option>
> +	  </term>
> +	  <listitem>
> +	    <para>
> +	    The file to which logging info should be written.
> +	    </para>
> +	  </listitem>
> +	</varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +    <title>Autostart</title>
> +    <para>
> +        The autostart options support marking which containers should be
> +        auto-started and in what order. These options may be used by LXC tools
> +        directly or by external tooling provided by the distributions.
> +    </para>
> +
> +    <variablelist>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.start.auto</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Whether the container should be auto-started.
> +              Valid values are 0 (off) and 1 (on).
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.start.delay</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              How long to wait (in seconds) after the container is
> +              started before starting the next one.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.start.order</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              An integer used to sort the containers when auto-starting
> +              a series of containers at once.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.group</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              A multi-value key (can be used multiple times) to put the
> +              container in a container group. Those groups can then be
> +              used (amongst other things) to start a series of related
> +              containers.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +  </refsect1>
> +
> +  <refsect1>
> +    <title>Examples</title>
> +      <para>
> +	In addition to the few examples given below, you will find
> +	some other examples of configuration file in @DOCDIR@/examples
> +      </para>
> +    <refsect2>
> +      <title>Network</title>
> +      <para>This configuration sets up a container to use a veth pair
> +	device with one side plugged to a bridge br0 (which has been
> +	configured before on the system by the administrator). The
> +	virtual network device visible in the container is renamed to
> +	eth0.</para>
> +      <programlisting>
> +	lxc.utsname = myhostname
> +	lxc.network.type = veth
> +	lxc.network.flags = up
> +	lxc.network.link = br0
> +	lxc.network.name = eth0
> +	lxc.network.hwaddr = 4a:49:43:49:79:bf
> +	lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
> +	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
> +      </programlisting>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>UID/GID mapping</title>
> +      <para>This configuration will map both user and group ids in the
> +        range 0-9999 in the container to the ids 100000-109999 on the host.
> +      </para>
> +      <programlisting>
> +	lxc.id_map = u 0 100000 10000
> +	lxc.id_map = g 0 100000 10000
> +      </programlisting>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Control group</title>
> +      <para>This configuration will setup several control groups for
> +      the application, cpuset.cpus restricts usage of the defined cpu,
> +      cpus.share prioritize the control group, devices.allow makes
> +      usable the specified devices.</para>
> +      <programlisting>
> +	lxc.cgroup.cpuset.cpus = 0,1
> +	lxc.cgroup.cpu.shares = 1234
> +	lxc.cgroup.devices.deny = a
> +	lxc.cgroup.devices.allow = c 1:3 rw
> +	lxc.cgroup.devices.allow = b 8:0 rw
> +      </programlisting>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Complex configuration</title>
> +      <para>This example show a complex configuration making a complex
> +      network stack, using the control groups, setting a new hostname,
> +      mounting some locations and a changing root file system.</para>
> +      <programlisting>
> +	lxc.utsname = complex
> +	lxc.network.type = veth
> +	lxc.network.flags = up
> +	lxc.network.link = br0
> +	lxc.network.hwaddr = 4a:49:43:49:79:bf
> +	lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255
> +	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
> +	lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588
> +	lxc.network.type = macvlan
> +	lxc.network.flags = up
> +	lxc.network.link = eth0
> +	lxc.network.hwaddr = 4a:49:43:49:79:bd
> +	lxc.network.ipv4 = 10.2.3.4/24
> +	lxc.network.ipv4 = 192.168.10.125/24
> +	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
> +	lxc.network.type = phys
> +	lxc.network.flags = up
> +	lxc.network.link = dummy0
> +	lxc.network.hwaddr = 4a:49:43:49:79:ff
> +	lxc.network.ipv4 = 10.2.3.6/24
> +	lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
> +	lxc.cgroup.cpuset.cpus = 0,1
> +	lxc.cgroup.cpu.shares = 1234
> +	lxc.cgroup.devices.deny = a
> +	lxc.cgroup.devices.allow = c 1:3 rw
> +	lxc.cgroup.devices.allow = b 8:0 rw
> +	lxc.mount = /etc/fstab.complex
> +	lxc.mount.entry = /lib /root/myrootfs/lib none ro,bind 0 0
> +	lxc.rootfs = /mnt/rootfs.complex
> +	lxc.cap.drop = sys_module mknod setuid net_raw
> +	lxc.cap.drop = mac_override
> +      </programlisting>
> +    </refsect2>
> +
> +  </refsect1>
> +
> +  <refsect1>
> +    <title>See Also</title>
> +    <simpara>
> +      <citerefentry>
> +	<refentrytitle><command>chroot</command></refentrytitle>
> +	<manvolnum>1</manvolnum>
> +      </citerefentry>,
> +
> +      <citerefentry>
> +	<refentrytitle><command>pivot_root</command></refentrytitle>
> +	<manvolnum>8</manvolnum>
> +      </citerefentry>,
> +
> +      <citerefentry>
> +	<refentrytitle><filename>fstab</filename></refentrytitle>
> +	<manvolnum>5</manvolnum>
> +      </citerefentry>,
> +
> +      <citerefentry>
> +	<refentrytitle><filename>capabilities</filename></refentrytitle>
> +	<manvolnum>7</manvolnum>
> +      </citerefentry>
> +    </simpara>
> +  </refsect1>
> +
> +  &seealso;
> +
> +  <refsect1>
> +    <title>Author</title>
> +    <para>Daniel Lezcano <email>daniel.lezcano at free.fr</email></para>
> +  </refsect1>
> +
> +</refentry>
> +
> +<!-- Keep this comment at the end of the file
> +Local variables:
> +mode: sgml
> +sgml-omittag:t
> +sgml-shorttag:t
> +sgml-minimize-attributes:nil
> +sgml-always-quote-attributes:t
> +sgml-indent-step:2
> +sgml-indent-data:t
> +sgml-parent-document:nil
> +sgml-default-dtd-file:nil
> +sgml-exposed-tags:nil
> +sgml-local-catalogs:nil
> +sgml-local-ecat-files:nil
> +End:
> +-->
> diff --git a/doc/lxc.system.conf b/doc/lxc.system.conf
> new file mode 100644
> index 0000000..c895ff5
> --- /dev/null
> +++ b/doc/lxc.system.conf
> @@ -0,0 +1,20 @@
> +# LVM: volume group to use for new containers
> +lxc.bdev.lvm.vg = lxc
> +
> +# LVM: thin pool to use for new containers
> +lxc.bdev.lvm.thin_pool = lxc
> +
> +# ZFS: Root path
> +lxc.bdev.zfs.root = lxc
> +
> +# Path to the containers
> +lxc.lxcpath = /var/lib/lxc/
> +
> +# Path to the default configuration file
> +lxc.default_config = /etc/lxc/default.conf
> +
> +# Pattern to use for the cgroup path
> +lxc.cgroup.pattern = lxc/%n
> +
> +# List of cgroups to use
> +lxc.cgroup.use =
> diff --git a/doc/lxc.system.conf.sgml.in b/doc/lxc.system.conf.sgml.in
> new file mode 100644
> index 0000000..a2b70ec
> --- /dev/null
> +++ b/doc/lxc.system.conf.sgml.in
> @@ -0,0 +1,206 @@
> +<!--
> +
> +lxc: linux Container library
> +
> +(C) Copyright Canonical Ltd. 2014
> +
> +Authors:
> +Stéphane Graber <stgraber at ubuntu.com>
> +
> +This library is free software; you can redistribute it and/or
> +modify it under the terms of the GNU Lesser General Public
> +License as published by the Free Software Foundation; either
> +version 2.1 of the License, or (at your option) any later version.
> +
> +This library is distributed in the hope that it will be useful,
> +but WITHOUT ANY WARRANTY; without even the implied warranty of
> +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +Lesser General Public License for more details.
> +
> +You should have received a copy of the GNU Lesser General Public
> +License along with this library; if not, write to the Free Software
> +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> +
> +-->
> +
> +<!DOCTYPE refentry PUBLIC @docdtd@ [
> +
> +<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
> +]>
> +
> +<refentry>
> +
> +  <docinfo><date>@LXC_GENERATE_DATE@</date></docinfo>
> +
> +  <refmeta>
> +    <refentrytitle>lxc.system.conf</refentrytitle>
> +    <manvolnum>5</manvolnum>
> +  </refmeta>
> +
> +  <refnamediv>
> +    <refname>lxc.system.conf</refname>
> +
> +    <refpurpose>
> +      LXC system configuration file
> +    </refpurpose>
> +  </refnamediv>
> +
> +  <refsect1>
> +    <title>Description</title>
> +
> +    <para>
> +      The system configuration is located at
> +      <filename>@LXC_GLOBAL_CONF@</filename> or
> +      <filename>~/.config/lxc/lxc.conf</filename> for unprivileged
> +      containers.
> +    </para>
> +
> +    <para>
> +      This configuration file is used to set values such as default
> +      lookup paths and storage backend settings for LXC.
> +    </para>
> +
> +    <refsect2>
> +      <title>Configuration paths</title>
> +
> +      <variablelist>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.lxcpath</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              The location in which all containers are stored.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.default_config</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              The path to the default container configuration.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>Control Groups</title>
> +
> +      <variablelist>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.cgroup.user</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Comma separated list of cgroup controllers to setup.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.cgroup.pattern</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Format string used to generate the cgroup path (e.g. lxc/%n).
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>LVM</title>
> +
> +      <variablelist>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.bdev.lvm.vg</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Default LVM volume group name.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.bdev.lvm.thin_pool</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Default LVM thin pool name.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +
> +    <refsect2>
> +      <title>ZFS</title>
> +
> +      <variablelist>
> +        <varlistentry>
> +          <term>
> +            <option>lxc.bdev.zfs.root</option>
> +          </term>
> +          <listitem>
> +            <para>
> +              Default ZFS root name.
> +            </para>
> +          </listitem>
> +        </varlistentry>
> +      </variablelist>
> +    </refsect2>
> +  </refsect1>
> +
> +  <refsect1>
> +    <simpara>
> +      <citerefentry>
> +        <refentrytitle><command>lxc</command></refentrytitle>
> +        <manvolnum>1</manvolnum>
> +      </citerefentry>,
> +      <citerefentry>
> +        <refentrytitle><command>lxc.container.conf</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
> +      </citerefentry>,
> +      <citerefentry>
> +        <refentrytitle><command>lxc.system.conf</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
> +      </citerefentry>,
> +      <citerefentry>
> +        <refentrytitle><command>lxc-usernet</command></refentrytitle>
> +        <manvolnum>5</manvolnum>
> +      </citerefentry>
> +    </simpara>
> +  </refsect1>
> +
> +  &seealso;
> +
> +  <refsect1>
> +    <title>Author</title>
> +    <para>Stéphane Graber <email>stgraber at ubuntu.com</email></para>
> +  </refsect1>
> +</refentry>
> +
> +<!-- Keep this comment at the end of the file
> +Local variables:
> +mode: sgml
> +sgml-omittag:t
> +sgml-shorttag:t
> +sgml-minimize-attributes:nil
> +sgml-always-quote-attributes:t
> +sgml-indent-step:2
> +sgml-indent-data:t
> +sgml-parent-document:nil
> +sgml-default-dtd-file:nil
> +sgml-exposed-tags:nil
> +sgml-local-catalogs:nil
> +sgml-local-ecat-files:nil
> +End:
> +-->
> -- 
> 1.8.5.3
> 
> _______________________________________________
> lxc-devel mailing list
> lxc-devel at lists.linuxcontainers.org
> http://lists.linuxcontainers.org/listinfo/lxc-devel


More information about the lxc-devel mailing list