From 0199fad79746541731d70637c10e8966d74b2142 Mon Sep 17 00:00:00 2001
From: Jakob Olsson <jakob.olsson@iopsys.eu>
Date: Fri, 9 Dec 2022 10:50:02 +0100
Subject: [PATCH] docs: update TS README

---
 docs/README-Traffic_Separation.md | 182 +++++++++++++++++-------------
 1 file changed, 104 insertions(+), 78 deletions(-)

diff --git a/docs/README-Traffic_Separation.md b/docs/README-Traffic_Separation.md
index 58ae9685d..bbcdcc805 100644
--- a/docs/README-Traffic_Separation.md
+++ b/docs/README-Traffic_Separation.md
@@ -2,28 +2,38 @@
 
 ## Overview
 
-This README documents important aspects regarding application of the Traffic Separation feature in Multi-AP system.
-When Traffic Separation is in effect, traffic from different VLANs are isolated from each other.
-Multiple SSIDs may belong to the same VLAN. The functionality for this is specified in Multi-AP Spec 2.0 chapter 19, which this
-implementation is based on.
-To achieve separation at layer 2 network, bridge vlan filtering feature is used and must be compiled into the kernel.
+This README documents important aspects regarding the Traffic Separation feature
+in a Multi-AP system. When Traffic Separation is in effect, traffic from
+different VLANs are isolated from each other. Multiple SSIDs may belong to the
+same VLAN. The functionality for this is specified in Multi-AP Spec 2.0 chapter
+19, which this implementation is based on. To achieve separation at layer 2
+network, bridge VLAN filtering feature is used and must be compiled into the
+kernel.
 
 ## Configuration
 
-The configuration governing the Traffic Separation (vlan tag numbering) comes from the map-controller.
+The configuration governing the Traffic Separation (per AP VLAN tag numbering)
+comes from the map-controller.
 
-Primary Vlan ID and Default PCP value is set via the controller global section, primary_vid '0' means
-Traffic Separation feature is disabled.
+### Enabling Traffic Separation
+
+To enable traffic separation there are two requirements for map-controller to
+pass the necessary Traffic Separation and Default 802.1Q Settings TLVs:
+* Traffic separation must be enabled via configuration (option enable_ts)
+* Primary VID must be set to a non-zero value (Today only '1' is supported)
 
 ```
 config controller 'controller'
 	option enabled '1'
 	option registrar '5 2'
 	option primary_vid '1'
-	option primary_pcp '2'
+	option primary_pcp '0'
+        option enable_ts '1'
 ```
 
-Each *ap* section specifies which Vlan ID it belongs to by the *vid* option:
+### Per AP VLAN Tagging
+
+Each *ap* section specifies which VLAN ID it belongs to by the *vid* option:
 
 ```
 config ap
@@ -51,7 +61,7 @@ config ap
         option key 'FPaY-7teN-hTHa-pgdT'
 
 config ap
-        option band '5'
+        option band '2'
         option ssid 'Another-Guest-Network'
         option encryption 'sae-mixed'
         option vid '20'         # Example guest VID 20
@@ -59,77 +69,94 @@ config ap
         option key 'FPaY-7teN-hTHa-pgdT'
 ```
 
+These VIDs will be passed in the Policy Config Request CMDU and during
+AP-Autoconfiguration along with AP-Autoconfiguration WSC (M2) CMDU and
+configured by map-agent.
+
 ## Implementation
 
-In order for map-agent to apply vlan tagging on the *Primary Network*, it must receive a **Default 802.1Q Settings TLV** containing the Primary Vlan ID.
-This can be received in any of three ways:
+In order for map-agent to apply VLAN tagging on the *Primary Network*, it must
+receive a **Default 802.1Q Settings TLV** containing the Primary VLAN ID. This
+can be received in any of three ways:
 - in a **AP-Autoconfiguration WSC** message from the map-controller
 - in a **Multi-AP Policy Config Request** message from the map-controller
 - as a Multi-AP IE subelement in **(Re-)Association Response** frames
 
-To apply tagging on *Secondary Networks*, it must receive a **Traffic Separation Policy TLV** containing at least one SSID to Vlan ID mapping.
-This can be received in either of the following CMDUs from map-controller:
+To apply tagging on *Secondary Networks*, it must receive a
+**Traffic Separation Policy TLV** containing at least one SSID to VLAN ID
+mapping. This can be received in either of the following CMDUs from
+map-controller:
 - a **AP-Autoconfiguration WSC** message
 - a **Multi-AP Policy Config Request** message
 
