Skip to content

Latest commit

 

History

History
114 lines (78 loc) · 3.62 KB

README-docker.md

File metadata and controls

114 lines (78 loc) · 3.62 KB
Raw

Unum and Docker

The files in this folder are used to build and start a Docker container complete with everything necessary to run as a Linux router, including the Unum agent.

For the Unum agent to function, a Minim Labs developer account is required. Sign up for an account or find out more on the Minim Labs website.

Known Limitations

  • Only supports USB wireless adapters on Linux
  • Does not support wireless adapters on macOS
  • Untested on Windows

Building and Starting

Run the docker_build.sh script under extras/linux_generic/ to build a new image and then start a container and configure it for use.

On Linux, the script must be run as root or have access to the docker daemon. From the unum root directory, assuming your host WAN interface is "ens33": sudo extras/docker/docker_build.sh ens33

Full usage:

extras/docker/docker_build.sh [-X|-B <builder>] <WAN ifname>

The WAN interface name (<WAN ifname> above) should be the host machine's internet-connected interface. A bridge is created between the host and Unum container and this is used as the WAN interface on the container.

Skip building an image at all by passing -X.

sudo extras/docker/docker_build.sh -X ens33

Skip building a builder image, but recreate and configure the Unum container:

sudo extras/docker/docker_build.sh \
        -B minimsecure/unum-builder:ubuntu-16.04 ens33

Starting Unum

Once the container is running, you'll be placed into a bash session running in the container.

You will need a specific, generated MAC address during first time setup. This MAC address is used to associate your agent with your Minim Labs account. Sign up and login to the Minim Labs developer portal, click the top- right drop down, then click "Provisioning Details".

Start everything with minim-config:

minim-config

On the first run, the script will interactively configure Unum and set the MAC address before starting hostapd, dnsmasq, and unum. Be sure to have the generated MAC address from the Minim Labs developer portal handy!

Adding a container to the LAN

Once the gateway container with Unum is configured and running, you can start another container and attach it to the LAN network with the option --network unum-demo-net-b-lan when invoking docker run:

sudo docker run --rm --privileged \
    --network unum-demo-net-b-lan \
    -it minimsecure/netbox /bin/bash

Technical Overview

There are two Docker images generated by the build, a "builder" and the actual Unum-enabled Linux router image.

The "builder" image, built from Dockerfile.build, has all of the build-time dependencies installed on an Ubuntu 16.04 base. When started, the container will run the unum build.sh script and generate a tarball in /usr/local/unum/out/ (inside the container). This tarball is used in the second stage of the process to install Unum.

The router image is built from Dockerfile and includes: dnsmasq, hostapd, iptables, the Unum agent, and a host of other programs for running a Linux router. Additionally, several shell scripts from the linux_generic "extras" are included.

Other notes:

  • Configuration files are stored in /etc/opt/unum
  • Log files and other runtime files are stored in /var/opt/unum
  • Unum and co are installed in /opt/unum

CircleCI integration

The unum and unum-builder images are also built continuously and published on Docker Hub using CircleCI. Check the CircleCI integration notes for more information on how this is done.