diff options
author | dlezcano <dlezcano> | 2008-11-20 15:08:22 +0000 |
---|---|---|
committer | dlezcano <dlezcano> | 2008-11-20 15:08:22 +0000 |
commit | 7f989f01d5c0831fb1ccbc469ba970ea0e0b5a21 (patch) | |
tree | 968e32a35f051d0847ff3780ee1f8d642c5c9ac5 /README | |
parent | Add lxc.7 man page (diff) | |
download | lxc-7f989f01d5c0831fb1ccbc469ba970ea0e0b5a21.tar.gz lxc-7f989f01d5c0831fb1ccbc469ba970ea0e0b5a21.tar.bz2 lxc-7f989f01d5c0831fb1ccbc469ba970ea0e0b5a21.zip |
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: Daniel Lezcano <dlezcano@fr.ibm.com>
Diffstat (limited to 'README')
-rw-r--r-- | README | 522 |
1 files changed, 283 insertions, 239 deletions
@@ -1,283 +1,327 @@ - -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> |