Skip to content
Snippets Groups Projects
README.md 33.9 KiB
Newer Older
  • Learn to ignore specific revisions
  • Sukru Senli's avatar
    Sukru Senli committed
    # MAP Controller
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    [Map-Controller](https://dev.iopsys.eu/iopsys/map-controller)
    
    
    ## Introduction
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    This package provides the mapcontroller daemon, which implements the WiFi
    Alliances Easymesh Controller component.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ## Overview
    
    
    This README will show how to properly setup the mapcontroller configuration file
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    and explain some features of map-controller:
    
    * Policy Configuration
    * AP-Autoconfig Renew
    * Channel Planning
    * STA Steering
    * Dynamic Controller Sync
    
    * Enabling Traffic Separation
    * Passing custom vendor extensions with WSC M2
    * IOPSYS Vendor Extensions
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ## UCI Configuration
    
    
    The table below lists the configuration parameters supported by map-controller.
    
    Anjan Chanda's avatar
    Anjan Chanda committed
    The config file is in UCI format and defaults to `"/etc/config/mapcontroller"`
    
    path.
    
    Section    | Name | Type | Required | Default | Description
    -----------|------|------|----------|---------|-------------
    controller | - | - | - | - | - |
     "         |enabled | boolean | yes | 1 | When set to 0, disables the map-controller |
     "         |id | MAC address | no | (auto) | Gets auto-set with the 1905 AL-macaddress of the locally running 1905 component. |
     "         |network\_id | UUID hexstring | no | (auto) | The unique identifier of the Multi-AP network managed by this Controller. When not set, gets autogenerated. |
     "       |registrar | list | no | (none) | List of WiFi frequency bands for which the Controller will act as a Configuration Registrar. Possible values are: 2, 5 and 6 |
     "       |bcn\_metrics\_max\_num | integer | no | 10 | Specifies the maximum number of 11k Beacon Metrics Responses per STA |
     "       |initial\_channel\_scan | boolean | no | false | Whether or not, a Channel Scan Request will be issued to an Agent immediately post its On-boarding |
     "       |primary\_vid | integer | no | 0 | Primary VLAN ID of the Multi-AP network managed by this Controller. When not set, the Multi-AP network is untagged  |
     "       |enable\_ts | boolean | no | false | When set to true, enables Traffic Separation in the Multi-AP network as defined in the EasyMesh standard |
     "       |max\_node\_bh\_hops | integer | no | 0 | When set to a positive integer greater than 0, Controller limits the depth of the Multi-AP network by not allowing the WiFi backhauls to grow beyond this number |
     "       |debug | integer | no | 0 | Set the verbosity level of debugging |
    
    Anjan Chanda's avatar
    Anjan Chanda committed
    ap |  | - | - | - | *This section defines the AP (or BSS) configuration of the Agent nodes, which the Controller will provision with during EasyMesh Onboarding.* |
    
     "       | band | integer | yes | 0 | WiFi frequency band for which the AP (or BSS) configuration of this config section is applicable. Values: 2, 5 or 6 for 2.4, 5 and 6 GHz bands respectively. |
     "       | ssid | string | yes |  | SSID of the AP configuration. |
     "       | encryption | string | yes |  | Security types for the AP configuration. Valid values are - "sae", "dpp+sae", "sae-mixed", "psk-mixed", "psk2", "psk", "wps-mixed", "wpa2", "wpa", "none" and "open". NOTE: Only a certain set of values may be valid for a given frequency 'band', f.e. "psk2" or "sae-mixed" are not valid when "band" = 6. |
     "       | key | string | yes |  | Security key, f.e., passphrase or psk. |
     "       | type | string | no | "fronthaul" | Type of the AP/BSS. Valid value is "backhaul", "fronthaul" or "combined". |
     "       | vid | integer | no | 1 | VLAN ID of the AP (or BSS) network. |
    
    Anjan Chanda's avatar
    Anjan Chanda committed
     "       | enabled | boolean | no | true | Whether this 'ap' section is enabled or not. *TODO* explain behavior with/without EASYMESH\_VENDOR\_EXT |
    
     "       | disallow\_bsta\_profile | integer | no |  | When set, configure the Agent nodes to disallow WiFi backhaul connections in the downstream with Agents supporting this profile. *TODO* valid values |
     "       | vendor\_ie | list | no |  | Hexstring of Vendor IEs. *TODO* explain usage in one-or-two lines |
    
    Anjan Chanda's avatar
    Anjan Chanda committed
    node | node\_xxyyzzaabbcc | - | - | - | Represents an EasyMesh Agent node. In the name, *xxyyzzaabbcc* represents the 1905-AL macaddress of the Agent node. Controller automatically appends one such config section for each new EasyMesh Agent which gets onboarded. This config section allows the Controller to set Agent specific configuration parameters and policies. |
    
     "       | agent\_id | MAC address | no | (auto) | Gets auto-set with the 1905 AL-macaddress of an Onboarded Agent node. |
     "       | report\_scan | boolean | no | 0 | Whether the Agent node should report scan-results from independent scanning done by it or not. |
     "       | report\_sta\_assocfails| boolean | no | 0 | Whether the Agent node should report STA association failures or not. |
     "       | report\_sta\_assocfails\_rate | integer | no | 0 | Periodicity with which the Agent node should report STA association failures. |
     "       | report\_metric\_periodic | integer | no | 0 | Periodicity with which the Agent node should report send Metric Reports to the Controller. |
     "       | steer\_disallow | boolean | no | 0 | When set to 1, disallows STA steering by the Agent node. |
     "       | steer\_exclude | list | no |  | List of STA macaddresses that are excluded from Independent STA steering by the Agent node. Default: Empty list, meaning all STAs to be steered by the Agent node should be steered only through the Steering Mandate command from the Controller. |
     "       | steer\_exclude\_btm | list | no |  | List of STA macaddresses that are excluded from 11v BTM steering carried out independently by the Agent node. Default: Empty list, meaning that all STAs to be BTM steered by the Agent node, should occur only through the Steering Mandate command from the Controller. |
     "       | traffic\_separation | boolean | no |  | When set to 0, Controller excludes the Agent node from Traffic Separation policy configuration. |
     "       | coordinated\_cac | boolean | no |  | Whether to enable or disable Coordicated CAC in the Agent node. |
    -----------
    
    
    
    A default configuration file which will propagate one fronthaul and one backhaul
    interface for the 5GHz and 2.4GHz bands respectively may look as such:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    config controller 'controller'
    	option enabled '1'
    	option registrar '5 2'
    	option debug '0'
    
    	option bcn_metrics_max_num '10'
    
    	option initial_channel_scan '0'
    
    	option primary_vid '1'
    
    	option enable_ts '0'
    
    	option primary_pcp '0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option allow_bgdfs '0'
    	option channel_plan '0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    config sta_steering
    	option steer_module 'rcpi'
    	option enabled '1'
    	option enable_sta_steer '0'
    	option enable_bsta_steer '0'
    	option use_bcn_metrics '0'
    	option use_usta_metrics '0'
    	option bandsteer '0'
    	option diffsnr '8'
    	option rcpi_threshold_2g '70'
    	option rcpi_threshold_5g '86'
    	option rcpi_threshold_6g '86'
    	option report_rcpi_threshold_2g '80'
    	option report_rcpi_threshold_5g '96'
    	option report_rcpi_threshold_6g '96'
    
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '5'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'iopsysWrt-021000000001'
    
    	option encryption 'sae-mixed'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    	option type 'fronthaul'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '2'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'iopsysWrt-021000000001'
    
    	option encryption 'sae-mixed'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    	option type 'fronthaul'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '5'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'MAP-021000000001-BH-5GHz'
    
    	option encryption 'sae'
    	option type 'backhaul'
    	option vid '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '2'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'MAP-021000000001-BH-2.4GHz'
    
    	option encryption 'sae'
    	option type 'backhaul'
    	list disallow_bsta '0'
    	option vid '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    
    
    ### Credentials
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    The `ap` sections are access point credentials that will be passed to agents in
    
    the network, which will setup the local wireless configuration accordingly.
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Fronthaul Credentials
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    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 the respective
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    wireless sections, after handled by an agent:
    
    
    ```
    config ap
    	option band '5'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'iopsysWrt-021000000001'
    
    	option encryption 'sae-mixed'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    	option type 'fronthaul'
    
    config ap
    	option band '2'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'iopsysWrt-021000000001'
    
    	option encryption 'sae-mixed'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    	option type 'fronthaul'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config wifi-iface 'default_wl0'
    	option device 'wl0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option network 'lan'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ifname 'wl0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option mode 'ap'
    	option wps '1'
    	option wps_pushbutton '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211k '1'
    	option bss_transition '1'
    	option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
    	option multi_ap '2'
    	option ssid 'iopsysWrt-021000000001'
    
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211w '1'
    	option start_disabled '0'
    	option multicast_to_unicast '1'
    	option isolate '0'
    	option multi_ap_backhaul_ssid 'MAP-021000000001-BH-5GHz'
    	option multi_ap_backhaul_key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    config wifi-iface 'default_wl1'
    	option device 'wl1'
    	option network 'lan'
    	option ifname 'wl1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option mode 'ap'
    	option wps '1'
    	option wps_pushbutton '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211k '1'
    	option bss_transition '1'
    	option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
    	option multi_ap '2'
    	option ssid 'iopsysWrt-021000000001'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    	option ieee80211w '1'
    	option start_disabled '0'
    	option multicast_to_unicast '1'
    	option isolate '0'
    	option multi_ap_backhaul_ssid 'MAP-021000000001-BH-2.4GHz'
    	option multi_ap_backhaul_key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    ### Backhaul Credentials
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    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 (other IEEE1905 and
    EasyMesh complianet devices) can connect to, in a Multi-AP environment.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    The following mapcontroller sections will be corresponding to the respective
    wireless sections, after handled by an agent:
    
    
    ```
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '2'
    	option ssid 'iopsysWrt-021000000001'
    	option encryption 'sae-mixed'
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'fronthaul'
    
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '5'
    	option ssid 'MAP-021000000001-BH-5GHz'
    
    	option encryption 'sae'
    	option type 'backhaul'
    	option vid '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config wifi-iface 'default_wl1_1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option device 'wl1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option mode 'ap'
    	option ifname 'wl1.1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option multi_ap '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option network 'lan'
    	option hidden '1'
    	option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211k '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'MAP-021000000001-BH-2.4GHz'
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    	option encryption 'sae+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211w '2'
    	option start_disabled '0'
    	option wps_device_type '6-0050f204-1'
    	option multicast_to_unicast '0'
    	option isolate '0'
    
    config wifi-iface 'default_wl0_1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option device 'wl0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option mode 'ap'
    	option ifname 'wl0.1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option multi_ap '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option network 'lan'
    	option hidden '1'
    	option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211k '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ssid 'MAP-021000000001-BH-5GHz'
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    	option encryption 'sae+aes'
    	option ieee80211w '2'
    	option start_disabled '0'
    	option wps_device_type '6-0050f204-1'
    	option multicast_to_unicast '0'
    	option isolate '0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    ### Combined Front/Back
    
    
    If combined fronthaul and backhaul interfaces are to be used, a `config ap`
    section with the option `type 'combined'` shall be provided:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    
    config ap
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option band '2'
    	option ssid 'iopsysWrt-021000000001'
    	option encryption 'sae-mixed'
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option vid '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'combined'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    
    In turn map-agent will create the interface with the option `multi_ap '3'`,
    meaning combined fronthaul/backhaul interface.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config wifi-iface 'default_wl0'
    	option device 'wl0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option network 'lan'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ifname 'wl0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option mode 'ap'
    	option wps '1'
    	option wps_pushbutton '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ieee80211k '1'
    	option bss_transition '1'
    	option uuid 'c8f1402f-1ef9-4801-9a68-021000000001'
    	option multi_ap '3'
    	option ssid 'iopsysWrt-021000000001'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    	option ieee80211w '1'
    	option start_disabled '0'
    	option multicast_to_unicast '1'
    	option isolate '0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Policy Configuration
    
    Agent, and agent radio specific configuration can be set from mapcontroller
    configuration, and propagated via Multi-AP Policy Configuration Request CMDU.
    
    #### Agent Specific Configuration
    
    Whenever the mapcontroller discovers an agent (via AP-Autoconfig Search
    messages), it will add a skeleton configuration sections with the bare minimum,
    assuming default values for the rest:
    
    ```
    config node 'node_ee6c9a52b027'
    	option agent_id 'ee:6c:9a:52:b0:27'
    # the following values are not explicitly set and the default values are used
    	option backhaul_ul_macaddr '00:00:00:00:00:00'
    	option backhaul_dl_macaddr '00:00:00:00:00:00'
    	option backhaul_type 'none'
    	option primary_vid '1'
    	option primary_pcp '0'
    	option report_sta_assocfails '0'
    	option report_sta_assocfails_rate '0'
    	option report_metric_periodic '0'
    	option report_scan '0'
    
    	list steer_exclude ''
    	list steer_exclude_btm ''
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option steer_disallow '0'
    	option coordinated_cac '0'
    	option traffic_separation '0'
    	option sta_steer '0'
    ```
    
    If these values are modified, a `SIGHUP` can be triggered to mapcontroller and
    the options will be propagated to the agent(s).
    
    #### Radio Specific Configuration
    
    When an agent is discovered it will proceed to complete AP-Autoconfiguration.
    During AP-Autoconfiguration, each radio on the agent will send an
    AP-Autoconfiguration WSC (M1), these radios will have their own sections created
    in the mapcontroller configuration with necessary policies. Each section maps to
    an agent section by `agent_id`.
    
    ```
    config radio 'radio_ec6c9a52acb9'
    	option agent_id 'ee:6c:9a:52:ac:b7'
    	option macaddr 'ec:6c:9a:52:ac:b9'
    	option band '5'
    # the following values are not explicitly set and the default values are used
    	option steer_policy '0'
    	option util_threshold '0'
    	option rcpi_threshold '86'                # 70 for 2.4GHz band
    	option report_rcpi_threshold '96'         # 80 for 2.4GHz band
    	option report_util_threshold '0'
    	option report_rcpi_hysteresis_margin '0'
    	option include_sta_stats '1'
    	option include_sta_metric '1'
    ```
    
    If these values are modified, a `SIGHUP` can be triggered to mapcontroller and
    the options will be propagated to the agent(s).
    
    
    ### QoS (Service Prioritization)
    
    Service Prioritization feature allows setting packet priorities which can be
    used by the switches and WiFi access points on the traffic path to accelerate
    properly marked packet types.
    
    The configuration of this features boils down to enabling QoS generally and
    adding rules. Controller would propagate these rules to agents by sending
    Service Prioritization Requests, and then it is up to agents to decide whether
    it is possible to enable them or not.
    
    For now, the only supported rule type is `dscp_pcp`, which allows mapping up to
    64 Differentiated Services Code Point (DSCP, `[0, 63]`) values to 8 Priority
    Call Point (PCP, `[0, 7]`) values. The sample configuration is provided below.
    
    ```
    config qos 'qos'
    	option enabled '1'
    
    config qos_rule 'qos_rule1'
    	option enabled '1'
    	option type 'dscp_pcp'
    	option output '8'
    	option always_match '1'
    
    	list dscp_pcp '58,1'
    	list dscp_pcp '58,2'
    	list dscp_pcp '10-21,5'
    
    ```
    
    The `output` value determines the target PCP. If the rule has `output`
    less than `8`, a PCP value of that range (`[0, 7]`) would be used as a target
    for all possible DSCP values. The value outside the `[0, 8]` range would be
    considered malformed and would trigger errors.
    
    The `always_match` flag is assumed for `dscp_pcp` type because rule matching is
    provided through TCLAS objects, which are not available for configuring for
    that rule type.
    
    The `dscp_pcp` is a comma-separated array of up to 64 integers in `[0, 7]`
    range. Each integer designates a PCP value which would be used for packets with
    the DSCP value corresponding to the index of the said PCP value.
    
    Note that DSCP/PCP mapping table can't be completely sparse in terms of used
    values and has to be made with care. Technically, the agent would have to
    convert this table to the list of PCP/DSCP ranges (8 ``[dscp_min, dscp_max]``
    ranges) and up to 21 DSCP exceptions (``[DSCP, PCP]``), which means there can be
    no precise conversion between original DSCP/PCP mapping table and the final map.
    Agent will do its best to generate a proper map, but will not inform controller
    about the possible imprecision.
    
    The support of the feature on the agent depends on the used WiFi driver. The
    agent passes the generated map directly to the driver, and it is up to driver
    to decide whether to activate it or not.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    ## AP-Autoconfig Renew (Network Reconfiguration)
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    Autoconfig Renew will trigger all agents to be reconfigured with updated
    credentials.
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Trigger
    
    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. Meaning i.e. an `ap` section SSID has changed.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ## Channel Planning
    
    Map-controller supports channel planning in the form of channel selection, and
    background CAC (if supported) to clear channels. Each locked behind their own
    UCI configuration options.
    
    Additionally, there are ubus methods available to do it manually:
    
    * ubus call map.controller scan '{"agent":"46:d4:37:71:be:80", "radio":["44:d4:37:71:be:8f"], "channel":[[]]}' - best call before channel_pref – to get fresh preference counters
    * ubus call map.controller channel_pref – get/update channel preferences from all nodes
    * ubus call map.controller channel_cleanup – run background CAC (preCAC) on nodes if required
    * ubus call map.controller channel_recalc – base on channel preference score choose best channel for each node and radio and request node to switch to this channel
    
    ### Channel Selection
    
    Map-controller will send a Channel Preference Query to its agents and collect
    the results. Whenever the channel selection periodic timer is hit,
    map-controller will calculate the best channel for the network.
    
    This feature is enabled by the UCI configuration:
    ```
    config controller 'controller'
    	option channel_plan '0'
    ```
    
    The `channel_plan` value corresponds to the timeout in seconds at which channel
    planning will be triggered. Any value less than 180 will be treated as invalid
    and default to 3600 * 3 seconds (three hours). Setting to 0 means disabled.
    
    Do note that this feature will not kick in for any radio which has a downstream
    agent wirelessly connected.
    
    ### Background DFS
    
    If enabled, map-controller will periodically trigger background dfs in each
    agent that supports it, based on bandwidth, channel and DFS availability.
    
    This feature is enabled by the UCI configuration:
    ```
    config controller 'controller'
    	option allow_bgdfs '0'
    ```
    
    The `allow_bgdfs` value corresponds to the timeout in seconds at which
    background DFS will be triggered. Any value less than 120 will be treated as
    invalid and default to 120 seconds (two minutes). Setting to 0 means disabled.
    
    
    ## STA Steering
    
    Map-controller initiated mandate steering based on beacon measurement is
    supported. For STA to be able to be steered its drivers must support 802.11k
    (RRM for beacon measurements) and 802.11v.
    
    
    To enable STA steering feature one must add following section in map-controller
    UCI config:
    
    ```
    config sta_steering
    	option steer_module 'rcpi'
    	option enabled '1'
    	option enable_sta_steer '1'
    	option use_bcn_metrics '1'
    ```
    
    
    The steer_module maps to the rcpi plugin in /usr/lib/mapcontroller/rcpi.so
    Sometimes it may also be needed to enable initial channel scan.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    config controller 'controller'
    
    	 option initial_channel_scan '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ```
    
    
    BTM steering may also work fine w/o the initial_channel_scan set - it
    
    depends on the bottom layer implementation (independent channel scan).
    
    
    Setting the initial_channel_scan option itself will cause a radio scan request
    to be issued towards given node and it's reported radios, providing there was
    no prior scan results reported on given radio. This radio channel scan will
    be issued once controller obtains first scan capability information tlv from
    given node. Radios, opclasses and channels to scan depend on these scan caps.
    
    
    The steering decision is based upon drop of the STA RCPI below report rcpi
    threshold, which can be modified globally using sta_steering section separately
    for each radio band
    
    ```
    config sta_steering
    	option report_rcpi_threshold_2g '80'
    	option report_rcpi_threshold_5g '96'
    	option report_rcpi_threshold_6g '96'
    ```
    
    Or per radio via radio section of UCI config:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ```
    config radio 'radio_44d4376af4cf'            
            option agent_id '46:d4:37:6a:f4:c0'  
            option macaddr '44:d4:37:6a:f4:cf'   
            option band '5'
            option rcpi_threshold '86'
            option report_rcpi_threshold '96'
    ```
    
    
    In case the rcpi_threshold is not set it defaults in code to 86 for 5GHz & 6Ghz
    and to 70 for 2.4GHz.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    Once the signal strength goes below the report_rcpi_threshold it’ll trigger
    link metrics response from agent to controller, causing controller to send
    beacon metrics request for the given STA on all operating classes/channels of
    nodes in the mesh. The beacon metrics results will be parsed and if there’s a
    better (at least 10dB difference in RSSI) BSS found for given STA, controller
    
    will try to to move STA to that BSS using BTM. Providing the signal dropped
    further below second tier thershold in the meanwhile
    
    ```
    config sta_steering
    	option rcpi_threshold_2g '70'
    	option rcpi_threshold_5g '86'
    	option rcpi_threshold_6g '86'
    ```
    
    rcpi_threshold_Xg can be set per radio similarily to report_rcpi_threshold_Xg
    
    Also the difference of RSSI of a new and an old AP must be above the diffsnr
    threshold for the steer to trigger
    
    ```
    config sta_steering
    	option diffsnr '8'
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    ### Steer Exclude
    
    There are two steering disallowed lists maintained in the controller:
    - steer_exclude (per node) – exclude STA from steering completely
    - steer_exclude_btm (per node) – do not allow to steer of the STA using BTM
    steering (but association control based steering will be possible in the future – once implemented).
    
    To put the STA on either of two lists one must just add a list entry per node in
    mapcontroller UCI config as in example:
    
    ```
    config node 'node_46d4376af4c0'       
            option agent_id '46:d4:37:6a:f4:c0'      
            list steer_exclude 'e0:d4:e8:79:c4:ee'   
            list steer_exclude 'e0:d4:e8:79:c4:11'   
            list steer_exclude_btm 'aa:bb:cc:dd:ee:ff'
    ```
    Removing STA MAC from the list will result in immediate allowing of the STA to
    be (BTM) steered again.
    
    
    ## Dynamic Controller Sync
    
    In a mesh where the controller node may change and taken by any device in the
    network, it is important to keep all mapcontroller configs in-sync. If not, the
    credentials, polices etc. may change upon a new device taking the controller
    role resulting in disruption for the clients in the network. While the logic for
    this primarily resides in the map-agent, it does have to be compile-time
    selected into mapcontroller in order for it to be supported.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    This compile-time flag for map-controller is
    `CONTROLLER_SYNC_DYNAMIC_CNTLR_CONFIG`.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Additionally, in ieee1905 and map-agent:
    * map-agent - `AGENT_SYNC_DYNAMIC_CNTLR_CONFIG`
    * ieee1905 - `MULTIAP_DYNAMIC_CNTLR_SYNC_CONFIG`
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    ## 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.
    
    
    ```
    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.
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ## DPP Easy Connect
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Wi-Fi QR Code based Onboarding
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    NOTE: The enrollee and the controller/configurator device must be operating at
    the same channel, as off channeling listening for DPP Chirp messages is
    currently not supported.
    
    To perform DPP Easy Connect, the enrollees bootstrap information must provided
    to the map-controller via its UBUS API:
    
    ```
    ubus call map.controller dpp_enrollee_uri '{"uri":"DPP:C:128/44;M:44d43771bb2f;V:2;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADa1Eoz/Lz0u0XO+Y+786MMst2kqGFJmCb8iOQWcekwS8=;;"}'
    ```
    
    All provided URIs are stored in reboot persistent memory in
    `/etc/multiap/dpp_uris.json`:
    
    ```
    root@eagle-44d43771bf50:~# cat /etc/multiap/dpp_uris.json
    {"uris":[{"uri":"DPP:C:81\/1;M:44d43771bb2e;V:2;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACQiHpcmOs5LhdwCBylPoDRdVS21swh6nrM+XQxGnGpG0=;;","type":"qr"}]}
    ```
    
    If map-controller is compiled with the ubus debug method (default) it can
    additionally be observed from its debug object:
    
    ```
    root@eagle-44d43771bf50:~# ubus call map.controller.dbg list_uris
    {
    	"uris": [
    		{
    			"macadr": "44:d4:37:71:bb:2e",
    			"type": "qrcode",
    			"uri": "DPP:C:81/1;M:44d43771bb2e;V:2;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACQiHpcmOs5LhdwCBylPoDRdVS21swh6nrM+XQxGnGpG0=;;",
    			"hashlen": 32,
    			"frames": [
    
    			]
    		}
    	]
    }
    ```
    
    For map-controller to accept the URI, some optional fields are mandated:
    * Opclass/Channel list must be provided. In the case of multiple, each
    Opclass/Channel must be provided separately, i.e. C:128/44,128/36;
    * The enrolle mac address must be included and match the backhaul station mac address
    of the enrollee.
    
    
    Once the map-controller has received the enrollee URI, it will listen and parse
    its chirps and proceed to onboard the enrollee onto the network.
    
    NOTE: Legacy AKMs are strongly recommended, as backhaul configuration Request/Response/Result
    are not yet implemented, fronthaul configurations relies on AP-Autoconfiguration,
    which does not support passing DPP AKMs. With this said, it is possible to onboard
    via DPP only AKMs and establish a connection.
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Ethernet QR Code based Onboarding
    
    DPP Ethernet onboarding is implemented leveraging
    [libdpp](https://dev.iopsys.eu/multi-ap/libdpp).
    
    For DPP Ethernet onboarding, no additional configuration sections needs to be
    present, but map-controller must be compiled with the CLFAGS including `USE_LIBDPP`.
    
    The credentials that are provisioned are picked up based on the backhaul `ap`
    sections in the map-controller configuration file.
    
    To perform DPP Ethernet onboarding, the enrollees bootstrap information must
    provided to the map-controller via its UBUS API `dpp_enrollee_uri_eth`:
    
    ```
    ubus call map.controller dpp_enrollee_uri_eth '{"uri":"DPP:C:81/1,115/36;V:2;K:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgACcwPoTjXxtZ2IJAjyZeH1kECGHXGhxhEEyPzcnpFo2ms=;;"}'
    ```
    
    Once provided, map-controller will be able to perform DPP Ethernet onboarding,
    triggered by AP-Autoconfig Search and DPP Direct Encapsulated messages.
    
    
    ## Control Depth of a Multi-AP Network
    
    Limit the max number of Wi-Fi backhaul links that are allowed in "daisy-chained"
    topology. By default the feature is disabled, which means that the EasyMesh
    network is not limited to any number of Wi-Fi backhaul hops.
    
    ```
    config controller 'controller'
    	option enabled '1'
    	...
    	option max_node_bh_hops '2'        # number of allowed Wi-Fi hops
    ```
    
    NOTE: Ethernet daisy-chains are still supported at any length, and forming a
    daisy-chain with Eth to Wi-Fi is still possible.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ## UBUS APIs
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Map-controller offers a variety of UBUS APIs, most of them map to CMDU request
    messages. The exceptions to this are:
    * `status` - Shows mapcontrollers view of the network and some stored data for
    each agent
    * `timers` - Will show time remaining till certain internal timers are triggered
    (so far only channel planning timers are added)
    * `steer_summary` and `steer_history` - Maps to TR-181 data model.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    root@eagle-44d43771bf50:~# ubus -v list map.controller
    'map.controller' @52dd51f5
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"status":{}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"status_full":{}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"timers":{}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"dpp_enrollee_uri":{"uri":"String","type":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"steer_summary":{"sta":"String"}
    	"steer_history":{"sta":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"ap_caps":{"agent":"String"}
    	"sta_caps":{"agent":"String","sta":"String","bssid":"String"}
    
    	"channel_pref":{"agent":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"channel_recalc":{"agent":"String","skip_dfs":"Boolean"}
    	"channel_cleanup":{"agent":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"bk_steer":{"agent":"String","bssid":"String","channel":"Integer","op_class":"Integer","bksta":"String"}
    	"agent_policy":{"agent":"String","radiolist":"Array","bsslist":"Array"}
    
    	"channel_select":{"agent":"String","radio_id":"String","class_id":"Integer","channel":"Array","preference":"Integer","transmit_power":"Integer"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"reconfig_ap":{"agent":"String"}
    
    	"steer":{"agent":"String","src_bssid":"String","sta":"Array","target_bssid":"Array","steer_timeout":"Integer","btm_timeout":"Integer","steer_req_mode":"Boolean"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"client_assoc_cntlr":{"agent":"String","bssid":"String","assoc_cntl_mode":"Integer","assoc_valid_timeout":"Integer","stalist":"Array"}
    	"ap_metric_query":{"agent":"String","bsslist":"Array","radiolist":"Array"}
    
    	"scan":{"agent":"String","radio":"Array","opclass":"Array","channel":"Array","fresh_scan":"Boolean"}
    
    	"scan_results":{"radio":"Array"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"sta_metric_query":{"agent":"String","sta":"String"}
    
    	"unassoc_sta_lm_query":{"agent":"String","opclass":"Integer","metrics":"Array"}
    	"bcn_metrics_query":{"agent":"String","sta":"String","opclass":"Integer","channel":"Integer","bssid":"String","reporting_detail":"Integer","ssid":"String","channel_report":"Array","request_element":"Array"}
    
    	"bcn_metrics_resp":{"sta":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"bk_caps":{"agent":"String"}
    	"topology_query":{"agent":"String"}
    
    	"cac_req":{"agent":"String","radiolist":"Array"}
    	"cac_term":{"agent":"String","radiolist":"Array"}
    	"higher_layer_data":{"agent":"String","protocol":"Integer","data":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"send_combined_metrics":{"agent":"String","bssid":"String"}
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	"dpp_cce_indication":{"agent":"String","cce_advertise":"Boolean"}