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