Skip to content

L
lxc
Commit 7f989f01 by dlezcano
Options

Make the README file a copy of lxc.7

From: Daniel Lezcano <dlezcano@fr.ibm.com> The man lxc.7 being complete enough, I copy the man to the README file. Signed-off-by: 's avatarDaniel Lezcano <dlezcano@fr.ibm.com>
parent 8b8b04f8
Showing with 245 additions and 201 deletions
README
NAME
Linux Container - LXC: lxc - linux containers
----------------------
QUICK START
This document provides a quick help to use the linux container. 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
Contents: predefined configuration template, it may work.
--------- lxc-execute -n foo -f /etc/lxc/lxc-macvlan.conf /bin/bash
0) Quick start
1) Overview OVERVIEW
2) Requirements The container technology is actively being pushed into the mainstream linux
3) Functional Specification kernel. It provides the resource management through the control groups aka
4) Future work process containers and resource isolation through the namespaces.
The linux containers, lxc, aims to use these new functionnalities to pro-
0) Quick start vide an userspace container object which provides full resource isolation
-------------- and resource control for an applications or a system.
You are in a hurry, and you don't want to read this README. Ok, The first objective of this project is to make the life easier for the ker-
without warranty, here are the commands to launch a shell inside a nel developers involved in the containers project and especially to con-
container with a predefined configuration template, it may work. tinue working on the Checkpoint/Restart new features. The lxc is small
enough to easily manage a container with simple command lines and complete
lxc-create -n foo -f /etc/lxc/lxc-macvlan.conf enough to be used for other purposes.
lxc-execute -n foo /bin/bash REQUIREMENTS
The lxc relies on a set of functionnalies provided by the kernel which
When your bash exits, you don't have to create 'foo' again, just call needs to be active. Depending of the missing functionnalities the lxc will
lxc-execute again. work with a restricted number of functionnalities or will simply fails.
1) Overview The following list gives the kernel features to be enabled in the kernel to
----------- have the full features container:
The container technology is actively being pushed into the mainstream * General
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 * Control Group support
-> namespace cgroup subsystem -> namespace cgroup subsystem
-> cpuset support -> cpuset support
...@@ -70,44 +45,109 @@ This is the list of the kernel features which needs to be compiled in: ...@@ -70,44 +45,109 @@ This is the list of the kernel features which needs to be compiled in:
-> IPC namespace -> IPC namespace
-> User namespace -> User namespace
-> Pid namespace -> Pid namespace
* Network support * Network support
-> Networking options -> Networking options
-> Network namespace support -> Network namespace support
For the moment the easiest way to have all the features in the kernel For the moment the easiest way to have all the features in the kernel is to
is to use the git tree at: use the git tree at:
:
git://git.kernel.org/pub/scm/linux/kernel/git/daveh/linux-2.6-lxc.git 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
Otherwise the latest version of 2.6.26 kernel is usable with LXC but lxc, this one will have less functionnalities but enough to be interesting.
without sysfs if the network namespace is activated and without the The planned kernel version which lxc should be fully functionnaly is
freezer subsystem. 2.6.29.
Before using LXC, the system should be configured as followed: 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-
* Control group file system must be mounted trol group should be mounted anywhere, eg: mount -t cgroup cgroup /cgroup
mount -t cgroup cgroup /cgroup FUNCTIONAL SPECIFICATION
A container is an object where the configuration is persistent. The appli-
* You must have root privileges cation will be launched inside this container and it will use the configu-
ration which was previously created.
3) Functional Specification
--------------------------- How to run an application in a container ?
A container is an object where the configuration is persistent. The Before running an application, you should know what are the resource you
application will be launched inside this container and it will want to isolate. The default configuration is isolation of the pids, the
use the configuration which was previously created. 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
3.1 Container life cycle 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
When the container is created, it contains the configuration empty directory. If you want to avoid the conflicts in all the cases, you
information. When a process is launched, the container will be can specify a rootfs for the container. The rootfs can be a directory tree,
starting and running. When the last process running inside the previously bind mounted with the initial rootfs, so you can still use your
container exits, the container is stopped. distro but with your own /etc and /home
In case of failure when the container is initialized, it will pass Here is an example of directory tree for sshd:
through the aborting state.
[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 |<--------------- | STOPPED |<---------------
...@@ -134,150 +174,154 @@ through the aborting state. ...@@ -134,150 +174,154 @@ through the aborting state.
| | | |
--------------------- ---------------------
3.2 Configuration file CONFIGURATION
---------------------- The container is configured through a configuration file, the format of the
configuration file is described in lxc.conf(5)
The configuration file has the following format:
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 fstab mount file. the different commands to refer to this container. The lxc-destroy command
lxc.mount = ./fstab will destroy the container object.
# the hostname to be set into the container lxc-create -n foo
lxc.utsname = virtnode lxc-destroy -n foo
# the rootfs if needed for the running application STARTING / STOPPING A CONTAINER
lxc.rootfs = /mnt/root 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
# The network has several of kind of configuration: stopped, that will kill all the processes of the container.
#
# * veth : the network will use the veth virtual device, the Running an application inside a container is not exactly the same thing as
# specified link must be a bridge running a system. For this reason, there is two commands to run an applica-
# * macvlan : the network will use the macvlan device, the specified tion into a container:
# link should be an existing interface, usually it is
# eth0 lxc-execute -n foo [-f config] /bin/bash
# * phys : the network will use a physical network device, the lxc-start -n foo [/bin/bash]
# specified link should be an existing interface
# * empty : the network namespace will be empty, only the default network lxc-execute command will run the specified command into a container but it
# devices will be created (loopback, gre, ...) will mount /proc and autocreate/autodestroy the container if it does not
exist. It will furthermore create an intermediate process, lxc-init, which
lxc.network.type = macvlan 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
# specify the flags to be used for the network, actually only <up> is pid 1 and the first process of the application has the pid 2.
# 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-start command will run the specified command into the container doing
lxc.network.flags = up 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
# specify the physical network device which will communicate with the /sbin/init.
# outside world
lxc.network.link = eth0 To summarize, lxc-execute is for running an application and lxc-start is
for running a system.
# NIC ethernet mac address
lxc.network.hwaddr = 4a:49:43:49:79:bd 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
# specify the ipv4 address of the container. Several lines are allowed the container without pity.
# and will mean several addresses will be assigned to the interface lxc-stop -n foo
lxc.network.ipv4 = 1.2.3.5/24
# 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
# specify the a cgroup value FREEZE / UNFREEZE A CONTAINER
lxc.cgroup.cpu.shares = 512 Sometime, it is useful to stop all the processes belonging to a container,
lxc.cgroup.cpuset.cpu = 0,1 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 This feature is enabled if the cgroup freezer is enabled in the kernel.
specifies the container name and the container configuration file.
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 lxc-ls -1
possible now to start an application inside.
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 lxc-ls -l
container configuration to launch another application.
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 lxc-ps will display the pids for a specific container. Like lxc-ls, lxc-ps
cases, it is usefully to wipe out such application. The following is built on top of ps and accepts the same options, eg:
command will kill the processes.
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 lxc-monitor command will monitor one or several containers. The parameter
defined in section 3.1. The following command allows to watch such of this command accept a regular expression for example:
states for a specific container.
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 lxc-monitor -n ".*"
container.
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 lxc-cgroup command is used to set or get a control group subsystem which is
container. 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. lxc-cgroup -n foo cpus.share 512
If the command is specified without value, the specified key is
retrieved otherwise it is set.
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 AUTHOR
* man pages Daniel Lezcano <daniel.lezcano@free.fr>
* improve monitoring support
* and more :)
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