Skip to content
Snippets Groups Projects
README.md 43.8 KiB
Newer Older
  • Learn to ignore specific revisions
  • # MAP Agent
    
    Andreas Jonson's avatar
    Andreas Jonson committed
    
    
    [Map-agent](https://dev.iopsys.eu/iopsys/map-agent)
    
    
    
    ## Introduction
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    This package provides the mapagent daemon, which implements the WiFi Alliances
    Easymesh Agent component.
    
    
    ## Overview
    
    This README will show how to properly setup the mapagent configuration file
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    and explain some key features of map-agent:
    
    * Onboarding
    * AP-Autoconfiguration
    * Controller Discovery
    * Dynamic Controller Sync
    * Dynamic Backhaul Upgrade
    * Island Prevention
    
    
    ## UCI Configuration
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    For full documentation of UCI configuration options, see
    [UCI docs](./docs/api/mapagent.md).
    
    
    When starting map-agent, the only _mandated_ section is the global agent
    section:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    ```
    config agent 'agent'
    	option enabled '1'
    	option debug '0'
    	option profile '2'
    	option brcm_setup '1'
    	option al_bridge 'br-lan'
    	option netdev 'wl'
    	option island_prevention '0'
    	option eth_onboards_wifi_bhs '1'
    	option guest_isolation '1'
    	option scan_on_boot_only '0'
    ```
    
    All the remaining mandatory (`radio`) and optionally mandatory (`ap`) may
    be generated by map-agent at start-up. Whereas the non-mandatory sections may
    use their default values.
    
    The `ap` sections will be automatically generated based on the presence of a
    `multi_ap` flag in the wireless configuration file under the `wifi-iface`
    sections. If such a flag is set, map-agent assumes it is a multi_ap interface.
    Nonetheless, it is recommended that the map-agent configuration is aligned
    with the respective `ap` section for each interface that is to be a part of the
    mesh and managed by map-agent. For more information on how to align the
    map-agent and wireless configuration file, see the quick start [guide](./docs/QUICK_START.md).
    Additional interfaces may be generated at runtime, as dictated by mapcontroller.
    
    Existing interfaces *not* included in the configuration will not be a part of
    the mesh, meaning no statistics will be gathered, clients steered and the
    interface will never be torn down or otherwise configured by mapagent.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    To summarize:
    
    * Mapagent may automatically generate mandatory `radio` and optionally mandatory
    `ap` sections
    * Mapagent will manage all interface provided within its configuration file
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    * Mapagent will not touch interfaces not in its configuration file. They will
    be left intact (and outside of the mesh) and be interleaved with any additional
    interfaces provided by mapcontroller
    * Mapagent will create interfaces as necessary, adding them to both mapagent
    and wireless configuration files
    
    
    **Some notes concerning multiap configuration files.**
    While preparing the */etc/config/wireless* configuration, please note that some options may be changed during autoconfiguration proces.
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    Such options are wps_pushbutton and hidden of wifi-iface section. Actions taken and final value of those options depends mainly on type
    
    of multi_ap interface (value of option multi_ap in current wifi-iface section).
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    
    
    For backhaul interfaces where
    ```
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    option multi_ap '1'
    ```
    following rules apply:
    
    * 'hidden' option when provided stays as it is,
    * if 'hidden' option is not provided in that wifi-iface section, it is set to hidden=1 by adding
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    
    
    For fronthaul and combined interfaces where
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    option multi_ap '2'
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    option multi_ap '3'
    ```
    
    following rules apply:
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    * 'wps_pushbutton' option when provided stays as it is,
    
    * if 'wps_pushbutton' option is not provided in that wifi-iface section, it is set to wps_pushbutton=1 by adding
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    option wps_pushbutton '1'
    ```
    
    
    Additional rule apply when traffic separation is enabled in */etc/config/mapcontroller* by
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    option enable_ts '1'
    ```
    
    in controller section of that config.
    
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    Additional rule concerns guest network which should be added in */etc/config/mapcontroller* file always after already existing networks.
    
    This rule is that guest network will always have wps_pushbutton disabled by
    
    Marek Puzyniak's avatar
    Marek Puzyniak committed
    ```
    option wps_pushbutton '0'
    ```
    always placed in that wifi-iface section.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ### Example Start Configurations
    
    
    A default configuration file may look as such:
    
    ```
    config agent 'agent'
    	option enabled '1'
    	option debug '0'
    	option profile '2'
    	option brcm_setup '1'
    	option al_bridge 'br-lan'
    	option netdev 'wl'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option island_prevention '0'
    
    config dynamic_backhaul
    	option missing_bh_timer '60'
    
    
    config controller_select
    	option local '0'
    	option id 'auto'
    	option probe_int '20'
    
    	option retry_int '9'
    
    	option autostart '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.1'
    
    	option band '5'
    	option device 'wl0'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl1.1'
    	option band '2'
    	option device 'wl1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl0'
    	option band '5'
    	option device 'wl0'
    
    	option priority '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl1'
    	option band '2'
    	option device 'wl1'
    
    	option priority '2'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl2'
    	option band '5'
    	option device 'wl2'
    	option priority '0'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config radio
    
    	option device 'wl2'
    	option band '5'
    	option dedicated_backhaul '1
    
    ```
    
    The above example of a mapagent config would map properly against the
    following wireless configuration file:
    
    ```
    config wifi-device 'wl0'
    	option type 'mac80211'
    
    	option channel 'auto'
    
    	option hwmode '11a'
    	option country 'DE'
    	option htmode 'HE80'
    	option apsta '1'
    	option phy 'phy0'
    
    config wifi-iface 'default_wl0'
    	option device 'wl0'
    	option network 'lan'
    	option ifname 'wl0.1'
    	option mode 'ap'
    
    	option ssid 'iopsysWrt-EC6C9A52ACB7'
    
    	option encryption 'psk2'
    
    	option key 'wifiEC6C9A52ACB7'
    
    	option wps '1'
    	option wps_pushbutton '1'
    	option ieee80211k '1'
    	option bss_transition '1'
    	option multi_ap '2'
    
    config wifi-device 'wl1'
    	option type 'mac80211'
    
    	option channel 'auto'
    
    	option hwmode '11g'
    	option country 'DE'
    	option htmode 'HE20'
    	option apsta '1'
    	option phy 'phy1'
    
    config wifi-iface 'default_wl1'
    	option device 'wl1'
    	option network 'lan'
    	option ifname 'wl1.1'
    	option mode 'ap'
    
    	option ssid 'iopsysWrt-EC6C9A52ACB7'
    
    	option encryption 'psk2'
    
    	option key 'wifiEC6C9A52ACB7'
    
    	option wps '1'
    	option wps_pushbutton '1'
    	option ieee80211k '1'
    	option bss_transition '1'
    	option multi_ap '2'
    
    
    config wifi-device 'wl2'
    	option type 'mac80211'
    	option channel 'auto'
    	option hwmode '11a'
    	option country 'DE'
    	option htmode 'HE80'
    	option apsta '1'
    	option phy 'phy2'
    
    config wifi-iface 'default_sta_wl1'
    	option device 'wl1'
    	option mode 'sta'
    	option ifname 'wl1'
    	option multi_ap '1'
    	option disabled '0'
    
    config wifi-iface 'default_sta_wl0'
    	option device 'wl0'
    	option mode 'sta'
    	option ifname 'wl0'
    	option multi_ap '1'
    	option disabled '0'
    
    config wifi-iface 'default_sta_wl2'
    	option device 'wl2'
    	option mode 'sta'
    	option ifname 'wl2'
    	option multi_ap '1'
    	option disabled '0'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    The `radio` section will primarily hold the band, device name and whether the
    
    radio is a dedicated backhaul. Dedicated backhaul means no AP interfaces
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    will be configured on the radio via AP-Autoconfig.
    
    Radio sections will be auto-generated on startup by mapagent if not present.
    
    
    An example config:
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config radio
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option device 'wl0'
    
    	option band '5'
    	option dedicated_backhaul '1'
    ```
    
    
    More radio specific configuration and policies will by the map-controller within
    the Multi-AP Policy Config Request CMDU.
    
    
    ### Interfaces
    
    When specifying an interface in the mapagent configuration file, there are four
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    parameters that must be set.
    
    Map-agent configuration divides interfaces into different section types, based
    
    on the interface type. Backhaul station interfaces are defined with the section
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    type `bsta`:
    
    ```Minimum BSTA configuration
    config bsta
    	option ifname 'wl1'
    	option band '2'
    	option device 'wl1'
    ```
    
    Fronthaul and backhaul BSS are created with the section type `ap`:
    
    ```Minimum AP configuration
    config ap
    	option ifname 'wl1.1'
    	option band '2'
    	option device 'wl1'
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Each interface section must at minimum contain the options:
    
    * `band` - Set `2` for 2.4GHz, `5` for 5GHz and `6` for 6GHz
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    * `ifname` - Interface name
    * `device` - Device name (i.e. radio name)
    
    An `ap` section may optionally include:
    * `type` - Human readable multi_ap flag. (`backhaul`, `fronthaul`, `combined`)
    * `ssid` - SSID of this AP
    * `key` - Key of this AP
    * `encryption` - Encryption used by this AP
    * `vid` - VLAN ID handled by this AP, if any
    * `enabled` - If interface is enabled and written to hostapd config.
    * `disallow_bsta` - Disallow connections from certain Multi-AP profiles. Used as
    bitmap.
    
    All optional arguments will be provided within WSC M2 provided by
    map-controller. If an AP is provided within a WSC M2 but there are no AP
    sections available within map-agent configuration, map-agent will generate a new
    interface section for it.
    
    
    #### Fronthaul Interfaces
    
    
    Fronthaul interfaces are `ap` sections with `type 'fronthaul'` set.
    
    
    Simon Tate's avatar
    Simon Tate committed
    Applicable options: `ssid`, `key`, `encryption`, `vid`, `enabled`.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.1'
    	option band '5'
    	option device 'wl0'
    	option ssid 'MAP-44D4376AF7F0-5GHz'
    	option key 'IFJBD2RGYLZ3NE'
    	option encryption 'psk2+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'fronthaul'
    
    	option vid '1'
    
    	option enabled '1'
    
    ```
    
    #### Backhaul Interfaces
    
    
    Backhaul interfaces are `ap` sections with `type 'backhaul'` set.
    
    
    Simon Tate's avatar
    Simon Tate committed
    Applicable options: `ssid`, `key`, `encryption`, `vid`, `enabled` and
    
    `disallow_bsta`.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.2'
    	option band '5'
    	option device 'wl0'
    	option ssid 'MAP-44D4376AF7F0-BH-5GHz'
    	option key 'd6971d59b096ba3906d20f50dde7e19e7159dfe6eea1765a414e17c90aaefe7a'
    	option encryption 'psk2+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'backhaul'
    
    	option disallow_bsta '0'
    	option vid '1'
    
    	option enabled '1'
    
    ```
    
    
    #### Combined Front/Back Interfaces
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Combined fronthaul/backhaul interfaces are `ap` sections with
    
    `type 'combined'` set.
    
    
    Simon Tate's avatar
    Simon Tate committed
    Applicable options: `ssid`, `key`, `encryption`, `vid`, `enabled` and
    
    `disallow_bsta`.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.1'
    	option band '5'
    	option device 'wl0'
    	option ssid 'MAP-44D4376AF7F0-COMBINED-5GHz'
    	option key 'IFJBD2RGYLZ3NE'
    	option encryption 'psk2+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'combined'
    
    	option disallow_bsta '0'
    
    	option vid '1'
    
    	option enabled '1'
    
    ```
    
    
    #### Backhaul Station Interfaces
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Backhaul station interfaces are `bsta` sections.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    If not present in map-agent configuration, all interfaces in the wireless
    configuration with `option mode 'sta'` will be automatically added to map-agent
    configuration.
    
    
    Once WPA onboarded, map-agent will set `option onboarded '1'` along with the
    passed credentials.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    An onboarded backhaul station may look as follows:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option ifname 'wl1'
    	option band '2'
    	option device 'wl1'
    	option priority '2'
    	option encryption 'sae-mixed'
    	option ssid 'MAP-021000000001-BH-2.4GHz'
    	option key '569dfdc9447e494da231d4def3441ed92c8f63985d8992cb521d77e1763c00d'
    
    	option onboarded '1'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option vid '1'
    	option bssid '0e:10:00:00:00:04'	# set upon connection
    	option enabled '1' 			# managed by mapagent for dynamic backhaul
    
    ### Multi-Link Operation
    
    Map-agent supports Multi-Link Operation (MLO) as configured by map-controller
    via Agent AP MLD Configuration TLVs and Backhaul STA MLD Configuration TLVs.
    
    ### Prerequisite
    If the device supports MLO, as can be observed via wifimngr output:
    
    ```
    root@iopsys:~# ubus call wifi.radio.radio0_band0 status
    {
            "radio": "radio0_band0",
            "phyname": "phy0",
            "macaddr": "ac:91:9b:b7:03:ec",
    	...
            "mlo_capable": true,
            "ap_caps": {
                    "emlsr_supported": true,
                    "emlmr_supported": false,
                    "max_links": 4,
                    "ttlm": 2
            },
            "sta_caps": {
                    "emlsr_supported": false,
                    "emlmr_supported": false,
                    "max_links": 0,
                    "ttlm": 0
            },
    ```
    
    If MLO support is indicated by the driver as can be observed by
    `"mlo_capable": true` the `ap_caps` and `sta_caps` array indicate the supported
    MLO operational modes.
    
    Additionally then, MLO must be configured in the repsective device's wireless
    configuration:
    
    ```
    config wifi-device 'radio0_band1'
    	...
    	option mlo '1'
    	option mlo_capable '1'
    ```
    
    #### Interfaces
    
    #### Map-agent
    If supported and the respective TLVs are provided by the map-controller,
    map-agent will create an `mld` configuration section in its UCI configuration.
    
    ```
    config mld
    	option id '1'
    	option ssid 'IOWRT-MLO-SSID'
    	option key '1234567890'
    	option type 'fronthaul'
    ```
    
    Each interface provided via AP-Autoconfiguration WSC message that has the
    same SSID as provided via the Agent AP MLD Configuration TLV will be added to
    the MLD by adding the option `mld_id` with the corresponding id.
    
    ```
    config ap
    	option ifname 'wlan01-1'
    	option band '5'
    	option device 'radio0_band1'
    	option ssid 'IOWRT-MLO-SSID'
    	option key '1234567890'
    	option encryption 'sae-mixed'
    	option type 'fronthaul'
    	option disallow_bsta '0'
    	option vid '1'
    	option enabled '1'
    	option mld_id '1'
    ```
    
    #### Wireless
    
    Similarily in the wireless UCI configuration, map-agent will generate the
    `wifi-mld` section with the respective configuration.
    
    ```
    
    config wifi-mld 'mld1	'
    
    	option ifname 'wlan0'
    	option sae_pwe '2'
    	option ssid 'IOWRT-MLO-SSID'
    	option key '1234567890'
    ```
    
    By adding the option `mld` to the interface configuration, the interface is
    added to the MLD.
    
    ```
    config wifi-iface 'default_wl0'
    	option device 'wl0'
    	option network 'lan'
    	option ifname 'wl0.1'
    	option mode 'ap'
    	option ssid 'iopsysWrt-EC6C9A52ACB7'
    	option encryption 'psk2'
    	option key 'wifiEC6C9A52ACB7'
    	option wps '1'
    	option wps_pushbutton '1'
    	option ieee80211k '1'
    	option bss_transition '1'
    	option multi_ap '2'
    	option mld 'mld1'
    ```
    
    
    ## Onboarding
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Onboarding includes backhaul credential exchange and establishment of the
    wireless link between two devices.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    This guide will focus on onboarding from a backhaul STA towards a
    backhaul BSS. If using a combined fronthaul/backhaul interface the steps still
    
    apply, with the exception of the uci options `multi_ap_backhaul_ssid` and
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    `multi_ap_backhaul_key` may be left out, and WPS be started directly on the
    combined interface.
    
    
    ### Prerequisites
    
    * To perform onboarding, mapagent must be running at both the registrar
    and enrollee node.
    * The registrar radio and enrollee radio must be running in a
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    compatible band
    
    * The wireless uci configuration must have the backhaul credentials in the
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    fronthaul section under the keys `multi_ap_backhaul_ssid` and
    
    `multi_ap_backhaul_key` (Automatically generated after AP-Autoconfiguration).
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    * The enrollee backhaul STA interface must not be a part of a bridge
    * Enrollee and registrar interface must both have the multi_ap options properly
    set in the wireless config (multi_ap '1' for STA and backhaul BSS, multi_ap '2'
    for fronthaul BSS) for the multiap IE to be passed.
    * It is recommended that `option channel 'auto'` is set for the backhaul STA
    radio in its wireless configuration.
    
    
    ### How to Start
    
    With the prerequisites in place, on the registrar, WPS must be started on the
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    fronthaul interface with role registrar (default), as backhaul BSS do not
    
    support WPS. However, with the `multi_ap` options set appropriately in the
    wireless configuration file a multiap IE will be passed with the WPS and the
    backhaul credentials be provided to the enrollee.
    
    Registrar:
    * `ubus call wifi.wps start '{"ifname":"wl0"}'`
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    On the enrollee side, wps must be performed over the backhaul STA interface,
    
    and the role `bsta` must be passed.
    
    Enrollee:
    * `ubus call wifi.wps start '{"ifname":"wl0", "role":"bsta"}'`
    
    When the devices pair, the credentials will be published as ubus event:
    ```
    { "wps_credentials": {"ifname":"wl0","encryption":"psk2", "ssid":"iopsysWrt-BACKHAUL-5GHz","key":"12345678BACKHAUL" }}
    ```
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Mapagent will pick up this ubus event and add these credential to the mapagent
    and wireless configuration and load them in-memory to wpa_supplicant
    (backhaul STA), after which wpa_supplicant will establish a connection.
    
    
    When the `wifi.bsta` connection event comes over ubus:
    
    ```
    { "wifi.bsta": {"ifname":"wl0","event":"connected","data":{"macaddr":"0a:10:00:00:00:03","ssid":"iopsysWrt-BACKHAUL-5GHz"}} }
    
    ```
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Mapagent will then wait till that interface has fully transitioned into 4address
    mode before adding the backhaul station to the bridge.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Once the backhaul station is in the bridge, connectivity to the upstream device
    is established and onboarding is complete.
    
    
    
    ## AP-Autoconfig
    
    AP-Autoconfig includes the triggering of AP-Autoconfig Search, AP-Autoconfig
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Response, AP-Autoconfig WSC and the configuration of the credentials provided
    
    with the AP-Autoconfig WSC.
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    For how to configure mapcontroller for AP-Autoconfiguration, see
    
    [Map-Controller](https://dev.iopsys.eu/iopsys/map-controller).
    
    
    ### Prerequisites
    
    * Mapcontroller must be active in the network.
    
    ### Mechanics
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Map-agent is periodically sending AP-Autoconfig Search messages, to find the
    map-controller, as well as other agents in the mesh. When an
    
    AP-Autoconfiguration Response with SupportedRole=Controller is received,
    map-agent will send an AP-Autoconfig WSC M1 if it has not been configured
    already.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    
    The periodicity of AP-Autoconfig Search messages is set by `probe_int`
    
    (defaults to 20s if not set) in the mapagent configuration. Once autoconfigured
    an interval of 70s will be used as heartbeat timer.
    
    
    #### Radio State
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Map-agent maintains a radio state for each radio, to prevent redundent
    configurations messages. A radio can be in one of two states:
    * `AUTOCFG_ACTIVE` - If an AP-Autoconfig Response is received from a mapcontroller
    in this state, map-agent will send back an AP-Autoconfig WSC M1
    * `AUTOCFG_HEARTBEAT` - Map-agent is only sending AP-Autoconfig Searches in order
    to establish that mapcontroller is still available. No further action upon
    responses.
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Some conditions that will set map-agent radios to an active state
    
    * Upon mapagent (re)start
    
    * Establishing a first-time connection over a backhaul STA
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    * No mapcontroller is observed for `probe_int` * `retry_int` seconds
    * New mapcontroller is discovered (almac of controller changed)
    * Connection was lost for `missing_bh_timer` + 15 seconds
    
    * Backhaul STA connects to a different BSSID
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    #### Upon Receival of AP-Autoconfig WSC M2
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    After map-agent finds a controller and it has sent an AP-Autoconfig WSC (M1) to
    which the mapcontroller will answer with an AP-Autoconfig WSC (M2).
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Within the M2 map-agent will find credentials which it will write to the
    mapagent and wireless configurations. After, it will schedule a wifi reload in 5
    seconds. The timeout is to account for any delayed CMDUs and batch the
    credentials rather than doing restarts one radio at a time. When a radio has
    been configured via an M2 there will be an event published over ubus:
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    { "map.agent": {"ifname":"wl0","event":"ap-autoconfiguration","data":{"status":"success","reason":"completed"}} }
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    After processing of the WSC CMDUs, mapagent config will have changed according
    to the received WSC:
    
    
    ```
    config agent 'agent'
    	option enabled '1'
    	option debug '0'
    	option profile '2'
    	option brcm_setup '1'
    	option al_bridge 'br-lan'
    	option netdev 'wl'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option island_prevention '0'
    
    	option controller_macaddr 'ee:6c:9a:52:b0:27'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config dynamic_backhaul
    	option missing_bh_timer '60'
    
    
    config controller_select
    	option local '0'
    	option id 'auto'
    	option probe_int '20'
    	option retry_int '9'
    	option autostart '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.1'
    	option band '5'
    	option device 'wl0'
    	option ssid 'MAP-EC6C9A52B027-5GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'fronthaul'
    
    	option enabled '1'
    	option vid '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl1.1'
    	option band '2'
    	option device 'wl1'
    	option ssid 'MAP-EC6C9A52B027-2.4GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'fronthaul'
    
    	option enabled '1'
    	option vid '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl0'
    	option band '5'
    	option device 'wl0'
    
    	option priority '1'
    	option enabled '0'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl1'
    	option band '2'
    	option device 'wl1'
    	option priority '2'
    	option enabled '0'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config bsta
    
    	option ifname 'wl2'
    	option band '5'
    	option device 'wl2'
    	option priority '0'
    	option encryption 'sae-mixed'
    	option ssid 'MAP-EC6C9A52B027-BH-5GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option default_disabled '0'
    	option onboarded '1'
    	option enabled '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config radio
    
    	option device 'wl2'
    	option band '5'
    	option dedicated_backhaul '1'
    
    	option onboarded '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config radio
    
    	option device 'wl0'
    	option band '5'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config radio
    
    	option device 'wl1'
    	option band '2'
    
    
    config policy
    	option pvid '1'
    	option pcp_default '0'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl0.2'
    	option band '5'
    	option device 'wl0'
    	option ssid 'MAP-EC6C9A52B027-BH-5GHz'
    
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'backhaul'
    
    	option enabled '1'
    
    	option disallow_bsta '0'
    	option vid '1'
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    config ap
    
    	option ifname 'wl1.2'
    
    	option band '2'
    	option device 'wl1'
    	option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
    
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae+aes'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    	option type 'backhaul'
    
    	option enabled '1'
    
    	option disallow_bsta '0'
    	option vid '1'
    ```
    
    And similarily the wireless config:
    
    
    ```
    
    config wifi-device 'wl0'
    	option type 'mac80211'
    	option channel 'auto'
    	option hwmode '11a'
    	option country 'DE'
    	option htmode 'HE80'
    	option apsta '1'
    	option phy 'phy0'
    
    config wifi-iface 'default_wl0'
    	option device 'wl0'
    
    	option network 'lan'
    
    	option ifname 'wl0.1'
    
    	option mode 'ap'
    
    	option wps '1'
    	option wps_pushbutton '1'
    
    	option ieee80211k '1'
    
    	option bss_transition '1'
    	option multi_ap '2'
    	option ssid 'MAP-EC6C9A52B027-5GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    	option ieee80211w '1'
    	option start_disabled '0'
    
    	option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
    
    	option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-5GHz'
    	option multi_ap_backhaul_key '7NTx-APvX-pba7-tvd7'
    
    config wifi-device 'wl1'
    	option type 'mac80211'
    	option channel 'auto'
    	option hwmode '11g'
    	option country 'DE'
    	option htmode 'HE20'
    	option apsta '1'
    	option phy 'phy1'
    
    config wifi-iface 'default_wl1'
    	option device 'wl1'
    
    	option network 'lan'
    
    	option ifname 'wl1.1'
    
    	option mode 'ap'
    
    	option wps '1'
    	option wps_pushbutton '1'
    
    	option ieee80211k '1'
    
    	option bss_transition '1'
    	option multi_ap '2'
    	option ssid 'MAP-EC6C9A52B027-2.4GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed+aes'
    	option ieee80211w '1'
    	option start_disabled '0'
    
    	option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
    
    	option multi_ap_backhaul_ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
    	option multi_ap_backhaul_key '7NTx-APvX-pba7-tvd7'
    
    config wifi-device 'wl2'
    	option type 'mac80211'
    	option channel 'auto'
    	option hwmode '11a'
    	option country 'DE'
    	option htmode 'HE80'
    	option apsta '1'
    	option phy 'phy2'
    
    config wifi-iface 'default_sta_wl1'
    	option device 'wl1'
    	option mode 'sta'
    	option ifname 'wl1'
    	option multi_ap '1'
    	option disabled '0'
    
    config wifi-iface 'default_sta_wl0'
    
    	option device 'wl0'
    	option mode 'sta'
    	option ifname 'wl0'
    	option multi_ap '1'
    
    	option ssid 'MAP-EC6C9A52B027-BH-5GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed'
    	option disabled '1'
    
    config wifi-iface 'default_sta_wl2'
    	option device 'wl2'
    	option mode 'sta'
    	option ifname 'wl2'
    	option multi_ap '1'
    
    	option disabled '0'
    	option ssid 'MAP-EC6C9A52B027-BH-5GHz'
    
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae-mixed'
    
    config wifi-iface 'wl0_2_ap'
    	option ifname 'wl0.2'
    
    	option network 'lan'
    
    	option ssid 'MAP-EC6C9A52B027-BH-5GHz'
    
    	option key '7NTx-APvX-pba7-tvd7'
    
    	option encryption 'sae+aes'
    
    	option mode 'ap'
    	option device 'wl0'
    
    	option multi_ap '1'
    
    	option ieee80211k '1'
    
    	option ieee80211w '2'
    	option start_disabled '0'
    
    	option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
    
    	option hidden '0'
    
    config wifi-iface 'wl1_2_ap'
    	option ifname 'wl1.2'
    
    	option network 'lan'
    
    	option ssid 'MAP-EC6C9A52B027-BH-2.4GHz'
    	option key '7NTx-APvX-pba7-tvd7'
    	option encryption 'sae+aes'
    
    	option mode 'ap'
    
    	option device 'wl1'
    
    	option multi_ap '1'
    	option ieee80211k '1'
    
    	option ieee80211w '2'
    	option start_disabled '0'
    
    	option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
    
    	option hidden '0'
    
    ```
    
    ## Controller Discovery
    
    
    ### UCI
    
    
    The following UCI config section in "mapagent" config is used to control how a
    
    MAP Controller is discovered and (auto)started/stopped on demand in a MAP
    network.
    
    ```
    config controller_select
    
    	option local     'true'
    	option id        'auto'
    	option probe_int '20'
    	option retry_int '3'
    	option autostart 'true'
    
    ```
    
    | Name	        | Type          | Required  | Default     | Description   |
    | ------------- |---------------| ----------|-------------|---------------|
    | local         | Boolean	| yes       | false	  | When set to true, the MAP Controller running in the same 1905 device as the MAP Agent, will be treated as the main or primary Controller. It takes precedence over others discovered in the network.		 |
    
    | id            | Mac address   | no        | auto-detect | User can provide the 1905 ALID of the device that will have the MAP Controller service. When set to 'auto', the MAP Agent will discover the MAP Controller ID. OPTION NOT YET SUPPORTED.		 |
    
    | probe_int     | Integer       | no        | 20s    	  |The time interval in seconds between controller discovery by the MAP Agent		 |
    | retry_int     | Integer       | no        | 15    	  |After these many failed attempts to discover a controller in the network, the agent will infer that the controller is not available and accordingly takes the next action.		 |
    
    | autostart     | Boolean       | no        | false    	  |When this is set to 'true', the agent will try to start the controller after not finding one in the network.		 |
    
    
    
    ### Algorithm
    
    During startup and at run-time, the MAP Agent will probe for the presence of a
    MAP Controller in the network.
    
    If it finds another, then take one of the following actions:
    
    1. If a MAP Controller is NOT running in the own device, then update its
    Controller-ID and the last-seen timestamp.
    
    2. If a MAP Controller is running in its own device, and local = true, then
    notify the detected Controller to user (e.g.: over UBUS).
    
    3. If a MAP controller is running in its own device, and local = false, then
    stop the local Controller. Update the Controller-ID and the last-seen timestamp.
    
    
    If after 'retry_int' number of times, the MAP Agent cannot discover a MAP
    
    Controller in the network, then take one of the following actions:
    
    
    1. When 'autostart' = true AND the compiler flag AGENT_DYNAMIC_CNTLR is set the
    MAP Agent will try to start the MAP Controller locally (see 'Notes'). It'll
    report status of the MAP Controller start to user (e.g.: over UBUS).
    
    2. When 'autostart' = false OR the compiler flag AGENT_DYNAMIC_CNTLR is NOT set
    the MAP Agent will simply report to user (over UBUS) that no Controller has been
    detected in the network.
    
    
    Notes:
        * The default time interval in seconds between controller discovery by the
        MAP Agent will increase to 70 seconds once Agent enters the heartbeat state
        (that is after controller discovery finished successfully).
        * Maximum time w/o controller in the network will be (probe_int * retry_int)
        - but not less than 75 seconds.
    * After detecting no Controller in the network, the MAP-Agent will try to start
    its local Controller after a random time chosen from a time window (10s). This
    helps to reduce the chance of multiple MAP-Agents trying to run the controller
    at the same time.
    
    ### Example
    
    While the aim for this controller discovery is to support the same configuration
    across all devices, one may want to have a designated mapcontroller device, then
    the following configuration may be used:
    
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Main Device: Controller to be run in a designated node only.
    
    
    ```
    config controller_select
    
    	option local 'true'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    Repeater Device: Controller start/stop automatically if another is not detected
    in the network.
    
    
    ```
    config controller_select
    
    	option local 'false'
    	option autostart 'true'
    
    Jakob Olsson's avatar
    Jakob Olsson committed
    ## Dynamic Controller Sync
    
    In a mesh where the controller node may change and taken up by any of the
    nodes in the mesh, it is important to keep all mapcontroller configs in sync. If
    not, when the controller role is taken by another node the credentials, polices
    etc. may change resulting in disruption for the clients in the network.
    
    This feature has to be compiled into multiple components by its compile-time
    flags.
    
    This compile-time flag are:
    * map-agent - `AGENT_SYNC_DYNAMIC_CNTLR_CONFIG`
    * map-controller - `CONTROLLER_SYNC_DYNAMIC_CNTLR_CONFIG`
    * ieee1905 - `MULTIAP_DYNAMIC_CNTLR_SYNC_CONFIG`
    
    This feature is additionally enabled or disabled via UCI configuration:
    
    ```
    onfig agent 'agent'
    	option dyn_cntlr_sync '1'
    ```
    
    ### Algorithm
    
    Dynamic controller sync leverages Higher Layer Data CMDUs to sync the
    credentials across the network. It uses a two or three step process, depending