0N/A

0N/A<!DOCTYPE refentry PUBLIC @docdtd@ [

0N/A

0N/A<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">

58N/A]>

0N/A

0N/A<refentry>

0N/A

0N/A <docinfo>

207N/A <date>@LXC_GENERATE_DATE@</date>

0N/A </docinfo>

0N/A

0N/A

58N/A <refmeta>

99N/A <refentrytitle>lxc</refentrytitle>

99N/A <manvolnum>7</manvolnum>

928N/A <refmiscinfo>

928N/A Version @PACKAGE_VERSION@

99N/A </refmiscinfo>

0N/A </refmeta>

0N/A

0N/A <refnamediv>

0N/A <refname>lxc</refname>

928N/A

0N/A <refpurpose>

0N/A linux containers

0N/A </refpurpose>

0N/A </refnamediv>

0N/A

0N/A <refsect1>

0N/A <title>Quick start</title>

0N/A <para>

58N/A You are in a hurry, and you don't want to read this man page. Ok,

207N/A without warranty, here are the commands to launch a shell inside

98N/A a container with a predefined configuration template, it may

98N/A work.

98N/A <command>@BINDIR@/lxc-execute -n foo -f

98N/A @DOCDIR@/examples/lxc-macvlan.conf /bin/bash</command>

819N/A </para>

928N/A </refsect1>

98N/A

98N/A <refsect1>

98N/A <title>Overview</title>

98N/A <para>

98N/A The container technology is actively being pushed into the

98N/A mainstream linux kernel. It provides the resource management

819N/A through the control groups aka process containers and resource

830N/A isolation through the namespaces.

98N/A </para>

98N/A

98N/A <para>

98N/A The linux containers, <command>lxc</command>, aims to use these

98N/A new functionalities to provide a userspace container object

98N/A which provides full resource isolation and resource control for

98N/A an applications or a system.

98N/A </para>

98N/A

98N/A <para>

98N/A The first objective of this project is to make the life easier

98N/A for the kernel developers involved in the containers project and

819N/A especially to continue working on the Checkpoint/Restart new

819N/A features. The <command>lxc</command> is small enough to easily

98N/A manage a container with simple command lines and complete enough

98N/A to be used for other purposes.

98N/A </para>

98N/A </refsect1>

98N/A

830N/A <refsect1>

58N/A <title>Requirements</title>

830N/A <para>

0N/A The <command>lxc</command> relies on a set of functionalities

0N/A provided by the kernel which needs to be active. Depending of

0N/A the missing functionalities the <command>lxc</command> will

0N/A work with a restricted number of functionalities or will simply

0N/A fail.

0N/A </para>

0N/A

830N/A <para>

0N/A The following list gives the kernel features to be enabled in

0N/A the kernel to have the full features container:

0N/A </para>

928N/A <programlisting>

819N/A * General setup

0N/A * Control Group support

0N/A -> Namespace cgroup subsystem

819N/A -> Freezer cgroup subsystem

819N/A -> Cpuset support

0N/A -> Simple CPU accounting cgroup subsystem

0N/A -> Resource counters

830N/A -> Memory resource controllers for Control Groups

830N/A * Group CPU scheduler

830N/A -> Basis for grouping tasks (Control Groups)

819N/A * Namespaces support

819N/A -> UTS namespace

819N/A -> IPC namespace

928N/A -> User namespace

819N/A -> Pid namespace

0N/A -> Network namespace

0N/A * Device Drivers

0N/A * Character devices

0N/A -> Support multiple instances of devpts

0N/A * Network device support

0N/A -> MAC-VLAN support

58N/A -> Virtual ethernet pair device

0N/A * Networking

0N/A * Networking options

0N/A -> 802.1d Ethernet Bridging

0N/A * Security options

0N/A -> File POSIX Capabilities

0N/A </programlisting>

0N/A

0N/A <para>

0N/A

819N/A The kernel version >= 2.6.32 shipped with the distros, will

0N/A work with <command>lxc</command>, this one will have less

0N/A functionalities but enough to be interesting.

0N/A

0N/A The helper script <command>lxc-checkconfig</command> will give

0N/A you information about your kernel configuration.

0N/A </para>

226N/A

58N/A <para>

928N/A The control group can be mounted anywhere, eg:

