From 452e71153e5619f61cd5b5b9d289e7a5b8ef8df1 Mon Sep 17 00:00:00 2001 From: Jakob Olsson <jakob.olsson@iopsys.eu> Date: Mon, 2 Jan 2023 16:56:54 +0100 Subject: [PATCH] README: add new features and minor fixes --- README.md | 164 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 151 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 769760c3..47dfc136 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,9 @@ and explain some features of map-controller: * Channel Planning * STA Steering * Dynamic Controller Sync +* Enabling Traffic Separation +* Passing custom vendor extensions with WSC M2 +* IOPSYS Vendor Extensions ## UCI Configuration @@ -29,12 +32,9 @@ config controller 'controller' option enabled '1' option registrar '5 2' option debug '0' - option enable_sta_steer '0' - option enable_bsta_steer '0' - option use_bcn_metrics '0' - option use_usta_metrics '0' option initial_channel_scan '0' option primary_vid '1' + option enable_ts '0' option primary_pcp '0' option allow_bgdfs '0' option channel_plan '0' @@ -85,7 +85,7 @@ Fronthaul AP credentials are identified by the human readable option `type 'fronthaul'`. Once propagated to agents, these interfaces are written with `option multi_ap '2'` to the wireless configuration. -As such, the following mapcontroller sections will generate to the respective +As such, the following mapcontroller sections will generate the respective wireless sections, after handled by an agent: ``` @@ -155,8 +155,8 @@ config wifi-iface 'default_wl1' Backhaul AP credentials are identified by `type 'backhaul'`. Once propagated to agents, these interfaces are written with `option multi_ap '1'` to the wireless -configuration. These will be the APs that backhaul stations will connect to, -in a Multi-AP environment. +configuration. These will be the APs that backhaul stations (other IEEE1905 and +EasyMesh complianet devices) can connect to, in a Multi-AP environment. The following mapcontroller sections will be corresponding to the respective wireless sections, after handled by an agent: @@ -320,7 +320,7 @@ If these values are modified, a `SIGHUP` can be triggered to mapcontroller and the options will be propagated to the agent(s). -## AP-Autoconfig Renew +## AP-Autoconfig Renew (Network Reconfiguration) Autoconfig Renew will trigger all agents to be reconfigured with updated credentials. @@ -331,10 +331,7 @@ Mapcontroller will re-read the mapcontroller credentials and policies upon receiving `SIGHUP`. In order to trigger AP-Autoconfig Renew the mapcontroller credentials loaded in memory at runtime, must differ from the ones in the config, causing mapcontroller to generate a AP-Autoconfig Renew for all agents -to be reconfigured. - -It should be noted that AP-Autoconfig Renew can be triggered by mapcontroller -on its own, as it may reload its configuration at runtime, based on events. +to be reconfigured. Meaning i.e. an `ap` section SSID has changed. ## Channel Planning @@ -396,7 +393,7 @@ config: config controller 'controller' option enable_sta_steer '1' option use_bcn_metrics '1' - option initial_channel_scan '1' + option initial_channel_scan '1' ``` BTM steering may also work fine w/o the initial_channel_scan set - it @@ -467,6 +464,147 @@ Additionally, in ieee1905 and map-agent: * map-agent - `AGENT_SYNC_DYNAMIC_CNTLR_CONFIG` * ieee1905 - `MULTIAP_DYNAMIC_CNTLR_SYNC_CONFIG` +## Traffic Separation + +For a more in-depth README on Traffic Separation see [link](https://dev.iopsys.eu/iopsys/map-agent/-/blob/devel/docs/README-Traffic_Separation.md). +For instructions on how to setup layer 3 Traffic Separation, see [link](https://dev.iopsys.eu/iopsys/map-agent/-/blob/devel/docs/README-Layer3ts.md). + +To enable Guest WiFi and Easymesh Traffic Segregation, the option 'primary_vid' +and 'enable_ts' must be set to a non-zero value in the map-controller config's +global section. + +NOTE: Currently, only primary_vid = '1' is supported: + +``` +config controller 'controller' + option enabled '1' + option registrar '5 2' + option primary_vid '1' + option primary_pcp '0' + option enable_ts '1' +``` + +To create a Guest WiFi network, a new 'ap' configuration section must be added +to the map-controller configuration, with a VID different from the primary. +Alternatively, an existing section may have its VID changed. + +``` +config ap + option band '5' + option ssid 'iopsysWrt-GUEST-5' + option encryption 'sae-mixed' + option key '1234567890' + option vid '10' + option type 'fronthaul' +``` + +After changing as above, issue a `SIGHUP` to map-controller in order to reload +the new configuration and propagate them to the map-agents in the Multi-AP +network. + + +## Dynamic Vendor Extensions + +UCI configurable vendor extensions can be passed by the map-controller within +the AP-Autoconfiguration WSC M2 frame to its agents. + +These vendor extensions are UCI configurable by `list vendor_ie <hex string>`, from the +map-controller AP section in the format of: + +``` +section ap + option band '5' + option ssid 'iopsysWrt-021000000001' + option encryption 'sae-mixed' + option key '7NTx-APvX-pba7-tvd7' + option vid '1' + option type 'fronthaul' + list vendor_ie '<oui><data>' # oui must be 3 bytes +``` + + +Values that are not provided as full bytes (i.e. not even number of characters) +are discarded. + +Each vendor_ie will be appended with Vendor Extension attribute ID 0x1049 in the +WSC M2 payload. When received by map-agent, they will be parsed and added to the +respective ap section in the same format. + +Example configuration - +From the map-controller AP section: + +``` +config ap + option band '5' + option ssid 'iopsysWrt-021000000001' + option encryption 'sae-mixed' + option key '7NTx-APvX-pba7-tvd7' + option vid '1' + option type 'fronthaul' + list vendor_ie '00112211' +``` + +As seen added to map-agent AP sections: + +``` +config ap + option ifname 'wl0' + option band '5' + option device 'wl0' + option type 'fronthaul' + option encryption 'sae-mixed+aes' + option vid '1' + option ssid 'iopsysWrt-021000000001' + option key '7NTx-APvX-pba7-tvd7' + option enabled '1' + list vendor_ie '00112211' # custom vendor extension +``` +## IOPSYS Vendor Extensions + +Map-controller supports a set of less impactful vendor extensions. All vendor +extensions are optionally included via the compile-time flag +`EASYMESH_VENDOR_EXT`. + +The OUI used by the vendor extensions can be selected by passing them with the +compile-time flag `EASYMESH_VENDOR_EXT_OUI`. If vendor extensions are enabled +but no OUI flag is passed, it will default to use the oui 0x001122. + +### Enabled SSID + +Under an `ap` section there is an `enabled` option, which has different behavor +when vendor extensions are compiled and not. + +``` +config ap + option band '5' + option ssid 'iopsysWrt-44D43771BB20' + option encryption 'sae-mixed' + option key '1234567890' + option vid '1' + option type 'fronthaul' + option enabled '0' +``` + +When `EASYMESH_VENDOR_EXT` is compiled in, the 'ap' section (as above) will be +propagated within an AP-Autoconfig WSC CMDU. A wsc vendor attribute gets +included inside the WSC-M2 TLV (with a custom attribute 0x4c), which carries +this 'enabled=0' information. + +If the receiving map-agent also has EASYMESH_VENDOR_EXT enabled and compiled in, +this 'ap' section received through the AP-autoconfiguration will have disabled = +'true' set when written to the 'wireless' and corresponding 'hostapd' +configuration. + +If `EASYMESH_VENDOR_EXT` is not included (*default*), map-controller will skip +this 'ap' section entirely, and the section will not be included in any +AP-Autoconfiguration WSC-M2 TLVs. + +### Backhaul BSS Identifying + +To easily identify a backhaul BSS, a vendor extension TLV is optionally added to +Topology Response CMDUs and parsed by map-controller. This is merely a cosmetic +improvement in the map-controller `status` UBUS API. + ## UBUS APIs Map-controller offers a variety of UBUS APIs, most of them map to CMDU request -- GitLab