README

   1
   2 Linux Container - LXC:
   3 ----------------------
   4
   5 This document provides a quick help to use the linux container.
   6
   7 Change log:
   8 -----------
   9
  10 version 0.1.0 : initial document, Daniel Lezcano <dlezcano@fr.ibm.com>, Aug 01, 2008
  11
  12 Contents:
  13 ---------
  14         0) Quick start
  15         1) Overview
  16         2) Requirements
  17         3) Functional Specification
  18         4) Future work
  19
  20
  21 0) Quick start
  22 --------------
  23
  24 You are in a hurry, and you don't want to read this README. Ok,
  25 without warranty, here are the commands to launch a shell inside a
  26 container with a predefined configuration template, it may work.
  27
  28    lxc-create -n foo -f /etc/lxc/lxc-macvlan.conf
  29
  30    lxc-execute -n foo /bin/bash
  31
  32 When your bash exits, you don't have to create 'foo' again, just call
  33 lxc-execute again.
  34
  35 1) Overview
  36 -----------
  37
  38 The container technology is actively being pushed into the mainstream
  39 linux kernel. It provides the resource management through the control
  40 groups aka process containers and resource isolation through the
  41 namespaces.
  42
  43 The LXC aims to use these new functionnalities to provide an userspace
  44 container object which provides full resource isolation and resource
  45 control for an applications or a system.
  46
  47 The first objective of this project is to make the life easier for the
  48 kernel developers involved in the containers project and especially
  49 to continue working on the Checkpoint/Restart new features. The LXC is
  50 small enough to easily manage a container with simple command lines
  51 and complete enough to be used for other purposes.
  52
  53 2) Requirements
  54 ---------------
  55
  56 The LXC relies on a set of functionnalies provided by the kernel which
  57 needs to be active. Depending of the missing functionnalities the LXC
  58 will work with a restricted number of functionnalities or will simply
  59 fails.
  60
  61 This is the list of the kernel features which needs to be compiled in:
  62
  63 * General
  64  * Control Group support
  65    -> namespace cgroup subsystem
  66    -> cpuset support
  67    -> Group CPU scheduler
  68    -> control group freeze subsystem
  69    -> Basis for grouping tasks (Control Groups)
  70    -> Simple CPU accounting
  71    -> Resource counters
  72    -> Memory resource controllers for Control Groups
  73    -> Namespace support
  74      -> UTS namespace
  75      -> IPC namespace
  76      -> User namespace
  77      -> Pid namespace
  78 * Network support
  79  -> Networking options
  80   -> Network namespace support
  81
  82 For the moment the easiest way to have all the features in the kernel
  83 is to use the git tree at:
  84
  85 git://git.kernel.org/pub/scm/linux/kernel/git/daveh/linux-2.6-lxc.git
  86
  87 Otherwise the latest version of 2.6.26 kernel is usable with LXC but
  88 without sysfs if the network namespace is activated and without the
  89 freezer subsystem.
  90
  91 Before using LXC, the system should be configured as followed:
  92
  93 * Control group file system must be mounted
  94
  95   mount -t cgroup cgroup /cgroup
  96
  97 * You must have root privileges
  98
  99 3) Functional Specification
 100 ---------------------------
 101
 102 A container is an object where the configuration is persistent. The
 103 application will be launched inside this container and it will
 104 use the configuration which was previously created.
 105
 106 3.1 Container life cycle
 107 ------------------------
 108
 109 When the container is created, it contains the configuration
 110 information. When a process is launched, the container will be
 111 starting and running. When the last process running inside the
 112 container exits, the container is stopped.
 113
 114 In case of failure when the container is initialized, it will pass
 115 through the aborting state.
 116
 117    ---------
 118   | STOPPED |<---------------
 119    ---------                 |
 120        |                     |
 121      start                   |
 122        |                     |
 123        V                     |
 124    ----------                |
 125   | STARTING |--error-       |
 126    ----------         |      |
 127        |              |      |
 128        V              V      |
 129    ---------    ----------   |
 130   | RUNNING |  | ABORTING |  |
 131    ---------    ----------   |
 132        |              |      |
 133   no process          |      |
 134        |              |      |
 135        V              |      |
 136    ----------         |      |
 137   | STOPPING |<-------       |
 138    ----------                |
 139        |                     |
 140         ---------------------
 141
 142 3.2 Configuration file
 143 ----------------------
 144
 145 The configuration file has the following format:
 146
 147 --------------------------------------------------------------------------------
 148
 149 # the fstab mount file.
 150 lxc.mount = ./fstab
 151
 152 # the hostname to be set into the container
 153 lxc.utsname = virtnode
 154
 155 # the chroot if needed for the running application
 156 lxc.chroot = /mnt/root
 157
 158 # The network has several of kind of configuration:
 159 #
 160 #  * veth : the network will use the veth virtual device, the
 161 #              specified link must be a bridge
 162 #  * macvlan : the network will use the macvlan device, the specified
 163 #              link should be an existing interface, usually it is
 164 #              eth0
 165 #  * phys : the network will use a physical network device, the
 166 #              specified link should be an existing interface
 167 lxc.network.type = macvlan
 168
 169 # specify the flags to be used for the network, actually only <up> is
 170 # allowed which mean the network should be set up when created. If the
 171 # network is set up, the loopback is automatically set up too.
 172 lxc.network.flags = up
 173
 174 # specify the physical network device which will communicate with the
 175 # outside world
 176 lxc.network.link = eth0
 177
 178 # NIC ethernet mac address
 179 lxc.network.hwaddr = 4a:49:43:49:79:bd
 180
 181 # specify the ipv4 address of the container. Several lines are allowed
 182 # and will mean several addresses will be assigned to the interface
 183 lxc.network.ipv4 = 1.2.3.5/24
 184
 185 # specify the ipv6 address of the container. Several lines are allowed
 186 # and will mean several addresses will be assigned to the interface
 187 lxc.network.ipv6 = 2003:db8:1:0:214:1234:fe0b:3596
 188
 189 --------------------------------------------------------------------------------
 190
 191  * lxc.mount is optional
 192  * lxc.utsname is optional
 193  * lxc.network.xxx are optional, if not specified, the network
 194  namespace will not be created
 195  * lxc.chroot is optional
 196
 197 3.3 Container creation
 198 ----------------------
 199
 200 The container is created via the 'lxc-create' command.  The command
 201 specifies the container name and the container configuration file.
 202
 203       lxc-create -n foo -f <config>
 204
 205
 206 3.4 Starting a container
 207 ------------------------
 208
 209 As the container has been created with the lxc-create command, it is
 210 possible now to start an application inside.
 211
 212       lxc-execute -n foo /bin/bash
 213
 214 When the application has exited, it is possible to continue using the
 215 container configuration to launch another application.
 216
 217 3.5 Stopping a container
 218 ------------------------
 219
 220 Usually, a container stops when the last process exits but in some
 221 cases, it is usefully to wipe out such application. The following
 222 command will kill the processes.
 223
 224       lxc-stop -n foo
 225
 226 3.6 Freezing/Unfreezing a container
 227 -----------------------------------
 228
 229 All the processes belonging to a container can be stopped and resumed.
 230
 231       lxc-freeze -n foo
 232
 233       lxc-unfreeze -n foo
 234
 235 3.7 Sending a signal to a container
 236 -----------------------------------
 237
 238 A signal can be sent to all processes running inside the container.
 239
 240       lxc-kill -n foo -s <signal>
 241
 242 3.8 Monitoring container states
 243 -------------------------------
 244
 245 A container has a life cycle and passes though different states as
 246 defined in section 3.1. The following command allows to watch such
 247 states for a specific container.
 248
 249      lxc-monitor -n foo
 250
 251 3.9 Getting container information
 252 ----------------------------------
 253
 254 At any time, the following command will retrieve informations of the
 255  container.
 256
 257      lxc-info -n foo
 258
 259 3.10 Showing processes list for a container
 260 ------------------------------------------
 261
 262 The following command will show all the processes for all the running
 263 container.
 264
 265      lxc-ps
 266
 267 4) Future work
 268 --------------
 269
 270  * change the lxc-start command to support system container
 271  * change the lxc-execute to have the first process to exec
 272  * take into account all the resource management
 273  * man pages
 274  * improve monitoring support
 275  * and more :)