Skip to content

Release 1.0.65 (for Raspbian 10/Ubuntu 18.04 LTS)

Pre-release
Pre-release
Compare
Choose a tag to compare
@craigpratt craigpratt released this 27 Nov 10:25
· 4 commits to releases/ubuntu-18.04 since this release
1.0.65
cd16295

Notes on this release

This release contains the following changes:

  • Initial DPP2 provisioning/reprovisioning support (includes a new version
    of hostapd and wpa_supplicant binaries)
  • The Micronet/device data model is now persisted to json files instead
    of the dnsmasq config file - which simplifies things and makes it easier
    to change the model.

Installation

If Micronets is already installed and running, you should stop the services first using:

sudo systemctl stop micronets-gw.service 
sudo systemctl stop micronets-hostapd.service

You might also want to save /opt/micronets-gw/config.py if you've made changes to this file.

Installing Dependent Packages

On Ubuntu 18.04, most of the dependancies 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

Installing micronets hostapd (to support wireless micronets)

This release includes a version of hostapd for Raspian 10 that includes openvswitch and DPP Reconfigure support. It can be downloaded and installed using:

curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.65/micronets-hostapd-1.0.25.arm.deb
sudo dpkg -i micronets-hostapd-1.0.25.arm.deb

To start micronets-hostapd service, and set it for autostart:

sudo systemctl enable micronets-hostapd.service
sudo systemctl start micronets-hostapd.service

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

sudo systemctl status micronets-hostapd.service

A Station client (wpa_supplicant) supporting a prototype implementation of DPP reconfigure can be downloaded using:

curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.65/micronets-wpa_supplicant.1.0.25.tar.gz

Note that you should only install this client if you're interested in testing DPP reconfigure on a Raspberry Pi.

The hostapd source and other releases can be found at the Micronets hostapd guthub repo.

Installing the Micronets Gateway Service on Ubuntu 18.04:

The Micronets Gateway Service is architecture-neutral. But the Debian package dependancies vary by release. The Debian installer included in this release is authored for Ubuntu 18.04. To install it run the following bash commands:

curl -L -O https://github.com/cablelabs/micronets-gw/releases/download/1.0.65/micronets-gw-1.0.65-U18.04.deb
sudo dpkg -i micronets-gw-1.0.65-U18.04.deb

Installing the micronets-gw package will:

  1. install the micronets gateway service in the /opt/micronets-gw directory,
  2. install the ifup/down and dnsmasq extension scripts for the configuration of openvswitch and the micronets-gw service via /etc/network/interfaces,
  3. install a sample ifupdown "interfaces" file in /opt/micronets-gw/doc/interfaces.sample, and
  4. install a systemd micronets-gw-service service control file

To start micronets-gw service, and set it for autostart:

sudo systemctl enable 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

Configuration

If this is the first install of the Micronets gateway, copy /opt/micronets-gw/doc/micronets.sample to /etc/network/interfaces.d/micronets and modify to suit your system.

If you have one wired and one wireless interface you want to enable for micronets, this should just be a matter of replacing interface names. e.g. If you want to enable interface eth1 as a wired micronet, and wlan0 for wireless micronets, lines in the interfaces file would appear respectively as:

#
# A wired interface managed by the Micronets gateway
#
allow-brmn001 eth1 
iface eth1inet manual
  ovs_type OVSPort
  ovs_bridge brmn001
  ovs_port_req 4
  ovs_port_initial_state blocked

#
# A wireless interface managed by the Micronets gateway
#
allow-brmn001 wlan0
iface wlan0 inet manual
  ovs_type OVSPort
  ovs_bridge brmn001
  ovs_port_req 3
  ovs_port_initial_state blocked

and ensure the bridge entry contains a ovs_ports line referring to the micronet interfaces. e.g.

and the bridge defintion would include the line:

auto brmn001
allow-ovs brmn001
iface brmn001 inet manual
  ovs_type OVSBridge
  ...
  # the ovs_ports should list all wired and wireless interfaces under Micronets management
  ovs_ports diagout1 eth1 wlan0
  ...

Note that more than one wired interface can be setup for micronets. Each needs to have a discreet "ovs_port_req" number and needs to be included in the bridge entry's "ovs_ports" line.

To setup the uplink interface (the interface used to connect to the internet), ensure the entry in the interfaces file for that interface is setup correctly for the network. e.g. if the uplink interface is eth0 and get its address via DHCP, the definition would be:

#
# The uplink port
#
auto eth0
iface eth0inet dhcp

