= 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
$ 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.
----
# 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
Use `exit` to leave the network namespace.
-`/etc/hosts` of each node (via `/etc/netns/<ns>/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/<ns>/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
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
[...]
== 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).
"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"
"link" <node> <node> <net-name>|"-" ["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"
ruderich.org/simon / linux-network-namespace-labs / linux-network-namespace-labs.git / commitdiff