-
-Linux Container - LXC:
-----------------------
-
-This document provides a quick help to use the linux container.
-
-Contents:
----------
- 0) Quick start
- 1) Overview
- 2) Requirements
- 3) Functional Specification
- 4) Future work
-
-
-0) Quick start
---------------
-
-You are in a hurry, and you don't want to read this README. Ok,
-without warranty, here are the commands to launch a shell inside a
-container with a predefined configuration template, it may work.
-
- lxc-create -n foo -f /etc/lxc/lxc-macvlan.conf
-
- lxc-execute -n foo /bin/bash
-
-When your bash exits, you don't have to create 'foo' again, just call
-lxc-execute again.
-
-1) Overview
------------
-
-The container technology is actively being pushed into the mainstream
-linux kernel. It provides the resource management through the control
-groups aka process containers and resource isolation through the
-namespaces.
-
-The LXC aims to use these new functionnalities to provide an userspace
-container object which provides full resource isolation and resource
-control for an applications or a system.
-
-The first objective of this project is to make the life easier for the
-kernel developers involved in the containers project and especially
-to continue working on the Checkpoint/Restart new features. The LXC is
-small enough to easily manage a container with simple command lines
-and complete enough to be used for other purposes.
-
-2) Requirements
----------------
-
-The LXC relies on a set of functionnalies provided by the kernel which
-needs to be active. Depending of the missing functionnalities the LXC
-will work with a restricted number of functionnalities or will simply
-fails.
-
-This is the list of the kernel features which needs to be compiled in:
-
-* General
- * Control Group support
- -> namespace cgroup subsystem
- -> cpuset support
- -> Group CPU scheduler
- -> control group freeze subsystem
- -> Basis for grouping tasks (Control Groups)
- -> Simple CPU accounting
- -> Resource counters
- -> Memory resource controllers for Control Groups
- -> Namespace support
- -> UTS namespace
- -> IPC namespace
- -> User namespace
- -> Pid namespace
-* Network support
- -> Networking options
- -> Network namespace support
-
-For the moment the easiest way to have all the features in the kernel
-is to use the git tree at:
+NAME
+ lxc - linux containers
+
+QUICK START
+ 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.
+ lxc-execute -n foo -f /etc/lxc/lxc-macvlan.conf /bin/bash
+
+OVERVIEW
+ The container technology is actively being pushed into the mainstream linux
+ kernel. It provides the resource management through the control groups aka
+ process containers and resource isolation through the namespaces.
+
+ The linux containers, lxc, aims to use these new functionnalities to pro-
+ vide an userspace container object which provides full resource isolation
+ and resource control for an applications or a system.
+
+ The first objective of this project is to make the life easier for the ker-
+ nel developers involved in the containers project and especially to con-
+ tinue working on the Checkpoint/Restart new features. The lxc is small
+ enough to easily manage a container with simple command lines and complete
+ enough to be used for other purposes.
+
+REQUIREMENTS
+ The lxc relies on a set of functionnalies provided by the kernel which
+ needs to be active. Depending of the missing functionnalities the lxc will
+ work with a restricted number of functionnalities or will simply fails.
+
+ The following list gives the kernel features to be enabled in the kernel to
+ have the full features container:
+
+ * General
+ * Control Group support
+ -> namespace cgroup subsystem
+ -> cpuset support
+ -> Group CPU scheduler
+ -> control group freeze subsystem
+ -> Basis for grouping tasks (Control Groups)
+ -> Simple CPU accounting
+ -> Resource counters
+ -> Memory resource controllers for Control Groups
+ -> Namespace support
+ -> UTS namespace
+ -> IPC namespace
+ -> User namespace
+ -> Pid namespace
+ * Network support
+ -> Networking options
+ -> Network namespace support
+
+ For the moment the easiest way to have all the features in the kernel is to
+ use the git tree at:
+:
git://git.kernel.org/pub/scm/linux/kernel/git/daveh/linux-2.6-lxc.git
+ But the kernel version >= 2.6.27 shipped with the distros, may work with
+ lxc, this one will have less functionnalities but enough to be interesting.
+ The planned kernel version which lxc should be fully functionnaly is
+ 2.6.29.
+
+ Before using the lxc, your system should be configured with the file capa-
+ bilities, otherwise you will need to run the lxc commands as root. The con-
+ trol group should be mounted anywhere, eg: mount -t cgroup cgroup /cgroup
+
+FUNCTIONAL SPECIFICATION
+ A container is an object where the configuration is persistent. The appli-
+ cation will be launched inside this container and it will use the configu-
+ ration which was previously created.
+
+ How to run an application in a container ?
+
+ Before running an application, you should know what are the resource you
+ want to isolate. The default configuration is isolation of the pids, the
+ sysv ipc and the mount points. If you want to run a simple shell inside a
+ container, a basic configuration is needed, especially if you want to share
+ the rootfs. If you want to run an application like sshd, you should provide
+ a new network stack and a new hostname. If you want to avoid conflicts with
+ some files eg. /var/run/httpd.pid, you should remount /var/run with an
+ empty directory. If you want to avoid the conflicts in all the cases, you
+ can specify a rootfs for the container. The rootfs can be a directory tree,
+ previously bind mounted with the initial rootfs, so you can still use your
+ distro but with your own /etc and /home
+
+ Here is an example of directory tree for sshd:
+
+ [root@lxc sshd]$ tree -d rootfs
+
+ rootfs
+ |-- bin
+ |-- dev
+ | |-- pts
+ | ‘-- shm
+ | ‘-- network
+ |-- etc
+ | ‘-- ssh
+ |-- lib
+ |-- proc
+ |-- root
+ |-- sbin
+ |-- sys
+ |-- usr
+ ‘-- var
+ |-- empty
+ | ‘-- sshd
+ |-- lib
+ | ‘-- empty
+ | ‘-- sshd
+ ‘-- run
+ ‘-- sshd
+ and the mount points file associated with it:
+
+ [root@lxc sshd]$ cat fstab
+
+ /lib /home/root/sshd/rootfs/lib none ro,bind 0 0
+ /bin /home/root/sshd/rootfs/bin none ro,bind 0 0
+ /usr /home/root/sshd/rootfs/usr none ro,bind 0 0
+ /sbin /home/root/sshd/rootfs/sbin none ro,bind 0 0
+
+ How to run a system in a container ?
+
+ Running a system inside a container is paradoxically easier than running an
+ application. Why ? Because you don’t have to care about the resources to be
+ isolated, everything need to be isolated except /dev which needs to be
+ remounted in the container rootfs, the other resources are specified as
+ being isolated but without configuration because the container will set
+ them up. eg. the ipv4 address will be setup by the system container init
+ scripts. Here is an example of the mount points file:
+
+ [root@lxc debian]$ cat fstab
+
+ /dev /home/root/debian/rootfs/dev none bind 0 0
+ /dev/pts /home/root/debian/rootfs/dev/pts none bind 0 0
+
+ A good idea to have the console is to mount bind this one to our tty, so we
+ see the output of the system container booting and we can log to it
+
+ /proc/self/fd/0 /home/root/debian/rootfs/dev/console none bind 0 0
+
+ These examples are avaible in the contrib package located at:
+ https://sourceforge.net/projects/lxc/
+
+ CONTAINER LIFE CYCLE
+ When the container is created, it contains the configuration information.
+ When a process is launched, the container will be starting and running.
+ When the last process running inside the container exits, the container is
+ stopped.
+
+ In case of failure when the container is initialized, it will pass through
+ the aborting state.
+
+ ---------
+ | STOPPED |<---------------
+ --------- |
+ | |
+ start |
+ | |
+ V |
+ ---------- |
+ | STARTING |--error- |
+ ---------- | |
+ | | |
+ V V |
+ --------- ---------- |
+ | RUNNING | | ABORTING | |
+ --------- ---------- |
+ | | |
+ no process | |
+ | | |
+ V | |
+ ---------- | |
+ | STOPPING |<------- |
+ ---------- |
+ | |
+ ---------------------
+
+ CONFIGURATION
+ The container is configured through a configuration file, the format of the
+ configuration file is described in lxc.conf(5)
+
+ CREATING / DESTROYING THE CONTAINERS
+ The container is created via the lxc-create command. It takes a container
+ name as parameter and an optional configuration file. The name is used by
+ the different commands to refer to this container. The lxc-destroy command
+ will destroy the container object.
+
+ lxc-create -n foo
+ lxc-destroy -n foo
+
+ STARTING / STOPPING A CONTAINER
+ When the container has been created, it is ready to run an application /
+ system. When the application has to be destroyed the container can be
+ stopped, that will kill all the processes of the container.
+
+ Running an application inside a container is not exactly the same thing as
+ running a system. For this reason, there is two commands to run an applica-
+ tion into a container:
-Otherwise the latest version of 2.6.26 kernel is usable with LXC but
-without sysfs if the network namespace is activated and without the
-freezer subsystem.
-
-Before using LXC, the system should be configured as followed:
-
-* Control group file system must be mounted
-
- mount -t cgroup cgroup /cgroup
-
-* You must have root privileges
-
-3) Functional Specification
----------------------------
-
-A container is an object where the configuration is persistent. The
-application will be launched inside this container and it will
-use the configuration which was previously created.
-
-3.1 Container life cycle
-------------------------
-
-When the container is created, it contains the configuration
-information. When a process is launched, the container will be
-starting and running. When the last process running inside the
-container exits, the container is stopped.
-
-In case of failure when the container is initialized, it will pass
-through the aborting state.
-
- ---------
- | STOPPED |<---------------
- --------- |
- | |
- start |
- | |
- V |
- ---------- |
- | STARTING |--error- |
- ---------- | |
- | | |
- V V |
- --------- ---------- |
- | RUNNING | | ABORTING | |
- --------- ---------- |
- | | |
- no process | |
- | | |
- V | |
- ---------- | |
- | STOPPING |<------- |
- ---------- |
- | |
- ---------------------
-
-3.2 Configuration file
-----------------------
-
-The configuration file has the following format:
-
---------------------------------------------------------------------------------
-
-# the fstab mount file.
-lxc.mount = ./fstab
-
-# the hostname to be set into the container
-lxc.utsname = virtnode
-
-# the rootfs if needed for the running application
-lxc.rootfs = /mnt/root
-
-# The network has several of kind of configuration:
-#
-# * veth : the network will use the veth virtual device, the
-# specified link must be a bridge
-# * macvlan : the network will use the macvlan device, the specified
-# link should be an existing interface, usually it is
-# eth0
-# * phys : the network will use a physical network device, the
-# specified link should be an existing interface
-# * empty : the network namespace will be empty, only the default network
-# devices will be created (loopback, gre, ...)
-
-lxc.network.type = macvlan
-
-# specify the flags to be used for the network, actually only <up> is
-# allowed which mean the network should be set up when created. If the
-# network is set up, the loopback is automatically set up too.
-lxc.network.flags = up
+ lxc-execute -n foo [-f config] /bin/bash
+ lxc-start -n foo [/bin/bash]
-# specify the physical network device which will communicate with the
-# outside world
-lxc.network.link = eth0
+ lxc-execute command will run the specified command into a container but it
+ will mount /proc and autocreate/autodestroy the container if it does not
+ exist. It will furthermore create an intermediate process, lxc-init, which
+ is in charge to launch the specified command, that allows to support dae-
+ mons in the container. In other words, in the container lxc-init has the
+ pid 1 and the first process of the application has the pid 2.
-# NIC ethernet mac address
-lxc.network.hwaddr = 4a:49:43:49:79:bd
+ lxc-start command will run the specified command into the container doing
+ nothing else than using the configuration specified by lxc-create. The pid
+ of the first process is 1. If no command is specified lxc-start will run
+ /sbin/init.
-# specify the ipv4 address of the container. Several lines are allowed
-# and will mean several addresses will be assigned to the interface
-lxc.network.ipv4 = 1.2.3.5/24
+ To summarize, lxc-execute is for running an application and lxc-start is
+ for running a system.
-# specify the ipv6 address of the container. Several lines are allowed
-# and will mean several addresses will be assigned to the interface
-lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
+ If the application is no longer responding, inaccessible and is not able to
+ finish by itself, a wild lxc-stop command will kill all the processes in
+ the container without pity.
+ lxc-stop -n foo
-# specify the a cgroup value
-lxc.cgroup.cpu.shares = 512
-lxc.cgroup.cpuset.cpu = 0,1
+ FREEZE / UNFREEZE A CONTAINER
+ Sometime, it is useful to stop all the processes belonging to a container,
+ eg. for job scheduling. The commands:
---------------------------------------------------------------------------------
+ lxc-freeze -n foo
-All fields are optional.
+ will put all the processes in an ininteruptible state and
+ lxc-unfreeze -n foo
-3.3 Container creation
-----------------------
+ will resume all the tasks.
-The container is created via the 'lxc-create' command. The command
-specifies the container name and the container configuration file.
+ This feature is enabled if the cgroup freezer is enabled in the kernel.
- lxc-create -n foo -f <config>
+ GETTING INFORMATION ABOUT THE CONTAINER
+ When there are a lot of containers, it is hard to follow what has been cre-
+ ated or destroyed, what is running or what are the pids running into a spe-
+ cific container. For this reason, the following commands give this informa-
+ tion:
+ lxc-ls
+ lxc-ps -n foo
+ lxc-info -n foo
-3.4 Starting a container
-------------------------
+ lxc-ls list the containers of the system. The command is a script built on
+ top of ls, so it accepts the options of the ls commands, eg:
-As the container has been created with the lxc-create command, it is
-possible now to start an application inside.
+ lxc-ls -1
- lxc-execute -n foo /bin/bash
+ will display the containers list in one column or:
-When the application has exited, it is possible to continue using the
-container configuration to launch another application.
+ lxc-ls -l
-3.5 Stopping a container
-------------------------
+ will display the containers list and their permissions.
-Usually, a container stops when the last process exits but in some
-cases, it is usefully to wipe out such application. The following
-command will kill the processes.
+ lxc-ps will display the pids for a specific container. Like lxc-ls, lxc-ps
+ is built on top of ps and accepts the same options, eg:
- lxc-stop -n foo
+ lxc-ps -n foo --forest
-3.6 Freezing/Unfreezing a container
------------------------------------
+ will display the process hierarchy for the container ’foo’.
-All the processes belonging to a container can be stopped and resumed.
+ lxc-info gives informations for a specific container, at present only the
+ state of the container is displayed.
- lxc-freeze -n foo
+ Here is an example on how the combination of these commands allow to list
+ all the containers and retrieve their state.
- lxc-unfreeze -n foo
+ for i in $(lxc-ls -1); do
+ lxc-info -n $i
+ done
-3.7 Sending a signal to a container
------------------------------------
+ And displaying all the pids of all the containers:
+ for i in $(lxc-ls -1); do
+ lxc-info -n $i
+ done
-A signal can be sent to all processes running inside the container.
+ And displaying all the pids of all the containers:
- lxc-kill -n foo -s <signal>
+ for i in $(lxc-ls -1); do
+ lxc-ps -n $i --forest
+ done
-3.8 Monitoring container states
--------------------------------
+ MONITORING THE CONTAINERS
+ It is sometime useful to track the states of a container, for example to
+ monitor it or just to wait for a specific state in a script.
-A container has a life cycle and passes though different states as
-defined in section 3.1. The following command allows to watch such
-states for a specific container.
+ lxc-monitor command will monitor one or several containers. The parameter
+ of this command accept a regular expression for example:
- lxc-monitor -n foo
+ lxc-monitor -n "foo|bar"
-3.9 Getting container information
-----------------------------------
+ will monitor the states of containers named ’foo’ and ’bar’, and:
-At any time, the following command will retrieve informations of the
- container.
+ lxc-monitor -n ".*"
- lxc-info -n foo
+ will monitor all the containers.
-3.10 Showing processes list for a container
--------------------------------------------
+ SETTING THE CONTROL GROUP FOR A CONTAINER
+ The container is tied with the control groups. A control group can be setup
+ when the container is running to change or to retrieve its value.
-The following command will show all the processes for all the running
-container.
+ lxc-cgroup command is used to set or get a control group subsystem which is
+ associated with a container. The subsystem name is handle by the user, the
+ command won’t do any syntax checking on name, if the name does not exists,
+ the command will fail.
- lxc-ps
+ lxc-cgroup -n foo cpuset.cpus
-3.11 Using the control group for a container
---------------------------------------------
+ will display the content of this subsystem.
-Each time a container is created, a cgroup is associated to it.
-If the command is specified without value, the specified key is
-retrieved otherwise it is set.
+ lxc-cgroup -n foo cpus.share 512
- lxc-cgroup -n foo cpuset.cpu 1
+ will set the subsystem to the specified value.
- lxc-cgroup -n foo cpu.shares
+BUGS
+ The lxc is still in development, so the command syntax and the API can
+ change. The version 1.0.0 will be the frozen version.
-4) Future work
---------------
+SEE ALSO
+ lxc-create(1), lxc-destroy(1), lxc-start(1), lxc-execute(1), lxc-stop(1),
+ lxc-monitor(1), lxc-wait(1), lxc-cgroup(1), lxc-ls(1), lxc-ps(1), lxc-
+ info(1), lxc-freeze(1), lxc-unfreeze(1), lxc.conf(5),
- * change the lxc-execute to have the first process to exec
- * man pages
- * improve monitoring support
- * and more :)
+AUTHOR
+ Daniel Lezcano <daniel.lezcano@free.fr>
projects / thirdparty / lxc.git / commitdiff