and ensure the bridge entry contains a ovs_bridge_uplink_port line referring to the uplink interface. e.g.

auto brmn001
allow-ovs brmn001
iface brmn001 inet manual
  ovs_type OVSBridge
  ...
  # This is the port that's connected to the Internet
  ovs_bridge_uplink_port eth0
  ...

The default configuration of the Micronets Gateway Service presumes the Micronets hostapd will be installed and running. If you're only running Micronets for wired networks, remove any wireless interface definitions from the /etc/network/interfaces.d/micronets file and change the following setting at the end of /opt/micronets-gw/config.py:

class DefaultConfig (LocalWirelessTestingConfig):
    pass

and change it to:

class DefaultConfig (LocalWiredTestingConfig):
    pass

Finally, to enable the Micronets gateway service to be started using systemctl, run the following bash commands:

sudo systemctl enable micronets-gw.service 
sudo systemctl start micronets-gw.service

Ensure that the file /etc/network/interfaces contains the line:

source-directory interfaces.d

And reboot the gateway to apply the changes to the /etc/network/interfaces.d/micronets file

Operation

Micronets can be defined on the local gateway using the local Micronets Gateway REST API.

Initially the list of micronets should be empty. This can be verified by running:

curl -X GET  http://localhost:5000/micronets/v1/gateway/micronets

which should return:

{
  "micronets": []
}

if the service is configured and operating.

Defining Wireless Micronets

To create a micronet on the wireless interface (e.g. wlan0), you can use:

curl -X POST -H "Content-Type: application/json" -d '{
        "micronet": {
            "micronetId": "micronet-1",
            "vlan": 1001,
            "ipv4Network": {
                "network": "10.135.1.0",
                "mask": "255.255.255.0",
                "gateway":"10.135.1.1"
            },
            "interface": "wlan0"
        }
    }' http://localhost:5000/micronets/v1/gateway/micronets

Multiple micronets can be defined on a wireless interface. The networkAddress elements needs to be compatible with the addresses defined for the micronets bridge in the /etc/network/interfaces.d/micronets file. e.g. This definition would allow for 5 micronets to be defined:

iface brmn001 inet static
  address 10.135.1.1/24

iface brmn001 inet static
  address 10.135.2.1/24

iface brmn001 inet static
  address 10.135.3.1/24

iface brmn001 inet static
  address 10.135.4.1/24

iface brmn001 inet static
  address 10.135.5.1/24

And to provision a device in the new wireless micronet defined above (using a PSK):

curl -X POST -H "Content-Type: application/json" -d '{
       "device": {
           "deviceId": "mydevice-001",
           "macAddress": {
               "eui48": "00:00:11:11:22:22"
           },
           "networkAddress": {
               "ipv4": "10.135.1.100"
           },
           "psk": "abcd1234"
       }
}' http://localhost:5000/micronets/v1/gateway/micronets/micronet-1/devices

Devices can also be provisioned for wireless Micronets using DPP. This isn't covered in this brief introduction.

Defining Wired Micronets

A wired micronet can be defined similar to a wireless micronets. But only one wired micronet can be defined on a wired interface. e.g.

curl -X POST -H "Content-Type: application/json" -d '{
        "micronet": {
            "micronetId": "micronet-5",
            "ipv4Network": {
                "network": "10.135.5.0",
                "mask": "255.255.255.0",
                "gateway":"10.135.5.1"
            },
            "interface": "eth1"
        }
    }' http://localhost:5000/micronets/v1/gateway/micronets

Adding a device to this wired Micronet is similar to adding a device to a wireless micronet. e.g.

curl -X POST -H "Content-Type: application/json" -d '{
       "device": {
           "deviceId": "mydevice-002",
           "macAddress": {
               "eui48": "00:00:11:11:22:33"
           },
           "networkAddress": {
               "ipv4": "10.135.5.100"
           }
       }
}' http://localhost:5000/micronets/v1/gateway/micronets/micronet-5/devices

Retrieving Micronet and device definitions

The list of currently defined Micronets can be retrieved using:

curl http://localhost:5000/micronets/v1/gateway/micronets

and the list of devices provisioned for a Micronet (e.g. "micronet-1") can be retrieved using:

curl http://localhost:5000/micronets/v1/gateway/micronets/micronet-1/devices

Checking the operation of the Micronets Gateway:

The status of the Micronets bridge and various settings can be checked by running:

sudo /opt/micronets-gw/bin/status

and to examine the flow of packets through the micronets bridge:

sudo /opt/micronets-gw/bin/watch-ovsrules
Assets 5
Loading