1 files changed, 90 insertions, 0 deletions
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.