lxc-network/README.md

# lxc-network

A network of LXC containers, managed through libvirt

## Dependencies

This script will most probably break on any other system than Linux, and will
definitely break on anything non-UNIX.

It relies on `libvirt`, `overlayfs` and `sudo` (to gain the required privileges
to use overlayfs).

## Setup

It is recommended to set up `lxc-network` within a *virtualenv*:

```bash
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt
```

Furthermore, you are expected to set up a system root tree within the directory
of your choice, and put its path in `lxc_net/settings.py`. This can be done eg.
in ArchLinux with

```bash
pacstrap [your_root_directory] base
```

or the equivalent `debootstrap` command on Debian.

This system is expected to use `systemd`, and to have enabled
`systemd-networkd` to setup its IP addresses.

## Usage

You can spawn a network using

```bash
./spawn_network.py topology_description.yml
```

where `topology_description.yml` is a valid topology description file (see
below).

When the network is spawned, you will get a (very basic) prompt. The available
commands are:

* `help`: display a list of available commands;
* `exit`: cleanup the network and quit the program;
* `dom`:
  * `dom down`: keep the networks up, but cleanup the containers. Useful to
    reset the containers or update binaries and settings.
  * `dom up`: spawn the containers, if they were cleaned up beforehand.
  * `dom restart`: equivalent to `dom down ; dom up`.

## Topology description file

A topology is described in a [YAML](https://en.wikipedia.org/wiki/YAML) file
looking like this:

```yaml
---
links:
  - domains: ['a', 'b']
    enable_v4: false
  - domains: ['b', 'c']
domains:
  b:
    enable_v4: false
    root_path: /path/to/root
```

The `links` element is mandatory, each link containing a mandatory `domains`
attribute, the list of domains (containers) connected to it. A domain is
described by an arbitrary name. Domains will be spawned (and indexed) in
alphabetical order.

The valid options for links are:
* `enable_v4`: boolean, specifies whether the NICs connected to this link have
  an IPv4 address.

A `domains` root element is optional, and may be used to specify
domain-specific options.

The valid options for domains are:
* `enable_v4`: boolean, specifies whether the domain has IPv4 addresses on its
  NICs.
* `root_path`: an optional path to a directory containing the root to use for
  this domain