99N/A <command>mount -t cgroup cgroup /cgroup</command>.

125N/A

125N/A It is however recommended to use cgmanager, cgroup-lite or systemd

0N/A to mount the cgroup hierarchy under /sys/fs/cgroup.

830N/A

207N/A </para>

207N/A

207N/A </refsect1>

207N/A

207N/A <refsect1>

207N/A <title>Functional specification</title>

207N/A <para>

830N/A A container is an object isolating some resources of the host,

830N/A for the application or system running in it.

830N/A </para>

830N/A <para>

830N/A The application / system will be launched inside a

830N/A container specified by a configuration that is either

928N/A initially created or passed as parameter of the starting commands.

830N/A </para>

830N/A

830N/A <para>How to run an application in a container ?</para>

830N/A <para>

830N/A Before running an application, you should know what are the

830N/A resources you want to isolate. The default configuration is to

830N/A isolate the pids, the sysv ipc and the mount points. If you want

830N/A to run a simple shell inside a container, a basic configuration

830N/A is needed, especially if you want to share the rootfs. If you

928N/A want to run an application like <command>sshd</command>, you

830N/A should provide a new network stack and a new hostname. If you

830N/A want to avoid conflicts with some files

207N/A eg. <filename>/var/run/httpd.pid</filename>, you should

830N/A remount <filename>/var/run</filename> with an empty

928N/A directory. If you want to avoid the conflicts in all the cases,

830N/A you can specify a rootfs for the container. The rootfs can be a

830N/A directory tree, previously bind mounted with the initial rootfs,

207N/A so you can still use your distro but with your

830N/A own <filename>/etc</filename> and <filename>/home</filename>

830N/A </para>

928N/A <para>

819N/A Here is an example of directory tree

928N/A for <command>sshd</command>:

819N/A <programlisting>

819N/A[root@lxc sshd]$ tree -d rootfs

819N/A

819N/Arootfs

819N/A|-- bin

819N/A|-- dev

819N/A| |-- pts

819N/A| `-- shm

928N/A| `-- network

819N/A|-- etc

819N/A| `-- ssh

819N/A|-- lib

819N/A|-- proc

819N/A|-- root

819N/A|-- sbin

819N/A|-- sys

819N/A|-- usr

819N/A`-- var

819N/A |-- empty

819N/A | `-- sshd

928N/A |-- lib

819N/A | `-- empty

819N/A | `-- sshd

819N/A `-- run

