scottk/wlan-docs
1
0
Fork 0
mirror of https://github.com/Telecominfraproject/wlan-docs.git synced 2025-11-02 19:57:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

GitBook: [#8] Installation notes

Browse Source
This commit is contained in:
Jaspreet Sachdev
2021-12-03 21:23:05 +00:00
committed by gitbook-bot
parent 34924ee464
commit a66e5c816f
8 changed files with 101 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
SUMMARY.md
View File

@@ -5,9 +5,7 @@
* [Getting Started](getting-started/README.md)
* [Cloud Discovery](getting-started/cloud-discovery/README.md)
* [Discovery without Cloud](getting-started/cloud-discovery/discovery-without-cloud.md)
* [Release 2.0 SDK](getting-started/sdk/README.md)
* [Deploy using Docker Compose](getting-started/sdk/deploy-using-docker-compose.md)
* [Deploy using Helm](getting-started/sdk/deploy-using-helm.md)
* [Release 2.0 SDK](getting-started/sdk.md)
* [Access Points](getting-started/access-points/README.md)
* [Local Device Settings](getting-started/access-points/local-device-settings.md)
* [Provisioning](provisioning/README.md)
@@ -24,6 +22,12 @@
* [Monitoring](monitoring/README.md)
* [ELK Integration](monitoring/elk-integration.md)
## SDK Installation - WIP
* [Overview](sdk-installation-wip/overview.md)
* [Deploy using Docker Compose](sdk-installation-wip/deploy-using-docker-compose.md)
* [Deploy using Helm](sdk-installation-wip/deploy-using-helm.md)
## Configuration Examples
* [Basic Device Provisioning](configuration-examples/basic-device-provisioning/README.md)
@@ -68,3 +72,7 @@
* [AP NOS](performance/ap-nos.md)
* [SDK](performance/sdk.md)
## Troubleshooting
* [Untitled](troubleshooting/untitled.md)

30
getting-started/README.md
View File

@@ -4,13 +4,13 @@ description: TIP OpenWiFi 2.0
# Getting Started
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.
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:
* Zero Touch Cloud Discovery
* Firmware Management
* User Interface
* User Interface 
* Device List
* Device Reboot
* Device LED Blink
@@ -20,27 +20,27 @@ OpenWiFi 2.0 Minimum Viable Product at the end of July, 2021 enables a cloud nat
* Device Remote TTY shell
* Remote Wi-Fi Scan
* Associations
* UE \(Wi-Fi Clients\)
* UE (Wi-Fi Clients)
* Mesh and WDS Clients
* MCS, NSS, RSSI, Channel, SSID, Tx/Rx
* Device Health Check
* Device Health Check 
* Interface Statistics
* Device Command History
Upcoming sprint for August includes Dynamic Provisioning service support for template based device configuration.
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.
OpenWiFi 2.0 SDK is deployable as both a Docker Compose or a Helm on Kubernetes model. See [Release 2.0 SDK](sdk.md) section for installation instructions.
## New in this Release
## New in this Release 
* Firmware
* Basic Features for OpenWiFi Switching
* Passpoint
* Passpoint 
* NAPTR Functionality
* Proxy Static Routing
* HSP Auth / Acc Service Discovery
* Last Resort Proxy
* RADIUS OpenRoaming Compliance
* Last Resort Proxy 
* RADIUS OpenRoaming Compliance 
* External 3rd Party Captive Portal Redirect
* Burst Rate Ad-Hoc Telemetry
* Static Routing
@@ -49,11 +49,11 @@ OpenWiFi 2.0 SDK is deployable as both a Docker Compose or a Helm on Kubernetes
* Timestamp on Health Check messages
* L2 DHCP Relay
* Station Association Idle and Session time
* SDK
* SDK
* OpenWiFi Provisioning Service
* OpenWiFi Inventory Service
* Multi Tenant Support
* Service Group - Venues
* Logical Regions - Entities
* OpenWiFi Provisioning Service
* OpenWiFi Inventory Service
* Multi Tenant Support 
* Service Group - Venues
* Logical Regions - Entities

0
getting-started/sdk/README.md → getting-started/sdk.md
View File

2
release-notes/security.md
View File

@@ -17,7 +17,7 @@ The following list of major security enhancements have been implemented within t
| [WIFI-5727](https://telecominfraproject.atlassian.net/browse/WIFI-5727) | Weak UUID generation with reduced entropy | Hardened UUID by increasing entropy |
| [WIFI-5772](https://telecominfraproject.atlassian.net/browse/WIFI-5772?src=confmacro) | RTTY-enabled APs can be overtaken by an adversary accessing RTTYS dedicated management interface using default hardcoded credentials | Hardened RTTYS access by randomizing default credentials at deployment |
### Major known security issues <a href="#major-known-security-issues" id="major-known-security-issues"></a>
### Known security issues <a href="#major-known-security-issues" id="major-known-security-issues"></a>
* [WIFI-5770](https://telecominfraproject.atlassian.net/browse/WIFI-5770) - RTTYS version used has security flaws which are to be resolved in next releases

73
getting-started/sdk/deploy-using-docker-compose.md → sdk-installation-wip/deploy-using-docker-compose.md
View File

@@ -4,7 +4,34 @@ description: TIP OpenWiFi 2.0 SDK
# Deploy using Docker Compose
The [wlan-cloud-ucentral-deploy repository](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy) contains a Compose file and the related files and directories to set up a local uCentral instance with Docker Compose. You'll find all related data under the `docker-compose/` directory.
The docker-compose [directory](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/release/v2.4.0/docker-compose) within the deploy repository contains all the relevant files for various modes of SDK.&#x20;
### Modes&#x20;
The following two modes are currently supported by docker-compose:
* Deployments without a Load Balancer
This model is suitable for scenarios where there are no additional needs on handling number of APs. This model contains single instances of SDK micro-services. A single local docker-compose deployment performance is listed [here](../performance/sdk.md). Additionally this deployment includes options to use either self-signed certificates or user provided certificates: &#x20;
* [Non-LB deployment with self-signed certificates](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/release/v2.4.0/docker-compose#non-lb-deployment-with-self-signed-certificates)
* [Non-LB deployment with own certificates](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/release/v2.4.0/docker-compose#non-lb-deployment-with-own-certificates)
* Deployments with a Load Balancer
This model is suitable for deployments where there is a need to scale performance and/or use Letsencrypt certificates for northbound service interactions. This deployment allows the user to scale up number of instances of micro-services to handle a larger load than listed [here](../performance/sdk.md). The repository contains the instructions here:&#x20;
* [LB deployment with self-signed certificates](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/release/v2.4.0/docker-compose#lb-deployment-with-self-signed-certificates)
* [LB deployment with Letsencrypt certificates](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/tree/release/v2.4.0/docker-compose#lb-deployment-with-letsencrypt-certificates)
&#x20;The docker-compose yaml files are related as follows to the modes above:
* docker-compose.yml : manages Non-LB deployment with self-signed and own certificates
* docker-compose.lb.selfsigned.yml: manages LB deployment with self-signed certificates
* docker-compose.lb.letsencrypt.yml: manages LB deployment with Letencrypt certificates
### Environment Variables
### Volumes
@@ -15,7 +42,7 @@ The deployment creates local volumes to persist mostly application and database
Service specific data directories and configuration files located under `docker-compose/` mounted into the appropriate containers.
{% hint style="info" %}
Be aware that the deployment uses bind mounts on the host to mount certificate and configuration data for the micro services and therefore these files and directories will be owned by the user in the container.
Be aware that the deployment uses bind mounts on the host to mount certificate and configuration data for the micro services and therefore these files and directories will be owned by the user in the container.\
Since the files are under version control, you may have to change the ownership to your user again before pulling changes.
{% endhint %}
@@ -33,34 +60,34 @@ The rest of the configuration is done through the config files located in the ap
Exposed port dependencies by application are listed below:
`127.0.0.1:80/tcp` - OpenWiFi-UI
`127.0.0.1:5912/tcp` - rttys dev
`127.0.0.1:5913/tcp` - rttys user
`0.0.0.0:15002/tcp` - OpenWiFi-uCentralGW websocket
`127.0.0.1:16002/tcp` - OpenWiFi-uCentralGW REST API public
`0.0.0.0:16003/tcp` - OpenWiFi-uCentralGW fileupload
`127.0.0.1:16102/tcp` - OpenWiFi-uCentralGW alivecheck
`127.0.0.1:16001/tcp` - OpenWiFi-uCentralSec REST API public
`127.0.0.1:80/tcp` - OpenWiFi-UI\
`127.0.0.1:5912/tcp` - rttys dev\
`127.0.0.1:5913/tcp` - rttys user\
`0.0.0.0:15002/tcp` - OpenWiFi-uCentralGW websocket\
`127.0.0.1:16002/tcp` - OpenWiFi-uCentralGW REST API public\
`0.0.0.0:16003/tcp` - OpenWiFi-uCentralGW fileupload\
`127.0.0.1:16102/tcp` - OpenWiFi-uCentralGW alivecheck\
`127.0.0.1:16001/tcp` - OpenWiFi-uCentralSec REST API public\
`127.0.0.1:16101/tcp` - OpenWiFi-uCentralSec alivecheck
{% hint style="info" %}
By default only the websocket and fileupload component of the OpenWiFi uCentralGW \(Gateway\) micro service are exposed on all interfaces. All other exposed services listen on localhost. You can change that according to your needs in the `ports` sections of`docker-compose/docker-compose.yml`.
By default only the websocket and fileupload component of the OpenWiFi uCentralGW (Gateway) micro service are exposed on all interfaces. All other exposed services listen on localhost. You can change that according to your needs in the `ports` sections of`docker-compose/docker-compose.yml`.
{% endhint %}
### Certificates
The repository includes a TIP Root CA Digicert-signed \(for the Gateway websocket to devices\) and a self-signed certificate \(for the REST API northbound and other components\), which you can use to create a local deployment out of the box.
The repository includes a TIP Root CA Digicert-signed (for the Gateway websocket to devices) and a self-signed certificate (for the REST API northbound and other components), which you can use to create a local deployment out of the box.
The certificates are valid for the `*.wlan.local` domain.
## How to
1. First you'll have to [install Docker Compose](https://docs.docker.com/compose/install/) according to your platform specific instructions. After that clone the repository with `git clone https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy`.
2. The Docker Compose uCentral micro service configs use `ucentral.wlan.local` as a hostname, so make sure you add an entry in your hosts file \(or in your local DNS solution\) which points to `127.0.0.1` or whatever the IP of the host running the deployment is.
3. Switch to the Compose project directory with `cd docker-compose/`.
1. First you'll have to [install Docker Compose](https://docs.docker.com/compose/install/) according to your platform specific instructions. After that clone the repository with `git clone https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy`. &#x20;
2. The Docker Compose uCentral micro service configs use `ucentral.wlan.local` as a hostname, so make sure you add an entry in your hosts file (or in your local DNS solution) which points to `127.0.0.1` or whatever the IP of the host running the deployment is. &#x20;
3. Switch to the Compose project directory with `cd docker-compose/`. &#x20;
4. Spin up the deployment with `docker-compose up -d`. If your deployment was successfully created, you should see the following output with `docker-compose ps`:
```text
```
Name Command State Ports
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
ucentral_kafka_1 /opt/bitnami/scripts/kafka ... Up 9092/tcp
@@ -71,16 +98,15 @@ 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
```
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\).
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.
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. &#x20;
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. &#x20;
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"
export FLAGS="-s --cacert <your-wlan-cloud-ucentral-deploy-location>/docker-compose/certs/restapi-ca.pem"
```
@@ -91,6 +117,5 @@ Stop the running containers with `docker-compose down`
Check out the new branch by repeating _Step 1_ from _How to_ above for the given release and `docker-compose up -d`.
Don’t forget to re-add the self-signed certificates to the containers with the provided script.
Don’t forget to re-add the self-signed certificates to the containers with the provided script.\
Also be aware that you may have to change back some file permissions. To obtain the most recent changes as the files are under version control, you may have to change the ownership to your user again before pulling changes.

23
getting-started/sdk/deploy-using-helm.md → sdk-installation-wip/deploy-using-helm.md
View File

@@ -4,11 +4,11 @@ description: TIP OpenWiFi 2.0 SDK
# Deploy using Helm
OpenWi-Fi 2.0 SDK can be deployed to Kubernetes using a Helm package. The Helm package code is located at [https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/) repository.
SDK can be deployed to Kubernetes using a Helm package. The Helm package code is located at [https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/) repository.
Each micro service in the OpenWiFi SDK system has its own Helm chart that is managed in the micro service’s own repository. The assembly chart collects all the relevant micro service charts and other external dependencies like kafka, rtty, etc. and deploys them together as one cohesive release.
You can review the full list of all the assembled micro services and related dependencies here: [https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/Chart.yaml\#L6](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/Chart.yaml#L6)
You can review the full list of all the assembled micro services and related dependencies here: [https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/Chart.yaml#L6](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/Chart.yaml#L6)
## Installation
@@ -33,15 +33,15 @@ There are multiple ways you can install OpenWiFi SDK with assembly charts:
The configuration of OpenWiFi SDK using Helm chart may be separated into layers:
1. Micro services default values - values files that are stored in micro service helm charts \(i.e. [https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/helm/values.yaml](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/helm/values.yaml) \). These values are used by default if no other parameters are supplied, so in case you have any microservice-related variables that need to be added in default installation \(for example new application configuration properties\), add them in the related helm chart values as they will be applied in next release update.
2. Assembly chart values - values that are stored in the assembly repository \([https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/values.yaml](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/values.yaml) \) – these are values that override default micro services values so that all uCentral components could connect to each other correctly, and the whole system can be installed as one bundle. These parameters are environment specific, and can differ between and installation of the bundle on an EKS cluster or a MicroK8s local setup.
3. Helm upgrade/install flag overwrites - these values cam be specific for each specific helm install command during execution and usually contain installation-specific values like TLS certificates, security credentials, loadbalancer configuration parameters and so on. These may be passed using --set flag or --values flag \(details may be found in [https://helm.sh/docs/chart\_best\_practices/values/](https://helm.sh/docs/chart_best_practices/values/) and in micro services helm charts\), or you can also save them into one file and reference this file during the helm upgrade command using the --values flag.
1. Micro services default values - values files that are stored in micro service helm charts (i.e. [https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/helm/values.yaml](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/helm/values.yaml) ). These values are used by default if no other parameters are supplied, so in case you have any microservice-related variables that need to be added in default installation (for example new application configuration properties), add them in the related helm chart values as they will be applied in next release update.
2. Assembly chart values - values that are stored in the assembly repository ([https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/values.yaml](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/blob/main/chart/values.yaml) ) – these are values that override default micro services values so that all uCentral components could connect to each other correctly, and the whole system can be installed as one bundle. These parameters are environment specific, and can differ between and installation of the bundle on an EKS cluster or a MicroK8s local setup.
3. Helm upgrade/install flag overwrites - these values cam be specific for each specific helm install command during execution and usually contain installation-specific values like TLS certificates, security credentials, loadbalancer configuration parameters and so on. These may be passed using --set flag or --values flag (details may be found in [https://helm.sh/docs/chart\_best\_practices/values/](https://helm.sh/docs/chart\_best\_practices/values/) and in micro services helm charts), or you can also save them into one file and reference this file during the helm upgrade command using the --values flag.
During deployment all values are merged as maps with priority to the level of deployment \(so Environment-specific values will override any overrides from Assembly chart values and so on\).
During deployment all values are merged as maps with priority to the level of deployment (so Environment-specific values will override any overrides from Assembly chart values and so on).
**Example**: Let’s pass environment-specific ucentralgw.properties configuration parameter \(which is probably quite common thing to test\). For example, we have an environment that requires to set parameter ucentral.websocket.host.0.backlog to 1000. For that we would need to run following command, extending our base command:
**Example**: Let’s pass environment-specific ucentralgw.properties configuration parameter (which is probably quite common thing to test). For example, we have an environment that requires to set parameter ucentral.websocket.host.0.backlog to 1000. For that we would need to run following command, extending our base command:
```text
```
helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy/@chart?ref=main --set ucentralgw.configProperties."ucentral\.websocket\.host\.0\.backlog"=1000
```
@@ -49,13 +49,12 @@ helm upgrade --install tip-ucentral git+https://github.com/Telecominfraproject/w
OpenWiFi SDK can also be deployed to an AWS labs environment using a Github actions workflow: [https://github.com/Telecominfraproject/wlan-testing/actions/workflows/ucentralgw-deployment.yaml](https://github.com/Telecominfraproject/wlan-testing/actions/workflows/ucentralgw-deployment.yaml).
The configuration is dynamic, and new namespaces \(a.k.a environments\) may be created by adjusting the json configuration in the workflow.
The configuration is dynamic, and new namespaces (a.k.a environments) may be created by adjusting the json configuration in the workflow.
The json format allows to deploy or upgrade and existing environment using the latest Docker images or to specify a specific version of each micro service.
To deploy specific version to the specific environment a list of things must be done:
1. First, you need to make sure that the Docker image with the correct version exists in Artifactory, otherwise, the Helm upgrade will fail.
2. Update the json configuration in the workflow to reference the require version for the require micro service \(examples are attached in the json file itself\)
3. Re-run the deployment in Github actions. You can also make all the above changes in a separate branch, and re-run the workflow from that branch \(using a drop-down in the top left corner in Github’s UI\).
2. Update the json configuration in the workflow to reference the require version for the require micro service (examples are attached in the json file itself)
3. Re-run the deployment in Github actions. You can also make all the above changes in a separate branch, and re-run the workflow from that branch (using a drop-down in the top left corner in Github’s UI).

12
sdk-installation-wip/overview.md Normal file
View File

@@ -0,0 +1,12 @@
# Overview
The [wlan-cloud-ucentral-deploy](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy) repository contains two packaging options:
* [Docker Compose](deploy-using-docker-compose.md)
* [Helm](deploy-using-helm.md)
The repository is managed using branches where:
* main branch: contains references to development SDK images&#x20;
* release/v\* branch: contains image references specific to the release artifacts. For example: release/v2.4.0 branch will have references to SDK images related to 2.4.0 &#x20;

2
troubleshooting/untitled.md Normal file
View File

@@ -0,0 +1,2 @@
# Untitled