MAP Agent
Introduction
This package provides the mapagent daemon, which is responsible for
configuring wireless credentials, vlans etc.
Today map-agent is bridge centered, and it is expected that there is a 'main'
bridge which holds the uplink interface, as specified by al_bridge in the
mapagent config.
Overview
This README will show how to properly setup the mapagent configuration file and explain some key features of map-agent.
UCI Configuration
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'
config controller_select
option local '0'
option id 'auto'
option probe_int '20'
option retry_int '9'
option autostart '1'
config ap
option ifname 'wl0.1'
option band '5'
option device 'wl0'
config ap
option ifname 'wl1.1'
option band '2'
option device 'wl1'
config bsta
option ifname 'wl0'
option band '5'
option device 'wl0'
option priority '1'
config bsta
option ifname 'wl1'
option band '2'
option device 'wl1'
option priority '2'
config bsta
option ifname 'wl2'
option band '5'
option device 'wl2'
option priority '0'
config radio
option device 'wl2'
option band '5'
option dedicated_backhaul '1The important part of this configuration file is to properly align the wireless configuration with the mapagent configuration for the default setup.
Interface which are not included in the config will never be torn down or modified by mapagent, thus if desired, interfaces may left out of multi-ap management.
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 ieee80211v '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 ieee80211v '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'
Radios
The radio section will primarily hold the band, device and whether the
radio is a dedicated backhaul, meaning no fronthaul interfaces will be
configured on this radio via AP-Autoconfig. This section will be auto-generated
on startup by mapagent if not present.
An example config:
config radio
option device 'wl2'
option band '5'
option dedicated_backhaul '1'Interfaces
When specifying an interface in the mapagent configuration file, there are four parameters that must be kept in consideration:
- Whether the interface is backhaul/fronthaul (
ap) or backhaul station interfaces (bsta). - Band of the interface, to be provided as i.e.
option band '2' - Interface name, to be provided as i.e.
option ifname 'wl0.1' - Device that the interface belongs to, to be provided as i.e.
option device 'wl0'
Fronthaul Interfaces
Fronthaul interfaces are ap sections with type 'fronthaul' set. This
section may also include the options ssid, key, encryption, and vid.
Today these are not mandatory, but will be written automatically during
AP-Autoconfiguration.
config ap
option ifname 'wl0.1'
option band '5'
option device 'wl0'
option ssid 'MAP-44D4376AF7F0-5GHz'
option key 'IFJBD2RGYLZ3NE'
option encryption 'psk2+aes'
option type 'fronthaul'
option vid '1'Backhaul Interfaces
Backhaul interfaces are ap sections with type 'backhaul' set. This
section may also include the options ssid, key, encryption, enabled,
vid and a disallow_bsta list. Today these are not mandatory, but will be
written automatically during AP-Autoconfiguration.
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'
option type 'backhaul'
option disallow_bsta '0'
option vid '1'
option enabled '1'Combined Front/Back Interfaces
Combined fronthaul/backhaul interfaces are ap sections with
type 'combined' set. This section may also include the options ssid, key,
encryption, and vid. Today these are not mandatory, but will be
written automatically during AP-Autoconfiguration.
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'
option type 'combined'
option vid '1'
option enabled '1'Backhaul Station Interfaces
Backhaul station interfaces are bsta sections.
Backhaul interface sections will be generated automatically by map-agent upon startup. This is because it is assumed a backhaul station is only relevant in a multi-ap network scenario.
Once onboarded, a bsta may be marked as option onboarded '1' by map-agent,
along with the respective radio section. An onboarded backhaul station
may look as follows:
config bsta
option ifname 'wl0'
option band '5'
option device 'wl0'
option onboarded '1'
option priority '0'The option priority will default to 2.
Onboarding
Onboarding encompasses WPS pushbutton event, backhaul credential exchange and establishment of the wireless link between two devices.
The prerequisites will be written from a dedicated backhaul and fronthaul
interface. If using a combined fronthaul/backhaul interface the steps still
apply, with the exception of the uci options multi_ap_backhaul_ssid and
multi_ap_backhaul_key may be left out, and WPS be started 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 compatible band and channel for the WPS exchange to take place.
- The wireless uci configuration must have the backhaul credentials in the
fronthaul secition under the keys
multi_ap_backhaul_ssidandmulti_ap_backhaul_key. - Enrollee backhaul sta interface must not be a part of a bridge
- Enrollee and registrar interface must both have the multi_ap options set in the wireless config (1 and 2 respectively) for the multiap IE to be passed.
How to Start
With the prerequisites in place, on the registrar, WPS must be started on the
fronthaul interface with role registrar (default), as backhaul interfaces 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"}'
On the enrollee side, wps must be performed over the backhaul station 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" }}Mapagent will pick up this ubus event and add these credential to the uci
wireless section and reload wifi, after which wpa_supplicant will establish a
connection to the backhaul interface, over the backhaul station interface.
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"}} }
mapagent will issue DHCP to verify that it has entered 4address mode (wds link is up and added to the bridge on registrar) before adding the backhaul station to the bridge.
Once backhaul station is in the bridge, onboarding is complete.
AP-Autoconfig
AP-Autoconfig includes the triggering of AP-Autoconfig Search, AP-Autoconfig Response and AP-Autoconfig WSC and the configuration of the credentials provided with the AP-Autoconfig WSC.
This will not include how to configure mapcontroller.
Prerequisites
- Mapcontroller must be active in the network.
Mechanics
AP-Autoconfig has a certain set of triggers with slight behavior differences. When understanding the different triggers, it is necessary to understand that during AP-Autoconfig, every radio will do its independent process, meaning AP-Autoconfig Search, Response and WSC.
Radio State
When a radio is available to be configured, will be consiered in an 'active' state, and when it is periodically probing it is considered to be in a 'heartbeat' state.
Some conditions that will set map-agent to an 'active' state
- Upon mapagent (re)start
- Establishing a connection over backhaul interface
- No mapcontroller is observed for
probe_int*retry_int - New mapcontroller is discovered
Search Triggers
All the triggers listed in Radio State will trigger AP-Autoconfig Search within a set time out (at most 5 seconds, depending on the event). Additionally it may be triggered by:
- Periodic interval
probe_int(defaults to 20s) - Connecting ethwan port.
Upon Completion
After AP-Autoconfig is completed, for a respective radio, there will be an event published over ubus:
{ "wifi.radio": {"ifname":"wl0","event":"ap-autoconfiguration","data":{"status":"success","reason":"completed"}} }Map-agent will wait for 5 seconds to account for any disruption and delayed CMDUs and then restart wifi - to be sure that all WSC that are coming over the link are received and processed.
After processing of the WSC CMDUs the 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'
option controller_macaddr 'ee:6c:9a:52:b0:27'
config controller_select
option local '0'
option id 'auto'
option probe_int '20'
option retry_int '9'
option autostart '1'
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'
option type 'fronthaul'
option enabled '1'
option vid '1'
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'
option type 'fronthaul'
option enabled '1'
option vid '1'
config bsta
option ifname 'wl0'
option band '5'
option device 'wl0'
option priority '1'
option enabled '0'
config bsta
option ifname 'wl1'
option band '2'
option device 'wl1'
option priority '2'
option enabled '0'
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'
config radio
option device 'wl2'
option band '5'
option dedicated_backhaul '1'
option onboarded '1'
config radio
option device 'wl0'
option band '5'
config radio
option device 'wl1'
option band '2'
config policy
option pvid '1'
option pcp_default '0'
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'
option type 'backhaul'
option enabled '1'
option disallow_bsta '0'
option vid '1'
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'
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 ieee80211v '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 ieee80211v '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 ieee80211v '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 ieee80211v '1'
option ieee80211w '2'
option start_disabled '0'
option uuid 'cfa7df87-06a3-5daf-911f-ec6c9a52acb7'
option hidden '0'Do note that a backhaul station interface will never be torn down by mapagent.
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:
-
If a MAP Controller is NOT running in the own device, then update its Controller-ID and the last-seen timestamp.
-
If a MAP Controller is running in its own device, and local = true, then notify the detected Controller to user (e.g.: over UBUS).
-
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:
-
When autostart = true, the MAP Agent will try to start the MAP Controller locally (*). Report status of the MAP Controller start to user (e.g.: over UBUS).
-
When autostart = false, 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:
Main Device (i.e. SmartHub3/Fibertwist): Controller to be run in a designated node only.
config controller_select
option local ‘true’Repeater Device (Disc/EX600): Controller start/stop automatically if another is not detected in the network.
config controller_select
option local ‘false’
option autostart ‘true’uBus
root@iopsys:~# ubus -v list map.agent
'map.agent' @21e6fc02
"apconfig":{"band":"Integer"}
"steer_policy":{"vif":"String","rule":"String"}
"steer":{"vif":"String","type":"String","sta":"String","to_bss":"Array","optime":"Integer"}
"assoc_control":{"vif":"String","sta":"String","enable":"Boolean","time":"Integer"}
"bcn_metrics_query":{"agent":"String","sta":"String","opclass":"Integer","channel":"Integer","bssid":"String","reporting_detail":"Integer","ssid":"String","channel_report":"Array","request_element":"Array"}
"unassoc_sta_lm_query":{"agent":"String","opclass":"Integer","metrics":"Array"}
"cmd":{"id":"Integer","data":"String"}
"higher_layer_data":{"agent":"String","protocol":"Integer","data":"String"}
"status":{}
"info":{}
"assoc_notify":{"bss_status_list":"Array"}