[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