Skip to content

NetReach Reference AP v1.2.0-dev

Pre-release
Pre-release
Compare
Choose a tag to compare
@craigpratt craigpratt released this 01 Dec 00:04
· 4 commits to netreach-integration since this release
v1.2.0-dev
4c4966e

1978 GMC Jimmy

Release notes for the Micronets Gateway Service + NetReach Reference Agent

This release adds the following features to the NetReach agent:

  • Added Trust Domain support. This new construct allows for the grouping of devices according to trust and policy.
  • Three Trust Domain types are supported:
    • PER_DEVICE_CRED_DOMAIN: Each device has its own credential
    • SHARED_CRED_CONFIRMED_DOMAIN: The domain has a credential which all devices can attempt to join with - but they are not included in the domain until confirmed by the customer/delegated user.
    • SHARED_CRED_TIMED_DOMAIN: The domain has a credential which all devices can use to connect to the domain, but their connection is time-limited based on the lease period set in the domain.

Note that the cloud implementation must also support Trust Domains. The NetReach agent included in this release is not backwards-compatible with previous NetReach controller APIs.

Installation

If you have prior versions of the NetReach/Micronets agent and/or micronets-hostap installed, please stop and uninstall them prior to installing this release. There are a number of changes in this release that makes configuration easier. However they can conflict with the configuration that was used in prior releases.

The following would cleanup all the project directories prior to installing this release:

  • Take a backup of your /opt/micronets-hostapd/lib folder - this contains the hostap.conf, hostap.vlan and hostap.wpa_psk files
  • Remove the /opt/micronets-gw and /opt/micronets-hostapd directory
  • Remove the /etc/network/interfaces.d/micronets file (not needed anymore)
  • You might also want to save the /opt/micronets-gw/config.py file if you have made any changes to it

Installing dependent packages

On Raspberry Pi OS 10 and Ubuntu 18.04 or 20.04 LTS, most dependencies are provided by the distribution.
This distribution has been tested on Raspberry Pi OS 10.

To install the required distribution-provided packages, perform the following steps:

sudo apt-get update
sudo apt-get install dnsmasq openvswitch-switch python3 virtualenvwrapper

Configuring system settings

The following settings are not strictly necessary for the gateway and hostap functionality to work but following them will ensure that you have a more optimal system to work with. The following settings disables certain spurious services that are activated by default on all new interfaces

Reducing dhcpcd chatter

Edit the /etc/dhcpcd.conf file and at the end of the file add the following

allowinterfaces eth0 #(Replace eth0 with whatever your wan port is)

This will ensure that dhcpcd does not get invoked on the other interfaces that we will be creating later

Reducing avahi chatter

Edit the /etc/avahi/avahi-daemon.conf file and change the following lines:

use-ipv4=no
use-ipv6=no
allow-interfaces=eth0

This ensures that avahi and mDNS traffic is suppressed from the router (we will still allow this traffic from clients, just not the router itself)

Installing the micronets/netreach hostapd

In addition to the PSK delegate support needed for NetReach, this version of hostapd adds support for the track_sta_list
hostapd_cli command.

curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/v1.2.0-dev/micronets-hostapd-1.0.29.deb
sudo dpkg -i micronets-hostapd-1.0.29.deb

To start the micronets-hostapd service

sudo systemctl start micronets-hostapd.service

We suggest that you do not set the hostap to autostart as there is some manual scripts that need to be run after each reboot (this will be automated in a future release).

You can check to see if the hostap service is running with:

sudo systemctl status micronets-hostapd.service

Installing the NetReach Agent

The Micronets Gateway Service contains the NetReach agent as an "adapter" and is architecture-neutral. But the Debian package dependancies vary by release. The Debian installer included in this release is authored for Rapberry Pi OS and Ubuntu 18.04+. To install it run the following bash commands:

curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/v1.2.0-dev/micronets-gw-1.2.0-U18.04+.deb
sudo dpkg -i micronets-gw-1.2.0-U18.04+.deb

Installing the micronets-gw package will:

  1. install the micronets gateway service in the /opt/micronets-gw directory,
  2. install the helper scripts in the /opt/micronets-gw/bin directory
  3. install a systemd micronets-gw-service service control file

To start the micronets-gw service:

sudo /opt/micronets-gw/bin/setup-vlan-bridges.sh
sudo systemctl start micronets-gw.service

Note: The setup-vlan-bridges.sh script only needs to be run once per reboot (see below).

You can check to see if the gateway service is running using:

sudo systemctl status micronets-gw.service

First-time Configuration

