README: document howto run in unprivileged user namespace

diff --git a/README.adoc b/README.adoc
index b5afc372ae5e1208dc38e043788a383bff19f66f..3c258fa0d73a5f104537121f08cab9a8759827fd 100644 (file)
--- a/README.adoc
+++ b/README.adoc
@@ -18,6 +18,7 @@ node. It is licensed under GPLv3+.
 
 - Linux compiled with `CONFIG_NET_NS` (available on most modern systems)
 - iproute2 (`ip`)
+- root (or unprivileged user namespaces, see below)
 
 
 == Build
@@ -105,6 +106,34 @@ https://en.wikipedia.org/wiki/DOT_(graph_description_language)[DOT] file:
 image::examples/readme/lab.png[DOT style diagram of network nodes and links]
 
 
+=== Running without root using unprivileged user namespaces
+
+Creating a named network namespace within a user namespace requires a few
+extra steps. Use the following commands:
+
+    $ unshare --user --net --mount --map-auto --map-root-user
+    # mount -t tmpfs tmpfs /run
+    # mount -t tmpfs tmpfs /etc/netns
+    # export PATH=$PATH:/usr/sbin
+
+The tmpfs mounts make the directories writable within the user namespace. The
+PATH is updated to ensure `sysctl` is found.
+
+To run the bird-ospf example:
+
+    # mkdir /run/bird
+    # lnnl up examples/bird-ospf/lab.conf
+    [...]
+    # ip netns exec r1 ip -br a
+    [...]
+    # birdc -s /run/bird/r1.ctl
+    [...]
+
+To enter the namespace from another terminal (get the PID with `echo $$`):
+
+    $ nsenter --user --net --mount --target $pid
+
+
 == Examples
 
 Have a look at `examples/`, which also includes running