From: Michel Normand Date: Thu, 29 Apr 2010 08:03:59 +0000 (+0200) Subject: man update lxc X-Git-Tag: lxc-0.7.0~97 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a941cc0bf6c215079f56d68930370dcd8c6002af;p=thirdparty%2Flxc.git man update lxc update lxc man page to better explain: * the notions of persistent and volatil container. * the difference between lxc-execute and lxc-start commands Signed-off-by: Michel Normand Signed-off-by: Daniel Lezcano --- diff --git a/doc/lxc.sgml.in b/doc/lxc.sgml.in index 2c73aea45..1b30fedb6 100644 --- a/doc/lxc.sgml.in +++ b/doc/lxc.sgml.in @@ -92,7 +92,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Requirements - The lxc relies on a set of functionalies + The lxc relies on a set of functionalities provided by the kernel which needs to be active. Depending of the missing functionalities the lxc will work with a restricted number of functionalities or will simply @@ -172,10 +172,13 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 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 or specified in parameter of the command. + A container is an object isolating some resources of the host, + for the application or system running in it. + + + The application / system will be launched inside a + container specified by a configuration that is either + initially created or passed as parameter of the starting commands. How to run an application in a container ? @@ -306,13 +309,6 @@ rootfs - - Volatile containers - The container can be directly started with a - configuration file in parameter without creating them before. - - - Configuration The container is configured through a configuration @@ -325,11 +321,14 @@ rootfs - Creating / Destroying the containers + Creating / Destroying container + (persistent container) - 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 + A persistent container object can be + created via the lxc-create + command. It takes a container name as parameter and + optional configuration file and template. + The name is used by the different commands to refer to this container. The lxc-destroy command will destroy the container object. @@ -341,41 +340,55 @@ rootfs - Starting / Stopping a container + Volatile container + It is not mandatory to create a container object + before to start it. + The container can be directly started with a + configuration file as parameter. + + + + + Starting / Stopping 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. If the container was not created before + application / system. + This is the purpose of the lxc-execute and + lxc-start commands. + If the container was not created before starting the application, the container will use the - configuration file passed as parameter to the command, otherwise - it will use the default isolation. + configuration file passed as parameter to the command, + and if there is no such parameter either, then + it will use a default isolation. + If the application is ended, the container will be stopped also, + but if needed the lxc-stop command can + be used to kill the still running application. + 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 application into a container: + same thing as running a system. For this reason, there are two + different commands to run an application into a container: lxc-execute -n foo [-f config] /bin/bash - lxc-start -n foo [/bin/bash] + lxc-start -n foo [-f config] [/bin/bash] 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 daemons - in the container. In other words, in the - container lxc-init has the pid 1 and the + specified command into the container via an intermediate + process, lxc-init. + This lxc-init after launching the specified command, + will wait for its end and all other reparented processes. + (that allows to support daemons 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. - lxc-start command will run the specified - command into the container doing nothing else than using the - configuration specified by lxc-create. + lxc-start command will run directly the specified + command into the container. The pid of the first process is 1. If no command is specified lxc-start will run /sbin/init. @@ -383,12 +396,12 @@ rootfs To summarize, lxc-execute is for running - an application and lxc-start is for + an application and lxc-start is better suited for running a system. - If the application is no longer responding, inaccessible or is + If the application is no longer responding, is inaccessible or is not able to finish by itself, a wild lxc-stop command will kill all the processes in the container without pity. @@ -413,7 +426,7 @@ rootfs - Freeze / Unfreeze a container + Freeze / Unfreeze container Sometime, it is useful to stop all the processes belonging to a container, eg. for job scheduling. The commands: @@ -427,7 +440,7 @@ rootfs lxc-unfreeze -n foo - will resume all the tasks. + will resume them. @@ -437,11 +450,11 @@ rootfs - Getting information about the container + Getting information about container When there are a lot of containers, it is hard to follow what has been created or destroyed, what is running or what are the pids running into a specific container. For this reason, the - following commands give this information: + following commands may be usefull: lxc-ls lxc-ps --name foo @@ -519,7 +532,7 @@ rootfs - Monitoring the containers + Monitoring container 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. @@ -576,7 +589,7 @@ rootfs - Setting the control group for a container + Setting the control group for container 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