Linux Containers (lxc) Hacky Userspace Tools
============================================

This is a collection of utility scripts I've written to make using lxc a bit
more bearable in Debian. For more information, see the article at:

http://nigel.mcnie.name/blog/a-five-minute-guide-to-linux-containers-for-debian

All of these scripts are released under the terms of the GNU GPL, version 3 or
later.

lxc-debian
----------

`lxc-debian' is a script to create and destroy debian based linux containers.
This particular version is based on the one that ships with the lxc package in
debian unstable (/usr/share/doc/lxc/examples/lxc-debian.gz), but with a few
modifications to make it a little easier to use.

To create a container, run

    lxc-debian create -n NAME -i IP [-r ROOTDIR]

To destroy a container, run

    lxc-debian destroy -n NAME -i IP [-r ROOTDIR]

If you want to script some operations for when a container is created, I have
added some hooks:

    /etc/lxc-debian/host-pre-create

        Shell script that runs on the host before the container is created. It
        is sourced by lxc-debian, so has access to variables like $NAME, which
        is the name of the container being created.

    /etc/lxc-debian/host-post-create

        Shell script that runs on the host after the container is created. It
        is sourced by lxc-debian, so has access to variables like $NAME, which
        is the name of the container being created.

    /etc/lxc-debian/guest-post-create

        Script that runs in the container after creation. It's run by chrooting
        in, so naturally it doesn't have access to variables, though you can
        get at that information through other ways (e.g. /etc/hostname).

init
----

`init' is an init.d script you can install as /etc/init.d/lxc, that allows you
to automatically start up and shut down containers on system start up/shut
down.

You can mark a container to be started on startup by doing this:

echo 1 > /var/lib/lxc/$CONTAINER/autostart

All containers will be stopped on shutdown, regardless of the autostart file.

Note that this script will endeavour to use lxc-halt if it's in /usr/bin, see
the docs for lxc-halt below for more information.

lxc-status
----------

Runs lxc-info on all the containers and exits, leading to output like this:

nigel@bubbles:~$ sudo bin/lxc-status
'test' is STOPPED
'debian-lenny' is STOPPED
'ponies' is RUNNING

lxc-halt
--------

Will stop a linux container SAFELY. ``lxc-stop`` brutally murders the container
and all processes in it, which isn't good especially if you have daemons inside
them. lxc-halt will run 'halt' in the container, then lxc-stop once all the
processes are gone (or after a configurable timeout if it's taking too long).

There's one trick - there's no easy way to run the halt command in the
container, because the lxc developers haven't provided a nice way to run a
single command in a running container yet. So you have to provide such a
command.

If you install the `default' file into /etc/default/lxc, you can edit that to
change the command to halt a container.  The default is ``ssh [container]
halt``, which of course will only work if your container is resolvable at that
hostname.

If you install lxc-halt in /usr/bin, then the init.d script will use it when
you issue /etc/init.d/lxc stop. It will try stopping all the containers in
parallel, but if you have a few containers it might take a while for all of
them to stop.