NetReach Reference AP v1.1.4-dev

Notes on this release

This release adds the following features to the NetReach PoC agent:

• Fix for hostapd PSK lookups. The PSK lookup delegate is no longer invoked when a station MAC is present in the WPA PSK file but the PSK doesn't match the entry.
• The NetReach Agent now updates the AP cloud entry with its geolocation and management address at startup. This can be configured to provide the address of a particular interface (via NETREACH_ADAPTER_MAN_INTERFACE) or specified explicitly (via NETREACH_ADAPTER_MAN_ADDRESS)

Installation

If you have prior versions of the micronets-gw 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 and Ubuntu 18.04+, the dependencies are provided by the distribution.

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 some 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

Reduce 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

Reduce 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 micronets hostapd

In addition to the PSK delegate support, 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.1.4-dev/micronets-hostapd-1.0.28.deb
sudo dpkg -i micronets-hostapd-1.0.28.deb

To start 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 the next 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.1.4-dev/micronets-gw-1.1.4-U18.04+.deb
sudo dpkg -i micronets-gw-1.1.4-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 micronets-gw service:

sudo systemctl start micronets-gw.service

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 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 later may be restricted.

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. These steps only needs to be done once after the agent installation

Manually generate a public/private ECC key-pair for the agent and register it with the NetReach Controller

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 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 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.

Automatically generate a public/private ECC key-pair for the agent and register it using a registration token

Register the AP with the Controller

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 a registrationToken which can be used one time by a NetReach agent to register its public ECC key.

Configure the NetReach agent with the registration token

Save the registrationToken returned above into the file /opt/micronets-gw/bin/netreach-reg-token.txt. 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.

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, simply run the script as follows

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

And it will create the necessary OVS bridges and interfaces. As part of the creation,

• 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)