From 7cae5e1f2233687ce47d65a23df7a36a6a4ca584 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Th=C3=A9ophile=20Bastian?= <contact@tobast.fr>
Date: Thu, 12 Mar 2020 11:52:07 +0100
Subject: [PATCH] Add better README

---
 README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 24a2cea..27c7632 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,70 @@
 # lxc-network
 
-A network of LXC containers, managed through libvirt
\ No newline at end of file
+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` and `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).
+
+## 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']
+  - domains: ['b', 'c']
+domains:
+  b:
+    enable_v4: false
+```
+
+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.
+
+A `domains` root element is optional, and may be used to specify
+domain-specific options.
+
+The valid options are:
+* `enable_v4`: boolean, specifies whether the domain has an IPv4 address.