819N/A `-- sshd

819N/A </programlisting>

207N/A

819N/A and the mount points file associated with it:

819N/A <programlisting>

819N/A [root@lxc sshd]$ cat fstab

819N/A

819N/A /lib /home/root/sshd/rootfs/lib none ro,bind 0 0

819N/A /bin /home/root/sshd/rootfs/bin none ro,bind 0 0

819N/A /usr /home/root/sshd/rootfs/usr none ro,bind 0 0

207N/A /sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0

0N/A </programlisting>

0N/A </para>

0N/A

510N/A <para>How to run a system in a container ?</para>

510N/A

510N/A <para>Running a system inside a container is paradoxically easier

849N/A than running an application. Why ? Because you don't have to care

510N/A about the resources to be isolated, everything need to be

510N/A isolated, the other resources are specified as being isolated but

0N/A without configuration because the container will set them

0N/A up. eg. the ipv4 address will be setup by the system container

0N/A init scripts. Here is an example of the mount points file:

345N/A

0N/A <programlisting>

850N/A [root@lxc debian]$ cat fstab

942N/A

942N/A /dev /home/root/debian/rootfs/dev none bind 0 0

942N/A /dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0

942N/A </programlisting>

942N/A

942N/A More information can be added to the container to facilitate the

107N/A configuration. For example, make accessible from the container

107N/A the resolv.conf file belonging to the host.

942N/A

942N/A <programlisting>

942N/A /etc/resolv.conf /home/root/debian/rootfs/etc/resolv.conf none bind 0 0

819N/A </programlisting>

158N/A </para>

151N/A

158N/A <refsect2>

152N/A <title>Container life cycle</title>

158N/A <para>

152N/A When the container is created, it contains the configuration

152N/A information. When a process is launched, the container will be

0N/A starting and running. When the last process running inside the

144N/A container exits, the container is stopped.

147N/A </para>

147N/A <para>

144N/A In case of failure when the container is initialized, it will

0N/A pass through the aborting state.

0N/A </para>

144N/A

0N/A <programlisting>

0N/A<![CDATA[

819N/A]]>

850N/A </programlisting>

98N/A </refsect2>

850N/A

98N/A <refsect2>

98N/A <title>Configuration</title>

98N/A <para>The container is configured through a configuration

98N/A file, the format of the configuration file is described in

98N/A <citerefentry>

0N/A <refentrytitle><filename>lxc.conf</filename></refentrytitle>

0N/A <manvolnum>5</manvolnum>

0N/A </citerefentry>

830N/A </para>

0N/A </refsect2>

0N/A

819N/A <refsect2>

99N/A <title>Creating / Destroying container

830N/A (persistent container)</title>

207N/A <para>

207N/A A persistent container object can be

830N/A created via the <command>lxc-create</command>

830N/A command. It takes a container name as parameter and

830N/A optional configuration file and template.

830N/A The name is used by the different

830N/A commands to refer to this

830N/A container. The <command>lxc-destroy</command> command will

830N/A destroy the container object.

830N/A <programlisting>

830N/A lxc-create -n foo

830N/A lxc-destroy -n foo

207N/A </programlisting>

830N/A </para>

830N/A </refsect2>

830N/A

830N/A <refsect2>

830N/A <title>Volatile container</title>

830N/A <para>It is not mandatory to create a container object

830N/A before to start it.

830N/A The container can be directly started with a

830N/A configuration file as parameter.

928N/A </para>

99N/A </refsect2>

99N/A

0N/A <refsect2>

603N/A <title>Starting / Stopping container</title>

0N/A <para>When the container has been created, it is ready to run an

0N/A application / system.

0N/A This is the purpose of the <command>lxc-execute</command> and

0N/A <command>lxc-start</command> commands.

0N/A If the container was not created before

0N/A starting the application, the container will use the

830N/A configuration file passed as parameter to the command,

0N/A and if there is no such parameter either, then

603N/A it will use a default isolation.

830N/A If the application is ended, the container will be stopped also,

603N/A but if needed the <command>lxc-stop</command> command can

603N/A be used to kill the still running application.

603N/A </para>

0N/A

0N/A <para>

0N/A Running an application inside a container is not exactly the

0N/A same thing as running a system. For this reason, there are two

0N/A different commands to run an application into a container:

0N/A <programlisting>

0N/A lxc-execute -n foo [-f config] /bin/bash

0N/A lxc-start -n foo [-f config] [/bin/bash]

0N/A </programlisting>

0N/A </para>

830N/A

0N/A <para>

603N/A <command>lxc-execute</command> command will run the

830N/A specified command into the container via an intermediate

603N/A process, <command>lxc-init</command>.

603N/A This lxc-init after launching the specified command,

830N/A will wait for its end and all other reparented processes.

0N/A (to support daemons in the container).

0N/A In other words, in the

0N/A container, <command>lxc-init</command> has the pid 1 and the

0N/A first process of the application has the pid 2.

0N/A </para>

830N/A

0N/A <para>

0N/A <command>lxc-start</command> command will run directly the specified

0N/A command into the container.

0N/A The pid of the first process is 1. If no command is

0N/A specified <command>lxc-start</command> will

830N/A run <filename>/sbin/init</filename>.

0N/A </para>

603N/A

830N/A <para>

603N/A To summarize, <command>lxc-execute</command> is for running

603N/A an application and <command>lxc-start</command> is better suited for

830N/A running a system.

0N/A </para>

0N/A

0N/A <para>

0N/A If the application is no longer responding, is inaccessible or is

0N/A not able to finish by itself, a

603N/A wild <command>lxc-stop</command> command will kill all the

603N/A processes in the container without pity.

603N/A <programlisting>

99N/A lxc-stop -n foo

830N/A </programlisting>

830N/A </para>

0N/A </refsect2>

830N/A

0N/A <refsect2>

0N/A <title>Connect to an available tty</title>

0N/A <para>

0N/A If the container is configured with the ttys, it is possible

0N/A to access it through them. It is up to the container to

0N/A provide a set of available tty to be used by the following

0N/A command. When the tty is lost, it is possible to reconnect it

0N/A without login again.

0N/A <programlisting>

0N/A lxc-console -n foo -t 3

820N/A </programlisting>

820N/A </para>

0N/A </refsect2>

0N/A

820N/A <refsect2>

0N/A <title>Freeze / Unfreeze container</title>

850N/A <para>

0N/A Sometime, it is useful to stop all the processes belonging to

0N/A a container, eg. for job scheduling. The commands:

0N/A <programlisting>

97N/A lxc-freeze -n foo

830N/A </programlisting>

850N/A

850N/A will put all the processes in an uninteruptible state and

850N/A

850N/A <programlisting>

850N/A lxc-unfreeze -n foo

850N/A </programlisting>

0N/A

0N/A will resume them.

0N/A </para>

0N/A

0N/A <para>

0N/A This feature is enabled if the cgroup freezer is enabled in the

0N/A kernel.

0N/A </para>

0N/A </refsect2>

0N/A

0N/A <refsect2>

0N/A <title>Getting information about container</title>

819N/A <para>When there are a lot of containers, it is hard to follow

0N/A what has been created or destroyed, what is running or what are

0N/A the pids running into a specific container. For this reason, the

0N/A following commands may be useful:

0N/A <programlisting>

0N/A lxc-ls

819N/A lxc-info -n foo

0N/A </programlisting>

0N/A </para>

0N/A <para>

0N/A <command>lxc-ls</command> lists the containers of the

850N/A system.

0N/A </para>

0N/A

0N/A <para>

0N/A <command>lxc-info</command> gives information for a specific

0N/A container.

819N/A </para>

0N/A

0N/A <para>

819N/A Here is an example on how the combination of these commands

0N/A allow to list all the containers and retrieve their state.

0N/A <programlisting>

0N/A for i in $(lxc-ls -1); do

0N/A lxc-info -n $i

0N/A done

0N/A </programlisting>

0N/A

0N/A </para>

0N/A

0N/A </refsect2>

0N/A

0N/A <refsect2>

0N/A <title>Monitoring container</title>

0N/A <para>It is sometime useful to track the states of a container,

0N/A for example to monitor it or just to wait for a specific

0N/A state in a script.

0N/A </para>

0N/A

0N/A <para>

0N/A <command>lxc-monitor</command> command will monitor one or

0N/A several containers. The parameter of this command accept a

0N/A regular expression for example:

58N/A <programlisting>

0N/A lxc-monitor -n "foo|bar"

0N/A </programlisting>

830N/A will monitor the states of containers named 'foo' and 'bar', and:

819N/A <programlisting>

0N/A lxc-monitor -n ".*"

0N/A </programlisting>

0N/A will monitor all the containers.

0N/A </para>

58N/A <para>

58N/A For a container 'foo' starting, doing some work and exiting,

0N/A the output will be in the form:

0N/A <programlisting>

0N/A 'foo' changed state to [STARTING]

0N/A 'foo' changed state to [RUNNING]

0N/A 'foo' changed state to [STOPPING]

0N/A 'foo' changed state to [STOPPED]

0N/A </programlisting>

0N/A </para>

0N/A <para>

0N/A <command>lxc-wait</command> command will wait for a specific

0N/A state change and exit. This is useful for scripting to

0N/A synchronize the launch of a container or the end. The

66N/A parameter is an ORed combination of different states. The

0N/A following example shows how to wait for a container if he went

0N/A to the background.

0N/A

0N/A <programlisting>

58N/A<![CDATA[

]]>

</programlisting>

</para>

</refsect2>

<refsect2>

<title>Setting the control group for container</title>

<para>The container is tied with the control groups, when a

container is started a control group is created and associated

with it. The control group properties can be read and modified

when the container is running by using the lxc-cgroup command.

</para>

<para>

<command>lxc-cgroup</command> command is used to set or get a

control group subsystem which is associated with a

container. The subsystem name is handled by the user, the

command won't do any syntax checking on the subsystem name, if

the subsystem name does not exists, the command will fail.

</para>

<para>

<programlisting>

lxc-cgroup -n foo cpuset.cpus

</programlisting>

will display the content of this subsystem.

<programlisting>

lxc-cgroup -n foo cpu.shares 512

</programlisting>

will set the subsystem to the specified value.

</para>

</refsect2>

</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;

<refsect1>

<title>Author</title>

<para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>

</refsect1>

</refentry>