Set a unique serial number for the NetReach Agent/AP

Create a file named /opt/micronets-gw/lib/netreach-serialnum.txt and enter a unique serial number for the AP. This is free-form text for now but may be restricted in a later release.

echo "BART-AP-0001" > /opt/micronets-gw/lib/netreach-serialnum.txt

Register the AP with the NetReach Controller

In order for the NetReach Agent adapter to login to the mqtt broker as well as the Controller, the following steps are needed to register the NetReach Agent/AP with the Netreach Controller. These steps only need to be done once after the agent installation.

There are two ways to have the AP registered with the controller:

  • The AP is provisioned with a "registration token". The AP generates it's own public/private keypair and uses the one-time-use registration token to register the AP with the Controller.
  • A public/private keypair is generated on (or for) the AP and the public key is registered with the controller (using user/operator credentials).

Both of these methods are detailed below.

Registering the NetReach Agent/AP with the NetReach Controller using a Registration Token

This is the simpler of the two methods and is recommended for most cases.

Creating the AP Entry with Registration Token

Before the NetReach agent can authenticate with the Controller, we can create a registration token to allow the NetReach agent to create and register its public/private ECC key-pair with the Controller the first time it starts up. This needs to be done by invoking the REST API with the Controller using an api-token that is generated with a user credential. The following is a template curl command that will need to be filled in with the relevant info

curl --location --request POST 'https://staging.api.controller.netreach.in/v1/access-points/' \
--header 'x-api-token: <api-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "<unique name for ap>",
    "serial": "<same-as-serialnum-file-above>",
    "enabled": true,
    "geolocation": {
        "latitude": "<XX>",
        "longitude": "<YY>"
    }
}'

This will return the registrationToken used below to register the NetReach Agent's public key.

Configure the NetReach agent with the registration token

Save the registrationToken returned above into the file /opt/micronets-gw/lib/netreach-reg-token.txt and restart the agent using sudo systemctl restart micronets-gw.service.

When the agent starts up, it will generate an ECC public/private keypair and register the public key using the registration token. Once used the netreach-reg-token.txt file will be deleted, since it's no longer valid. This can be verified by examining the Micronets/NetReach Agent log at /opt/micronets-gw/micronets-gw.log.

Registering the NetReach Agent/AP with the NetReach Controller using a pre-defined Public Key

The steps below are for registering the AP using a pre-defined public/private keypair. This should be skipped if the AP is being registered using a registration token.

Manually create a public/private ECC key-pair for the NetReach agent

openssl  ecparam -name prime256v1 -genkey -noout -out netreach-privkey.pem
openssl ec -in netreach-privkey.pem -pubout -out netreach-pubkey.pem
sudo cp netreach-*key.pem /opt/micronets-gw/lib/

Register the AP and associated public key with the Controller

Before the NetReach agent can authenticate with the Controller, we need to enroll its public key (generated above) with the Controller. This needs to be done by invoking the REST API with the Controller using an api-token that is generated with a user credential. The following is a template curl command that will need to be filled in with the relevant info:

curl --location --request POST 'https://staging.api.controller.netreach.in/v1/access-points/' \
--header 'x-api-token: <api-token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "<unique name for ap>",
    "serial": "<same-as-serialnum-file-above>",
    "enabled": true,
    "geolocation": {
        "latitude": "<XX>",
        "longitude": "<YY>"
    },
    "publicKey": "<public-key-from-above>"
}'

Note that the newlines in the key.pem file need to be replaced with "\n" and make the entire public key a single string (including the first and the last header lines)

Once the key has been registered with the Controller, the NetReach adapter will be able to authenticate and retrieve an api-token to authenticate with the mqtt broker and invoke the other API endpoints on the Controller.

Follow the steps below prior to starting the micronets-gw service.

Configuration after each reboot

All the core gateway configuration has now been automated through the /opt/micronets-gw/bin/setup-vlan-bridges.sh script. After each reboot of the AP, run the script as follows (or incorporate these steps into your system startup)

sudo /opt/micronets-gw/bin/setup-vlan-bridges.sh

This will create the necessary OVS bridges and interfaces. Specifically:

  • It creates a veth pair "haport/haport-sw". The "haport" is the means to hook up hostapd's vlan tagged traffic to the OVS switch.
  • Ensure that the vlan-tagged-interface setting in /opt/micronets-hostapd/lib/hostapd.conf file has the value "haport" (this should be the default)
  • Ensure that the bridge parameter in the hostap.conf file is commented out
  • Ensure that you only have one IP address on your WAN port (typically eth0)
Assets 5
Loading