From 4f1db2acf53f46b4dbc2069f3adb5b60dc2eeb4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Karel=20Ko=C4=8D=C3=AD?= <cynerd@email.cz>
Date: Tue, 1 Nov 2022 16:44:55 +0100
Subject: docs: add some initial more advanced documentation

The primary point of this is to describe installation procedure but we
should also describe basic router usage with NixOS as that ain't
documented elsewhere.
---
 docs/switch.adoc | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 docs/switch.adoc

(limited to 'docs/switch.adoc')

diff --git a/docs/switch.adoc b/docs/switch.adoc
new file mode 100644
index 0000000..10d5434
--- /dev/null
+++ b/docs/switch.adoc
@@ -0,0 +1,90 @@
+= NixOS as switch
+
+The Linux system uses DSA to manage on board switch. DSA provides switch
+configuration abstraction in such a way that every LAN port of the switch is
+actually available for the network configuration. Thus switch configuration is
+as simple as assigning the correct port to the bridge.
+
+NOTE: The examples shown here are for Turris Mox with 4 port switch but
+modification required for Omnia and other Mox configurations should be clear
+from them.
+
+The default single LAN setting would look something like this:
+
+[sources,nix]
+----
+networking = {
+  bridges.brlan <3> = {
+    interfaces = [
+      "eth0" "lan1" "lan2" "lan3" "lan4" <2>
+    ];
+  };
+  dhcpcd.allowInterfaces = [ "brlan" ]; <3>
+};
+----
+
+<1> The bridge interface name.
+<2> Bridge WAN port with all LAN ports. Note that this automatically disables
+DHCP on these ports in NixOS.
+<3> Set DHCP server on our new bridge as it ignores bridges automatically.
+
+The more complex setup with VLANs might look like this. Let's consider that WAN
+port is connected to the router that provides three VLANs and we want to assign
+VLAN 1 to `lan1` and VLAN 2 to `lan2` while connecting `lan3` and `lan4` with
+WAN. The VLAN100 is administation and switch should listen only on that network
+with static IP.
+
+[sources,nix]
+----
+networking = {
+  vlans = { <1>
+    "brlan.1" = {
+      id = 1;
+      interface = "brlan";
+    };
+    "brlan.2" = {
+      id = 2;
+      interface = "brlan";
+    };
+    "brlan.100" = {
+      id = 100;
+      interface = "brlan";
+    };
+  };
+  bridges = {
+    brlan.interfaces = [
+        "eth0" "lan3" "lan4" <2>
+    ];
+    brlan1.interfaces = [
+        "brlan.1" "lan1"
+    ];
+    brlan2.interfaces = [
+        "brlan.2" "lan2"
+    ];
+  };
+  interfaces."brlan.100" = { <3>
+    ipv4 = {
+      addresses = [{
+        address = "192.168.100.42";
+        prefixLength = 24;
+      }];
+    };
+  };
+  defaultGateway = "192.168.100.1";
+  nameservers = [ "192.168.100.1" "1.1.1.1" "8.8.8.8" ];
+  networking.useDHCP = false; <4>
+};
+----
+
+<1> Create VLAN interfaces used in bridges and to actually access the router.
+<2> This bridge provides inteconnection between WAN and `lan3` and `lan4` while
+serving as base for our VLANs.
+<3> Static IPv4 configuration for our management port. The IPv6 should be
+assigned by SLAAC.
+<4> Disable DHCP as we do not want access to the router from any other interface
+than statically configured one.
+
+WARNING: The vlan filtering can't be easilly configured and obvious way of
+adding `lan0.1` to `br1` and `lan0` to `br2` results in tagged traffic being
+included in both `br1` and `br2`. The "correct" way of configuring the complex
+example here would be by using single bridge and filtering VLANs.
-- 
cgit v1.2.3