scottk/wlan-cloud-ucentralgw
1
0
Fork 0
mirror of https://github.com/Telecominfraproject/wlan-cloud-ucentralgw.git synced 2025-11-01 11:17:52 +00:00
Code Issues Packages Projects Releases 10 Wiki Activity

https://telecominfraproject.atlassian.net/browse/WIFI-12308

Browse Source 
Signed-off-by: stephb9959 <stephane.bourque@gmail.com>
This commit is contained in:
stephb9959
2023-02-21 11:15:02 -08:00
parent 1df3fd1185
commit 2968bcd9a0
2 changed files with 128 additions and 283 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
CONFIGURATION.md
View File

@@ -154,19 +154,38 @@ This is the maximum uploaded file size. The default maximum size if 10MB. This s
This is the URI that will be passed to the AP. You must make sure that the AP can resolve this URI.
## Microservice information
These are different Microservie parameters. Following is a brief explanation.
```properties
openwifi.service.key = $OWGW_ROOT/certs/restapi-key.pem
openwifi.service.key.password = mypassword
openwifi.system.data = $OWGW_ROOT/data
openwifi.system.debug = true
openwifi.system.uri.private = https://localhost:17002
openwifi.system.uri.public = https://ucentral.dpaas.arilia.com:16002
openwifi.system.uri.ui = https://ucentral-ui.arilia.com
openwifi.security.restapi.disable = false
openwifi.system.commandchannel = /tmp/app.ucentralgw
openwifi.autoprovisioning = true
openwifi.devicetypes.0 = AP:linksys_ea8300,edgecore_eap101,linksys_e8450-ubi
openwifi.devicetypes.1 = SWITCH:edgecore_ecs4100-12ph
openwifi.devicetypes.2 = IOT:esp32
```
### openwifi.service.key
From time to time, the microservice must encrypt information. This is the key it should use. You may use the
same keey as you RESTAPI or your server.
### openwifi.service.key.password
The password for the `openwifi.service.key`
### openwifi.system.data
The location of system data. This path must exist.
### openwifi.system.uri.private
The URI to reach the controller on the internal port.
### openwifi.system.uri.public
The URI to reach the controller from the outside world.
### openwifi.system.uri.ui
The URI of the UI to manage this service
### openwifi.security.restapi.disable
This allows to disable security for internal and external API calls. This should only be used if the controller
sits behind an application load balancer that will actually do TLS. Setting this to `true` disables security.
### openwifi.system.commandchannel
The UNIX socket command channel used by this service.
### openwifi.autoprovisioning
Allow unknown devices to be provisioned by the system.
## OUI Service
The controller has a built-in OUI resolver for MAC addresses. The GW will periodically load this file to obtain the latest.
@@ -231,20 +250,39 @@ This is the country code to be used if no information can be found at one of the
You must select onf of the possible services and the fill the appropriate token or api key parameter.
## Provisioning link
This parameter tells the controller how to behave when it receives a request from a device for the first time. In this case, we tell
the controller to look at the provisioning service first, then apply any local configurations.
```properties
autoprovisioning.process = prov,default
```
## Restricted Device Signature Manager
If are using restricted devices, then you can include different keys for each vendor who provided
you with their information. This allows the controller to automatically sign requests to the device. You can have as many vendors
as it is necessary.
```properties
signature.manager.0.key.public = $OWGW_ROOT/certs/signatures/test1-public-key.pem
signature.manager.0.key.private = $OWGW_ROOT/certs/signatures/test1-private-key.pem
signature.manager.0.vendor = test1
signature.manager.1.key.public = $OWGW_ROOT/certs/signatures/test2-public-key.pem
signature.manager.1.key.private = $OWGW_ROOT/certs/signatures/test2-private-key.pem
signature.manager.1.vendor = test2
```
## OWLS Simulator ID
simulatorid = 53494d
If you plan on using OWLS (OpenWifi Load Simulator), then you will need to put your Simulator ID right here.
This ID must be obtained from TIP.
```properties
simulatorid = 53494dFFEEDD
```
## RTTY parameters
## RTTY Service
The controller comes with the ability to run an RTTY service. The service can either be internal (the prefered choice)
or external. If you decide to use the internal RTTY, the you only need to specify `rtty.internal = true`. If you choose
to use an external RTTY, you must specify the remainder of the parameters.
```properties
rtty.internal = true
rtty.enabled = true
rtty.server = rtty-tip.arilia.com
@@ -253,61 +291,108 @@ rtty.token = 96181c567b4d0d98c50f127230068fa8
rtty.timeout = 60
rtty.viewport = 5913
rtty.assets = $OWGW_ROOT/rtty_ui
```
## RADIUS proxy config
If you are going to use the buil-in RADIUS proxy service, you need to enable this parameter and provide
the ports for you PROXY.
```properties
radius.proxy.enable = false
radius.proxy.accounting.port = 1813
radius.proxy.authentication.port = 1812
radius.proxy.coa.port = 3799
```
## NLB Support
## ALB Support
In order to support an application load balancer health check verification, your need to provide the following parameters.
```properties
alb.enable = true
alb.port = 16102
```
## Kafka
The controller use Kafka, like all the other microservices. You must configure the kafka section in order for the
system to work.
```properties
openwifi.kafka.group.id = gateway
openwifi.kafka.client.id = gateway1
openwifi.kafka.enable = true
openwifi.kafka.brokerlist = a1.arilia.com:9092
openwifi.kafka.brokerlist = my_Kafka.example.com:9092
openwifi.kafka.auto.commit = false
openwifi.kafka.queue.buffering.max.ms = 50
```
### openwifi.kafka.group.id
The group ID is a single word that should identify the type of service tunning. In the case `gateway`
### openwifi.kafka.client.id
The client ID is a single service within that group ID. Each participant must have a unique client ID.
### openwifi.kafka.enable
Kafka should always be enabled.
### openwifi.kafka.brokerlist
The list of servers where your Kafka server is running. Comma separated.
### openwifi.kafka.auto.commit
Auto commit flag in Kafka. Leave as `false`.
### openwifi.kafka.queue.buffering.max.ms
Kafka buffering. Leave as `50`.
## Kafka security
If you intend to use SSL, you should look into Kafka Connect and specify the certificates below.
```properties
penwifi.kafka.ssl.ca.location =
openwifi.kafka.ssl.certificate.location =
openwifi.kafka.ssl.key.location =
openwifi.kafka.ssl.key.password =
```
## DB Type
The controller supports 3 types of Database. SQLite should only be used for sites with less than 100 APs or for testing in the lab.
In order to select which database to use, you must set the `storage.type` value to sqlite, postgresql, or mysql.
```properties
storage.type = sqlite
#storage.type = postgresql
#storage.type = mysql
#storage.type = odbc
```
## Storage SQLite
## Storage SQLite parameters
Additional parameters to set for SQLite. The only important one is `storage.type.sqlite.db` which is the database name on disk.
```properties
storage.type.sqlite.db = devices.db
storage.type.sqlite.idletime = 120
storage.type.sqlite.maxsessions = 128
```
## Storage Postgres
Additional parameters to set if you select Postgres for your database. You must specify `host`, `username`, `password`,
`database`, and `port`.
```properties
storage.type.postgresql.maxsessions = 64
storage.type.postgresql.idletime = 60
storage.type.postgresql.host = localhost
storage.type.postgresql.username = stephb
storage.type.postgresql.password = snoopy99
storage.type.postgresql.database = ucentral
storage.type.postgresql.username = gateway
storage.type.postgresql.password = gateway_password
storage.type.postgresql.database = gateway
storage.type.postgresql.port = 5432
storage.type.postgresql.connectiontimeout = 60
```
## Storage MySQL/MariaDB
Additional parameters to set if you select mysql for your database. You must specify `host`, `username`, `password`,
`database`, and `port`.
```properties
storage.type.mysql.maxsessions = 64
storage.type.mysql.idletime = 60
storage.type.mysql.host = localhost
storage.type.mysql.username = stephb
storage.type.mysql.password = snoopy99
storage.type.mysql.database = ucentral
storage.type.postgresql.username = gateway
storage.type.postgresql.password = gateway_password
storage.type.postgresql.database = gateway
storage.type.mysql.port = 3306
storage.type.mysql.connectiontimeout = 60
```
## Auto Archiver Parameters
The auto archiver is responsible for removing all stale data. The default is to remove old data after 7 days.
```properties
archiver.enabled = true
archiver.schedule = 03:00
archiver.db.0.name = healthchecks
@@ -318,10 +403,17 @@ archiver.db.2.name = devicelogs
archiver.db.2.keep = 7
archiver.db.3.name = commandlist
archiver.db.3.keep = 7
```
## Logging Parameters
The controller provides extensive logging. If you would like to keep logging on disk, set the `logging.type = file`. If you only want
console logging, `set logging.type = console`. When selecting file, `logging.path` must exist. `logging.level` sets the
basic logging level for the entire controller. `logging.websocket` disables WebSocket logging.
```properties
logging.type = file
logging.path = $OWGW_ROOT/logs
logging.level = information
logging.asynch = true
logging.websocket = false
```

