</para>
<para>
- LXC has supports unprivileged containers. Unprivileged containers are
+ LXC has support for unprivileged containers. Unprivileged containers are
containers that are run without any privilege. This requires support for
user namespaces in the kernel that the container is run on. LXC was the
first runtime to support unprivileged containers after user namespaces
</para>
<para>
- LXC namespaces configuration keys by using single dots. This means complex
+ LXC namespaces configuration keys use single dots. This means complex
configuration keys such as <option>lxc.net.0</option> expose various
subkeys such as <option>lxc.net.0.type</option>,
<option>lxc.net.0.link</option>, <option>lxc.net.0.ipv6.address</option>, and
</variablelist>
</refsect2>
+ <refsect2>
+ <title>Init working directory</title>
+ <para>
+ Sets the absolute path inside the container as the working directory for the containers.
+ LXC will switch to this directory before executing init.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>lxc.init.cwd</option>
+ </term>
+ <listitem>
+ <para>
+ Absolute path inside the container to use as the working directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2>
<title>Init ID</title>
<para>
Sets the UID/GID to use for the init system, and subsequent commands.
- Note that using a non-root uid when booting a system container will
+ Note that using a non-root UID when booting a system container will
likely not work due to missing privileges. Setting the UID/GID is mostly
- useful when running application container.
+ useful when running application containers.
Defaults to: UID(0), GID(0)
</para>
</variablelist>
</refsect2>
+ <refsect2>
+ <title>Proc</title>
+ <para>
+ Configure proc filesystem for the container.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>lxc.proc.[proc file name]</option>
+ </term>
+ <listitem>
+ <para>
+ Specify the proc file name to be set. The file names available
+ are those listed under /proc/PID/.
+ Example:
+ </para>
+ <programlisting>
+ lxc.proc.oom_score_adj = 10
+ </programlisting>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2>
<title>Ephemeral</title>
<para>
<listitem>
<para>
The only allowed values are 0 and 1. Set this to 1 to destroy a
- container on shutdown.
+ container on shutdown.
</para>
</listitem>
</varlistentry>
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.
+ host. Note that unprivileged containers do not work with this
+ setting due to an inability to mount sysfs. An unsafe workaround
+ would be to bind mount the host's sysfs.
</para>
<para>
the <option>lxc.net.[i].veth.pair</option> option (except for
unprivileged containers where this option is ignored for security
reasons).
+
+ Static routes can be added on the host pointing to the container using the
+ <option>lxc.net.[i].veth.ipv4.route</option> and
+ <option>lxc.net.[i].veth.ipv6.route</option> options.
+ Several lines specify several routes.
+ The route is in format x.y.z.t/m, eg. 192.168.1.0/24.
</para>
<para>
different macvlan on the same upper device. The accepted
modes are <option>private</option>, <option>vepa</option>,
<option>bridge</option> and <option>passthru</option>.
- In <option>private</option> mode, the device never
+ In <option>private</option> mode, the device never
communicates with any other device on the same upper_dev (default).
In <option>vepa</option> mode, the new Virtual Ethernet Port
Aggregator (VEPA) mode, it assumes that the adjacent
mode is possible for one physical interface.
</para>
+ <para>
+ <option>ipvlan:</option> an ipvlan interface is linked
+ with the interface specified by
+ the <option>lxc.net.[i].link</option> and assigned to
+ the container.
+ <option>lxc.net.[i].ipvlan.mode</option> specifies the
+ mode the ipvlan will use to communicate between
+ different ipvlan on the same upper device. The accepted
+ modes are <option>l3</option>, <option>l3s</option> and
+ <option>l2</option>. It defaults to <option>l3</option> mode.
+ In <option>l3</option> mode TX processing up to L3 happens on the stack instance
+ attached to the slave device and packets are switched to the stack instance of the
+ master device for the L2 processing and routing from that instance will be
+ used before packets are queued on the outbound device. In this mode the slaves
+ will not receive nor can send multicast / broadcast traffic.
+ In <option>l3s</option> mode TX processing is very similar to the L3 mode except that
+ iptables (conn-tracking) works in this mode and hence it is L3-symmetric (L3s).
+ This will have slightly less performance but that shouldn't matter since you are
+ choosing this mode over plain-L3 mode to make conn-tracking work.
+ In <option>l2</option> mode TX processing happens on the stack instance attached to
+ the slave device and packets are switched and queued to the master device to send
+ out. In this mode the slaves will RX/TX multicast and broadcast (if applicable) as well.
+ <option>lxc.net.[i].ipvlan.isolation</option> specifies the isolation mode.
+ The accepted isolation values are <option>bridge</option>,
+ <option>private</option> and <option>vepa</option>.
+ It defaults to <option>bridge</option>.
+ In <option>bridge</option> isolation mode slaves can cross-talk among themselves
+ apart from talking through the master device.
+ In <option>private</option> isolation mode the port is set in private mode.
+ i.e. port won't allow cross communication between slaves.
+ In <option>vepa</option> isolation mode the port is set in VEPA mode.
+ i.e. port will offload switching functionality to the external entity as
+ described in 802.1Qbg.
+ </para>
+
<para>
<option>phys:</option> an already existing interface
specified by the <option>lxc.net.[i].link</option> is
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.net.[i].l2proxy</option>
+ </term>
+ <listitem>
+ <para>
+ Controls whether layer 2 IP neighbour proxy entries will be added to the
+ lxc.net.[i].link interface for the IP addresses of the container.
+ Can be set to 0 or 1. Defaults to 0.
+ When used with IPv4 addresses, the following sysctl values need to be set:
+ net.ipv4.conf.[link].forwarding=1
+ When used with IPv6 addresses, the following sysctl values need to be set:
+ net.ipv6.conf.[link].proxy_ndp=1
+ net.ipv6.conf.[link].forwarding=1
+ </para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>
<option>lxc.net.[i].mtu</option>
interface (as specified by the
<option>lxc.net.[i].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.
+ using the <option>veth</option>,
+ <option>macvlan</option> and <option>ipvlan</option> network types.
+ Can also have the special value of <option>dev</option>,
+ which means to set the default gateway as a device route.
+ This is primarily for use with layer 3 network modes, such as IPVLAN.
</para>
</listitem>
</varlistentry>
-
<varlistentry>
<term>
<option>lxc.net.[i].ipv6.address</option>
interface (as specified by the
<option>lxc.net.[i].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.
+ using the <option>veth</option>,
+ <option>macvlan</option> and <option>ipvlan</option> network types.
+ Can also have the special value of <option>dev</option>,
+ which means to set the default gateway as a device route.
+ This is primarily for use with layer 3 network modes, such as IPVLAN.
</para>
</listitem>
</varlistentry>
<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.
+ from the host side.
+ </para>
+
+ <para>
+ In addition to the information available to all hooks. The
+ following information is provided to the script:
+ <itemizedlist>
+ <listitem>
+ <para>
+ LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_HOOK_SECTION: the section type 'net'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_TYPE: the network type. This is one of the valid
+ network types listed here (e.g. 'vlan', 'macvlan', 'ipvlan', 'veth').
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_PARENT: the parent device on the host. This is only
+ set for network types 'mavclan', 'veth', 'phys'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_PEER: the name of the peer device on the host. This is
+ only set for 'veth' network types. Note that this information
+ is only available when <option>lxc.hook.version</option> is set
+ to 1.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Whether this information is provided in the form of environment
+ variables or as arguments to the script depends on the value of
+ <option>lxc.hook.version</option>. If set to 1 then information is
+ provided in the form of environment variables. If set to 0
+ information is provided as arguments to the script.
</para>
+
<para>
Standard output from the script is logged at debug level.
Standard error is not logged, but can be captured by the
<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.
+ host side.
+ </para>
+
+ <para>
+ In addition to the information available to all hooks. The
+ following information is provided to the script:
+ <itemizedlist>
+ <listitem>
+ <para>
+ LXC_HOOK_TYPE: the hook type. This is either 'up' or 'down'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_HOOK_SECTION: the section type 'net'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_TYPE: the network type. This is one of the valid
+ network types listed here (e.g. 'vlan', 'macvlan', 'ipvlan', 'veth').
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_PARENT: the parent device on the host. This is only
+ set for network types 'mavclan', 'veth', 'phys'.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ LXC_NET_PEER: the name of the peer device on the host. This is
+ only set for 'veth' network types. Note that this information
+ is only available when <option>lxc.hook.version</option> is set
+ to 1.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ Whether this information is provided in the form of environment
+ variables or as arguments to the script depends on the value of
+ <option>lxc.hook.version</option>. If set to 1 then information is
+ provided in the form of environment variables. If set to 0
+ information is provided as arguments to the script.
</para>
+
<para>
Standard output from the script is logged at debug level.
Standard error is not logged, but can be captured by the
ringbuffer. Note that ringbuffer must be at least as big as a
standard page size. When passed a value smaller than a single page
size liblxc will allocate a ringbuffer of a single page size. A page
- size is usually 4kB.
+ size is usually 4KB.
The keyword 'auto' will cause liblxc to allocate a ringbuffer of
- 128kB.
+ 128KB.
When manually specifying a size for the ringbuffer the value should
be a power of 2 when converted to bytes. Valid size prefixes are
- 'kB', 'MB', 'GB'. (Note that all conversions are based on multiples
- of 1024. That means 'kb' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'.)
+ 'KB', 'MB', 'GB'. (Note that all conversions are based on multiples
+ of 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'.
+ Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and
+ 'Kb' are treated equally.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <option>lxc.console.buffer.logfile</option>
+ <option>lxc.console.size</option>
</term>
<listitem>
<para>
- Setting this option instructs liblxc to write the in-memory
- ringbuffer to disk. For performance reasons liblxc will only write
- the in-memory ringbuffer to disk when requested. Note that the this
- option is only used by liblxc when
- <option>lxc.console.buffer.size</option> is set.
+ Setting this option instructs liblxc to place a limit on the size of
+ the console log file specified in
+ <option>lxc.console.logfile</option>. Note that size of the log file
+ must be at least as big as a standard page size. When passed a value
+ smaller than a single page size liblxc will set the size of log file
+ to a single page size. A page size is usually 4KB.
+
+ The keyword 'auto' will cause liblxc to place a limit of 128KB on
+ the log file.
+
+ When manually specifying a size for the log file the value should
+ be a power of 2 when converted to bytes. Valid size prefixes are
+ 'KB', 'MB', 'GB'. (Note that all conversions are based on multiples
+ of 1024. That means 'KB' == 'KiB', 'MB' == 'MiB', 'GB' == 'GiB'.
+ Additionally, the case of the suffix is ignored, i.e. 'kB', 'KB' and
+ 'Kb' are treated equally.)
- By default liblxc will dump the contents of the in-memory ringbuffer
- to disk when the container terminates. This allows users to diagnose
- boot failures when the container crashed before an API request to
- retrieve the in-memory ringbuffer could be sent or handled.
+ If users want to mirror the console ringbuffer on disk they should set
+ <option>lxc.console.size</option> equal to
+ <option>lxc.console.buffer.size</option>.
</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>
- specify a mount point corresponding to a line in the
+ Specify a mount point corresponding to a line in the
fstab format.
- Moreover lxc add two options to mount.
+ Moreover lxc supports mount propagation, such as rslave or
+ rprivate, and adds three additional mount options.
<option>optional</option> don't fail if mount does not work.
<option>create=dir</option> or <option>create=file</option>
to create dir (or file) when the point will be mounted.
- </para>
+ <option>relative</option> source path is taken to be relative to
+ the mounted container root. For instance,
+ </para>
+<screen>
+dev/null proc/kcore none bind,relative 0 0
+</screen>
+ <para>
+ Will expand dev/null to ${<option>LXC_ROOTFS_MOUNT</option>}/dev/null,
+ and mount it to proc/kcore inside the container.
+ </para>
</listitem>
</varlistentry>
<filename>/sys</filename> as read-write
</para>
</listitem>
+
<listitem>
<para>
<option>cgroup:mixed</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.
+ Mount a tmpfs to <filename>/sys/fs/cgroup</filename>,
+ create directories for all hierarchies to which the container
+ is added, create subdirectories in those hierarchies 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:mixed:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup:mixed</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
+ </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:ro</option>: similar to
- <option>cgroup:mixed</option>, but everything will
- be mounted read-only.
+ <option>cgroup:ro:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup:ro</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
</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>
+ <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:rw:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup:rw</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
+ </para>
+ </listitem>
+
<listitem>
<para>
<option>cgroup</option> (without specifier):
<option>cgroup:mixed</option> otherwise.
</para>
</listitem>
+
<listitem>
<para>
<option>cgroup-full:mixed</option>:
container.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ <option>cgroup-full:mixed:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup-full:mixed</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
+ </para>
+ </listitem>
+
<listitem>
<para>
<option>cgroup-full:ro</option>: similar to
will be mounted read-only.
</para>
</listitem>
+
+ <listitem>
+ <para>
+ <option>cgroup-full:ro:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup-full:ro</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
+ </para>
+ </listitem>
+
<listitem>
<para>
<option>cgroup-full:rw</option>: similar to
do so anyway.)
</para>
</listitem>
+
+ <listitem>
+ <para>
+ <option>cgroup-full:rw:force</option>:
+ The <option>force</option> option will cause LXC to perform
+ the cgroup mounts for the container under all circumstances.
+ Otherwise it is similar to <option>cgroup-full:rw</option>.
+ This is mainly useful when the cgroup namespaces are enabled
+ where LXC will normally leave mounting cgroups to the init
+ binary of the container since it is perfectly safe to do so.
+ </para>
+ </listitem>
+
<listitem>
<para>
<option>cgroup-full</option> (without specifier):
<option>cgroup-full:mixed</option> otherwise.
</para>
</listitem>
+
</itemizedlist>
<para>
If cgroup namespaces are enabled, then any <option>cgroup</option>
itself should be mounted. <filename>overlayfs:/lower:/upper</filename>
specifies that the rootfs should be an overlay with <filename>/upper</filename>
being mounted read-write over a read-only mount of <filename>/lower</filename>.
- <filename>aufs:/lower:/upper</filename> does the same using aufs in place
- of overlayfs. For both <filename>overlayfs</filename> and
- <filename>aufs</filename> multiple <filename>/lower</filename>
+ For <filename>overlay</filename> multiple <filename>/lower</filename>
directories can be specified. <filename>loop:/file</filename> tells lxc to attach
<filename>/file</filename> to a loop device and mount the loop device.
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.rootfs.managed</option>
+ </term>
+ <listitem>
+ <para>
+ Set this to 0 to indicate that LXC is not managing the
+ container storage, then LXC will not modify the
+ container storage. The default is 1.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</refsect2>
<variablelist>
<varlistentry>
<term>
- <option>lxc.cgroup.[subsystem name]</option>
+ <option>lxc.cgroup.[controller 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>
+ Specify the control group value to be set on a legacy cgroup
+ hierarchy. The controller name is the literal name of the control
+ group. 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>
+ <varlistentry>
+ <term>
+ <option>lxc.cgroup2.[controller name]</option>
+ </term>
+ <listitem>
+ <para>
+ Specify the control group value to be set on the unified cgroup
+ hierarchy. The controller name is the literal name of the control
+ group. 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.cgroup2.memory.high</option>
</para>
</listitem>
</varlistentry>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.cgroup.relative</option>
+ </term>
+ <listitem>
+ <para>
+ Set this to 1 to instruct LXC to never escape to the
+ root cgroup. This makes it easy for users to adhere to
+ restrictions enforced by cgroup2 and
+ systemd. Specifically, this makes it possible to run LXC
+ containers as systemd services.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
</refsect2>
<refsect2>
- <title>Namespace Inheritance</title>
+ <title>Namespaces</title>
<para>
- The capabilities can be dropped in the container if this one
- is run as root.
+ A namespace can be cloned (<option>lxc.namespace.clone</option>),
+ kept (<option>lxc.namespace.keep</option>) or shared
+ (<option>lxc.namespace.share.[namespace identifier]</option>).
</para>
<variablelist>
<varlistentry>
<term>
- <option>lxc.namespace.[namespace identifier]</option>
+ <option>lxc.namespace.clone</option>
+ </term>
+ <listitem>
+ <para>
+ Specify namespaces which the container is supposed to be created
+ with. The namespaces to create are specified as a space separated
+ list. Each namespace must correspond to one of the standard
+ namespace identifiers as seen in the
+ <filename>/proc/PID/ns</filename> directory.
+ When <option>lxc.namespace.clone</option> is not explicitly set all
+ namespaces supported by the kernel and the current configuration
+ will be used.
+ </para>
+
+ <para>
+ To create a new mount, net and ipc namespace set
+ <option>lxc.namespace.clone=mount net ipc</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>lxc.namespace.keep</option>
+ </term>
+ <listitem>
+ <para>
+ Specify namespaces which the container is supposed to inherit from
+ the process that created it. The namespaces to keep are specified as
+ a space separated list. Each namespace must correspond to one of the
+ standard namespace identifiers as seen in the
+ <filename>/proc/PID/ns</filename> directory.
+ The <option>lxc.namespace.keep</option> is a
+ blacklist option, i.e. it is useful when enforcing that containers
+ must keep a specific set of namespaces.
+ </para>
+
+ <para>
+ To keep the network, user and ipc namespace set
+ <option>lxc.namespace.keep=user net ipc</option>.
+ </para>
+
+ <para>
+ Note that sharing pid namespaces will likely not work with most init
+ systems.
+ </para>
+
+ <para>
+ Note that if the container requests a new user namespace and the
+ container wants to inherit the network namespace it needs to inherit
+ the user namespace as well.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>lxc.namespace.share.[namespace identifier]</option>
</term>
<listitem>
<para>
<para>
To inherit the namespace from another process set the
- <option>lxc.namespace.[namespace identifier]</option> to the PID of
- the process, e.g. <option>lxc.namespace.net=42</option>.
+ <option>lxc.namespace.share.[namespace identifier]</option> to the PID of
+ the process, e.g. <option>lxc.namespace.share.net=42</option>.
</para>
<para>
- To inherit the namespace from another container set the
- <option>lxc.namespace.[namespace identifier]</option> to the name of
- the container, e.g. <option>lxc.namespace.pid=c3</option>.
+ To inherit the namespace from another container set the
+ <option>lxc.namespace.share.[namespace identifier]</option> to the name of
+ the container, e.g. <option>lxc.namespace.share.pid=c3</option>.
</para>
<para>
To inherit the namespace from another container located in a
different path than the standard liblxc path set the
- <option>lxc.namespace.[namespace identifier]</option> to the full
+ <option>lxc.namespace.share.[namespace identifier]</option> to the full
path to the container, e.g.
- <option>lxc.namespace.user=/opt/c3</option>.
+ <option>lxc.namespace.share.user=/opt/c3</option>.
</para>
<para>
process wants to inherit the other's network namespace it usually
needs to inherit the user namespace as well.
</para>
+
+ <para>
+ Note that without careful additional configuration of an LSM,
+ sharing user+pid namespaces with a task may allow that task to
+ escalate privileges to that of the task calling liblxc.
+ </para>
</listitem>
</varlistentry>
</variablelist>
</variablelist>
</refsect2>
+ <refsect2>
+ <title>Sysctl</title>
+ <para>
+ Configure kernel parameters for the container.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>
+ <option>lxc.sysctl.[kernel parameters name]</option>
+ </term>
+ <listitem>
+ <para>
+ Specify the kernel parameters to be set. The parameters available
+ are those listed under /proc/sys/.
+ Note that not all sysctls are namespaced. Changing Non-namespaced
+ sysctls will cause the system-wide setting to be modified.
+ <citerefentry>
+ <refentrytitle><command>sysctl</command></refentrytitle>
+ <manvolnum>8</manvolnum>
+ </citerefentry>.
+ If used with no value, lxc will clear the parameters specified up
+ to this point.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2>
<title>Apparmor profile</title>
<para>
container should be run can be specified in the container
configuration. The default is <command>lxc-container-default-cgns</command>
if the host kernel is cgroup namespace aware, or
- <command>lxc-container-default</command> othewise.
+ <command>lxc-container-default</command> otherwise.
</para>
<variablelist>
<varlistentry>
are nesting containers and are already confined), then use
</para>
<programlisting>lxc.apparmor.profile = unchanged</programlisting>
+ <para>
+ If you instruct LXC to generate the apparmor profile,
+ then use
+ </para>
+ <programlisting>lxc.apparmor.profile = generated</programlisting>
</listitem>
</varlistentry>
<varlistentry>
</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>lxc.apparmor.allow_nesting</option>
+ </term>
+ <listitem>
+ <para>
+ If set this to 1, causes the following changes. When
+ generated apparmor profiles are used, they will contain
+ the necessary changes to allow creating a nested
+ container. In addition to the usual mount points,
+ <filename>/dev/.lxc/proc</filename>
+ and <filename>/dev/.lxc/sys</filename> will contain
+ procfs and sysfs mount points without the lxcfs
+ overlays, which, if generated apparmor profiles are
+ being used, will not be read/writable directly.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>lxc.apparmor.raw</option>
+ </term>
+ <listitem>
+ <para>
+ A list of raw AppArmor profile lines to append to the
+ profile. Only valid when using generated profiles.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</refsect2>
Versions 1 and 2 are currently supported. In version 1, the
policy is a simple whitelist. The second line therefore must
read "whitelist", with the rest of the file containing one (numeric)
- sycall number per line. Each syscall number is whitelisted,
+ syscall number per line. Each syscall number is whitelisted,
while every unlisted number is blacklisted for use in the container
</para>
2
blacklist
mknod errno 0
+ ioctl notify
</programlisting>
+ <para>
+ Specifying "errno" as action will cause LXC to register a seccomp filter
+ that will cause a specific errno to be returned to the caller. The errno
+ value can be specified after the "errno" action word.
+ </para>
+
+ <para>
+ Specifying "notify" as action will cause LXC to register a seccomp
+ listener and retrieve a listener file descriptor from the kernel. When a
+ syscall is made that is registered as "notify" the kernel will generate a
+ poll event and send a message over the file descriptor. The caller can
+ read this message, inspect the syscalls including its arguments. Based on
+ this information the caller is expected to send back a message informing
+ the kernel which action to take. Until that message is sent the kernel
+ will block the calling process. The format of the messages to read and
+ sent is documented in seccomp itself.
+ </para>
+
<variablelist>
<varlistentry>
<term>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.seccomp.allow_nesting</option>
+ </term>
+ <listitem>
+ <para>
+ If this flag is set to 1, then seccomp filters will be stacked
+ regardless of whether a seccomp profile is already loaded.
+ This allows nested containers to load their own seccomp profile.
+ The default setting is 0.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.seccomp.notify.proxy</option>
+ </term>
+ <listitem>
+ <para>
+ Specify a unix socket to which LXC will connect and forward
+ seccomp events to. The path must by in the form
+ unix:/path/to/socket or unix:@socket. The former specifies a
+ path-bound unix domain socket while the latter specifies an
+ abstract unix domain socket.
+ </para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
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:
+ When a container hook is executed, additional information is passed
+ along. The <option>lxc.hook.version</option> argument can be used to
+ determine if the following arguments are passed as command line
+ arguments or 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.
- In the case of the stop hook, paths to filedescriptors
- for each of the container's namespaces along with their types
- are passed. </para></listitem>
+ case of the clone hook, any extra arguments passed will appear as
+ further arguments to the hook. In the case of the stop hook, paths to
+ filedescriptors for each of the container's namespaces along with
+ their types are passed. </para></listitem>
</itemizedlist>
The following environment variables are set:
<itemizedlist>
+ <listitem><para> LXC_CGNS_AWARE: indicator whether the container is
+ cgroup namespace aware. </para></listitem>
+ <listitem><para> LXC_CONFIG_FILE: the path to the container
+ configuration file. </para></listitem>
+ <listitem><para> LXC_HOOK_TYPE: the hook type (e.g. 'clone', 'mount',
+ 'pre-mount'). Note that the existence of this environment variable is
+ conditional on the value of <option>lxc.hook.version</option>. If it
+ is set to 1 then LXC_HOOK_TYPE will be set.
+ </para></listitem>
+ <listitem><para> LXC_HOOK_SECTION: the section type (e.g. 'lxc',
+ 'net'). Note that the existence of this environment variable is
+ conditional on the value of <option>lxc.hook.version</option>. If it
+ is set to 1 then LXC_HOOK_SECTION will be set.
+ </para></listitem>
+ <listitem><para> LXC_HOOK_VERSION: the version of the hooks. This
+ value is identical to the value of the container's
+ <option>lxc.hook.version</option> config item. If it is set to 0 then
+ old-style hooks are used. If it is set to 1 then new-style hooks are
+ used. </para></listitem>
+ <listitem><para> LXC_LOG_LEVEL: the container's log level. </para></listitem>
<listitem><para> LXC_NAME: is the container's name. </para></listitem>
+ <listitem><para> LXC_[NAMESPACE IDENTIFIER]_NS: path under
+ /proc/PID/fd/ to a file descriptor referring to the container's
+ namespace. For each preserved namespace type there will be a separate
+ environment variable. These environment variables will only be set if
+ <option>lxc.hook.version</option> is set to 1. </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.path 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>
- <listitem><para> LXC_CGNS_AWARE: indicated whether the container is cgroup namespace aware. </para></listitem>
- <listitem><para> LXC_LOG_LEVEL: the container's log level. </para></listitem>
+ <listitem><para> LXC_ROOTFS_PATH: this is the lxc.rootfs.path 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>
+ <listitem><para> LXC_SRC_NAME: in the case of the clone hook, this is
+ the original container's name. </para></listitem>
</itemizedlist>
</para>
<para>
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.version</option>
+ </term>
+ <listitem>
+ <para>
+ To pass the arguments in new style via environment variables set to
+ 1 otherwise set to 0 to pass them as arguments.
+ This setting affects all hooks arguments that were traditionally
+ passed as arguments to the script. Specifically, it affects the
+ container name, section (e.g. 'lxc', 'net') and hook type (e.g.
+ 'clone', 'mount', 'pre-mount') arguments. If new-style hooks are
+ used then the arguments will be available as environment variables.
+ The container name will be set in LXC_NAME. (This is set
+ independently of the value used for this config item.) The section
+ will be set in LXC_HOOK_SECTION and the hook type will be set in
+ LXC_HOOK_TYPE.
+ It also affects how the paths to file descriptors referring to the
+ container's namespaces are passed. If set to 1 then for each
+ namespace a separate environment variable LXC_[NAMESPACE
+ IDENTIFIER]_NS will be set. If set to 0 then the paths will be
+ passed as arguments to the stop hook.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
<variablelist>
<varlistentry>
<term>
</varlistentry>
<varlistentry>
<term>
- <option>lxc.log</option>
+ <option>lxc.log.file</option>
</term>
<listitem>
<para>
</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <option>lxc.monitor.signal.pdeath</option>
+ </term>
+ <listitem>
+ <para>
+ Set the signal to be sent to the container's init when the lxc
+ monitor exits. By default it is set to SIGKILL which will cause
+ all container processes to be killed when the lxc monitor process
+ dies.
+ To ensure that containers stay alive even if lxc monitor dies set
+ this to 0.
+ </para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term>
<option>lxc.group</option>
lxc.environment = APP_ENV=production
lxc.environment = SYSLOG_SERVER=192.0.2.42
</programlisting>
+ <para>
+ It is possible to inherit host environment variables by setting the
+ name of the variable without a "=" sign. For example:
+ </para>
+ <programlisting>
+ lxc.environment = PATH
+ </programlisting>
</listitem>
</varlistentry>
</variablelist>
projects / mirror_lxc.git / blobdiff