Skip to content

L
lxc
Unverified Commit 67e963fe by Christian Brauner Committed by Stéphane Graber
Options

doc: tweak lxc.container.conf a little

Signed-off-by: 's avatarChristian Brauner <christian.brauner@ubuntu.com>
parent 5e924aa8
Showing with 160 additions and 136 deletions
doc/lxc.container.conf.sgml.in
...@@ -49,43 +49,71 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -49,43 +49,71 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<title>Description</title> <title>Description</title>
<para> <para>
The linux containers (<command>lxc</command>) are always created LXC is the well-known and heavily tested low-level Linux container
before being used. This creation defines a set of system runtime. It is in active development since 2008 and has proven itself in
resources to be virtualized / isolated when a process is using critical production environments world-wide. Some of its core contributors
the container. By default, the pids, sysv ipc and mount points are the same people that helped to implement various well-known
are virtualized and isolated. The other system resources are containerization features inside the Linux kernel.
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>
<para> <para>
The configuration file defines the different system resources to LXC's main focus is system containers. That is, containers which offer an
be assigned for the container. At present, the utsname, the environment as close as possible as the one you'd get from a VM but
network, the mount points, the root file system, the user namespace, without the overhead that comes with running a separate kernel and
and the control groups are supported. simulating all the hardware.
</para> </para>
<para> <para>
Each option in the configuration file has the form <command>key This is achieved through a combination of kernel security features such as
= value</command> fitting in one line. The '#' character means namespaces, mandatory access control and control groups.
the line is a comment. List options, like capabilities and cgroups </para>
options, can be used with no value to clear any previously
defined values of that option. <para>
LXC has supports 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
were merged into the mainline kernel.
</para>
<para>
In essence, user namespaces isolate given sets of UIDs and GIDs. This is
achieved by establishing a mapping between a range of UIDs and GIDs on the
host to a different (unprivileged) range of UIDs and GIDs in the
container. The kernel will translate this mapping in such a way that
inside the container all UIDs and GIDs appear as you would expect from the
host whereas on the host these UIDs and GIDs are in fact unprivileged. For
example, a process running as UID and GID 0 inside the container might
appear as UID and GID 100000 on the host. The implementation and working
details can be gathered from the corresponding user namespace man page.
UID and GID mappings can be defined with the <option>lxc.id_map</option>
key.
</para>
<para>
Linux containers are defined with a simple configuration file. 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. List options, like capabilities and cgroups options, can be used
with no value to clear any previously defined values of that option.
</para>
<para>
LXC namespaces configuration keys by using single dots. This means complex
configuration keys such as <option>lxc.network</option> expose various
subkeys such as <option>lxc.network.type</option>,
<option>lxc.network.link</option>, <option>lxc.network.ipv6</option>, and
others for even more fine-grained configuration.
</para> </para>
<refsect2> <refsect2>
<title>Configuration</title> <title>Configuration</title>
<para> <para>
In order to ease administration of multiple related containers, it In order to ease administration of multiple related containers, it is
is possible to have a container configuration file cause another possible to have a container configuration file cause another file to be
file to be loaded. For instance, network configuration loaded. For instance, network configuration can be defined in one common
can be defined in one common file which is included by multiple file which is included by multiple containers. Then, if the containers
containers. Then, if the containers are moved to another host, are moved to another host, only one file may need to be updated.
only one file may need to be updated.
</para> </para>
<variablelist> <variablelist>
...@@ -106,11 +134,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -106,11 +134,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Architecture</title> <title>Architecture</title>
<para> <para>
Allows one to set the architecture for the container. For example, Allows one to set the architecture for the container. For example, set a
set a 32bits architecture for a container running 32bits 32bits architecture for a container running 32bits binaries on a 64bits
binaries on a 64bits host. This fixes the container scripts host. This fixes the container scripts which rely on the architecture to
which rely on the architecture to do some work like do some work like downloading the packages.
downloading the packages.
</para> </para>
<variablelist> <variablelist>
...@@ -123,7 +150,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -123,7 +150,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Specify the architecture for the container. Specify the architecture for the container.
</para> </para>
<para> <para>
Valid options are Some valid options are
<option>x86</option>, <option>x86</option>,
<option>i686</option>, <option>i686</option>,
<option>x86_64</option>, <option>x86_64</option>,
...@@ -138,10 +165,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -138,10 +165,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Hostname</title> <title>Hostname</title>
<para> <para>
The utsname section defines the hostname to be set for the The utsname section defines the hostname to be set for the container.
container. That means the container can set its own hostname That means the container can set its own hostname without changing the
without changing the one from the system. That makes the one from the system. That makes the hostname private for the container.
hostname private for the container.
</para> </para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
...@@ -160,12 +186,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -160,12 +186,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Halt signal</title> <title>Halt signal</title>
<para> <para>
Allows one to specify signal name or number, sent by lxc-stop to the Allows one to specify signal name or number sent to the container's
container's init process to cleanly shutdown the container. Different init process to cleanly shutdown the container. Different init systems
init systems could use different signals to perform clean shutdown could use different signals to perform clean shutdown sequence. This
sequence. This option allows the signal to be specified in kill(1) option allows the signal to be specified in kill(1) fashion, e.g.
fashion, e.g. SIGPWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The SIGPWR, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal is
default signal is SIGPWR. SIGPWR.
</para> </para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
...@@ -184,10 +210,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -184,10 +210,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Reboot signal</title> <title>Reboot signal</title>
<para> <para>
Allows one to specify signal name or number, sent by lxc-stop to Allows one to specify signal name or number to reboot the container.
reboot the container. This option allows signal to be specified in This option allows signal to be specified in kill(1) fashion, e.g.
kill(1) fashion, e.g. SIGTERM, SIGRTMIN+14, SIGRTMAX-10 or plain number. SIGTERM, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default signal
The default signal is SIGINT. is SIGINT.
</para> </para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
...@@ -206,10 +232,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -206,10 +232,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Stop signal</title> <title>Stop signal</title>
<para> <para>
Allows one to specify signal name or number, sent by lxc-stop to forcibly Allows one to specify signal name or number to forcibly shutdown the
shutdown the container. This option allows signal to be specified in container. This option allows signal to be specified in kill(1) fashion,
kill(1) fashion, e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number. e.g. SIGKILL, SIGRTMIN+14, SIGRTMAX-10 or plain number. The default
The default signal is SIGKILL. signal is SIGKILL.
</para> </para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
...@@ -251,9 +277,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -251,9 +277,10 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<refsect2> <refsect2>
<title>Init ID</title> <title>Init ID</title>
<para> <para>
Sets the UID/GID to use for the init system, and subsequent command, executed by lxc-execute. 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
These options are only used when lxc-execute is started in a private user namespace. likely not work due to missing privileges. Setting the UID/GID is mostly
useful when running application container.
Defaults to: UID(0), GID(0) Defaults to: UID(0), GID(0)
</para> </para>
...@@ -264,7 +291,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -264,7 +291,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
</term> </term>
<listitem> <listitem>
<para> <para>
UID to use within a private user namesapce for init. UID to use for init.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -274,7 +301,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -274,7 +301,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
</term> </term>
<listitem> <listitem>
<para> <para>
GID to use within a private user namesapce for init. GID to use for init.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -325,18 +352,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -325,18 +352,22 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.type</option> <option>lxc.network.[i].type</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify what kind of network virtualization to be used specify what kind of network virtualization to be used
for the container. Each time for the container.
a <option>lxc.network.type</option> field is found a new Multiple networks can be specified by using an additional index
round of network configuration begins. In this way, <option>i</option>
several network virtualization types can be specified after all <option>lxc.network.*</option> keys. For example,
for the same container, as well as assigning several <option>lxc.network.0.type = veth</option> and
network interfaces for one container. The different <option>lxc.network.1.type = veth</option> specify two different
virtualization types can be: networks of the same type. All keys sharing the same index
<option>i</option> will be treated as belonging to the same
network. For example, <option>lxc.network.0.link = br0</option>
will belong to <option>lxc.network.0.type</option>.
Currently, the different virtualization types can be:
</para> </para>
<para> <para>
...@@ -427,12 +458,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -427,12 +458,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.flags</option> <option>lxc.network.[i].flags</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify an action to do for the Specify an action to do for the network.
network.
</para> </para>
<para><option>up:</option> activates the interface. <para><option>up:</option> activates the interface.
...@@ -442,83 +472,76 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -442,83 +472,76 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.link</option> <option>lxc.network.[i].link</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the interface to be used for real network Specify the interface to be used for real network traffic.
traffic.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.mtu</option> <option>lxc.network.[i].mtu</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the maximum transfer unit for this interface. Specify the maximum transfer unit for this interface.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.name</option> <option>lxc.network.[i].name</option>
</term> </term>
<listitem> <listitem>
<para> <para>
the interface name is dynamically allocated, but if The interface name is dynamically allocated, but if another name
another name is needed because the configuration files is needed because the configuration files being used by the
being used by the container use a generic name, container use a generic name, eg. eth0, this option will rename
eg. eth0, this option will rename the interface in the the interface in the container.
container.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.hwaddr</option> <option>lxc.network.[i].hwaddr</option>
</term> </term>
<listitem> <listitem>
<para> <para>
the interface mac address is dynamically allocated by The interface mac address is dynamically allocated by default to
default to the virtual interface, but in some cases, the virtual interface, but in some cases, this is needed to
this is needed to resolve a mac address conflict or to resolve a mac address conflict or to always have the same
always have the same link-local ipv6 address. link-local ipv6 address. Any "x" in address will be replaced by
Any "x" in address will be replaced by random value, random value, this allows setting hwaddr templates.
this allows setting hwaddr templates.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.ipv4</option> <option>lxc.network.[i].ipv4</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the ipv4 address to assign to the virtualized Specify the ipv4 address to assign to the virtualized interface.
interface. Several lines specify several ipv4 addresses. Several lines specify several ipv4 addresses. The address is in
The address is in format x.y.z.t/m, format x.y.z.t/m, eg. 192.168.1.123/24.
eg. 192.168.1.123/24. The broadcast address should be
specified on the same line, right after the ipv4
address.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.ipv4.gateway</option> <option>lxc.network.[i].ipv4.gateway</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the ipv4 address to use as the gateway inside the Specify the ipv4 address to use as the gateway inside the
container. The address is in format x.y.z.t, eg. container. The address is in format x.y.z.t, eg. 192.168.1.123.
192.168.1.123.
Can also have the special value <option>auto</option>, Can also have the special value <option>auto</option>,
which means to take the primary address from the bridge which means to take the primary address from the bridge
...@@ -534,27 +557,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -534,27 +557,26 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.ipv6</option> <option>lxc.network.[i].ipv6</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the ipv6 address to assign to the virtualized Specify the ipv6 address to assign to the virtualized
interface. Several lines specify several ipv6 addresses. interface. Several lines specify several ipv6 addresses. The
The address is in format x::y/m, address is in format x::y/m, eg.
eg. 2003:db8:1:0:214:1234:fe0b:3596/64 2003:db8:1:0:214:1234:fe0b:3596/64
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.ipv6.gateway</option> <option>lxc.network.[i].ipv6.gateway</option>
</term> </term>
<listitem> <listitem>
<para> <para>
specify the ipv6 address to use as the gateway inside the Specify the ipv6 address to use as the gateway inside the
container. The address is in format x::y, container. The address is in format x::y, eg. 2003:db8:1:0::1
eg. 2003:db8:1:0::1
Can also have the special value <option>auto</option>, Can also have the special value <option>auto</option>,
which means to take the primary address from the bridge which means to take the primary address from the bridge
...@@ -569,11 +591,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -569,11 +591,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.script.up</option> <option>lxc.network.[i].script.up</option>
</term> </term>
<listitem> <listitem>
<para> <para>
add a configuration option to specify a script to be Add a configuration option to specify a script to be
executed after creating and configuring the network used executed after creating and configuring the network used
from the host side. The following arguments are passed from the host side. The following arguments are passed
to the script: container name and config section name to the script: container name and config section name
...@@ -594,11 +616,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -594,11 +616,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
<varlistentry> <varlistentry>
<term> <term>
<option>lxc.network.script.down</option> <option>lxc.network.[i].script.down</option>
</term> </term>
<listitem> <listitem>
<para> <para>
add a configuration option to specify a script to be Add a configuration option to specify a script to be
executed before destroying the network used from the executed before destroying the network used from the
host side. The following arguments are passed to the host side. The following arguments are passed to the
script: container name and config section name (net) script: container name and config section name (net)
...@@ -822,9 +844,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -822,9 +844,9 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
most cases should be a relative path, which will become most cases should be a relative path, which will become
relative to the mounted container root. For instance, relative to the mounted container root. For instance,
</para> </para>
<screen> <programlisting>
proc proc proc nodev,noexec,nosuid 0 0 proc proc proc nodev,noexec,nosuid 0 0
</screen> </programlisting>
<para> <para>
Will mount a proc filesystem under the container's /proc, Will mount a proc filesystem under the container's /proc,
regardless of where the root filesystem comes from. This regardless of where the root filesystem comes from. This
...@@ -1295,11 +1317,13 @@ proc proc proc nodev,noexec,nosuid 0 0 ...@@ -1295,11 +1317,13 @@ proc proc proc nodev,noexec,nosuid 0 0
allowed except for mknod, which will simply do nothing and allowed except for mknod, which will simply do nothing and
return 0 (success), looks like: return 0 (success), looks like:
</para> </para>
<screen>
2 <programlisting>
blacklist 2
mknod errno 0 blacklist
</screen> mknod errno 0
</programlisting>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term> <term>
...@@ -1896,26 +1920,26 @@ mknod errno 0 ...@@ -1896,26 +1920,26 @@ mknod errno 0
mounting some locations and a changing root file system.</para> mounting some locations and a changing root file system.</para>
<programlisting> <programlisting>
lxc.utsname = complex lxc.utsname = complex
lxc.network.type = veth lxc.network.0.type = veth
lxc.network.flags = up lxc.network.0.flags = up
lxc.network.link = br0 lxc.network.0.link = br0
lxc.network.hwaddr = 4a:49:43:49:79:bf lxc.network.0.hwaddr = 4a:49:43:49:79:bf
lxc.network.ipv4 = 10.2.3.5/24 10.2.3.255 lxc.network.0.ipv4 = 10.2.3.5/24 10.2.3.255
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597 lxc.network.0.ipv6 = 2003:db8:1:0:214:1234:fe0b:3597
lxc.network.ipv6 = 2003:db8:1:0:214:5432:feab:3588 lxc.network.0.ipv6 = 2003:db8:1:0:214:5432:feab:3588
lxc.network.type = macvlan lxc.network.1.type = macvlan
lxc.network.flags = up lxc.network.1.flags = up
lxc.network.link = eth0 lxc.network.1.link = eth0
lxc.network.hwaddr = 4a:49:43:49:79:bd lxc.network.1.hwaddr = 4a:49:43:49:79:bd
lxc.network.ipv4 = 10.2.3.4/24 lxc.network.1.ipv4 = 10.2.3.4/24
lxc.network.ipv4 = 192.168.10.125/24 lxc.network.1.ipv4 = 192.168.10.125/24
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596 lxc.network.1.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
lxc.network.type = phys lxc.network.2.type = phys
lxc.network.flags = up lxc.network.2.flags = up
lxc.network.link = dummy0 lxc.network.2.link = dummy0
lxc.network.hwaddr = 4a:49:43:49:79:ff lxc.network.2.hwaddr = 4a:49:43:49:79:ff
lxc.network.ipv4 = 10.2.3.6/24 lxc.network.2.ipv4 = 10.2.3.6/24
lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297 lxc.network.2.ipv6 = 2003:db8:1:0:214:1234:fe0b:3297
lxc.cgroup.cpuset.cpus = 0,1 lxc.cgroup.cpuset.cpus = 0,1
lxc.cgroup.cpu.shares = 1234 lxc.cgroup.cpu.shares = 1234
lxc.cgroup.devices.deny = a lxc.cgroup.devices.deny = a
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment