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:

git://git.kernel.org/pub/scm/linux/kernel/git/daveh/linux-2.6-lxc.git

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

# specify the physical network device which will communicate with the
# outside world
lxc.network.link = eth0

# NIC ethernet mac address
lxc.network.hwaddr = 4a:49:43:49:79:bd

# 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

# 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
lxc.cgroup.cpu.shares = 512
lxc.cgroup.cpuset.cpu = 0,1

--------------------------------------------------------------------------------

All fields are optional.


3.3 Container creation
----------------------

The container is created via the 'lxc-create' command.  The command
specifies the container name and the container configuration file.

      lxc-create -n foo -f <config>


3.4 Starting a container
------------------------

As the container has been created with the lxc-create command, it is
possible now to start an application inside.

      lxc-execute -n foo /bin/bash

When the application has exited, it is possible to continue using the
container configuration to launch another application.

3.5 Stopping a container
------------------------

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-stop -n foo

3.6 Freezing/Unfreezing a container
-----------------------------------

All the processes belonging to a container can be stopped and resumed.

      lxc-freeze -n foo

      lxc-unfreeze -n foo

3.7 Sending a signal to a container
-----------------------------------

A signal can be sent to all processes running inside the container.

      lxc-kill -n foo -s <signal>

3.8 Monitoring container states
-------------------------------

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 -n foo

3.9 Getting container information
----------------------------------

At any time, the following command will retrieve informations of the
 container.

     lxc-info -n foo

3.10 Showing processes list for a container
-------------------------------------------

The following command will show all the processes for all the running
container.

     lxc-ps

3.11 Using the control group for a container
--------------------------------------------

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 cpuset.cpu 1

     lxc-cgroup -n foo cpu.shares

4) Future work
--------------

 * change the lxc-execute to have the first process to exec
 * man pages
 * improve monitoring support
 * and more :)