</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
</term>
<listitem>
<para>
- Specify the proc file name to be set. The file name available
+ Specify the proc file name to be set. The file names available
are those listed under /proc/PID/.
Example:
</para>
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>
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.
- 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.
+ 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.)
+
+ 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.
Will expand dev/null to ${<option>LXC_ROOTFS_MOUNT</option>}/dev/null,
and mount it to proc/kcore inside the container.
</para>
- <para>
- </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:ro</option>: similar to
- <option>cgroup:mixed</option>, but everything will
- be mounted read-only.
+ <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: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>
<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 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. 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 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>
</refsect2>
<refsect2>
- <title>Namespace Inheritance</title>
+ <title>Namespaces</title>
<para>
- A namespace can be inherited from another container or process.
+ 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>.
+ <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>
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>
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>
<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>
</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