lxc.sgml.in revision 57da8c32f85c0255efa61ee32e260068afdaa565
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanolxc: linux Container library
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano(C) Copyright IBM Corp. 2007, 2008
9afe19d634946d50eab30e3b90cb5cebcde39eeaDaniel LezcanoDaniel Lezcano <daniel.lezcano at free.fr>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoThis library is free software; you can redistribute it and/or
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanomodify it under the terms of the GNU Lesser General Public
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoLicense as published by the Free Software Foundation; either
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoversion 2.1 of the License, or (at your option) any later version.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoThis library is distributed in the hope that it will be useful,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanobut WITHOUT ANY WARRANTY; without even the implied warranty of
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoLesser General Public License for more details.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoYou should have received a copy of the GNU Lesser General Public
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanoLicense along with this library; if not, write to the Free Software
250b1eec71b074acdff1c5f6b5a1f0d7d2c20b77Stéphane GraberFoundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
99e4008cad9e959b683c6f48411fcf15a92be3b5Michel Normand<!ENTITY seealso SYSTEM "@builddir@/see_also.sgml">
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <refmiscinfo>
d5cf438682963ac84c3617941032ba623d4ac9b2Michel Normand Version @PACKAGE_VERSION@
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refmiscinfo>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <refnamediv>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <refpurpose>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano linux containers
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refpurpose>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refnamediv>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano You are in a hurry, and you don't want to read this man page. Ok,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano without warranty, here are the commands to launch a shell inside
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano a container with a predefined configuration template, it may
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano <command>@BINDIR@/lxc-execute -n foo -f
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano @DOCDIR@/examples/lxc-macvlan.conf /bin/bash</command>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The container technology is actively being pushed into the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano mainstream linux kernel. It provides the resource management
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano through the control groups aka process containers and resource
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano isolation through the namespaces.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The linux containers, <command>lxc</command>, aims to use these
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano new functionalities to provide an userspace container object
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano which provides full resource isolation and resource control for
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano an applications or a system.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The first objective of this project is to make the life easier
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano for the kernel developers involved in the containers project and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano especially to continue working on the Checkpoint/Restart new
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano features. The <command>lxc</command> is small enough to easily
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano manage a container with simple command lines and complete enough
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano to be used for other purposes.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand The <command>lxc</command> relies on a set of functionalities
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano provided by the kernel which needs to be active. Depending of
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano the missing functionalities the <command>lxc</command> will
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano work with a restricted number of functionalities or will simply
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The following list gives the kernel features to be enabled in
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the kernel to have the full features container:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi * General setup
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano * Control Group support
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Namespace cgroup subsystem
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Freezer cgroup subsystem
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Cpuset support
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Simple CPU accounting cgroup subsystem
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano -> Resource counters
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Memory resource controllers for Control Groups
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi * Group CPU scheduler
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Basis for grouping tasks (Control Groups)
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi * Namespaces support
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> UTS namespace
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> IPC namespace
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> User namespace
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Pid namespace
0478642a4349846ab8e76e318909886e795df92dFilippo Giunchedi -> Network namespace
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano * Device Drivers
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano * Character devices
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano -> Support multiple instances of devpts
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano * Network device support
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano -> MAC-VLAN support
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano -> Virtual ethernet pair device
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano * Networking options
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano -> 802.1d Ethernet Bridging
ac30d6a43245e0c50aad9e2ebfb88d80aaeea691Filippo Giunchedi * Security options
ac30d6a43245e0c50aad9e2ebfb88d80aaeea691Filippo Giunchedi -> File POSIX Capabilities
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano The kernel version >= 2.6.27 shipped with the distros, will
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano work with <command>lxc</command>, this one will have less
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano functionalities but enough to be interesting.
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano With the kernel 2.6.29, <command>lxc</command> is fully
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano The helper script <command>lxc-checkconfig</command> will give
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano you information about your kernel configuration.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Before using the <command>lxc</command>, your system should be
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano configured with the file capabilities, otherwise you will need
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano to run the <command>lxc</command> commands as root.
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano The control group can be mounted anywhere, eg:
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano <command>mount -t cgroup cgroup /cgroup</command>.
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano If you want to dedicate a specific cgroup mount point
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano for <command>lxc</command>, that is to have different cgroups
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano mounted at different places with different options but
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano let <command>lxc</command> to use one location, you can bind
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano the mount point with the <option>lxc</option> name, eg:
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano <command>mount -t cgroup lxc /cgroup4lxc</command> or
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano <command>mount -t cgroup -ons,cpuset,freezer,devices
0d9f8e188c1c4832e4f6b9de646478947ae86877Daniel Lezcano lxc /cgroup4lxc</command>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand A container is an object isolating some resources of the host,
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand for the application or system running in it.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand The application / system will be launched inside a
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand container specified by a configuration that is either
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand initially created or passed as parameter of the starting commands.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>How to run an application in a container ?</para>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Before running an application, you should know what are the
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano resources you want to isolate. The default configuration is to
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano isolate the pids, the sysv ipc and the mount points. If you want
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano to run a simple shell inside a container, a basic configuration
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano is needed, especially if you want to share the rootfs. If you
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano want to run an application like <command>sshd</command>, you
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano should provide a new network stack and a new hostname. If you
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano want to avoid conflicts with some files
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano eg. <filename>/var/run/httpd.pid</filename>, you should
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano remount <filename>/var/run</filename> with an empty
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano directory. If you want to avoid the conflicts in all the cases,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano you can specify a rootfs for the container. The rootfs can be a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano directory tree, previously bind mounted with the initial rootfs,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano so you can still use your distro but with your
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano own <filename>/etc</filename> and <filename>/home</filename>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Here is an example of directory tree
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano[root@lxc sshd]$ tree -d rootfs
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano| `-- network
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano | `-- empty
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano and the mount points file associated with it:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano [root@lxc sshd]$ cat fstab
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>Running a system inside a container is paradoxically easier
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano than running an application. Why ? Because you don't have to care
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano about the resources to be isolated, everything need to be
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano isolated, the other resources are specified as being isolated but
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano without configuration because the container will set them
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano up. eg. the ipv4 address will be setup by the system container
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano init scripts. Here is an example of the mount points file:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano [root@lxc debian]$ cat fstab
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano /dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano More information can be added to the container to facilitate the
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano configuration. For example, make accessible from the container
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano the resolv.conf file belonging to the host.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano /etc/resolv.conf /home/root/debian/rootfs/etc/resolv.conf none bind 0 0
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano When the container is created, it contains the configuration
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano information. When a process is launched, the container will be
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano starting and running. When the last process running inside the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano container exits, the container is stopped.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano In case of failure when the container is initialized, it will
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano pass through the aborting state.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano | STOPPED |<---------------
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano --------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ---------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano | STARTING |--error- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ---------- | |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano --------- ---------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano | RUNNING | | ABORTING | |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano --------- ---------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano no process | |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ---------- | |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano | STOPPING |<------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ---------- |
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano ---------------------
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>The container is configured through a configuration
f79d43bbe70a01454049b77d6f15f6369744959eStéphane Graber file, the format of the configuration file is described in
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <citerefentry>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <refentrytitle><filename>lxc.conf</filename></refentrytitle>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </citerefentry>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand <title>Creating / Destroying container
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand (persistent container)</title>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand A persistent container object can be
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand created via the <command>lxc-create</command>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand command. It takes a container name as parameter and
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand optional configuration file and template.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand The name is used by the different
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano commands to refer to this
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano container. The <command>lxc-destroy</command> command will
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano destroy the container object.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-create -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-destroy -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand <para>It is not mandatory to create a container object
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand before to start it.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand The container can be directly started with a
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand configuration file as parameter.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>When the container has been created, it is ready to run an
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand application / system.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand This is the purpose of the <command>lxc-execute</command> and
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand If the container was not created before
6a22713f648be8bd21297f57d9b631eb4c537ffeDaniel Lezcano starting the application, the container will use the
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand configuration file passed as parameter to the command,
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand and if there is no such parameter either, then
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand it will use a default isolation.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand If the application is ended, the container will be stopped also,
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand but if needed the <command>lxc-stop</command> command can
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand be used to kill the still running application.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Running an application inside a container is not exactly the
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand same thing as running a system. For this reason, there are two
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand different commands to run an application into a container:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-execute</command> command will run the
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand specified command into the container via an intermediate
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand This lxc-init after launching the specified command,
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand will wait for its end and all other reparented processes.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand (that allows to support daemons in the container).
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand In other words, in the
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand container, <command>lxc-init</command> has the pid 1 and the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano first process of the application has the pid 2.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand <command>lxc-start</command> command will run directly the specified
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand command into the container.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The pid of the first process is 1. If no command is
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano To summarize, <command>lxc-execute</command> is for running
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand an application and <command>lxc-start</command> is better suited for
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano running a system.
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand If the application is no longer responding, is inaccessible or is
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano not able to finish by itself, a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano wild <command>lxc-stop</command> command will kill all the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano processes in the container without pity.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-stop -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano If the container is configured with the ttys, it is possible
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano to access it through them. It is up to the container to
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano provide a set of available tty to be used by the following
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano command. When the tty is lost, it is possible to reconnect it
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano without login again.
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano <programlisting>
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano lxc-console -n foo -t 3
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano </programlisting>
b0a33c1eb65d2c87e886c740a0dadd8ad5f8d87ddlezcano </refsect2>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Sometime, it is useful to stop all the processes belonging to
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano a container, eg. for job scheduling. The commands:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-freeze -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f79d43bbe70a01454049b77d6f15f6369744959eStéphane Graber will put all the processes in an uninteruptible state and
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-unfreeze -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand will resume them.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano This feature is enabled if the cgroup freezer is enabled in the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand <title>Getting information about container</title>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>When there are a lot of containers, it is hard to follow
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano what has been created or destroyed, what is running or what are
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the pids running into a specific container. For this reason, the
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand following commands may be usefull:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano lxc-ps --name foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-info -n foo
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-ls</command> lists the containers of the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano system. The command is a script built on top
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano of <command>ls</command>, so it accepts the options of the ls
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano commands, eg:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will display the containers list in one column or:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will display the containers list and their permissions.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-ps</command> will display the pids for a specific
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano container. Like <command>lxc-ls</command>, <command>lxc-ps</command>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano is built on top of <command>ps</command> and accepts the same
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano options, eg:
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano <programlisting>lxc-ps --name foo --forest</programlisting>
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano will display the processes hierarchy for the processes
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano belonging the 'foo' container.
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano <programlisting>lxc-ps --lxc</programlisting>
c159cb963868d4646cf415abb064d8fd4b6ee848Daniel Lezcano will display all the containers and their processes.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-info</command> gives informations for a specific
b6d441f289eb03a1a6fe0662a14c26ecc852be21dlezcano container, at present time, only the state of the container is
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano Here is an example on how the combination of these commands
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano allow to list all the containers and retrieve their state.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano for i in $(lxc-ls -1); do
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-info -n $i
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano And displaying all the pids of all the containers:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano for i in $(lxc-ls -1); do
83c2e175242f590ef8984174fe62fa13720ea654Michel Normand lxc-ps --name $i --forest
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-netstat</command> display network information for
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano a specific container. This command is built on top of
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the <command>netstat</command> command and will accept its
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano The following command will display the socket informations for
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the container 'foo'.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-netstat -n foo -tano
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>It is sometime useful to track the states of a container,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano for example to monitor it or just to wait for a specific
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano state in a script.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-monitor</command> command will monitor one or
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano several containers. The parameter of this command accept a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano regular expression for example:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-monitor -n "foo|bar"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will monitor the states of containers named 'foo' and 'bar', and:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-monitor -n ".*"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will monitor all the containers.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano For a container 'foo' starting, doing some work and exiting,
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the output will be in the form:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano 'foo' changed state to [STARTING]
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano 'foo' changed state to [RUNNING]
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano 'foo' changed state to [STOPPING]
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano 'foo' changed state to [STOPPED]
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-wait</command> command will wait for a specific
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano state change and exit. This is useful for scripting to
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano synchronize the launch of a container or the end. The
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano parameter is an ORed combination of different states. The
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano following example shows how to wait for a container if he went
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano to the background.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano # launch lxc-wait in background
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-wait -n foo -s STOPPED &
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano LXC_WAIT_PID=$!
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano # this command goes in background
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-execute -n foo mydaemon &
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano # block until the lxc-wait exits
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano # and lxc-wait exits when the container
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano # is STOPPED
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano wait $LXC_WAIT_PID
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano echo "'foo' is finished"
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
a941cc0bf6c215079f56d68930370dcd8c6002afMichel Normand <title>Setting the control group for container</title>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>The container is tied with the control groups, when a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano container is started a control group is created and associated
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano with it. The control group properties can be read and modified
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano when the container is running by using the lxc-cgroup command.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <command>lxc-cgroup</command> command is used to set or get a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano control group subsystem which is associated with a
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano container. The subsystem name is handled by the user, the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano command won't do any syntax checking on the subsystem name, if
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the subsystem name does not exists, the command will fail.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-cgroup -n foo cpuset.cpus
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will display the content of this subsystem.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano lxc-cgroup -n foo cpu.shares 512
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </programlisting>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano will set the subsystem to the specified value.
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect2>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>The <command>lxc</command> is still in development, so the
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano command syntax and the API can change. The version 1.0.0 will be
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano the frozen version.</para>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano <para>Daniel Lezcano <email>daniel.lezcano@free.fr</email></para>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano </refsect1>
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcano<!-- Keep this comment at the end of the file Local variables: mode:
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosgml sgml-omittag:t sgml-shorttag:t sgml-minimize-attributes:nil
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosgml-always-quote-attributes:t sgml-indent-step:2 sgml-indent-data:t
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosgml-parent-document:nil sgml-default-dtd-file:nil
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosgml-exposed-tags:nil sgml-local-catalogs:nil
f1d8791c17f7e0f131de20d7bbc8836b992bd4dbdlezcanosgml-local-ecat-files:nil End: -->