docs/drvlxc.html.in

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4   <body>
   5     <h1>LXC container driver</h1>
   6
   7     <ul id="toc"></ul>
   8
   9 <p>
  10 The libvirt LXC driver manages "Linux Containers". At their simplest, containers
  11 can just be thought of as a collection of processes, separated from the main
  12 host processes via a set of resource namespaces and constrained via control
  13 groups resource tunables. The libvirt LXC driver has no dependency on the LXC
  14 userspace tools hosted on sourceforge.net. It directly utilizes the relevant
  15 kernel features to build the container environment. This allows for sharing
  16 of many libvirt technologies across both the QEMU/KVM and LXC drivers. In
  17 particular sVirt for mandatory access control, auditing of operations,
  18 integration with control groups and many other features.
  19 </p>
  20
  21 <h2><a name="cgroups">Control groups Requirements</a></h2>
  22
  23 <p>
  24 In order to control the resource usage of processes inside containers, the
  25 libvirt LXC driver requires that certain cgroups controllers are mounted on
  26 the host OS. The minimum required controllers are 'cpuacct', 'memory' and
  27 'devices', while recommended extra controllers are 'cpu', 'freezer' and
  28 'blkio'. Libvirt will not mount the cgroups filesystem itself, leaving
  29 this up to the init system to take care of. Systemd will do the right thing
  30 in this respect, while for other init systems the <code>cgconfig</code>
  31 init service will be required. For further information, consult the general
  32 libvirt <a href="cgroups.html">cgroups documentation</a>.
  33 </p>
  34
  35 <h2><a name="namespaces">Namespace requirements</a></h2>
  36
  37 <p>
  38 In order to separate processes inside a container from those in the
  39 primary "host" OS environment, the libvirt LXC driver requires that
  40 certain kernel namespaces are compiled in. Libvirt currently requires
  41 the 'mount', 'ipc', 'pid', and 'uts' namespaces to be available. If
  42 separate network interfaces are desired, then the 'net' namespace is
  43 required. If the guest configuration declares a
  44 <a href="formatdomain.html#elementsOSContainer">UID or GID mapping</a>,
  45 the 'user' namespace will be enabled to apply these. <strong>A suitably
  46 configured UID/GID mapping is a pre-requisite to making containers
  47 secure, in the absence of sVirt confinement.</strong>
  48 </p>
  49
  50 <h2><a name="init">Default container setup</a></h2>
  51
  52 <h3><a name="cliargs">Command line arguments</a></h3>
  53
  54 <p>
  55 When the container "init" process is started, it will typically
  56 not be given any command line arguments (eg the equivalent of
  57 the bootloader args visible in <code>/proc/cmdline</code>). If
  58 any arguments are desired, then must be explicitly set in the
  59 container XML configuration via one or more <code>initarg</code>
  60 elements. For example, to run <code>systemd --unit emergency.service</code>
  61 would use the following XML
  62 </p>
  63
  64 <pre>
  65   &lt;os&gt;
  66     &lt;type arch='x86_64'&gt;exe&lt;/type&gt;
  67     &lt;init&gt;/bin/systemd&lt;/init&gt;
  68     &lt;initarg&gt;--unit&lt;/initarg&gt;
  69     &lt;initarg&gt;emergency.service&lt;/initarg&gt;
  70   &lt;/os&gt;
  71 </pre>
  72
  73 <h3><a name="envvars">Environment variables</a></h3>
  74
  75 <p>
  76 When the container "init" process is started, it will be given several useful
  77 environment variables. The following standard environment variables are mandated
  78 by <a href="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">systemd container interface</a>
  79 to be provided by all container technologies on Linux.
  80 </p>
  81
  82 <dl>
  83 <dt>container</dt>
  84 <dd>The fixed string <code>libvirt-lxc</code> to identify libvirt as the creator</dd>
  85 <dt>container_uuid</dt>
  86 <dd>The UUID assigned to the container by libvirt</dd>
  87 <dt>PATH</dt>
  88 <dd>The fixed string <code>/bin:/usr/bin</code></dd>
  89 <dt>TERM</dt>
  90 <dd>The fixed string <code>linux</code></dd>
  91 </dl>
  92
  93 <p>
  94 In addition to the standard variables, the following libvirt specific
  95 environment variables are also provided
  96 </p>
  97
  98 <dl>
  99 <dt>LIBVIRT_LXC_NAME</dt>
 100 <dd>The name assigned to the container by libvirt</dd>
 101 <dt>LIBVIRT_LXC_UUID</dt>
 102 <dd>The UUID assigned to the container by libvirt</dd>
 103 <dt>LIBVIRT_LXC_CMDLINE</dt>
 104 <dd>The unparsed command line arguments specified in the container configuration.
 105 Use of this is discouraged, in favour of passing arguments directly to the
 106 container init process via the <code>initarg</code> config element.</dd>
 107 </dl>
 108
 109 <h3><a name="fsmounts">Filesystem mounts</a></h3>
 110
 111 <p>
 112 In the absence of any explicit configuration, the container will
 113 inherit the host OS filesystem mounts. A number of mount points will
 114 be made read only, or re-mounted with new instances to provide
 115 container specific data. The following special mounts are setup
 116 by libvirt
 117 </p>
 118
 119 <ul>
 120 <li><code>/dev</code> a new "tmpfs" pre-populated with authorized device nodes</li>
 121 <li><code>/dev/pts</code> a new private "devpts" instance for console devices</li>
 122 <li><code>/sys</code> the host "sysfs" instance remounted read-only</li>
 123 <li><code>/proc</code> a new instance of the "proc" filesystem</li>
 124 <li><code>/proc/sys</code> the host "/proc/sys" bind-mounted read-only</li>
 125 <li><code>/sys/fs/selinux</code> the host "selinux" instance remounted read-only</li>
 126 <li><code>/sys/fs/cgroup/NNNN</code> the host cgroups controllers bind-mounted to
 127 only expose the sub-tree associated with the container</li>
 128 <li><code>/proc/meminfo</code> a FUSE backed file reflecting memory limits of the container</li>
 129 </ul>
 130
 131
 132 <h3><a name="devnodes">Device nodes</a></h3>
 133
 134 <p>
 135 The container init process will be started with <code>CAP_MKNOD</code>
 136 capability removed and blocked from re-acquiring it. As such it will
 137 not be able to create any device nodes in <code>/dev</code> or anywhere
 138 else in its filesystems. Libvirt itself will take care of pre-populating
 139 the <code>/dev</code> filesystem with any devices that the container
 140 is authorized to use. The current devices that will be made available
 141 to all containers are
 142 </p>
 143
 144 <ul>
 145 <li><code>/dev/zero</code></li>
 146 <li><code>/dev/null</code></li>
 147 <li><code>/dev/full</code></li>
 148 <li><code>/dev/random</code></li>
 149 <li><code>/dev/urandom</code></li>
 150 <li><code>/dev/stdin</code> symlinked to <code>/proc/self/fd/0</code></li>
 151 <li><code>/dev/stdout</code> symlinked to <code>/proc/self/fd/1</code></li>
 152 <li><code>/dev/stderr</code> symlinked to <code>/proc/self/fd/2</code></li>
 153 <li><code>/dev/fd</code> symlinked to <code>/proc/self/fd</code></li>
 154 <li><code>/dev/ptmx</code> symlinked to <code>/dev/pts/ptmx</code></li>
 155 <li><code>/dev/console</code> symlinked to <code>/dev/pts/0</code></li>
 156 </ul>
 157
 158 <p>
 159 In addition, for every console defined in the guest configuration,
 160 a symlink will be created from <code>/dev/ttyN</code> symlinked to
 161 the corresponding <code>/dev/pts/M</code> pseudo TTY device. The
 162 first console will be <code>/dev/tty1</code>, with further consoles
 163 numbered incrementally from there.
 164 </p>
 165
 166 <p>
 167 Since /dev/ttyN and /dev/console are linked to the pts devices. The
 168 tty device of login program is pts device. the pam module securetty
 169 may prevent root user from logging in container. If you want root
 170 user to log in container successfully, add the pts device to the file
 171 /etc/securetty of container.
 172 </p>
 173
 174 <p>
 175 Further block or character devices will be made available to containers
 176 depending on their configuration.
 177 </p>
 178
 179 <h2><a name="security">Security considerations</a></h2>
 180
 181 <p>
 182 The libvirt LXC driver is fairly flexible in how it can be configured,
 183 and as such does not enforce a requirement for strict security
 184 separation between a container and the host. This allows it to be used
 185 in scenarios where only resource control capabilities are important,
 186 and resource sharing is desired. Applications wishing to ensure secure
 187 isolation between a container and the host must ensure that they are
 188 writing a suitable configuration.
 189 </p>
 190
 191 <h3><a name="securenetworking">Network isolation</a></h3>
 192
 193 <p>
 194 If the guest configuration does not list any network interfaces,
 195 the <code>network</code> namespace will not be activated, and thus
 196 the container will see all the host's network interfaces. This will
 197 allow apps in the container to bind to/connect from TCP/UDP addresses
 198 and ports from the host OS. It also allows applications to access
 199 UNIX domain sockets associated with the host OS, which are in the
 200 abstract namespace. If access to UNIX domains sockets in the abstract
 201 namespace is not wanted, then applications should set the
 202 <code>&lt;privnet/&gt;</code> flag in the
 203 <code>&lt;features&gt;....&lt;/features&gt;</code> element.
 204 </p>
 205
 206 <h3><a name="securefs">Filesystem isolation</a></h3>
 207
 208 <p>
 209 If the guest configuration does not list any filesystems, then
 210 the container will be set up with a root filesystem that matches
 211 the host's root filesystem. As noted earlier, only a few locations
 212 such as <code>/dev</code>, <code>/proc</code> and <code>/sys</code>
 213 will be altered. This means that, in the absence of restrictions
 214 from sVirt, a process running as user/group N:M inside the container
 215 will be able to access almost exactly the same files as a process
 216 running as user/group N:M in the host.
 217 </p>
 218
 219 <p>
 220 There are multiple options for restricting this. It is possible to
 221 simply map the existing root filesystem through to the container in
 222 read-only mode. Alternatively a completely separate root filesystem
 223 can be configured for the guest. In both cases, further sub-mounts
 224 can be applied to customize the content that is made visible. Note
 225 that in the absence of sVirt controls, it is still possible for the
 226 root user in a container to unmount any sub-mounts applied. The user
 227 namespace feature can also be used to restrict access to files based
 228 on the UID/GID mappings.
 229 </p>
 230
 231 <p>
 232 Sharing the host filesystem tree, also allows applications to access
 233 UNIX domains sockets associated with the host OS, which are in the
 234 filesystem namespaces. It should be noted that a number of init
 235 systems including at least <code>systemd</code> and <code>upstart</code>
 236 have UNIX domain socket which are used to control their operation.
 237 Thus, if the directory/filesystem holding their UNIX domain socket is
 238 exposed to the container, it will be possible for a user in the container
 239 to invoke operations on the init service in the same way it could if
 240 outside the container. This also applies to other applications in the
 241 host which use UNIX domain sockets in the filesystem, such as DBus,
 242 Libvirtd, and many more. If this is not desired, then applications
 243 should either specify the UID/GID mapping in the configuration to
 244 enable user namespaces and thus block access to the UNIX domain socket
 245 based on permissions, or should ensure the relevant directories have
 246 a bind mount to hide them. This is particularly important for the
 247 <code>/run</code> or <code>/var/run</code> directories.
 248 </p>
 249
 250
 251 <h3><a name="secureusers">User and group isolation</a></h3>
 252
 253 <p>
 254 If the guest configuration does not list any ID mapping, then the
 255 user and group IDs used inside the container will match those used
 256 outside the container. In addition, the capabilities associated with
 257 a process in the container will infer the same privileges they would
 258 for a process in the host. This has obvious implications for security,
 259 since a root user inside the container will be able to access any
 260 file owned by root that is visible to the container, and perform more
 261 or less any privileged kernel operation. In the absence of additional
 262 protection from sVirt, this means that the root user inside a container
 263 is effectively as powerful as the root user in the host. There is no
 264 security isolation of the root user.
 265 </p>
 266
 267 <p>
 268 The ID mapping facility was introduced to allow for stricter control
 269 over the privileges of users inside the container. It allows apps to
 270 define rules such as "user ID 0 in the container maps to user ID 1000
 271 in the host". In addition the privileges associated with capabilities
 272 are somewhat reduced so that they cannot be used to escape from the
 273 container environment. A full description of user namespaces is outside
 274 the scope of this document, however LWN has
 275 <a href="https://lwn.net/Articles/532593/">a good write-up on the topic</a>.
 276 From the libvirt point of view, the key thing to remember is that defining
 277 an ID mapping for users and groups in the container XML configuration
 278 causes libvirt to activate the user namespace feature.
 279 </p>
 280
 281
 282 <h2><a name="activation">Systemd Socket Activation Integration</a></h2>
 283
 284 <p>
 285 The libvirt LXC driver provides the ability to pass across pre-opened file
 286 descriptors when starting LXC guests. This allows for libvirt LXC to support
 287 systemd's <a href="http://0pointer.de/blog/projects/socket-activated-containers.html">socket
 288 activation capability</a>, where an incoming client connection
 289 in the host OS will trigger the startup of a container, which runs another
 290 copy of systemd which gets passed the server socket, and then activates the
 291 actual service handler in the container.
 292 </p>
 293
 294 <p>
 295 Let us assume that you already have a LXC guest created, running
 296 a systemd instance as PID 1 inside the container, which has an
 297 SSHD service configured. The goal is to automatically activate
 298 the container when the first SSH connection is made. The first
 299 step is to create a couple of unit files for the host OS systemd
 300 instance. The <code>/etc/systemd/system/mycontainer.service</code>
 301 unit file specifies how systemd will start the libvirt LXC container
 302 </p>
 303
 304 <pre>
 305 [Unit]
 306 Description=My little container
 307
 308 [Service]
 309 ExecStart=/usr/bin/virsh -c lxc:/// start --pass-fds 3 mycontainer
 310 ExecStop=/usr/bin/virsh -c lxc:/// destroy mycontainer
 311 Type=oneshot
 312 RemainAfterExit=yes
 313 KillMode=none
 314 </pre>
 315
 316 <p>
 317 The <code>--pass-fds 3</code> argument specifies that the file
 318 descriptor number 3 that <code>virsh</code> inherits from systemd,
 319 is to be passed into the container. Since <code>virsh</code> will
 320 exit immediately after starting the container, the <code>RemainAfterExit</code>
 321 and <code>KillMode</code> settings must be altered from their defaults.
 322 </p>
 323
 324 <p>
 325 Next, the <code>/etc/systemd/system/mycontainer.socket</code> unit
 326 file is created to get the host systemd to listen on port 23 for
 327 TCP connections. When this unit file is activated by the first
 328 incoming connection, it will cause the <code>mycontainer.service</code>
 329 unit to be activated with the FD corresponding to the listening TCP
 330 socket passed in as FD 3.
 331 </p>
 332
 333 <pre>
 334 [Unit]
 335 Description=The SSH socket of my little container
 336
 337 [Socket]
 338 ListenStream=23
 339 </pre>
 340
 341 <p>
 342 Port 23 was picked here so that the container doesn't conflict
 343 with the host's SSH which is on the normal port 22. That's it
 344 in terms of host side configuration.
 345 </p>
 346
 347 <p>
 348 Inside the container, the <code>/etc/systemd/system/sshd.socket</code>
 349 unit file must be created
 350 </p>
 351
 352 <pre>
 353 [Unit]
 354 Description=SSH Socket for Per-Connection Servers
 355
 356 [Socket]
 357 ListenStream=23
 358 Accept=yes
 359 </pre>
 360
 361 <p>
 362 The <code>ListenStream</code> value listed in this unit file, must
 363 match the value used in the host file. When systemd in the container
 364 receives the pre-opened FD from libvirt during container startup, it
 365 looks at the <code>ListenStream</code> values to figure out which
 366 FD to give to which service. The actual service to start is defined
 367 by a correspondingly named <code>/etc/systemd/system/sshd@.service</code>
 368 </p>
 369
 370 <pre>
 371 [Unit]
 372 Description=SSH Per-Connection Server for %I
 373
 374 [Service]
 375 ExecStart=-/usr/sbin/sshd -i
 376 StandardInput=socket
 377 </pre>
 378
 379 <p>
 380 Finally, make sure this SSH service is set to start on boot of the container,
 381 by running the following command inside the container:
 382 </p>
 383
 384 <pre>
 385 # mkdir -p /etc/systemd/system/sockets.target.wants/
 386 # ln -s /etc/systemd/system/sshd.socket /etc/systemd/system/sockets.target.wants/
 387 </pre>
 388
 389 <p>
 390 This example shows how to activate the container based on an incoming
 391 SSH connection. If the container was also configured to have an httpd
 392 service, it may be desirable to activate it upon either an httpd or a
 393 sshd connection attempt. In this case, the <code>mycontainer.socket</code>
 394 file in the host would simply list multiple socket ports. Inside the
 395 container a separate <code>xxxxx.socket</code> file would need to be
 396 created for each service, with a corresponding <code>ListenStream</code>
 397 value set.
 398 </p>
 399
 400 <!--
 401 <h2>Container configuration</h2>
 402
 403 <h3>Init process</h3>
 404
 405 <h3>Console devices</h3>
 406
 407 <h3>Filesystem devices</h3>
 408
 409 <h3>Disk devices</h3>
 410
 411 <h3>Block devices</h3>
 412
 413 <h3>USB devices</h3>
 414
 415 <h3>Character devices</h3>
 416
 417 <h3>Network devices</h3>
 418 -->
 419
 420 <h2>Container security</h2>
 421
 422 <h3>sVirt SELinux</h3>
 423
 424 <p>
 425 In the absence of the "user" namespace being used, containers cannot
 426 be considered secure against exploits of the host OS. The sVirt SELinux
 427 driver provides a way to secure containers even when the "user" namespace
 428 is not used. The cost is that writing a policy to allow execution of
 429 arbitrary OS is not practical. The SELinux sVirt policy is typically
 430 tailored to work with an simpler application confinement use case,
 431 as provided by the "libvirt-sandbox" project.
 432 </p>
 433
 434 <h3>Auditing</h3>
 435
 436 <p>
 437 The LXC driver is integrated with libvirt's auditing subsystem, which
 438 causes audit messages to be logged whenever there is an operation
 439 performed against a container which has impact on host resources.
 440 So for example, start/stop, device hotplug will all log audit messages
 441 providing details about what action occurred and any resources
 442 associated with it. There are the following 3 types of audit messages
 443 </p>
 444
 445 <ul>
 446 <li><code>VIRT_MACHINE_ID</code> - details of the SELinux process and
 447 image security labels assigned to the container.</li>
 448 <li><code>VIRT_CONTROL</code> - details of an action / operation
 449 performed against a container. There are the following types of
 450 operation
 451   <ul>
 452     <li><code>op=start</code> - a container has been started. Provides
 453       the machine name, uuid and PID of the <code>libvirt_lxc</code>
 454       controller process</li>
 455     <li><code>op=init</code> - the init PID of the container has been
 456       started. Provides the machine name, uuid and PID of the
 457       <code>libvirt_lxc</code> controller process and PID of the
 458       init process (in the host PID namespace)</li>
 459     <li><code>op=stop</code> - a container has been stopped. Provides
 460       the machine name, uuid</li>
 461   </ul>
 462 </li>
 463 <li><code>VIRT_RESOURCE</code> - details of a host resource
 464 associated with a container action.</li>
 465 </ul>
 466
 467 <h3>Device access</h3>
 468
 469 <p>
 470 All containers are launched with the CAP_MKNOD capability cleared
 471 and removed from the bounding set. Libvirt will ensure that the
 472 /dev filesystem is pre-populated with all devices that a container
 473 is allowed to use. In addition, the cgroup "device" controller is
 474 configured to block read/write/mknod from all devices except those
 475 that a container is authorized to use.
 476 </p>
 477
 478 <h2><a name="exconfig">Example configurations</a></h2>
 479
 480 <h3>Example config version 1</h3>
 481 <p></p>
 482 <pre>
 483 &lt;domain type='lxc'&gt;
 484   &lt;name&gt;vm1&lt;/name&gt;
 485   &lt;memory&gt;500000&lt;/memory&gt;
 486   &lt;os&gt;
 487     &lt;type&gt;exe&lt;/type&gt;
 488     &lt;init&gt;/bin/sh&lt;/init&gt;
 489   &lt;/os&gt;
 490   &lt;vcpu&gt;1&lt;/vcpu&gt;
 491   &lt;clock offset='utc'/&gt;
 492   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 493   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 494   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 495   &lt;devices&gt;
 496     &lt;emulator&gt;/usr/libexec/libvirt_lxc&lt;/emulator&gt;
 497     &lt;interface type='network'&gt;
 498       &lt;source network='default'/&gt;
 499     &lt;/interface&gt;
 500     &lt;console type='pty' /&gt;
 501   &lt;/devices&gt;
 502 &lt;/domain&gt;
 503 </pre>
 504
 505 <p>
 506 In the &lt;emulator&gt; element, be sure you specify the correct path
 507 to libvirt_lxc, if it does not live in /usr/libexec on your system.
 508 </p>
 509
 510 <p>
 511 The next example assumes there is a private root filesystem
 512 (perhaps hand-crafted using busybox, or installed from media,
 513 debootstrap, whatever) under /opt/vm-1-root:
 514 </p>
 515 <p></p>
 516 <pre>
 517 &lt;domain type='lxc'&gt;
 518   &lt;name&gt;vm1&lt;/name&gt;
 519   &lt;memory&gt;32768&lt;/memory&gt;
 520   &lt;os&gt;
 521     &lt;type&gt;exe&lt;/type&gt;
 522     &lt;init&gt;/init&lt;/init&gt;
 523   &lt;/os&gt;
 524   &lt;vcpu&gt;1&lt;/vcpu&gt;
 525   &lt;clock offset='utc'/&gt;
 526   &lt;on_poweroff&gt;destroy&lt;/on_poweroff&gt;
 527   &lt;on_reboot&gt;restart&lt;/on_reboot&gt;
 528   &lt;on_crash&gt;destroy&lt;/on_crash&gt;
 529   &lt;devices&gt;
 530     &lt;emulator&gt;/usr/libexec/libvirt_lxc&lt;/emulator&gt;
 531     &lt;filesystem type='mount'&gt;
 532       &lt;source dir='/opt/vm-1-root'/&gt;
 533       &lt;target dir='/'/&gt;
 534     &lt;/filesystem&gt;
 535     &lt;interface type='network'&gt;
 536       &lt;source network='default'/&gt;
 537     &lt;/interface&gt;
 538     &lt;console type='pty' /&gt;
 539   &lt;/devices&gt;
 540 &lt;/domain&gt;
 541 </pre>
 542
 543
 544 <h2><a name="usage">Container usage / management</a></h2>
 545
 546 <p>
 547 As with any libvirt virtualization driver, LXC containers can be
 548 managed via a wide variety of libvirt based tools. At the lowest
 549 level the <code>virsh</code> command can be used to perform many
 550 tasks, by passing the <code>-c lxc:///</code> argument. As an
 551 alternative to repeating the URI with every command, the <code>LIBVIRT_DEFAULT_URI</code>
 552 environment variable can be set to <code>lxc:///</code>. The
 553 examples that follow outline some common operations with virsh
 554 and LXC. For further details about usage of virsh consult its
 555 manual page.
 556 </p>
 557
 558 <h3><a name="usageSave">Defining (saving) container configuration</a></h3>
 559
 560 <p>
 561 The <code>virsh define</code> command takes an XML configuration
 562 document and loads it into libvirt, saving the configuration on disk
 563 </p>
 564
 565 <pre>
 566 # virsh -c lxc:/// define myguest.xml
 567 </pre>
 568
 569 <h3><a name="usageView">Viewing container configuration</a></h3>
 570
 571 <p>
 572 The <code>virsh dumpxml</code> command can be used to view the
 573 current XML configuration of a container. By default the XML
 574 output reflects the current state of the container. If the
 575 container is running, it is possible to explicitly request the
 576 persistent configuration, instead of the current live configuration
 577 using the <code>--inactive</code> flag
 578 </p>
 579
 580 <pre>
 581 # virsh -c lxc:/// dumpxml myguest
 582 </pre>
 583
 584 <h3><a name="usageStart">Starting containers</a></h3>
 585
 586 <p>
 587 The <code>virsh start</code> command can be used to start a
 588 container from a previously defined persistent configuration
 589 </p>
 590
 591 <pre>
 592 # virsh -c lxc:/// start myguest
 593 </pre>
 594
 595 <p>
 596 It is also possible to start so called "transient" containers,
 597 which do not require a persistent configuration to be saved
 598 by libvirt, using the <code>virsh create</code> command.
 599 </p>
 600
 601 <pre>
 602 # virsh -c lxc:/// create myguest.xml
 603 </pre>
 604
 605
 606 <h3><a name="usageStop">Stopping containers</a></h3>
 607
 608 <p>
 609 The <code>virsh shutdown</code> command can be used
 610 to request a graceful shutdown of the container. By default
 611 this command will first attempt to send a message to the
 612 init process via the <code>/dev/initctl</code> device node.
 613 If no such device node exists, then it will send SIGTERM
 614 to PID 1 inside the container.
 615 </p>
 616
 617 <pre>
 618 # virsh -c lxc:/// shutdown myguest
 619 </pre>
 620
 621 <p>
 622 If the container does not respond to the graceful shutdown
 623 request, it can be forcibly stopped using the <code>virsh destroy</code>
 624 </p>
 625
 626 <pre>
 627 # virsh -c lxc:/// destroy myguest
 628 </pre>
 629
 630
 631 <h3><a name="usageReboot">Rebooting a container</a></h3>
 632
 633 <p>
 634 The <code>virsh reboot</code> command can be used
 635 to request a graceful shutdown of the container. By default
 636 this command will first attempt to send a message to the
 637 init process via the <code>/dev/initctl</code> device node.
 638 If no such device node exists, then it will send SIGHUP
 639 to PID 1 inside the container.
 640 </p>
 641
 642 <pre>
 643 # virsh -c lxc:/// reboot myguest
 644 </pre>
 645
 646 <h3><a name="usageDelete">Undefining (deleting) a container configuration</a></h3>
 647
 648 <p>
 649 The <code>virsh undefine</code> command can be used to delete the
 650 persistent configuration of a container. If the guest is currently
 651 running, this will turn it into a "transient" guest.
 652 </p>
 653
 654 <pre>
 655 # virsh -c lxc:/// undefine myguest
 656 </pre>
 657
 658 <h3><a name="usageConnect">Connecting to a container console</a></h3>
 659
 660 <p>
 661 The <code>virsh console</code> command can be used to connect
 662 to the text console associated with a container.
 663 </p>
 664
 665 <pre>
 666 # virsh -c lxc:/// console myguest
 667 </pre>
 668
 669 <p>
 670 If the container has been configured with multiple console devices,
 671 then the <code>--devname</code> argument can be used to choose the
 672 console to connect to.
 673 In LXC, multiple consoles will be named
 674 as 'console0', 'console1', 'console2', etc.
 675 </p>
 676
 677 <pre>
 678 # virsh -c lxc:/// console myguest --devname console1
 679 </pre>
 680
 681 <h3><a name="usageEnter">Running commands in a container</a></h3>
 682
 683 <p>
 684 The <code>virsh lxc-enter-namespace</code> command can be used
 685 to enter the namespaces and security context of a container
 686 and then execute an arbitrary command.
 687 </p>
 688
 689 <pre>
 690 # virsh -c lxc:/// lxc-enter-namespace myguest -- /bin/ls -al /dev
 691 </pre>
 692
 693 <h3><a name="usageTop">Monitoring container utilization</a></h3>
 694
 695 <p>
 696 The <code>virt-top</code> command can be used to monitor the
 697 activity and resource utilization of all containers on a
 698 host
 699 </p>
 700
 701 <pre>
 702 # virt-top -c lxc:///
 703 </pre>
 704
 705 <h3><a name="usageConvert">Converting LXC container configuration</a></h3>
 706
 707 <p>
 708 The <code>virsh domxml-from-native</code> command can be used to convert
 709 most of the LXC container configuration into a domain XML fragment
 710 </p>
 711
 712 <pre>
 713 # virsh -c lxc:/// domxml-from-native lxc-tools /var/lib/lxc/myguest/config
 714 </pre>
 715
 716 <p>
 717 This conversion has some limitations due to the fact that the
 718 domxml-from-native command output has to be independent of the host. Here
 719 are a few things to take care of before converting:
 720 </p>
 721
 722 <ul>
 723 <li>
 724 Replace the fstab file referenced by <tt>lxc.mount</tt> by the corresponding
 725 lxc.mount.entry lines.
 726 </li>
 727 <li>
 728 Replace all relative sizes of tmpfs mount entries to absolute sizes. Also
 729 make sure that tmpfs entries all have a size option (default is 50%).
 730 </li>
 731 <li>
 732 Define <tt>lxc.cgroup.memory.limit_in_bytes</tt> to properly limit the memory
 733 available to the container. The conversion will use 64MiB as the default.
 734 </li>
 735 </ul>
 736
 737   </body>
 738 </html>