-When Map Agent receive proper Traffic Separation policy config it will reconfigure */etc/config/network* to enable
-vlan filtering on *al_bridge* (default br-lan) and configure vlan for Ethernet ports that were already bridged
-to *al_bridge* and create *sink* veth interfaces that allow network layer 3 (IP, IPv6, DHCP etc.) access to the vlan networks.
-
-```
-config device 'br_lan'
-        option name 'br-lan'
-	config device 'br_lan'
-        option type 'bridge'
-        list ports 'eth2'
-        list ports 'eth3'
-        list ports 'eth4'
-        option macaddr '44:D4:37:71:BE:32'
-        option vlan_filtering '1'
-```
-
-Individual vlan ids for ports are configured using *bridge-vlan* network config entries.
-Ports having *:t* appended will keep the vlan id tag for ingress end egress traffic
-(802.1q frames will be sent out and received on the port). List port entries without
-*:t* will add a tag for ingress and remove on egress traffic, which is proper
-for *sink* interfaces and Ethernet interfaces for primary network.
+When Map Agent receive proper Traffic Separation policy config it will
+reconfigure */etc/config/network* to enable VLAN filtering on *al_bridge*
+(default br-lan) and configure VLAN for Ethernet ports that were already bridged
+to *al_bridge*.
+
+Individual VLAN IDs for ports are configured using *bridge-vlan* network config
+entries. A bridge-vlan section allows a configuration of how a VLAN ID should
+be appended or untagged at the bridge and each specified port.
+
+| Option | type    | Description |
+|--------|---------|-------------|
+| name   | string  | Unique section identifier |
+| device | string  | Map to a device section with the same name |
+| vlan   | integer | VLAN ID for which this section dictates tagging ruels |
+| flags  | string  | List of egress and ingress rules for the bridge.<br /> 'untagged' = Packets egress untagged for specified VID<br /> 'pvid' = Add VID tag for ingressing untagged frames |
+| local  | boolean | Whether any tagging rules should be applied at bridge level for this VLAN ID |
+| ports  | string  | List of ports and port desired VLAN ID handling at port level<br /> '*port*:t' = Keep VID tag intact for ingressing and egressing traffic<br /> '*port*:*' = Add VID tag for ingress and remove tag on egress<br /> '*port*' = Add VID tag for ingress and remove tag on egress |
+
+Map-agent will create these sections for each passed VLAN ID within the Traffic
+Separation TLV. At the Ethernet port level map-agent will add egress and ingress
+tagging rules for the primary VLAN ID and keep tags as-is for secondary VLAN
+IDs. At the bridge level all VLAN IDs will be handled and egress untagged,
+whereas ingressing packets will receive a Primary VLAN ID tag.
 
 ```
-config bridge-vlan
-        option device 'br-lan'
-        option vlan '1'
-        list ports 'eth2'
-        list ports 'eth3'
-        list ports 'eth4'
-        list ports 'sink_peer1'
-
-config bridge-vlan
-        option device 'br-lan'
-        option vlan '50'
-        list ports 'eth2:t'
-        list ports 'eth3:t'
-        list ports 'eth4:t'
-        list ports 'sink_peer50'
+config bridge-vlan 'vlan1'
+	option name 'vlan1'
+	option device 'br-lan'
+	option vlan '1'
+	option flags 'untagged pvid'
+	option local '1'
+	list ports 'eth1:*'
+	list ports 'eth2:*'
+	list ports 'eth3:*'
+	list ports 'eth4:*'
+
+config bridge-vlan 'vlan50'
+	option name 'vlan50'
+	option device 'br-lan'
+	option vlan '50'
+	option flags 'untagged'
+	option local '1'
+	list ports 'eth1:t'
+	list ports 'eth2:t'
+	list ports 'eth3:t'
+	list ports 'eth4:t'
+
+config bridge-vlan 'vlan20'
+	option name 'vlan20'
+	option device 'br-lan'
+	option vlan '20'
+	option flags 'untagged'
+	option local '1'
+	list ports 'eth1:t'
+	list ports 'eth2:t'
+	list ports 'eth3:t'
+	list ports 'eth4:t'
 ```
 
-By convention vlan *vid* network is configured to be 192.168.*vid*.0/24 ip network.
+Bridge VLAN filtering configuration can be seen by *bridge vlan* command and
+an example output can look like:
 
 ```
-config interface 'vlan50'
-        option device 'sink50'
-        option is_lan '1'
-        option proto 'static'
-        option ipaddr '192.168.50.1'
-        option netmask '255.255.255.0'
-
-```
-
-Specific vlan configuration can be seen by *bridge vlan* command and example
-output can look like this:
-
-```
-root@iopsys:~# bridge vlan
+root@iopsys-021000000001:~# bridge vlan
 port              vlan-id  
+eth1              1 PVID Egress Untagged
+                  20
+                  50
 eth2              1 PVID Egress Untagged
                   20
                   50
@@ -141,22 +168,21 @@ eth4              1 PVID Egress Untagged
                   50
 wl0               1 PVID Egress Untagged
 wl1               1 PVID Egress Untagged
-sink_peer1        1 PVID Egress Untagged
-br-lan            1
-                  20
-                  50
+br-lan            1 PVID Egress Untagged
+                  20 Egress Untagged
+                  50 Egress Untagged
 wl1.1             1 PVID Egress Untagged
-wl1.2             20 PVID Egress Untagged
 wl0.1             1 PVID Egress Untagged
-wl0.2             50 PVID Egress Untagged
-sink_peer50       50 PVID Egress Untagged
-sink_peer20       20 PVID Egress Untagged
+wl0.2             1 Egress Untagged
+                  50 PVID Egress Untagged
+wl1.2             1 Egress Untagged
+                  20 PVID Egress Untagged
 ```
 
-PVID Egress Untagged entries will add/remove vlan id tag on for incoming/outgoing frames
-on that port. Vlan id listed without PVID Egress Untagged mean that particular
-vlan tag is accepted on the port, non listed vlan tags are dropped.
-In example above *eth2* will:
+PVID Egress Untagged entries will add/remove VLAN ID tag on for
+incoming/outgoing frames on that port. VLAN IDs listed without PVID Egress
+Untagged mean that particular VLAN tag is accepted on the port, non listed VLAN
+tags are dropped. In example above *eth2* will:
 * Accept 802.1q frames with VIDs 20 and 50
 * Change untagged incoming ethernet frames to 802.1q with vid 1
 * Remove tags for outgoing frames
-- 
GitLab