285
README.md
View File

@@ -264,122 +264,20 @@ The gateway requires a key/certificate/ca for the REST interface. These files yo
document. You, may choose to select LestEncrypt or any other Certificate Authority. Once you have these files, you need to renamed them `restapi-key.pem`, `restapi-cert.pem`, and `restapi-ca.pem`.
This will guarantee proper HTTPS in your browser and RESTAPI.
#### Configuration
The configuration for this service is kept in a properties file. This file is called `owgw.properties` and you can
see the latest version [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/owgw.properties). The file will be loaded from
the directory set by the environment variable `UCENTRALGW_CONFIG`. To use environment variables in the configuration,
you must use `$<varname>`. Only `path names` support the use of environment variables. The sample configuration requires very
little changes if you keep the suggested directory structure. For the sample configuration to work, you need to define 2
environment variables.
```
### Environment variables
The following environment variables should be set from the root directory of the service.
```bash
export OWGW_ROOT=`pwd`
export OWGW_CONFIG=`pwd`
```
If your current working directory is the root of the project, this will set the variables properly. Otherwise, you can set the variables
to point to wherever is necessary.
### Configuration
The configuration is kept in a file called `owgw.properties`. To understand the content of this file,
please look [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/CONFIGURATION.md)
You can find a list of configuration parameters in [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/CONFIGURATION.md)
###### This is the RESTAPI endpoint
```asm
openwifi.restapi.host.0.backlog = 100
openwifi.restapi.host.0.security = relaxed
openwifi.restapi.host.0.rootca = $OWGW_ROOT/certs/restapi-ca.pem
openwifi.restapi.host.0.address = *
openwifi.restapi.host.0.port = 16002
openwifi.restapi.host.0.cert = $OWGW_ROOT/certs/restapi-cert.pem
openwifi.restapi.host.0.key = $OWGW_ROOT/certs/restapi-key.pem
openwifi.restapi.host.0.key.password = mypassword
```
##### This is the end point for the devices to connect with
This is the crucial section. I bet that 97.4% of all your problems will come from here, and it's boring. So put some good music on,
give the kids the iPad, get a cup of coffee, and pay attention. Every field will be explained.
###### ucentral.websocket.host.0.backlog
This is the number of concurrent devices you are expecting to call all at once. Not the current number of devices. This is how many will connect in the same exact second.
Take the total number of devices you have and divide by 100. That's a good rule of thumb. Never go above 500.
###### ucentral.websocket.host.0.rootca
This is the root file as supplied by Digicert. You can find it [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/root.pem)
###### ucentral.websocket.host.0.issuer
This is the issuer file as supplied by Digicert. You can find it [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/issuer.pem)
###### ucentral.websocket.host.0.cert
This is a `pem` file that you will receive from Digicert for the gateway itself. This is the certificate for the gateway.
###### ucentral.websocket.host.0.key
This is a `pem` file that you will receive from Digicert for the gateway itself. The is the private key for the gateway.
###### ucentral.websocket.host.0.clientcas
This is a `pem` file that contains both the issuer and the root CA certificates. You can find it You can find it [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/clientcas.pem)
###### ucentral.websocket.host.0.cas
This is a directory where you will copy your own `cert.pem`, the `root.pem`, and the `issuer.pem` files.
###### ucentral.websocket.host.0.address
Leve this a `*` in teh case you want to bind to all interfaces on your gateway host or select the address of a single interface.
###### ucentral.websocket.host.0.port
Leave to 15002 for now.
###### ucentral.websocket.host.0.security
Leave this as strict for now for devices.
###### ucentral.websocket.host.0.key.password
If you key file uses a password, please enter it here.
###### ucentral.websocket.maxreactors
A single reactor can handle between 1000-2000 devices. Never leave this smaller than 5 or larger than 50.
#### Conclusion
You will need to get the `cert.pem` and `key.pem` from Digicert. The rest is here.
```asm
ucentral.websocket.host.0.backlog = 500
ucentral.websocket.host.0.rootca = $OWGW_ROOT/certs/root.pem
ucentral.websocket.host.0.issuer = $OWGW_ROOT/certs/issuer.pem
ucentral.websocket.host.0.cert = $OWGW_ROOT/certs/websocket-cert.pem
ucentral.websocket.host.0.key = $OWGW_ROOT/certs/websocket-key.pem
ucentral.websocket.host.0.clientcas = $OWGW_ROOT/certs/clientcas.pem
ucentral.websocket.host.0.cas = $OWGW_ROOT/certs/cas
ucentral.websocket.host.0.address = *
ucentral.websocket.host.0.port = 15002
ucentral.websocket.host.0.security = strict
ucentral.websocket.host.0.key.password = mypassword
ucentral.websocket.maxreactors = 20
```
###### This is the end point for the devices when uploading files
```asm
openwifi.fileuploader.host.0.backlog = 100
openwifi.fileuploader.host.0.rootca = $OWGW_ROOT/certs/restapi-ca.pem
openwifi.fileuploader.host.0.security = relaxed
openwifi.fileuploader.host.0.address = *
openwifi.fileuploader.host.0.name = 192.168.1.176
openwifi.fileuploader.host.0.port = 16003
openwifi.fileuploader.host.0.cert = $OWGW_ROOT/certs/restapi-cert.pem
openwifi.fileuploader.host.0.key = $OWGW_ROOT/certs/restapi-key.pem
openwifi.fileuploader.host.0.key.password = mypassword
openwifi.fileuploader.path = $OWGW_ROOT/uploads
openwifi.fileuploader.maxsize = 10000
```
###### host.0.address entries
If you want to limit traffic to a specific interface, you should specify the IP address of that interface instead of
the `*`. Using the `*` means all interfaces will be able to accept connections. You can add multiple interfaces
by changing the `0` to another index. You need to repeat the whole configuration block for each index. Indexes must be sequential
start at `0`.
###### openwifi.fileuploader.host.0.name
This must point to the IP or FQDN of your uCentralGW.
#### Running the gateway
### Running the gateway
Tu run the gateway, you must run the executable `ucentralgw`. You can use several command line options to run as a daemon or specify the configuration file location.
#### Device configuration
### Device configuration
Once you have the gateway configured, you will need to have some devices coming to it. For now, you will need to get
the following in order to use the gateway:
- A DigiCert certificate that you will call `cert.pem`
@@ -393,16 +291,7 @@ You will need to upgrade your device to the latest firmware. Once updated, you w
the `/certificates` directory. Please remove all old keys or certificates from the `/etc/ucentral` directory
(anything ending in `.pem`).
#### Server key entry
The gateway needs to encrypt information from time to time. In order to do so, it must have a crypto key. This key
can be any of the keys you are already using. You must keep that keep secret and always use it. In the configutation,
this is the entry
```asm
openwifi.service.key = $OWGW_ROOT/certs/websocket-key.pem
```
#### Command line options
### Command line options
The current implementation supports the following. If you use the built-in configuration file, you do not need to use any command-line
options. However, you may decide to use the `--daemon` or `umask` options.
@@ -420,113 +309,21 @@ A uCentral gateway implementation for TIP.
--logs=dir specify the log directory and file (i.e. dir/file.log)
```
##### file
#### file
This allows you to point to another file without specifying the UCENTRALGW_CONFIG variable. The file name must end in `.properties`.
##### daemon
#### daemon
Run this as a UNIX service
##### pidfile
#### pidfile
When running as a daemon, the pid of the running service will be set in the speficied file
##### debug
#### debug
Run the service in debug mode.
##### logs
#### logs
Speficy where logs should be kept. You must include an existing directory and a file name. For example `/var/ucentral/logs/log.0`.
##### umask
#### umask
Seet the umask for the running service.
### ALB Support
Support for AWS ALB is provided through the following configuration elements
```asm
alb.enable = true
alb.port = 16102
```
### Docker
So building this thing from scratch is not your thing? I can't blame you. It takes some patience and
in the end, there's still more work. Here comes `docker` to the rescue. You can run a docker version following
these instructions. The following is the content of the `docker_run.sh` script you can find
[here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/docker_run.sh):
```bash
#!/bin/sh
HUBNAME=tip-tip-wlan-cloud-ucentral.jfrog.io
IMAGE_NAME=ucentralgw
DOCKER_NAME=$HUBNAME/$IMAGE_NAME
CONTAINER_NAME=ucentralgw
#stop previously running images
docker container stop $CONTAINER_NAME
docker container rm $CONTAINER_NAME --force
if [[ ! -d logs ]]
then
mkdir logs
fi
if [[ ! -d certs ]]
then
echo "certs directory does not exist. Please create and add the proper certificates."
exit 1
fi
if [[ ! -f owgw.properties ]]
then
echo "Configuration file owgw.properties is missing in the current directory"
exit 2
fi
docker run -d -p 15002:15002 \
-p 16002:16002 \
-p 16003:16003 \
--init \
--volume="$PWD:/ucentral-data" \
-e UCENTRAL_ROOT="/ucentral-data" \
-e UCENTRALGW_CONFIG="/ucentral-data" \
--name="ucentralgw" $DOCKER_NAME
```
Create yourself a directory and copy that script which you can also get from [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/docker_run.sh).
You must have the basic configuration file copied in the directory. This file must be called `owgw.properties`. You can bring your own or
copy it from [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/owgw.properties). Please look at [this](#certificates-with-docker) to have the right
certificates. You need to make sure that the names match the content of the `owgw.properties`
file. Once all this is done, you can simply run `docker_run.sh`.
#### Docker installation directory layout
Here is the layout expected for your Docker installation
```asm
Run-time root
|
----- certs (same as above)
+---- logs (dir)
+---- uploads (dir)
+---- owgw.properties (file)
```
#### `owgw.properties` for Docker
If you use the pre-made configuration file, and you follow the directory layout, the only line you must change
is the following line:
```asm
openwifi.fileuploader.host.0.name = 192.168.1.176
```
This line should reflect the IP of your gateway or its FQDN. You must make sure that this name or IP is accessible
from your devices. This is used during file uploads from the devices.
#### Certificates with Docker
Please refer to the `certs` directory from the sections above.
#### Configuration with Docker
The configuration for this service is kept in a properties file. Currently, this configuration file must be kept in the
current directory of uCentral or one level up. This file is called `owgw.properties` and you can see the latest version
[here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/owgw.properties). The file will be loaded from
the directory set by the environment variable `UCENTRALGW_CONFIG`. To use environment variables in the configuration,
you must use `$<varname>`. The path for the logs for the service must exist prior to starting the
service. The path is defined under `logging.channels.c2.path`. Only `path names` support the use of
environment variables. Here is a sample configuration:
## Docker
If you would rather launch the docker-compose or helm for the controller, please click [here](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy).
## uCentral communication protocol
The communication protocol between the device and the controller is detailed in this [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/PROTOCOL.md).
@@ -546,56 +343,12 @@ More scripts will be added in the future.
- Devices use the TCP port 16003 to upload files. This port is configurable in the `owgw.properties` file. Look for `openwifi.fileuploader.host.0.port`.
- The RESTAPI is accessed through TCP port 16002 by default. This port is configurable in the `owgw.properties` file. Look for the entry `openwifi.restapi.host.0.port`.
## Kafka integration
So what about Kafka? Well, the gateway has basic integration with Kafka. It is turned off by default, to turn it on, in the configuration:
```asm
openwifi.kafka.enable = false
openwifi.kafka.brokerlist = 127.0.0.1:9092
openwifi.kafka.commit = false
openwifi.kafka.queue.buffering.max.ms = 50
```
#### `openwifi.kafka.enable`
Kind of obvious but hey, set `true` or `false`. Default is `false`
#### `openwifi.kafka.brokerlist`
This is a comma separator list of the brokers in your `kafka` deployment.
#### Kafka topics
## Kafka topics
Toe read more about Kafka, follow the [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/KAFKA.md)
#### Securing `kafka`
This is beyond the scope of this document. As it stands today, the communication between the gateway and `kafka` is expected to be behind a firewall.
#### `iptocountry` feature
In the UI, you will notice the presence of small flags showing where the device connections are from. This feature is
available through the `iptocountry` settings in the configuration. This feature is then also available through the `OpenAPI` for the CLI
and other applications.
##### Config file entries
In the configuration file, you must include the following lines:
```asm
iptocountry.default = US
iptocountry.provider = ipinfo
#iptocountry.provider = ipdata
#iptocountry.provider = ipdata
iptocountry.ipinfo.token =
#ip2location.ipinfo.token =
#iptocountry.ipdata.apikey =
#iptocountry.ip2location.apikey =
```
So you select your provider with the `iptocountry.provider` be specifying ipinfo, or ipdata, or ip2location.
And then you provide the corresponding api key or token.
Only select one. If you select 2, undefined behaviour. All the line you do not need, just put a `#` before to comment it
out.
You will find the supported providers at: `ip2location.com`, `ipinfo.io`, or `ipdata.co`. You MUST supply a valid default
country code in `iptocountry.default`.
## Contributions
We need more contributors. Should you wish to contribute, please follow the [coding style](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/CODING_STYLE.md) document.
## Pull Requests
Please create a branch with the Jira addressing the issue you are fixing or the feature you are adding.
Please create a branch with the Jira addressing the issue you are fixing or the feature you are implementing.
Create a pull-request from the branch into master.