From 3e6e113fdbfdb8a2e230fc74ebe8a36f9696ede2 Mon Sep 17 00:00:00 2001
From: Jakob Olsson <jakob.olsson@iopsys.eu>
Date: Wed, 7 Jul 2021 11:58:59 +0200
Subject: [PATCH] add README
---
README.md | 226 ++++++++++++++++++++++++++++---
{doc => docs}/MultiAP-IOPSYS.pdf | Bin
docs/api/mapcontroller.md | 1 +
schemas/uci/mapcontroller.json | 158 +++++++++++++++++++++
4 files changed, 369 insertions(+), 16 deletions(-)
rename {doc => docs}/MultiAP-IOPSYS.pdf (100%)
create mode 100644 docs/api/mapcontroller.md
create mode 100644 schemas/uci/mapcontroller.json
diff --git a/README.md b/README.md
index 6cbd3cff..438986be 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,218 @@
# MAP Controller
-Multi-AP Controller
+[Map-Controller](https://dev.iopsys.eu/iopsys/map-controller)
+
+
+## Introduction
+
+This package provides the `mapcontroller` daemon, which is responsible for
+distributing wireless credentials, vlan configuration and more.
+
+## Overview
+
+This READMe will show how to properly setup the mapcontroller configuration file
+and trigger mapcontroller functionality.
+
+## UCI Configuration
+
+A default configuration file may look as such:
+
+```
+config controller 'controller'
+ option enabled '1'
+ option registrar '5 2'
+ option debug '0'
+ option al_bridge 'br-lan'
+
+config vlan 'lan'
+ option network 'lan'
+ option id '1'
+
+config fh-credentials
+ option band '5'
+ option ssid 'MAP-44D4376AF600-5GHz'
+ option encryption 'psk2'
+ option key '5YXJOLWWQPGL2H'
+ option vlan '1'
+
+config fh-credentials
+ option band '2'
+ option ssid 'MAP-44D4376AF600-2.4GHz'
+ option encryption 'psk2'
+ option key '5YXJOLWWQPGL2H'
+ option vlan '1'
+
+config bk-credentials
+ option band '5'
+ option ssid 'MAP-44D4376AF600-BH-5GHz'
+ option encryption 'psk2'
+ option multi_ap '1'
+ option vlan '1'
+ option key '5f9f0ce167b43ec3b71915db7561932cb5d1f618ed8a83afd4f6d5db6f08cca8'
+
+config bk-credentials
+ option band '2'
+ option ssid 'MAP-44D4376AF600-BH-2.4GHz'
+ option encryption 'psk2'
+ option multi_ap '1'
+ option disallow_bsta '0'
+ option vlan '1'
+ option key '5f9f0ce167b43ec3b71915db7561932cb5d1f618ed8a83afd4f6d5db6f08cca8'
+```
+
+The important part of this configuration file is to properly setup the wireless
+credentials.
+
+### Fronthaul Credentials
+
+The section`fh-credentials` refers to fronthaul credentials (`multi_ap '2'`
+by default). The two fh-credentials sections in the provided example above will
+in practice be setup as follows in the wireless configuration by map-agent:
+
+```
+config wifi-iface 'wl1_ap'
+ option ifname 'wl1'
+ option network 'lan'
+ option ssid 'MAP-44D4376AF600-2.4GHz'
+ option key '5YXJOLWWQPGL2H'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-44D4376AF600-BH-2.4GHz'
+ option multi_ap_backhaul_key '53c2b08edd53b55d6628c340ce12d0f185ba467d0c928a7fb241becec7d6ee06'
+
+config wifi-iface 'wl0_ap'
+ option ifname 'wl0'
+ option network 'lan'
+ option ssid 'MAP-44D4376AF600-5GHz'
+ option key '5YXJOLWWQPGL2H'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '2'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option wps '1'
+ option wps_pushbutton '1'
+ option multi_ap_backhaul_ssid 'MAP-44D4376AF600-BH-5GHz'
+ option multi_ap_backhaul_key '53c2b08edd53b55d6628c340ce12d0f185ba467d0c928a7fb241becec7d6ee06'
+```
+
+### Backhaul Credentials
+
+The section `bk-credentials` refers to backhaul credentials (`multi_ap '1'` by
+default). The two bk-credentials sections in the provided example will in
+practice be setup as follows in the wireless configuration by map-agent:
+
+```
+config wifi-iface 'wl1_1_ap'
+ option ifname 'wl1.1'
+ option network 'lan'
+ option ssid 'MAP-44D4376AF600-BH-2.4GHz'
+ option key '53c2b08edd53b55d6628c340ce12d0f185ba467d0c928a7fb241becec7d6ee06'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl1'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option hidden '1'
+
+config wifi-iface 'wl0_1_ap'
+ option ifname 'wl0.1'
+ option network 'lan'
+ option ssid 'MAP-44D4376AF600-BH-5GHz'
+ option key '53c2b08edd53b55d6628c340ce12d0f185ba467d0c928a7fb241becec7d6ee06'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '1'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option hidden '1'
+```
+
+### Combined Front/Back
+
+If combined fronthaul and backhaul interfaces are to be used, specify a
+`config fh-credentials` section, and add an option `multi_ap '3'` to that
+section:
+
+```
+config fh-credentials
+ option band '5'
+ option ssid 'MAP-44D4376AF600-COMBINED-5GHz'
+ option encryption 'psk2'
+ option key '5YXJOLWWQPGL2H'
+ option vlan '1'
+ option multi_ap '3'
+```
+
+In turn map-agent will create the interface with multi_ap to set to 3, meaning
+combined fronthaul/backhaul interface.
+
+```
+config wifi-iface 'wl0_ap'
+ option ifname 'wl0'
+ option network 'lan'
+ option ssid 'MAP-44D4376AF600-COMBINED-5GHz'
+ option key '5YXJOLWWQPGL2H'
+ option encryption 'psk2+aes'
+ option mode 'ap'
+ option device 'wl0'
+ option multi_ap '3'
+ option ieee80211k '1'
+ option ieee80211v '1'
+ option uuid 'cfa7df87-06a3-5daf-911f-44d4376af600'
+ option wps '1'
+ option wps_pushbutton '1'
+```
+
+
+## AP-Autoconfig Renew
+
+Autoconfig Renew will trigger all agents to be reconfigured with updated
+credentials.
+
+### Prerequisites
+
+* Mapcontroller must be running
+
+### How to Trigger
+
+Mapcontroller will re-read the mapcontroller network credentials (and vlan
+section) upon receiving `SIGHUP`. In order to trigger AP-Autoconfig Renew the
+mapcontroller credentials loaded in memory at runtime, must differ from what
+are in its config, causing mapcontroller to generate a AP-Autoconfig Renew for
+all agents to be reconfigured.
## uBus
```
root@iopsys:~# ubus -v list map.controller
-'map.controller' @5917ca35
- "status":{}
- "ap_caps":{"agent":"String"}
- "sta_caps":{"agent":"String","sta":"String","bssid":"String"}
- "channels":{"agent":"String"}
- "bk_steer":{"agent":"String","bssid":"String","channel":"Integer","op_class":"Integer","bksta":"String"}
- "agent_policy":{"agent":"String","radiolist":"Array","bsslist":"Array"}
- "channel":{"agent":"String","radio_id":"String","class_id":"Integer","channel":"Array","preference":"Integer","transmit_power":"Integer"}
- "reconfig_ap":{"agent":"String","almac":"String","egress":"String"}
- "client_steering":{"agent":"String","src_bssid":"String","sta":"Array","target_bssid":"Array","steer_timeout":"Integer","btm_timeout":"Integer","steer_req_mode":"Boolean"}
- "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","channel":"Array"}
- "sta_metric_query":{"agent":"String","sta":"String"}
- "bk_caps":{"agent":"String"}
+'map.controller' @2d8adaa3
+ "status":{}
+ "ap_caps":{"agent":"String"}
+ "sta_caps":{"agent":"String","sta":"String","bssid":"String"}
+ "channels":{"agent":"String"}
+ "bk_steer":{"agent":"String","bssid":"String","channel":"Integer","op_class":"Integer","bksta":"String"}
+ "agent_policy":{"agent":"String","radiolist":"Array","bsslist":"Array"}
+ "channel":{"agent":"String","radio_id":"String","class_id":"Integer","channel":"Array","preference":"Integer","transmit_power":"Integer"}
+ "reconfig_ap":{"agent":"String"}
+ "client_steering":{"agent":"String","src_bssid":"String","sta":"Array","target_bssid":"Array","steer_timeout":"Integer","btm_timeout":"Integer","steer_req_mode":"Boolean"}
+ "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","channel":"Array"}
+ "sta_metric_query":{"agent":"String","sta":"String"}
+ "bk_caps":{"agent":"String"}
+ "topology_query":{"agent":"String"}
```
diff --git a/doc/MultiAP-IOPSYS.pdf b/docs/MultiAP-IOPSYS.pdf
similarity index 100%
rename from doc/MultiAP-IOPSYS.pdf
rename to docs/MultiAP-IOPSYS.pdf
diff --git a/docs/api/mapcontroller.md b/docs/api/mapcontroller.md
new file mode 100644
index 00000000..1ede1916
--- /dev/null
+++ b/docs/api/mapcontroller.md
@@ -0,0 +1 @@
+<tbody><tr><td colspan="2"><div style="font-weight: bold">mapagent</div><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">section</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td><td><div style="font-weight: bold; font-size: 14px">multi</div></td><td><div style="font-weight: bold; font-size: 14px">options</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">mapcontroller</div></td><td class="td_row_even"><div class="td_row_even">Mapcontroller daemon Configuration</div></td><td class="td_row_even"><div class="td_row_even">false</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">enabled</div></td><td class="td_row_even"><div class="td_row_even">boolean</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><div class="td_row_even">Enables mapcontroller daemon</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">debug</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">0</div></td><td class="td_row_odd"><div class="td_row_odd">Mapcontroller debug level</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">registrar</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">The bands on which mapcontroller acts as registrar</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">al_bridge</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd">br-lan</div></td><td class="td_row_odd"><div class="td_row_odd">To be deprecated. No longer used</div></td></tr></tbody></table></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">vlan</div></td><td class="td_row_odd"><div class="td_row_odd">Vlan configuration of a bridge</div></td><td class="td_row_odd"><div class="td_row_odd">true</div></td><td class="td_row_odd"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">network</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">lan</div></td><td class="td_row_even"><div class="td_row_even">The network name</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">id</div></td><td class="td_row_odd"><div class="td_row_odd">integer</div></td><td class="td_row_odd"><div class="td_row_odd">no</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">The vlan ID</div></td></tr></tbody></table></td></tr><tr><td class="td_row_even"><div class="td_row_even">fh-credentials</div></td><td class="td_row_even"><div class="td_row_even">Credentials to be configured as a fronthual interface</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">band</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Band for which the credentials applies</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">ssid</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">SSID to be transferred</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">encryption</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">psk2+aes</div></td><td class="td_row_even"><div class="td_row_even">Encryption for the credentials</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">key</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Password for the SSID</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">vlan</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Vlan section (mapped against ID)</div></td></tr></tbody></table></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">bk-credentials</div></td><td class="td_row_odd"><div class="td_row_odd">Credentials to be configured as a backhaul interface</div></td><td class="td_row_odd"><div class="td_row_odd">true</div></td><td class="td_row_odd"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">band</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Band for which the credentials applies</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">ssid</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">SSID to be transferred</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">encryption</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">no</div></td><td class="td_row_even"><div class="td_row_even">psk2+aes</div></td><td class="td_row_even"><div class="td_row_even">Encryption for the credentials</div></td></tr><tr><td class="td_row_odd"><div class="td_row_odd">key</div></td><td class="td_row_odd"><div class="td_row_odd">string</div></td><td class="td_row_odd"><div class="td_row_odd">yes</div></td><td class="td_row_odd"><div class="td_row_odd"></div></td><td class="td_row_odd"><div class="td_row_odd">Password for the SSID</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">vlan</div></td><td class="td_row_even"><div class="td_row_even">integer</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">Vlan section (mapped against ID)</div></td></tr></tbody></table></td></tr><tr><td class="td_row_even"><div class="td_row_even">agent-policy</div></td><td class="td_row_even"><div class="td_row_even">An agent and its configuration policy as provided by mapcontroller</div></td><td class="td_row_even"><div class="td_row_even">true</div></td><td class="td_row_even"><table style="width:100%"><tbody><tr><td><div style="font-weight: bold; font-size: 14px">name</div></td><td><div style="font-weight: bold; font-size: 14px">type</div></td><td><div style="font-weight: bold; font-size: 14px">required</div></td><td><div style="font-weight: bold; font-size: 14px">default</div></td><td><div style="font-weight: bold; font-size: 14px">description</div></td></tr><tr><td class="td_row_even"><div class="td_row_even">agent_id</div></td><td class="td_row_even"><div class="td_row_even">string</div></td><td class="td_row_even"><div class="td_row_even">yes</div></td><td class="td_row_even"><div class="td_row_even"></div></td><td class="td_row_even"><div class="td_row_even">AL-ID of this agent</div></td></tr></tbody></table></td></tr></tbody></table></td></tr></tbody>
\ No newline at end of file
diff --git a/schemas/uci/mapcontroller.json b/schemas/uci/mapcontroller.json
new file mode 100644
index 00000000..976c1321
--- /dev/null
+++ b/schemas/uci/mapcontroller.json
@@ -0,0 +1,158 @@
+{
+ "mapagent": [
+ {
+ "section": "mapcontroller",
+ "description": "Mapcontroller daemon Configuration",
+ "multi": false,
+ "options": [
+ {
+ "name": "enabled",
+ "type": "boolean",
+ "required": "no",
+ "default": true,
+ "description": "Enables mapcontroller daemon"
+ },
+ {
+ "name": "debug",
+ "type": "integer",
+ "required": "no",
+ "default": "0",
+ "description": "Mapcontroller debug level"
+ },
+ {
+ "name": "registrar",
+ "type": "integer",
+ "required": "no",
+ "default": "",
+ "description": "The bands on which mapcontroller acts as registrar"
+ },
+ {
+ "name": "al_bridge",
+ "type": "string",
+ "required": "no",
+ "default": "br-lan",
+ "description": "To be deprecated. No longer used"
+ }
+ ]
+ },
+ {
+ "section": "vlan",
+ "description": "Vlan configuration of a bridge",
+ "multi": true,
+ "options": [
+ {
+ "name":"network",
+ "type":"string",
+ "required":"no",
+ "default": "lan",
+ "description": "The network name"
+ },
+ {
+ "name":"id",
+ "type":"integer",
+ "required":"no",
+ "default": "",
+ "description": "The vlan ID"
+ }
+ ]
+ },
+ {
+ "section": "fh-credentials",
+ "description": "Credentials to be configured as a fronthual interface",
+ "multi": true,
+ "options":[
+ {
+ "name": "band",
+ "type": "integer",
+ "required": "yes",
+ "default": "",
+ "description": "Band for which the credentials applies"
+ },
+ {
+ "name": "ssid",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "SSID to be transferred"
+ },
+ {
+ "name": "encryption",
+ "type": "string",
+ "required": "no",
+ "default": "psk2+aes",
+ "description": "Encryption for the credentials"
+ },
+ {
+ "name": "key",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Password for the SSID"
+ },
+ {
+ "name": "vlan",
+ "type": "integer",
+ "required": "yes",
+ "default": "",
+ "description": "Vlan section (mapped against ID)"
+ }
+ ]
+ },
+ {
+ "section": "bk-credentials",
+ "description": "Credentials to be configured as a backhaul interface",
+ "multi": true,
+ "options":[
+ {
+ "name": "band",
+ "type": "integer",
+ "required": "yes",
+ "default": "",
+ "description": "Band for which the credentials applies"
+ },
+ {
+ "name": "ssid",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "SSID to be transferred"
+ },
+ {
+ "name": "encryption",
+ "type": "string",
+ "required": "no",
+ "default": "psk2+aes",
+ "description": "Encryption for the credentials"
+ },
+ {
+ "name": "key",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "Password for the SSID"
+ },
+ {
+ "name": "vlan",
+ "type": "integer",
+ "required": "yes",
+ "default": "",
+ "description": "Vlan section (mapped against ID)"
+ }
+ ]
+ },
+ {
+ "section": "agent-policy",
+ "description": "An agent and its configuration policy as provided by mapcontroller",
+ "multi": true,
+ "options":[
+ {
+ "name": "agent_id",
+ "type": "string",
+ "required": "yes",
+ "default": "",
+ "description": "AL-ID of this agent"
+ }
+ ]
+ }
+ ]
+ }
--
GitLab