From a9281020fccf0490d1af9760e8c3adaf141d4a6e Mon Sep 17 00:00:00 2001 From: Simon Ruderich Date: Sun, 12 Jul 2026 07:04:05 +0200 Subject: [PATCH] README: better wording --- README.adoc | 64 +++++++++++++++++++++------------------- examples/readme/lab.conf | 10 +++---- 2 files changed, 38 insertions(+), 36 deletions(-) diff --git a/README.adoc b/README.adoc index a3bc458..acb60fa 100644 --- a/README.adoc +++ b/README.adoc @@ -1,11 +1,11 @@ = README -linux-network-namespace-labs is a small program to create networking lab -setups based on Linux network namespaces in a simple manner. It provides a -quick way to setup labs using a text file describing the architecture -(networks, nodes, links, commands). This is much simpler than running each -node in a separate virtual machine or manually allocating the IP addresses for -each node. It is licensed under GPLv3+. +linux-network-namespace-labs is a small program to easily create networking +lab setups based on Linux network namespaces. It provides a quick way to set +up labs using a text file describing the architecture (networks, nodes, links, +commands). This is much simpler than running each node in a separate virtual +machine or manually allocating the IP addresses for each node. It is licensed +under GPLv3+. == Requirements @@ -24,13 +24,13 @@ each node. It is licensed under GPLv3+. $ go build -Then copy the binary `linux-network-namespace-labs` to somewhere in your +Then copy the binary `linux-network-namespace-labs` to a directory in your `$PATH`. == Usage -The following configuration from `examples/readme/` setups a lab with three +The following configuration from `examples/readme/` sets up a lab with three nodes (routers) and configures static routes. ---- @@ -39,22 +39,22 @@ net loops 192.0.2.0/24 3fff::/20 # Network range for interfaces between nodes net addrs 198.51.100.0/24 2001:db8::/32 -# Setup three nodes (routers) and assign IPv4 and IPv6 loopback addresses +# Set up three nodes (routers) and assign IPv4 and IPv6 loopback addresses node r1 loops node r2 loops node r3 loops -# Links between routers: /31 or /127 is used for each interface +# Links between routers: /31 or /127 prefixes are used for each interface link r1 r2 addrs link r2 r3 addrs -# Commands to run on each node; $1 is the node name (= name of network -# namespace). Here it's used to setup static routes but can also be used to -# start routing daemons like bird. +# Commands to run on each node; $1 is the node name (= name of the network +# namespace). Here it's used to set up static routes but can also be used to +# start routing daemons like Bird. cmd ./setup.sh $1 ---- -Then setup the lab by running (as root): +Then set up the lab by running (as root): # cd examples/readme # linux-network-namespace-labs up lab.conf @@ -75,8 +75,9 @@ traceroute: Use `exit` to leave the network namespace. -`/etc/hosts` of each node (via `/etc/netns//hosts`) is automatically -filled with all known addresses so you can use hostnames as well: +The `/etc/hosts` file of each node (via `/etc/netns//hosts`) is +automatically filled with all known addresses so you can use hostnames as +well: # ping -c1 r3-loop PING r3-loop(r3-loop (3fff::2)) 56 data bytes @@ -86,7 +87,7 @@ filled with all known addresses so you can use hostnames as well: rtt min/avg/max/mdev = 0.266/0.266/0.266/0.000 ms When you change the configuration you can simply rerun "up" and it will remove -the lab (and killing all processes inside it) before starting it up again: +the lab (and kill all processes inside it) before restarting it: # linux-network-namespace-labs up lab.conf [...] @@ -107,17 +108,17 @@ image::examples/readme/lab.png[DOT style diagram of network nodes and links] == Examples -Have a look at `examples/` for some examples which also include running +Have a look at `examples/`, which also includes running https://bird.network.cz/[Bird] on each node and spawning a Podman container -inside the created nodes running https://frrouting.org/[FRR]. +inside the created nodes with https://frrouting.org/[FRR]. == Syntax of configuration file -One option per line, empty lines are permitted as well as comments at the -beginning of the line with `#`. +One option per line, empty lines are permitted as well as comments starting +with `#`. -The config files is parsed from top to bottom and the options "net", "node", +The config file is parsed from top to bottom and the options "net", "node", "link" must be given in this order. "cmd" can be put anywhere (but is only executed at the end). @@ -127,9 +128,9 @@ executed at the end). "net" creates a new prefix which is used to allocate addresses for loopback and link interfaces. Multiple IPv4 and IPv6 prefixes can be specified. When -the network is used one address of each prefix is assigned to the interface. -"net"s used for loopback interfaces must be separate from "net"s used for link -interfaces. +the network is used, one address from each prefix is assigned to the +interface. "net"s used for loopback interfaces must be separate from "net"s +used for link interfaces. === Option "node" @@ -144,13 +145,14 @@ new interface "lo2". "link" |"-" ["l3"] "link" creates links between nodes. The IP addresses are taken from the given -network name. /31 is used for IPv4- and /127 for IPv6-prefixes. If "-" is used -as net-name then no addresses are assigned (useful for unnumbered links). The -MAC address is not static and allocated by the kernel. The link is named after +network. /31 is used for IPv4- and /127 for IPv6-prefixes. If "-" is used as +the net-name then no addresses are assigned (useful for unnumbered links). The +MAC address is dynamically allocated by the kernel. The link is named after the node "on the other side". Multiple links can be created between two nodes. -In this case "_2", "_3", etc. is appended to the interface name. By default -veth interfaces are used, adding "l3" changes this to netkit which provide a -layer-3 connection without needing ARP (requires kernel 6.7, iproute2 6.8). +In this case, suffixes like "_2", "_3", etc. are appended to the interface +name. By default, veth interfaces are used. Adding "l3" changes this to +netkit, which provides a layer-3 connection without needing ARP (requires +kernel 6.7, iproute2 6.8). === Option "cmd" diff --git a/examples/readme/lab.conf b/examples/readme/lab.conf index 75d1248..3a47787 100644 --- a/examples/readme/lab.conf +++ b/examples/readme/lab.conf @@ -6,16 +6,16 @@ net loops 192.0.2.0/24 3fff::/20 # Network range for interfaces between nodes net addrs 198.51.100.0/24 2001:db8::/32 -# Setup three nodes (routers) and assign IPv4 and IPv6 loopback addresses +# Set up three nodes (routers) and assign IPv4 and IPv6 loopback addresses node r1 loops node r2 loops node r3 loops -# Links between routers: /31 or /127 is used for each interface +# Links between routers: /31 or /127 prefixes are used for each interface link r1 r2 addrs link r2 r3 addrs -# Commands to run on each node; $1 is the node name (= name of network -# namespace). Here it's used to setup static routes but can also be used to -# start routing daemons like bird. +# Commands to run on each node; $1 is the node name (= name of the network +# namespace). Here it's used to set up static routes but can also be used to +# start routing daemons like Bird. cmd ./setup.sh $1 -- 2.55.0