mirror of
https://github.com/Telecominfraproject/wlan-docs.git
synced 2025-11-03 20:28:09 +00:00
GitBook: [2.1.0] 46 pages and 5 assets modified
This commit is contained in:
Chris Busch
BIN
.gitbook/assets/image (22) (1).png
Normal file
BIN
.gitbook/assets/image (22) (1).png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 125 KiB |
|
Before Width: | Height: | Size: 101 KiB After Width: | Height: | Size: 101 KiB |
|
Before Width: | Height: | Size: 147 KiB After Width: | Height: | Size: 147 KiB |
@@ -2,7 +2,7 @@
|
||||
description: Telecom Infra Project OpenWiFi
|
||||
---
|
||||
|
||||
# OpenWiFi Release 2.0
|
||||
# OpenWiFi Release 2.1
|
||||
|
||||
## What is OpenWiFi?
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Table of contents
|
||||
|
||||
* [OpenWiFi Release 2.0](README.md)
|
||||
* [OpenWiFi Release 2.1](README.md)
|
||||
* [Ordering OpenWiFi APs](ordering-open-wi-fi-aps.md)
|
||||
* [Getting Started](getting-started/README.md)
|
||||
* [Cloud Discovery](getting-started/cloud-discovery/README.md)
|
||||
|
||||
@@ -7,46 +7,46 @@ description: OpenWiFi 2.0 SDK
|
||||
OpenWiFi services follow the OpenAPI 3.0 definition.
|
||||
The complete API is described here: [OpenWiFi SDK OpenAPI](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/openapi/ucentral/ucentral.yaml)
|
||||
|
||||
### Devices
|
||||
## Devices
|
||||
|
||||
OpenWiFi devices are Access Points or Switches \(and other forms in the future\), that support the uCentral configuration schema. Devices contact a controller using the uCentral protocol.
|
||||
|
||||
### Communication
|
||||
## Communication
|
||||
|
||||
The communication between the controller and the devices use the uCentral protocol. This protocol is defined in this [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/PROTOCOL.md).
|
||||
|
||||
### Device Configuration
|
||||
## Device Configuration
|
||||
|
||||
A device is configured by ingesting a uCentral configuration. That configuration will be provided by the SDK Gateway as a result of a command through the API. Command processing occurs when the device's configuration is older than what is known in the SDK Gateway. The uCentral schema is a JSON document containing parameters to set on a particular device.
|
||||
|
||||
### SDK Gateway Communication
|
||||
## SDK Gateway Communication
|
||||
|
||||
In order to speak to the Gateway, you must implement a client that uses the OpenAPI definition for the gateway. You can find its [definition here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/openapi/ucentral/ucentral.yaml). You cannot talk to a device directly.
|
||||
|
||||
### API Basics
|
||||
## API Basics
|
||||
|
||||
#### Device `serialNumber`
|
||||
### Device `serialNumber`
|
||||
|
||||
Throughout the API, the `serialNumber` of the device is used as the key. The `serialNumber` is actual the MAC address of the device, without its `:`. The `serialNumber` is guaranteed to be unique worldwide. The device uses its serial number to identify itself to the controller.
|
||||
|
||||
#### Device Configuration
|
||||
### Device Configuration
|
||||
|
||||
The configuration can be supplied when the device is created. After the device is created, the only way to modify the configuration is by using the `/device/{serialNumber}/configure` endpoint. The Gateway maintains the versioning of the configuration through the use of a `uuid`. The Gateway maintains that number and will ignore anything your supply. The controller also does minimum validation on the configuration: it must be a valid JSON document and must have a `uuid` field which will be ignored.
|
||||
|
||||
#### Device Capabilities
|
||||
### Device Capabilities
|
||||
|
||||
Device capabilities are uploaded to the Gateway when the device performs its initial connection. Capabilities tell the Gateway what the device is able to support. The Gateway uses this information to provide a configuration matched to the device type.
|
||||
|
||||
#### Command Queue
|
||||
### Command Queue
|
||||
|
||||
The Gateway will send commands to the devices. These commands are kept in a table and are sent at the appropriate time or immediately when the device connects.
|
||||
For example, you could ask a device to change its configuration, however it might be unreachable. Upon next device connection, this configure command will be sent. The list of commands is retrieved using the `/commands` endpoint.
|
||||
|
||||
#### Commands
|
||||
### Commands
|
||||
|
||||
Several commands maybe sent to a device: reboot, configure, factory reset, firmware upgrade, LEDs, trace, message request, etc. The API endpoint `/device/{serialNumber}/{command}` details all the available commands.
|
||||
|
||||
#### Device Specific Collections
|
||||
### Device Specific Collections
|
||||
|
||||
For each device, a number of collections are collected and kept in the database. Here's a brief list:
|
||||
|
||||
@@ -55,7 +55,7 @@ For each device, a number of collections are collected and kept in the database.
|
||||
* `healthchecks`: periodically, a device will run a self-test and report its results. These includes anything that maybe going wrong with the current device configuration. A `sanity` level is associated to the degree of health of the device. 100 meaning a properly operating device.
|
||||
* `status`: tells you where the device is and how much data is used for protocol communication.
|
||||
|
||||
### The API is for an operator
|
||||
## The API is for an operator
|
||||
|
||||
This API is meant for an operator who would have to help a subscriber in configuring devices, reboot, manage firmware, etc.
|
||||
|
||||
|
||||
@@ -4,16 +4,16 @@ description: OpenWiFi 2.0 SDK
|
||||
|
||||
# OpenAPI Definitions
|
||||
|
||||
### Where is the OpenAPI?
|
||||
## Where is the OpenAPI?
|
||||
|
||||
This uses OpenAPI definition 3.0 and can be found [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/openapi/ucentral/ucentral.yaml). All endpoints begin with `/api/v1`.
|
||||
|
||||
### API Flow
|
||||
## API Flow
|
||||
|
||||
API endpoints are secured with bearer-token authentication using end-point `/oauth2`.
|
||||
Once you obtain `access-token`, you will need to pass it in the headers under `Authorization: Bearer <place your token here>`.
|
||||
|
||||
### Basic Entities
|
||||
## Basic Entities
|
||||
|
||||
The API revolves around `devices`, `commands`, and `default_configurations`.
|
||||
To retrieve a list of `devices` to know what is available and then use the endpoint `device` to access all device specific information.
|
||||
@@ -24,7 +24,7 @@ Most operations rely on the `serialNumber` of a device. That `serialNumber` is u
|
||||
* `commands`: The list of commands issued by the system. This list could also be large.
|
||||
* `default_configurations`: A list of default configurations used to supply existing devices.
|
||||
|
||||
### Relationships
|
||||
## Relationships
|
||||
|
||||
A device is a physical \(or potentially logical\) entity using the ucentral protocol.
|
||||
Currently, APs and Switches are the only devices used. A device has several attributes.
|
||||
@@ -49,7 +49,7 @@ Commands supported for each device:
|
||||
|
||||
The `file` end point is used to retrieve and remove files produced by the Gateway. Currently this is limited to the results of a `trace` command. The file name will always match the `uuid` of the command that produced it. If several files are needed, the files will be named `uuid`, `uuid.1`, `uuid.2`, etc.
|
||||
|
||||
### Dates
|
||||
## Dates
|
||||
|
||||
All dates should use the format defined in [RFC3339](https://tools.ietf.org/html/rfc3339). All times are UTC based. Here is an example:
|
||||
|
||||
@@ -57,11 +57,11 @@ All dates should use the format defined in [RFC3339](https://tools.ietf.org/html
|
||||
1985-04-12T23:20:50.52Z
|
||||
```
|
||||
|
||||
### Command `when` parameter
|
||||
## Command `when` parameter
|
||||
|
||||
Most commands use a `when` parameter to suggest to the device when to perform the command. This is a _suggestion_ only. The device may decide to perform the command when it is optimal for itself. It maybe busy doing something and decline to do a reboot for several minutes for example. The device may reply with the actual `when` it will perform the command.
|
||||
|
||||
### Configuration UUID
|
||||
## Configuration UUID
|
||||
|
||||
The gateway manages the configuration UUID. So if you set a UUID for a configuration, it will be ignored. The gateway uses UUID as versioning. The UUID is unique within a single device. The resulting UUID or a configuration change is returned as part of the `configure` command.
|
||||
|
||||
|
||||
@@ -89,7 +89,7 @@ To associate a logical SSID interface directly to the WAN, place SSID configurat
|
||||
{% endtab %}
|
||||
|
||||
{% tab title="Dual SSID Bridge Rate-Limit to WAN" %}
|
||||
```
|
||||
```text
|
||||
"interfaces": [
|
||||
{
|
||||
"name": "WAN",
|
||||
|
||||
@@ -6,7 +6,7 @@ description: OpenWiFi 2.0
|
||||
|
||||
OpenWiFi supports multiple models for Captive Portal. A built-in captive portal is described below. With multiple overlay tunnel services such as GRE and L2TP in addition to VLAN features, OpenWiFi is also easily deployed with any number of Captive Portal appliance solutions in either in-band or out-of-band style deployments.
|
||||
|
||||
### Local Captive Portal
|
||||
## Local Captive Portal
|
||||
|
||||
Creating a local captive portal involves associating the "captive" service with an interface. In the example below, "captive" is enabled on a downstream role interface. Any associated SSID on LAN side of this Access Point will be subject to configuration of the local captive portal. This would also apply to LAN interfaces if also associated with "captive".
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ For information about becoming an expressWIFI partner please visit their [site.]
|
||||
|
||||
|
||||
|
||||
### Configuration
|
||||
## Configuration
|
||||
|
||||
ExpressWiFi builds a captive portal experience using a control plane protocol called OpenFlow.
|
||||
Configuring OpenWiFi for use with expressWiFi is as simple as defining a downstream interface and associating with an SSID and the open-flow service.
|
||||
|
||||
@@ -61,6 +61,5 @@ For example, to send all content of a specific SSID over an L2TP tunnel, the fol
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
```
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@ description: OpenWiFi 2.0
|
||||
|
||||
# Metrics
|
||||
|
||||
### Metrics
|
||||
## Metrics
|
||||
|
||||
Several metrics are reported during intervals to the OpenWiFi Gateway. In general metrics contain traffic counters, neighbor tables, discovered clients.
|
||||
|
||||
|
||||
@@ -6,15 +6,15 @@ description: OpenWiFi 2.0
|
||||
|
||||
Passpoint® requires ANQP to supply three information elements from the Access Point.
|
||||
|
||||
#### PLMN-Id
|
||||
## PLMN-Id
|
||||
|
||||
Public Land Mobile Network Id is defined by 3GPP and comprised of two, three digit numbers to uniquely identify the Mobile Network Operator \(MNO\).
|
||||
|
||||
#### Realm
|
||||
## Realm
|
||||
|
||||
A Fully Qualified Domain Name \(FQDN\) is a realm representing the service provider of the Wi-Fi service. Non MNO operators are an example of 'realm-based' service advertisements. Examples include Cable MSOs, Enterprises or other on MNO providers. Authentication methods used with realm-based configuration are EAP-TLS and EAP-TTLS.
|
||||
|
||||
#### OI / RCOI
|
||||
## OI / RCOI
|
||||
|
||||
Organization Id or as defined by Wireless Broadband Alliance, Roaming Consortium Organization Id indicate the federated identity capable of authentication. Examples would be OpenRoaming, Eduroam and follow the Passpoint® EAP authentication methods.
|
||||
|
||||
|
||||
@@ -80,7 +80,6 @@ TIP OpenWiFi enables operators to deploy the full range of Passpoint® and OpenR
|
||||
<td style="text-align:left">OSU</td>
|
||||
<td style="text-align:left">
|
||||
<p>Online Signup - Advertised over ANQP contains:</p>
|
||||
<p></p>
|
||||
<ul>
|
||||
<li>OSU SSID</li>
|
||||
<li>OSU URI</li>
|
||||
@@ -98,5 +97,3 @@ TIP OpenWiFi enables operators to deploy the full range of Passpoint® and OpenR
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -21,8 +21,6 @@ Capabilities for Hotspot 2.0 / Passpoint® include:
|
||||
* firendly-name
|
||||
* icons
|
||||
|
||||
|
||||
|
||||
```text
|
||||
"interfaces": [
|
||||
{
|
||||
|
||||
@@ -151,7 +151,6 @@ Many parameters are possible with RADIUS authentications given the many methods
|
||||
<li>port ( example 1813)</li>
|
||||
<li>secret ( Shared secret with RADIUS server )</li>
|
||||
</ul>
|
||||
<p></p>
|
||||
<p>Additional methods within Access-Request sent in Accounting</p>
|
||||
<ul>
|
||||
<li>request-attribute ( id of RADIUS server )
|
||||
|
||||
@@ -51,7 +51,7 @@ To configure Dynamic VLANs with RADIUS, associate an SSID with RADIUS authentica
|
||||
},
|
||||
```
|
||||
|
||||
### RADIUS Access-Accept
|
||||
## RADIUS Access-Accept
|
||||
|
||||
OpenWiFi devices will determine a VLAN is associated to the authentication of a subscriber when the access-accept message returns the following attribute value pairs:
|
||||
|
||||
|
||||
@@ -6,11 +6,11 @@ description: OpenWiFi 2.0
|
||||
|
||||
Radio Resource Management and Self Organizing Network features in OpenWiFi 2.0 operate by default in local mode from the Access Point device without dependency on the cloud. Data and state related to client steering and roaming is also possible in co-operation with the cloud when so configured.
|
||||
|
||||
Metrics and telemetry are sent to the cloud as desired based on configuration however operation of 802.11k/v/r behavior and autonomous channel control are built in features of all OpenWiFi 2.0 Access Points.
|
||||
Metrics and telemetry are sent to the cloud as desired based on configuration however operation of 802.11k/v/r behavior and autonomous channel control are built in features of all OpenWiFi 2.0 Access Points.
|
||||
|
||||
### Steering
|
||||
## Steering
|
||||
|
||||
OpenWiFi services feature "wifi-steering" determines the operating parameters of RRM on the Access Point.
|
||||
OpenWiFi services feature "wifi-steering" determines the operating parameters of RRM on the Access Point.
|
||||
|
||||
```text
|
||||
"services": {
|
||||
@@ -38,7 +38,7 @@ Which network association, in this case "upstream" will steering be operating on
|
||||
| required-roam-snr | minimum signal level in dBm client roaming threshold |
|
||||
| load-kick-threshold | minimum channel load as % available before clients are kicked |
|
||||
|
||||
### Apply Wi-Fi Steering to enable 802.11r Fast Roaming SSIDs
|
||||
## Apply Wi-Fi Steering to enable 802.11r Fast Roaming SSIDs
|
||||
|
||||
```text
|
||||
"ssids": [
|
||||
@@ -68,16 +68,13 @@ Each SSID to participate in roaming must have "services" : \[ "wifi-steering" \]
|
||||
|
||||
Additional fast roaming configuration is possible including setting message-exchange either to "air" or "ds" to determine pre authenticated message exchange occurs over the air or distribution system.
|
||||
|
||||
|
||||
The generate-psk option generates FT response locally for PSK networks. This avoids use of PMK-R1 push/pull from other APs with FT-PSK networks.
|
||||
|
||||
|
||||
Configuring domain-identifier sets Mobility Domain identifier \(dot11FTMobilityDomainID, MDID\) permitting segmentation of fast roaming RF topologies.
|
||||
|
||||
|
||||
When pmk-r0-key-holder and pmk-r1-key-holder are left un-configured, the pairwise master key R0 and R1 will generate a deterministic key automatically for fast mobility domain exchange over the air.
|
||||
|
||||
### RRM 802.11k
|
||||
## RRM 802.11k
|
||||
|
||||
To enable 80211k parameters, associate these on a participating SSID basis.
|
||||
|
||||
@@ -112,7 +109,7 @@ To enable 80211k parameters, associate these on a participating SSID basis.
|
||||
|
||||
In addition to 802.11k features for neighbor reporting, fine timing measurement responder and stationary ap indication, OpenWiFi also supports LCI measurement, Civic Location subelement as well.
|
||||
|
||||
### Automatic Channel Balancing
|
||||
## Automatic Channel Balancing
|
||||
|
||||
As part of "wifi-steering" feature, autonomous channel management algorithm may be enabled to establish a self organizing Wi-Fi network.
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ OpenWiFi devices have global services that operate either independently system w
|
||||
|
||||
Within the "services" configuration block, define the operating mode for each service, then associate a service with an interface.
|
||||
|
||||
### SSH
|
||||
## SSH
|
||||
|
||||
Secure shell may optionally be enabled on OpenWiFi devices, associated to specific interface\(s\), and optionally support operator defined keys or password authentication.
|
||||
|
||||
@@ -27,7 +27,7 @@ Secure shell may optionally be enabled on OpenWiFi devices, associated to specif
|
||||
}
|
||||
```
|
||||
|
||||
#### Associate Service to Interface
|
||||
### Associate Service to Interface
|
||||
|
||||
```text
|
||||
{
|
||||
@@ -43,9 +43,7 @@ Secure shell may optionally be enabled on OpenWiFi devices, associated to specif
|
||||
],
|
||||
```
|
||||
|
||||
###
|
||||
|
||||
### NTP
|
||||
## NTP
|
||||
|
||||
Network time protocol for OpenWiFi devices may be configured to listen for time synchronization from NTP sources and may also be configured to supply NTP source.
|
||||
|
||||
@@ -60,7 +58,7 @@ Network time protocol for OpenWiFi devices may be configured to listen for time
|
||||
}
|
||||
```
|
||||
|
||||
#### Associate to an Interface
|
||||
### Associate to an Interface
|
||||
|
||||
```text
|
||||
{
|
||||
@@ -80,7 +78,7 @@ Network time protocol for OpenWiFi devices may be configured to listen for time
|
||||
},
|
||||
```
|
||||
|
||||
### LLDP
|
||||
## LLDP
|
||||
|
||||
Link Layer Discovery Protocol describes interfaces and capabilities between directly attached neighbors over Layer 2.
|
||||
|
||||
@@ -93,7 +91,7 @@ Link Layer Discovery Protocol describes interfaces and capabilities between dire
|
||||
|
||||
Associate "lldp" as a services attribute to any interface.
|
||||
|
||||
### MDNS
|
||||
## MDNS
|
||||
|
||||
To assist in device or service discovery over smaller networks, multicast DNS \(mDNS\) protocol if often used. In an mDNS environment there is no local name server for resources to leverage. mDNS zero-configuration service effectively behaves as unicast Domain Name Service \(DNS\).
|
||||
|
||||
@@ -105,7 +103,7 @@ To assist in device or service discovery over smaller networks, multicast DNS \
|
||||
|
||||
Associate "mdns" as a services attribute to any interface.
|
||||
|
||||
### Syslog
|
||||
## Syslog
|
||||
|
||||
Remote syslog systems may be configured to receive device logs in a central location. This content is standard device log and not related to telemetry for metrics and service information received by the OpenWiFi Gateway. Valid port range is from 100 - 65535 with operation over UDP or TCP.
|
||||
|
||||
@@ -119,7 +117,7 @@ Remote syslog systems may be configured to receive device logs in a central loca
|
||||
|
||||
Associate "log" as a services attribute to appropriate interface.
|
||||
|
||||
### IGMP
|
||||
## IGMP
|
||||
|
||||
When enabled the OpenWiFi device will process IGMP Proxy.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ In a traditional L2 switch a behavior known as flood and learn is used for unkno
|
||||
|
||||
The next frame for the same MAC will not incur a miss because the table will reflect the port it exists on. VXLAN preserves this behavior over an IP network using IP multicast groups.
|
||||
|
||||
### Configure VxLAN
|
||||
## Configure VxLAN
|
||||
|
||||
OpenWiFi device will establish a VTEP adjacency to the upstream switch. It is anticipated that any Wi-Fi networks in a VxLAN topology are associated to "upstream" interface\(s\).
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ description: OpenWiFi 2.0
|
||||
|
||||
OpenWiFi 2.0 Minimum Viable Product at the end of July, 2021 enables a cloud native and cloud agnostic Software Development Kit \(SDK\) with management and deployment support for a wide range of Access Point and PoE network switch platforms.
|
||||
|
||||
### Initial release 2.0 SDK includes:
|
||||
## Initial release 2.0 SDK includes:
|
||||
|
||||
* Zero Touch Cloud Discovery
|
||||
* Firmware Management
|
||||
@@ -31,5 +31,3 @@ Upcoming sprint for August includes Dynamic Provisioning service support for tem
|
||||
|
||||
OpenWiFi 2.0 SDK is deployable as both a Docker Compose or a Helm on Kubernetes model. See [Release 2.0 SDK](sdk/) section for installation instructions.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ Initial Minimum Viable Product Release 2.0 does not include template driven devi
|
||||
|
||||
Given many cloud and ODM partners wish to consume the 2.0 reference stack early, some with their own device provisioning logic as part of commercial cloud controllers, the following describes uCentral based management and telemetry, interactions with the OpenWiFi SDK processing provisioning and telemetry data.
|
||||
|
||||
### Device Interactions with SDK
|
||||
## Device Interactions with SDK
|
||||
|
||||
|
||||
|
||||
@@ -30,5 +30,3 @@ For example results returned to SDK from a device configuration error:
|
||||
],
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ OpenWiFi 2.0 supports these scenarios. When a device does not have an existing c
|
||||
For all Wi-Fi devices this means a Wi-Fi network with the SSID 'Maverick' will become available.
|
||||
Association with and logging in to the device will permit initial WAN connectivity to be entered.
|
||||
|
||||
### Using Maverick
|
||||
## Using Maverick
|
||||
|
||||
|
||||
|
||||
@@ -42,29 +42,17 @@ Otherwise leave the Uplink configuration to DHCP or cloud defaults.
|
||||
|
||||
|
||||
|
||||
### Manual Redirector and Certificate Upload
|
||||
## Manual Redirector and Certificate Upload
|
||||
|
||||
If under rare circumstances it is not possible to discover the OpenWiFi cloud associated with the device or there is a need to replace device certificates, this may be configured in Settings.
|
||||
|
||||
|
||||
|
||||
### System
|
||||
## System
|
||||
|
||||
It is possible to reset the device to defaults, or locally update firmware using the commands available from System.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
\*\*\*\*
|
||||
|
||||
|
||||
@@ -22,7 +22,3 @@ When an operator or end customer seeks to change the cloud associated with their
|
||||
|
||||
TIP OpenWiFi ODM partners are able to manage device records directly using the Certificate Authority portal. All other users should send an email to licensekeys@telecominfraproject.com to request update of cloud discovery.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -19,5 +19,3 @@ Features of the 2.0 SDK at July MVP include:
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -71,12 +71,14 @@ ucentral_ucentralsec.wlan.local_1 /bin/sh -c /ucentral/ucent ... Up 127
|
||||
ucentral_zookeeper_1 /docker-entrypoint.sh zkSe ... Up 2181/tcp, 2888/tcp, 3888/tcp, 8080/tcp
|
||||
```
|
||||
|
||||
5. Since the certificate for the REST API and other components is self-signed, you have to add it to the system trust store of the containers communicating together internally via TLS. The `add-ca-cert.sh` script located in the Compose project directory does the work for you.
|
||||
You also have to trust the self-signed REST API certificate on your local machine. To achieve that you either have to add `certs/restapi-ca.pem` to your trusted browser certificates or add certificate exceptions in your browser by visiting `https://ucentral.wlan.local:16001` and `https://ucentral.wlan.local:16002` and accepting the self-signed SSL certificate warnings \(make sure to visit both and add the exceptions\).
|
||||
6. Connect to your AP via SSH and add a static hosts entry in `/etc/hosts` for `ucentral.wlan.local` which points to the address of the host the Compose deployment runs on.
|
||||
7. While staying in the SSH session, copy the content of `certs/restapi-ca.pem` on your local machine to your clipboard and append it to the file `/etc/ssl/cert.pem` on the AP. This way your AP will also trust the self-signed certificate.
|
||||
8. Go to `http://ucentral.wlan.local` to visit the UI and login with username `tip@ucentral.com` and password `openwifi` if you didn't change the default credentials in the uCentralSec configuration.
|
||||
9. To use the curl test scripts which are included in the micro service repositories make sure to set the following environment variables before issuing a request:
|
||||
1. Since the certificate for the REST API and other components is self-signed, you have to add it to the system trust store of the containers communicating together internally via TLS. The `add-ca-cert.sh` script located in the Compose project directory does the work for you.
|
||||
|
||||
You also have to trust the self-signed REST API certificate on your local machine. To achieve that you either have to add `certs/restapi-ca.pem` to your trusted browser certificates or add certificate exceptions in your browser by visiting `https://ucentral.wlan.local:16001` and `https://ucentral.wlan.local:16002` and accepting the self-signed SSL certificate warnings \(make sure to visit both and add the exceptions\).
|
||||
|
||||
2. Connect to your AP via SSH and add a static hosts entry in `/etc/hosts` for `ucentral.wlan.local` which points to the address of the host the Compose deployment runs on.
|
||||
3. While staying in the SSH session, copy the content of `certs/restapi-ca.pem` on your local machine to your clipboard and append it to the file `/etc/ssl/cert.pem` on the AP. This way your AP will also trust the self-signed certificate.
|
||||
4. Go to `http://ucentral.wlan.local` to visit the UI and login with username `tip@ucentral.com` and password `openwifi` if you didn't change the default credentials in the uCentralSec configuration.
|
||||
5. To use the curl test scripts which are included in the micro service repositories make sure to set the following environment variables before issuing a request:
|
||||
|
||||
```text
|
||||
export UCENTRALSEC="ucentral.wlan.local:16001"
|
||||
|
||||
@@ -17,16 +17,16 @@ There are multiple ways you can install OpenWiFi SDK with assembly charts:
|
||||
1. One way is by installing directly from the assembly chart’s repository. For that, you’ll need to install and extra Helm plugin that is used to pull the latest charts code from all the referenced micro services: [https://github.com/aslafy-z/helm-git](https://github.com/aslafy-z/helm-git).
|
||||
2. Another way, which is considered more stable, is by installing from a prepackaged bundle that is published to [https://tip.jfrog.io/ui/native/tip-wlan-cloud-ucentral-helm/](https://tip.jfrog.io/ui/native/tip-wlan-cloud-ucentral-helm/) on every official uCentral release. For this approach to work, you don’t need to install any additional plugins or dependencies, just to make sure you’ve got Helm installed on your local system.
|
||||
|
||||
#### Directly from the Assembly repository
|
||||
### Directly from the Assembly repository
|
||||
|
||||
1. Install the helm-git pluging according to the official documentation
|
||||
2. Run helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=main
|
||||
3. You can also reference any other open branch from the deployment repository. For example, if you want to deploy using the assembly code from the v2.0.0-rc1 branch, you can just run helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=v2.0.0-rc1
|
||||
2. Run helm upgrade --install tip-ucentral git+[https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=main](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=main)
|
||||
3. You can also reference any other open branch from the deployment repository. For example, if you want to deploy using the assembly code from the v2.0.0-rc1 branch, you can just run helm upgrade --install tip-ucentral git+[https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=v2.0.0-rc1](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=v2.0.0-rc1)
|
||||
|
||||
#### Using the pre-built Helm package
|
||||
### Using the pre-built Helm package
|
||||
|
||||
1. This method doesn’t require to install anything locally other than Helm
|
||||
2. Start by adding the wlan-cloud-ucentral Helm repository to your local list of repositories by running helm repo add tip-ucentral https://tip.jfrog.io/artifactory/tip-wlan-cloud-ucentral-helm/
|
||||
2. Start by adding the wlan-cloud-ucentral Helm repository to your local list of repositories by running helm repo add tip-ucentral [https://tip.jfrog.io/artifactory/tip-wlan-cloud-ucentral-helm/](https://tip.jfrog.io/artifactory/tip-wlan-cloud-ucentral-helm/)
|
||||
3. helm upgrade --install tip-ucentral wlan-cloud-ucentral to install the latest version, or specify the release you want to install by adding the --version x.y.z flag.
|
||||
|
||||
## Chart configuration using the Values file
|
||||
|
||||
@@ -13,14 +13,13 @@ OpenWiFi also provides options to receive telemetry and events over both OpenAPI
|
||||
|
||||
In future sprints of OpenWiFi dynamic device provisioning will be available as an added micro service.
|
||||
|
||||
### Gateway
|
||||
## Gateway
|
||||
|
||||
OpenWiFi 2.0 Gateway implements the uCentral device management interface. uCentral specifies the data model and interface for management and telemetry of OpenWrt based devices.
|
||||
Gateway uCentral interface is a websocket JSON-RPC based design between OpenWiFi Gateway and the device running uCentral agent.
|
||||
|
||||
|
||||
|
||||
|
||||
All communications from Gateway to Device are secured using mutual Transport Layer Security \(mTLS\). In mTLS systems each endpoint is a unique device sharing the same signed root or intermediate trust. In OpenWiFi each device has a signed certificate, key and device identifier. These are validated by the uCentral-Gateway to establish mTLS session.
|
||||
|
||||
Upon successful connection the device exchanges its capabilities with the OpenWiFi SDK. OpenWIFi SDK, via the Gateway micro service will send the entire device provisioning data as a JSON payload.
|
||||
@@ -29,7 +28,6 @@ If any data presented can not be processed by the local agent, this is returned
|
||||
|
||||
|
||||
|
||||
|
||||
If the device agrees with provisioning information presented, the render process builds calls into the operating system configuration sub-system known as UCI. The Unified Configuration Interface ensures OpenWrt compliant syntax is persisted within the device.
|
||||
|
||||
Configuration source of truth is the OpenWiFi SDK. Consistency of device configuration is handled with an applied hash compared by the Gateway for each device. If the value differs on device from that of the stored information in cloud, the device will be immediately resent its configuration from the OpenWiFi SDK Gateway service.
|
||||
|
||||
@@ -6,7 +6,7 @@ description: OpenWiFi 2.0 Device Configuration
|
||||
|
||||
To introduce the Community to the uCentral data model structure, the below illustrates a basic Access Point configuration that assumes a typical enterprise Wi-Fi scenario of a ceiling mount or wall mount device presenting a single WAN interface with a private management network and separate Wi-Fi network on a virtual local area network.
|
||||
|
||||
### Start with Location and Radios
|
||||
## Start with Location and Radios
|
||||
|
||||
We will set the unit location and timezone, then proceed to configure radios.
|
||||
|
||||
@@ -53,7 +53,7 @@ OpenWiFi radios may be set to require UE clients to associate to a minimum stand
|
||||
|
||||
Control of beacon interval and multicast rates is possible per radio as shown in the "rates" section.
|
||||
|
||||
### Interfaces
|
||||
## Interfaces
|
||||
|
||||
OpenWiFi 2.0 offers a highly flexible model for arranging network interfaces. Multi-port devices may be easily provisioned for numerous types of network segmentation and logical network configuration. We will start with a simple WAN that has a management IP and also a VLAN sub-interface for a logical SSID in a subsequent step.
|
||||
|
||||
@@ -80,7 +80,7 @@ In the above configuration block we have a WAN interface, its role is "upstream"
|
||||
|
||||
Note we want this port to have an IP address for its management, therefore the "ipv4" configuration is associated as a child of any Ethernet WAN ports and set to DHCP.
|
||||
|
||||
#### Common Config - VLAN on WAN for SSID
|
||||
### Common Config - VLAN on WAN for SSID
|
||||
|
||||
Imagine the OpenWiFi device is an enterprise Access Point mounted on a ceiling. These devices do not always have a LAN port. Also in an enterprise, it is likely the Wi-Fi services are in their own network segments and not subject to Network Address Translation \(NAT\). Since the enterprise would also not want Wi-Fi on the same network as Management, an 802.1Q Virtual LAN is used.
|
||||
|
||||
@@ -122,7 +122,7 @@ To associate the Wi-Fi with the VLAN interface define, we continue within the WA
|
||||
"services": [ "wifi-frames"]
|
||||
```
|
||||
|
||||
Within the "ssids" configuration block we can process an array of SSIDs. Often there may be separate "2G" and "5G" configurations. We have grouped them in this introductory example for simplicity however "2G", "5G", "5G-lower", "5G-upper", "6G" are all valid options.
|
||||
Within the "ssids" configuration block we can process an array of SSIDs. Often there may be separate "2G" and "5G" configurations. We have grouped them in this introductory example for simplicity however "2G", "5G", "5G-lower", "5G-upper", "6G" are all valid options.
|
||||
|
||||
The "name" value is the advertised SSID clients will discover for this access point. Hidden is supported by setting the "hidden-ssid" to true.
|
||||
Which operating mode is determined by "bss-mode". The "bss-mode" is a highly flexible operating parameter to determine "ap", "sta", mesh", "wds-ap", "wds-sta", "wds-repeater" radio modes of operation.
|
||||
@@ -132,7 +132,7 @@ Lastly, for devices that support, 802.11w protected management frames are define
|
||||
|
||||
Metrics for wifi-frames will be described next.
|
||||
|
||||
#### Sending Data
|
||||
### Sending Data
|
||||
|
||||
Add metrics to our configuration that will help expose state of the Wi-Fi network and its services to the cloud.
|
||||
|
||||
@@ -177,7 +177,7 @@ For all SSIDs that have wifi-frames associated as a service, the listed manageme
|
||||
|
||||
To assist with fingerprinting and client troubleshooting, dhcp-snooping sends the cloud all current client DHCP and DHCPv6 state.
|
||||
|
||||
#### Global Services
|
||||
### Global Services
|
||||
|
||||
The final section of the simple configuration example turns on LLDP and SSH where those services were associated to interfaces listed above.
|
||||
|
||||
@@ -196,8 +196,5 @@ The final section of the simple configuration example turns on LLDP and SSH wher
|
||||
|
||||
The complete simple configuration file as described in this page may be downloaded here:
|
||||
|
||||
|
||||
{% file src="../.gitbook/assets/simpleconfig\_openwifidocs.json" caption="SimpleConfig\_Wi-Fi\_VLAN" %}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -12,13 +12,12 @@ Within the model it is possible to provision or return state for all aspects of
|
||||
|
||||
The complete data model may be found here : [https://ucentral.io/docs/ucentral-schema.html](https://ucentral.io/docs/ucentral-schema.html)
|
||||
|
||||
### Organization
|
||||
## Organization
|
||||
|
||||
Each device has a Universally Unique Identifier \(UUID\). For each device, the configuration presented either manually, via the future Provisioning service from OpenWifi or via a commercial controller generation of provisioning data, the high level relationships of the schema may be understood as follows.
|
||||
|
||||
|
||||
|
||||
|
||||
The unique device record has a set of top level configurations. A device is referred to as a 'unit' that may have a Description, Location, TimeZone as example. Each unit may have globals for IPv4 and IPv6 networks that are derived to lower lever interfaces in later generation.
|
||||
|
||||
Services and Metrics are associated with logical and physical interfaces. Services enable configuration of features such as LLDP or SSH, rTTY, IGMP, 802.1x, RADIUS Proxy, WiFi-Steering, or NTP and are then associated with Interfaces as desired.
|
||||
|
||||
@@ -6,25 +6,25 @@ description: OpenWiFi 2.0
|
||||
|
||||
Release 2.0 uses a Single-Page Application \(SPA\) as an example user interface built using React to demonstrate several interactions using the northbound OpenAPI.
|
||||
|
||||
### Login to OpenWiFi SDK
|
||||
## Login to OpenWiFi SDK
|
||||
|
||||
|
||||
|
||||
Default username is: **`tip@ucentral.com`** and password is: **`openwifi`**
|
||||
|
||||
### **Base Navigation**
|
||||
## **Base Navigation**
|
||||
|
||||
A left side navigation menu provides direction to major feature or service settings.
|
||||
|
||||
|
||||
|
||||
### Internationalization
|
||||
## Internationalization
|
||||
|
||||
OpenWiFi 2.0 SDK supports multiple languages. Simply select the desired language from the right drop down for pages to re-populate accordingly.
|
||||
|
||||
|
||||
|
||||
### Devices
|
||||
## Devices
|
||||
|
||||
Upon login the first page presented is a Devices table. This table reflects all discovered and managed devices known by the OpenWiFi SDK.
|
||||
|
||||
@@ -40,7 +40,7 @@ Compatible model, Tx, Rx, and connected IP Address present basic information of
|
||||
|
||||
Three final columns provide Details \(also obtained by selecting the serial number\), Wi-Fi Analysis presenting current Wi-Fi associations and their performance and Refresh commands.
|
||||
|
||||
### Displaying Associations
|
||||
## Displaying Associations
|
||||
|
||||
From the Devices table, second from right column icon the WiFi Analysis may be accessed. This may also be accessed within the Device View page of a single record along the top right of Statistics section.
|
||||
|
||||
@@ -54,7 +54,7 @@ For each association the device MAC address, mode of connection and SSID are dis
|
||||
|
||||
Associations have RSSI, Rx Rate & Bytes, Tx Rate & Bytes, MCS negotiated, Number Spatial Streams and IP Address information.
|
||||
|
||||
### Dashboard View
|
||||
## Dashboard View
|
||||
|
||||
OpenWiFi SDK provides visual indications on the overall health of the deployed Wi-Fi network. this includes Device Status for connected and non-connected devices. Device health indicating percentage of devices failing a health check. Distribution of devices by vendor in the network and by model.
|
||||
|
||||
|
||||
@@ -16,17 +16,16 @@ Each device presents Metrics and Health check data to the Gateway. Devices view
|
||||
|
||||
|
||||
|
||||
### Status
|
||||
## Status
|
||||
|
||||
Connection status reflects the Gateway to Device current communications status.
|
||||
Uptime and Last Contact reflect communication state.
|
||||
Load indicates processing load on the device.
|
||||
Memory Used indicates free memory on the device.
|
||||
|
||||
|
||||
|
||||
|
||||
### Configuration
|
||||
## Configuration
|
||||
|
||||
Device UUID, Serial Number, MAC Address and Device Type are displayed.
|
||||
Last configuration update date and timestamp reflects the last time a "configure" action completed on the device.
|
||||
@@ -34,19 +33,19 @@ Password may be set and device notes may be added.
|
||||
|
||||
|
||||
|
||||
### Logs
|
||||
## Logs
|
||||
|
||||
Log history of the device is presented within Logs. Expand the tile selecting the down arrow.
|
||||
|
||||
|
||||
|
||||
### Health
|
||||
## Health
|
||||
|
||||
Health score is an active tile reflecting the device health out of a score reported by the device to Gateway. Health metrics are configured on the device based on chosen data model options. When the device falls out of 100%, this tile changes to red. Expanding the tile will present all health reports. Those with less than 100% score will contain reasons for the result from this interface.
|
||||
|
||||
|
||||
|
||||
### Commands
|
||||
## Commands
|
||||
|
||||
Commands tile provides a number of administrative actions for the user:
|
||||
|
||||
|
||||
@@ -24,5 +24,3 @@ Remote packet capture is shown as the trace command history. When packet capture
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -7,45 +7,43 @@ description: OpenWiFi 2.0 SDK
|
||||
Within the devices view, the Commands tile offers a number of features and administrative actions.
|
||||
Each of these represent API calls exposed on the OpenAPI northbound interface from the SDK.
|
||||
|
||||
### Reboot
|
||||
## Reboot
|
||||
|
||||
Selecting the Reboot action will prompt the below dialog. Options presented permit an immediate reboot or a scheduled reboot based on date and time.
|
||||
|
||||
|
||||
|
||||
### Firmware Upgrade
|
||||
## Firmware Upgrade
|
||||
|
||||
Multiple methods exist to execute a remote Firmware Upgrade of a device. When selecting Firmware Upgrade via the Commands tile, a simple dialog to upgrade immediately or at a scheduled time is presented. Alternatively using the Firmware Management Service provides a complete solution including managed access to all TIP firmware images.
|
||||
|
||||
|
||||
|
||||
### Wi-Fi Scan
|
||||
## Wi-Fi Scan
|
||||
|
||||
OpenWiFi devices may perform channel scanning and return this neighbor and RF data to the SDK in an on demand or ongoing manner.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### Wi-Fi Scan Results
|
||||
### Wi-Fi Scan Results
|
||||
|
||||
Scan operations function over all channels. If 5GHz channels do not display in the returned results \( either via the UI or over API \) this indicates the device is configured in a DFS channel for which it may not return survey scans at this time.
|
||||
|
||||
|
||||
|
||||
### Connect
|
||||
## Connect
|
||||
|
||||
OpenWiFi enables remote connection to any managed device using rTTY encrypted shell session. Selecting Connect will cause a browser tab to open with the login session to current device.
|
||||
|
||||
|
||||
|
||||
### Blink
|
||||
## Blink
|
||||
|
||||
To assist with remote identification of devices in the network, it is possible to turn the LED lights On, Off, of continuous blinking. This may be run on-demand or scheduled.
|
||||
|
||||
|
||||
|
||||
### Trace
|
||||
## Trace
|
||||
|
||||
Trace feature enables a remote packet capture to occur on the managed device, over a specified period of time or amount of traffic, returning the "pcap" packet capture file locally to the OpenWiFi admin user.
|
||||
|
||||
@@ -55,7 +53,7 @@ Once complete the user is asked to open or save the packet capture file locally.
|
||||
|
||||
|
||||
|
||||
### Factory Reset
|
||||
## Factory Reset
|
||||
|
||||
It is possible to revert a device to initial out of box state from the OpenWiFi SDK. Sending a Factory Reset will remove all configuration on the device and optionally reset the discovered cloud stored as the 'Redirector' in the device configuration.
|
||||
|
||||
@@ -65,11 +63,9 @@ It is possible to revert a device to initial out of box state from the OpenWiFi
|
||||
Note: When Redirector is not kept, devices will re-contact the Certificate Authority to re-discover their OpenWiFi cloud address
|
||||
{% endhint %}
|
||||
|
||||
### Configure
|
||||
## Configure
|
||||
|
||||
Prior to the introduction of OpenWiFi 2.0 Provisioning Service, device configuration is done through creation of the JSON provisioning file and either loading that file or applying its contents using the dialog presented via Configure. The same options exist when using the API directly.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ Accessing Wi-Fi Analysis and Last Statistics may be found at the top right of St
|
||||
|
||||
|
||||
|
||||
### Wi-Fi Analysis
|
||||
## Wi-Fi Analysis
|
||||
|
||||
Operating channels, channel width, noise floor and transmit power are the first values reported in Radios table.
|
||||
|
||||
@@ -30,7 +30,7 @@ The access point view of RSSI, Rx and Tx Rate, Modulation Coding Scheme and Numb
|
||||
|
||||
Using the slider along the top, the last 15 to 30 minutes of performances data may be viewed.
|
||||
|
||||
### Latest Statistics
|
||||
## Latest Statistics
|
||||
|
||||
The option to view Latest Statistics is at time of the MVP release, intended to help the Community see on a per device basis how much, or how little depending on device configuration, is being sent to the OpenWiFi Gateway in terms of telemetry.
|
||||
|
||||
|
||||
@@ -6,13 +6,13 @@ description: OpenWiFi 2.0 SDK
|
||||
|
||||
Firmware management service integrates across all OpenWiFi Gateways deployed in a cluster enabling updates to running firmware either from the latest published version, or any other released version.
|
||||
|
||||
### Dashboard
|
||||
## Dashboard
|
||||
|
||||
Firmware dashboard provides a single view for overall health of deployed device firmware. Latest firmware charts, device firmware version distribution, distribution of device by type and current connected devices.
|
||||
|
||||
|
||||
|
||||
### Device Table
|
||||
## Device Table
|
||||
|
||||
From the Devices table, any device with a newer firmware published by TIP OpenWiFi is indicated with a yellow icon. Selecting this icon presents the option to upgrade to latest or specify which firmware to use.
|
||||
|
||||
@@ -20,7 +20,7 @@ From the Devices table, any device with a newer firmware published by TIP OpenWi
|
||||
|
||||
When the upgrade has been sent successfully, a green Success dialog will display in the upper right on the screen. Devices with latest firmware version will show a green firmware icon in the Devices row.
|
||||
|
||||
### Firmware Management Service
|
||||
## Firmware Management Service
|
||||
|
||||
Viewing the contents of Firmware Management Service is available from the left navigation, select Firmware.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user