Skip to content

L
lxc
Unverified Commit 594d6e30 by Christian Brauner
Options

doc: lxc.sgml.in

Signed-off-by: 's avatarChristian Brauner <christian.brauner@ubuntu.com>
parent e6ecdcbe
Showing with 119 additions and 213 deletions
doc/lxc.sgml.in
...@@ -52,136 +52,67 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA ...@@ -52,136 +52,67 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
</refnamediv> </refnamediv>
<refsect1> <refsect1>
<title>Quick start</title>
<para>
You are in a hurry, and you don't want to read this man page. Ok,
without warranty, here are the commands to launch a shell inside
a container with a predefined configuration template, it may
work.
<command>@BINDIR@/lxc-execute -n foo -f
@DOCDIR@/examples/lxc-macvlan.conf /bin/bash</command>
</para>
</refsect1>
<refsect1>
<title>Overview</title> <title>Overview</title>
<para> <para>
The container technology is actively being pushed into the The container technology is actively being pushed into the mainstream
mainstream linux kernel. It provides the resource management Linux kernel. It provides resource management through control groups and
through the control groups aka process containers and resource resource isolation via namespaces.
isolation through the namespaces.
</para> </para>
<para> <para>
The linux containers, <command>lxc</command>, aims to use these <command>lxc</command>, aims to use these new functionalities to provide a
new functionalities to provide a userspace container object userspace container object which provides full resource isolation and
which provides full resource isolation and resource control for resource control for an applications or a full system.
an applications or a system.
</para> </para>
<para> <para>
The first objective of this project is to make the life easier <command>lxc</command> is small enough to easily manage a container with
for the kernel developers involved in the containers project and simple command lines and complete enough to be used for other purposes.
especially to continue working on the Checkpoint/Restart new
features. The <command>lxc</command> is small enough to easily
manage a container with simple command lines and complete enough
to be used for other purposes.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Requirements</title> <title>Requirements</title>
<para> <para>
The <command>lxc</command> relies on a set of functionalities The kernel version >= 3.10 shipped with the distros, will work with
provided by the kernel which needs to be active. Depending of <command>lxc</command>, this one will have less functionalities but enough
the missing functionalities the <command>lxc</command> will to be interesting.
work with a restricted number of functionalities or will simply
fail.
</para>
<para>
The following list gives the kernel features to be enabled in
the kernel to have the full features container:
</para>
<programlisting>
* General setup
* Control Group support
-> Namespace cgroup subsystem
-> Freezer cgroup subsystem
-> Cpuset support
-> Simple CPU accounting cgroup subsystem
-> Resource counters
-> Memory resource controllers for Control Groups
* Group CPU scheduler
-> Basis for grouping tasks (Control Groups)
* Namespaces support
-> UTS namespace
-> IPC namespace
-> User namespace
-> Pid namespace
-> Network namespace
* Device Drivers
* Character devices
-> Support multiple instances of devpts
* Network device support
-> MAC-VLAN support
-> Virtual ethernet pair device
* Networking
* Networking options
-> 802.1d Ethernet Bridging
* Security options
-> File POSIX Capabilities
</programlisting>
<para>
The kernel version >= 3.10 shipped with the distros, will
work with <command>lxc</command>, this one will have less
functionalities but enough to be interesting.
The helper script <command>lxc-checkconfig</command> will give
you information about your kernel configuration.
</para> </para>
<para> <para>
The control group can be mounted anywhere, eg: <command>lxc</command> relies on a set of functionalities provided by the
<command>mount -t cgroup cgroup /cgroup</command>. kernel. The helper script <command>lxc-checkconfig</command> will give
you information about your kernel configuration, required, and missing
It is however recommended to use cgmanager, cgroup-lite or systemd features.
to mount the cgroup hierarchy under /sys/fs/cgroup.
</para> </para>
</refsect1> </refsect1>
<refsect1> <refsect1>
<title>Functional specification</title> <title>Functional specification</title>
<para> <para>
A container is an object isolating some resources of the host, A container is an object isolating some resources of the host, for the
for the application or system running in it. application or system running in it.
</para> </para>
<para> <para>
The application / system will be launched inside a The application / system will be launched inside a container specified by
container specified by a configuration that is either a configuration that is either initially created or passed as a parameter
initially created or passed as parameter of the starting commands. of the commands.
</para> </para>
<para>How to run an application in a container ?</para> <para>How to run an application in a container</para>
<para> <para>
Before running an application, you should know what are the Before running an application, you should know what are the resources you
resources you want to isolate. The default configuration is to want to isolate. The default configuration is to isolate PIDs, the sysv
isolate the pids, the sysv ipc and the mount points. If you want IPC and mount points. If you want to run a simple shell inside a
to run a simple shell inside a container, a basic configuration container, a basic configuration is needed, especially if you want to
is needed, especially if you want to share the rootfs. If you share the rootfs. If you want to run an application like
want to run an application like <command>sshd</command>, you <command>sshd</command>, you should provide a new network stack and a new
should provide a new network stack and a new hostname. If you hostname. If you want to avoid conflicts with some files eg.
want to avoid conflicts with some files <filename>/var/run/httpd.pid</filename>, you should remount
eg. <filename>/var/run/httpd.pid</filename>, you should <filename>/var/run</filename> with an empty directory. If you want to
remount <filename>/var/run</filename> with an empty avoid the conflicts in all the cases, you can specify a rootfs for the
directory. If you want to avoid the conflicts in all the cases, container. The rootfs can be a directory tree, previously bind mounted
you can specify a rootfs for the container. The rootfs can be a with the initial rootfs, so you can still use your distro but with your
directory tree, previously bind mounted with the initial rootfs,
so you can still use your distro but with your
own <filename>/etc</filename> and <filename>/home</filename> own <filename>/etc</filename> and <filename>/home</filename>
</para> </para>
<para> <para>
...@@ -225,15 +156,17 @@ rootfs ...@@ -225,15 +156,17 @@ rootfs
</programlisting> </programlisting>
</para> </para>
<para>How to run a system in a container ?</para> <para>How to run a system in a container</para>
<para>Running a system inside a container is paradoxically easier <para>
than running an application. Why ? Because you don't have to care Running a system inside a container is paradoxically easier
about the resources to be isolated, everything need to be than running an application. Why? Because you don't have to care
about the resources to be isolated, everything needs to be
isolated, the other resources are specified as being isolated but isolated, the other resources are specified as being isolated but
without configuration because the container will set them without configuration because the container will set them
up. eg. the ipv4 address will be setup by the system container up. eg. the ipv4 address will be setup by the system container
init scripts. Here is an example of the mount points file: init scripts. Here is an example of the mount points file:
</para>
<programlisting> <programlisting>
[root@lxc debian]$ cat fstab [root@lxc debian]$ cat fstab
...@@ -242,26 +175,17 @@ rootfs ...@@ -242,26 +175,17 @@ rootfs
/dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0 /dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
</programlisting> </programlisting>
More information can be added to the container to facilitate the
configuration. For example, make accessible from the container
the resolv.conf file belonging to the host.
<programlisting>
/etc/resolv.conf /home/root/debian/rootfs/etc/resolv.conf none bind 0 0
</programlisting>
</para>
<refsect2> <refsect2>
<title>Container life cycle</title> <title>Container life cycle</title>
<para> <para>
When the container is created, it contains the configuration When the container is created, it contains the configuration
information. When a process is launched, the container will be information. When a process is launched, the container will be starting
starting and running. When the last process running inside the and running. When the last process running inside the container exits,
container exits, the container is stopped. the container is stopped.
</para> </para>
<para> <para>
In case of failure when the container is initialized, it will In case of failure when the container is initialized, it will pass
pass through the aborting state. through the aborting state.
</para> </para>
<programlisting> <programlisting>
...@@ -306,17 +230,14 @@ rootfs ...@@ -306,17 +230,14 @@ rootfs
</refsect2> </refsect2>
<refsect2> <refsect2>
<title>Creating / Destroying container <title>Creating / Destroying containers</title>
(persistent container)</title> <para>
<para> A persistent container object can be created via the
A persistent container object can be <command>lxc-create</command> command. It takes a container name as
created via the <command>lxc-create</command> parameter and optional configuration file and template. The name is
command. It takes a container name as parameter and used by the different commands to refer to this container. The
optional configuration file and template. <command>lxc-destroy</command> command will destroy the container
The name is used by the different object.
commands to refer to this
container. The <command>lxc-destroy</command> command will
destroy the container object.
<programlisting> <programlisting>
lxc-create -n foo lxc-create -n foo
lxc-destroy -n foo lxc-destroy -n foo
...@@ -326,33 +247,30 @@ rootfs ...@@ -326,33 +247,30 @@ rootfs
<refsect2> <refsect2>
<title>Volatile container</title> <title>Volatile container</title>
<para>It is not mandatory to create a container object <para>
before to start it. It is not mandatory to create a container object before starting it.
The container can be directly started with a The container can be directly started with a configuration file as
configuration file as parameter. parameter.
</para> </para>
</refsect2> </refsect2>
<refsect2> <refsect2>
<title>Starting / Stopping container</title> <title>Starting / Stopping container</title>
<para>When the container has been created, it is ready to run an <para>
application / system. When the container has been created, it is ready to run an application /
This is the purpose of the <command>lxc-execute</command> and system. This is the purpose of the <command>lxc-execute</command> and
<command>lxc-start</command> commands. <command>lxc-start</command> commands. If the container was not created
If the container was not created before before starting the application, the container will use the
starting the application, the container will use the configuration file passed as parameter to the command, and if there is
configuration file passed as parameter to the command, no such parameter either, then it will use a default isolation. If the
and if there is no such parameter either, then application ended, the container will be stopped, but if needed the
it will use a default isolation. <command>lxc-stop</command> command can be used to stop the container.
If the application is ended, the container will be stopped also, </para>
but if needed the <command>lxc-stop</command> command can
be used to kill the still running application. <para>
</para> Running an application inside a container is not exactly the same thing
as running a system. For this reason, there are two different commands
<para> to run an application into a container:
Running an application inside a container is not exactly the
same thing as running a system. For this reason, there are two
different commands to run an application into a container:
<programlisting> <programlisting>
lxc-execute -n foo [-f config] /bin/bash lxc-execute -n foo [-f config] /bin/bash
lxc-start -n foo [-f config] [/bin/bash] lxc-start -n foo [-f config] [/bin/bash]
...@@ -360,39 +278,35 @@ rootfs ...@@ -360,39 +278,35 @@ rootfs
</para> </para>
<para> <para>
<command>lxc-execute</command> command will run the The <command>lxc-execute</command> command will run the specified command
specified command into the container via an intermediate into a container via an intermediate process,
process, <command>lxc-init</command>. <command>lxc-init</command>.
This lxc-init after launching the specified command, This lxc-init after launching the specified command, will wait for its
will wait for its end and all other reparented processes. end and all other reparented processes. (to support daemons in the
(to support daemons in the container). container). In other words, in the container,
In other words, in the <command>lxc-init</command> has PID 1 and the first process of the
container, <command>lxc-init</command> has the pid 1 and the application has PID 2.
first process of the application has the pid 2.
</para> </para>
<para> <para>
<command>lxc-start</command> command will run directly the specified The <command>lxc-start</command> command will directly run the specified
command into the container. command in the container. The PID of the first process is 1. If no
The pid of the first process is 1. If no command is command is specified <command>lxc-start</command> will run the command
specified <command>lxc-start</command> will defined in lxc.init.cmd or if not set, <filename>/sbin/init</filename> .
run the command defined in lxc.init.cmd or if not set,
<filename>/sbin/init</filename> .
</para> </para>
<para> <para>
To summarize, <command>lxc-execute</command> is for running To summarize, <command>lxc-execute</command> is for running an
an application and <command>lxc-start</command> is better suited for application and <command>lxc-start</command> is better suited for
running a system. running a system.
</para> </para>
<para> <para>
If the application is no longer responding, is inaccessible or is If the application is no longer responding, is inaccessible or is not
not able to finish by itself, a able to finish by itself, a wild <command>lxc-stop</command> command
wild <command>lxc-stop</command> command will kill all the will kill all the processes in the container without pity.
processes in the container without pity.
<programlisting> <programlisting>
lxc-stop -n foo lxc-stop -n foo -k
</programlisting> </programlisting>
</para> </para>
</refsect2> </refsect2>
...@@ -400,11 +314,10 @@ rootfs ...@@ -400,11 +314,10 @@ rootfs
<refsect2> <refsect2>
<title>Connect to an available tty</title> <title>Connect to an available tty</title>
<para> <para>
If the container is configured with the ttys, it is possible If the container is configured with ttys, it is possible to access it
to access it through them. It is up to the container to through them. It is up to the container to provide a set of available
provide a set of available tty to be used by the following ttys to be used by the following command. When the tty is lost, it is
command. When the tty is lost, it is possible to reconnect it possible to reconnect to it without login again.
without login again.
<programlisting> <programlisting>
lxc-console -n foo -t 3 lxc-console -n foo -t 3
</programlisting> </programlisting>
...@@ -430,30 +343,28 @@ rootfs ...@@ -430,30 +343,28 @@ rootfs
</para> </para>
<para> <para>
This feature is enabled if the cgroup freezer is enabled in the This feature is enabled if the freezer cgroup v1 controller is enabled
kernel. in the kernel.
</para> </para>
</refsect2> </refsect2>
<refsect2> <refsect2>
<title>Getting information about container</title> <title>Getting information about container</title>
<para>When there are a lot of containers, it is hard to follow <para>
what has been created or destroyed, what is running or what are When there are a lot of containers, it is hard to follow what has been
the pids running into a specific container. For this reason, the created or destroyed, what is running or what are the PIDs running in a
following commands may be useful: specific container. For this reason, the following commands may be useful:
<programlisting> <programlisting>
lxc-ls lxc-ls -f
lxc-info -n foo lxc-info -n foo
</programlisting> </programlisting>
</para> </para>
<para> <para>
<command>lxc-ls</command> lists the containers of the <command>lxc-ls</command> lists containers.
system.
</para> </para>
<para> <para>
<command>lxc-info</command> gives information for a specific <command>lxc-info</command> gives information for a specific container.
container.
</para> </para>
<para> <para>
...@@ -464,22 +375,20 @@ rootfs ...@@ -464,22 +375,20 @@ rootfs
lxc-info -n $i lxc-info -n $i
done done
</programlisting> </programlisting>
</para> </para>
</refsect2> </refsect2>
<refsect2> <refsect2>
<title>Monitoring container</title> <title>Monitoring container</title>
<para>It is sometime useful to track the states of a container, <para>
for example to monitor it or just to wait for a specific It is sometime useful to track the states of a container, for example to
state in a script. monitor it or just to wait for a specific state in a script.
</para> </para>
<para> <para>
<command>lxc-monitor</command> command will monitor one or <command>lxc-monitor</command> command will monitor one or several
several containers. The parameter of this command accept a containers. The parameter of this command accepts a regular expression
regular expression for example: for example:
<programlisting> <programlisting>
lxc-monitor -n "foo|bar" lxc-monitor -n "foo|bar"
</programlisting> </programlisting>
...@@ -504,8 +413,8 @@ rootfs ...@@ -504,8 +413,8 @@ rootfs
state change and exit. This is useful for scripting to state change and exit. This is useful for scripting to
synchronize the launch of a container or the end. The synchronize the launch of a container or the end. The
parameter is an ORed combination of different states. The parameter is an ORed combination of different states. The
following example shows how to wait for a container if he went following example shows how to wait for a container if it successfully
to the background. started as a daemon.
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
...@@ -527,11 +436,12 @@ rootfs ...@@ -527,11 +436,12 @@ rootfs
</refsect2> </refsect2>
<refsect2> <refsect2>
<title>Setting the control group for container</title> <title>cgroup settings for containers</title>
<para>The container is tied with the control groups, when a <para>
container is started a control group is created and associated The container is tied with the control groups, when a container is
with it. The control group properties can be read and modified started a control group is created and associated with it. The control
when the container is running by using the lxc-cgroup command. group properties can be read and modified when the container is running
by using the lxc-cgroup command.
</para> </para>
<para> <para>
<command>lxc-cgroup</command> command is used to set or get a <command>lxc-cgroup</command> command is used to set or get a
...@@ -553,18 +463,14 @@ rootfs ...@@ -553,18 +463,14 @@ rootfs
</refsect2> </refsect2>
</refsect1> </refsect1>
<refsect1>
<title>Bugs</title>
<para>The <command>lxc</command> is still in development, so the
command syntax and the API can change. The version 1.0.0 will be
the frozen version.</para>
</refsect1>
&seealso; &seealso;
<refsect1> <refsect1>
<title>Author</title> <title>Author</title>
<para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para> <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
<para>Christian Brauner <email>christian.brauner@ubuntu.com</email></para>
<para>Serge Hallyn <email>serge@hallyn.com</email></para>
<para>Stéphane Graber <email>stgraber@ubuntu.com</email></para>
</refsect1> </refsect1>
</refentry> </refentry>
......
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