How-To Guides

I. Accessing the ENF

We first shed light on how a customer can connect different endpoints to the Edge Network Fabric. The subsequent chapters discuss how the customer may then use and manage their network. The articles below are fairly technical and centered on the accompanying enfcli tool.

Working with Card Profiles

This how-to will walk through creating and updating a profile. Adding a WiFi Configuration and configuring a firmware update are covered in other how-to articles under the ** section.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • User has DOMAIN_ADMIN account
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    

Create a Profile

Create a profile with an appropriate name.

> captive create-profile --device-mode=secure-host --profile-name=RFD-devices
Name                  : RFD-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 1
Firmware Update ID    : < not configured >
Mode                  : secure-host
Wifi config           : < not configured >

Currently, only the secure-host mode is supported.

Profiles are not deleted or overwritten. When a change is made to a profile, the system automatically bumps the version up. This ensures that there is a history of all of the changes to a profile. Only the latest profile will be applied to devices.

Create a Profile with Existing WiFi / Update Configurations

If a WiFi Configuration or Firmware Update Record already exists, you can include either or both of those IDs in the create-profile command to save a step.

> captive create-profile --device-mode=secure-host --profile-name=Scranton-devices --wifi-id=1aad6bdd-8b09-49bc-bd43-d5255d543c78
Name                  : Scranton-devices
Profile ID            : c61404e4-ddb0-4b73-9f80-0edfb77fe8b3
Configuration version : 1
Firmware Update ID    : < not configured >
Mode                  : secure-host
Wifi config           :
    id                : 1aad6bdd-8b09-49bc-bd43-d5255d543c78
    domain            : 2607:8f80:8080::/48
    name              : Demo
    config version    : 4

Apply a Profile to a Device

The Captive Server will query the IAM server to get a list of all provisioned devices. The details of the device will be populated automatically once it connects to the ENF.

To have the Captive Server apply the setting from a profile to a device, the device must be updated to use the profile.

Devices may be identified either by the serial number or the IPv6 address.

  1. List the devices.
    > captive list-devices
    +-----------------+----------+--------------------------------------+-------------+-----------+---------------+
    | Serial No       | Dev Name | Dev Addr                             | Router Mode | Connected | SSID          |
    +-----------------+----------+--------------------------------------+-------------+-----------+---------------+
    | XRW0441900A001  |          | 2607:8F80:8080:9:7B86:E00F:D00F:FADD | secure-host | true      | xaprc_default |
    | XRW0441900A002  |          | 2607:8F80:8080:7:4B1A:C340:DDD2:F6DA | secure-host | true      | xaprc_default |
    | XRW0441900B003  |          | 2607:8F80:8080:7:82C5:3E33:CC8E:1D84 | secure-host | false     |               |
    +-----------------+----------+--------------------------------------+-------------+-----------+---------------+
    

    We are going to be working with the first device in the list.

  2. Get the device status to verify it is connected to the ENF.
    > captive get-device-status --device-id=XRW0441900A001
    Serial Number        : XRW0441900A001
    Router Mode          : secure-host
    Uptime (in seconds)  : 7563.81
    Status refresh time  : 2020-07-15T18:27:04Z
    WIFI status          :
     connected        : true
     SSID             : xaprc_default
     IPv4 addresses   :
         IPv4         : 192.168.2.222
     IPv6 addresses   :
         IPv6         : fdc3:c108:dc6a:0:b2a6:f5ff:fe00:fbe
         IPv6         : fe80::b2a6:f5ff:fe00:fbe
    WIFI configuration   :
     Name          :
     Wifi ID       :
    Firmware Status      :
     image name       : < not available >
     operating state  : normal
    
  3. Update the device to use the new profile.
    > captive update-device --device-id=XRW0441900A001 --profile-id=d37a1806-3989-48fb-9742-6a4d22191dd9
    Serial Number     : XRW0441900A001
    Device Name       : demo-device-1
    Device Address    : 2607:8F80:8080:9:7B86:E00F:D00F:FADD
    Mac Address       : B0:A6:F5:00:10:A6
    Firmware Version  : xaprw001-v1.0.9-0-gb5b1470
    Hardware Model    : xaprw001
    Profile           :
     Name                  : Chicago-North
     Profile ID            : d37a1806-3989-48fb-9742-6a4d22191dd9
     Configuration version : 1
     Firmware Update ID    : < not configured >
    Status            :
     Router Mode   : secure-host
     wifi connected:  < unknown >
    

The Captive Server will schedule an update task to send the new configuration to the device. The update usually takes between 3 and 10 minutes, depending on how busy the Captive Server is.

Update a Profile

The profile name, WiFi Configuration, and Firmware Update fields of a profile may be modified.

Updating the profile name:

> captive update-profile --profile-id=70a82dd2-5a5a-40cb-9575-aaff5b7414dc --profile-name=TEST-devices
Name                  : TEST-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 2
Firmware Update ID    : < not configured >
Mode                  : secure-host
Wifi config           : < not configured >

Configuring WiFi Access

This how-to describes setting up the WiFi credentials and configuration of the ENF Router Card. After a WiFi Configuration is created or updated, the profile must be updated to use the new WiFi Configuration.

The router card can only be configured via the enfcli and ENF. Since there is no local, configuration page, it is nearly impossible for a malicious actor to misconfigure the WiFi – even with physical access.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • User has DOMAIN_ADMIN account
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    

Create the WiFi Configuration JSON file

The WiFi configuration is created as a JSON file and uploaded via the enfcli.

Using your favorite text editor, create the WiFi configuration JSON file. For this example, the file will be in ~/chicago-north.json
It should be in the format:

{
    "name" : "Chicago-North-Wifi",
    "description" : "Connects Chicago North Factory Floor",
    "networks" : [
        {   "name" : "Acme Mfg.",
            "SSID" : "AcmeHidden",
            "SSID_type" : "string",
            "auth" : {
                "type" : "psk",
                "passphrase" : "WileE.CoyoteGenius"
            },
            "IPv4" : {
				"type" : "dhcp"
			},
            "IPv6" : {
				"type" : "auto"
			}
        }
    ]
}

Create the WiFi configuration record

The JSON file informs the Captive Server how to create the configuration record that will be sent to the router-card. The JSON file must be uploaded via the enfcli.

> captive create-wifi-configuration --wifi-config-file=/home/jqpublic/chicago-north.json
Name          : Chicago-North-Wifi
Wifi ID       : 9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258
WiFi Networks :
    Name          : Acme Mfg.
        SSID         : AcmeHidden
        SSID type    : string
        auth         : psk
        IPv4         : dhcp
        IPv6         : auto

To list the WiFi configurations:

> captive list-wifi-configurations
+--------------------------------------+--------------------+--------------+
| ID                                   | Wifi Name          | Config Vers. |
+--------------------------------------+--------------------+--------------+
| 9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258 | Chicago-North-Wifi | 1            |
+--------------------------------------+--------------------+--------------+

Assign WiFi Configuration to a Profile

Once the WiFi Configuration record is created, it must be assigned to a Profile in order for it to be applied to one or more devices.

This example uses the Profile that was created in the Router Card Profile example. To view that Profile, issue the following:

> captive get-profile --profile-id=70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Name                  : TEST-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 1
Firmware Update ID    : < not configured >
Mode                  : secure-host
Wifi config           : < not configured >

Now, update the profile using the new WiFi Configuration:

> captive update-profile --profile-id=70a82dd2-5a5a-40cb-9575-aaff5b7414dc --wifi-id=9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258
Name                  : TEST-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 2
Firmware Update ID    : < not configured >
Mode                  : secure-host
Wifi config           :
    id                : 9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258
    domain            : 2607:8f80:8080::/48
    name              : Chicago-North-Wifi
    config version    : 1

As mentioned in the Router Card Profile article, an existing WiFi Configuration can be added to a profile in the create-profile command.

Updating Card Firmware

The Captive Server manages firmware updates for the ENF Router Card. To accomodate customer scheduling needs, the Captive Server has flexible scheduling capabilities.

The Xaptum engineering team will make the new firmware release available to the ENF. At that point, the customer follows three steps to install the firmware.

  • Create a schedule for the installation.
  • Create a firmware-update task.
  • Assign the firmware-update task to a device profile.

Before applying any update, the Captive Server will check to ensure that the currently running firmware is older than the requested update.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • User has DOMAIN_ADMIN account
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    

Create an Installation Schedule

The Captive Server scheduling is defined in a JSON file and is similar to a Unix cron schedule. The user defines the year, month, day of the month, hour, minute, and day of the week for the schedule to become active. The installation schedule has two additional fields: the domain and a description. Schedules only apply to a single domain – if the same timing is desired for a different domain, you must create a new schedule. Note that in the installation schedule, the domain field may refer to a /48 domain or a /64 network.

  1. Using your favorite text editor, create a schedule JSON file that looks like:
    {
     "name" : "Weekend_update",
     "domain" : "2607:8F80:8080:0009::/64",
     "times" : [
         {
             "minute" : "*",
             "hour" : "23,0-2",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "0"
         },
         {
             "minute" : "*",
             "hour" : "23",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "6"
         },
         {
             "minute" : "*",
             "hour" : "0-2",
             "day_of_month" : "*",
             "month" : "*",
             "year" : "*",
             "day_of_week" : "1"
         }
     ]
    }
    

The schedule JSON is an object with three elements:

  • name - a user-defined string
  • domain - a string containing the /48 or /64 domain.
  • times - an array of timing objects.

The times objects contain the following string elements:

  • minute
  • hour
  • day_of_month
  • month
  • year
  • day_of_week - where 0 is Sunday

The example above schedules an update on domain 2607:8F80:8080:0009::/64 for Saturday and Sunday nights from 1 1PM until 2 AM.

  1. Create the update
    > captive create-schedule --schedule=/Users/jqpublic/schedule-weekend.json
    Schedule Name    : Weekend_update
    Shedule ID       : dc8a7576-51c9-4854-ac12-cac13024d836
    domain           : 2607:8f80:8080:9::/64
    Times:
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    | Name | year | Month | Date | Weekday | Hour   | Minute | id                                   |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    |      | *    | *     | *    | 0       | 23,0-2 | *      | 55da6480-a0e0-4f4a-9057-dd9ee516c343 |
    |      | *    | *     | *    | 6       | 23     | *      | 6e94a908-aa00-4cda-99ee-4a1e49a445be |
    |      | *    | *     | *    | 1       | 0-2    | *      | 0ebf132e-a65b-4028-828f-c03c379f5ad6 |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    
  2. List existing schedules
    > captive list-schedules
    +----------------+--------------------------------------+
    | Name           | ID                                   |
    +----------------+--------------------------------------+
    | Weekend_update | dc8a7576-51c9-4854-ac12-cac13024d836 |
    +----------------+--------------------------------------+
    
  3. Get details on a specific schedule
    > captive get-schedule --schedule-id=dc8a7576-51c9-4854-ac12-cac13024d836
    Schedule Name    : Weekend_update
    Shedule ID       : dc8a7576-51c9-4854-ac12-cac13024d836
    domain           : 2607:8f80:8080:9::/64
    Times:
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    | Name | year | Month | Date | Weekday | Hour   | Minute | id                                   |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    |      | *    | *     | *    | 0       | 23,0-2 | *      | 55da6480-a0e0-4f4a-9057-dd9ee516c343 |
    |      | *    | *     | *    | 6       | 23     | *      | 6e94a908-aa00-4cda-99ee-4a1e49a445be |
    |      | *    | *     | *    | 1       | 0-2    | *      | 0ebf132e-a65b-4028-828f-c03c379f5ad6 |
    +------+------+-------+------+---------+--------+--------+--------------------------------------+
    

Create Firmware Update Task

The firmware update task associates a firmware version. It also provides for selecting the percentage of devices to update. For example, it is possible to upgrade only 10% of the devices to firmware version 1.2.0, using the schedule listed above.

The update task is created as a JSON file and then uploaded to the captive server via enfcli.

  1. Examine the available firmware versions.
    > captive list-firmware-images
    +------------------+
    | Firmware Version |
    +------------------+
    | 1.0.13           |
    | 1.0.14           |
    | 1.1.1            |
    | 1.2.0            |
    +------------------+
    
  2. If desired, get detailed information on the specific firmware image.
    > captive get-firmware-info --version=1.2.0
    Release version: 1.2.0
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    | Image Name                                            | Hardware Model | Update Type | SHA256                                       |
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    | artifact-signed-xaprw001_dev-v1.2.0-0-g25a335e.mender | xaprw001_dev   | update      | 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU= |
    +-------------------------------------------------------+----------------+-------------+----------------------------------------------+
    1 rows in set
    
  3. Using your favorite editor, create an update-task JSON file.
    {
     "version" : "1.2.0",
     "schedule_id" : "dc8a7576-51c9-4854-ac12-cac13024d836",
     "update_percentage" : 10
    }
    
  4. Create the update task.
    > captive create-firmware-update --update=/Users/jqpublic/update-test.json
    Update Task ID               : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
    Schedule ID                  : dc8a7576-51c9-4854-ac12-cac13024d836
    Firmware Version             : 1.2.0
    Percent of devices to update : 10.0
    

Add Update Task to a Profile

Once an updat task has been created, it must be applied to one or more profiles. Without this step, the task is not associated with any devices and the Captive Server will not act on it.

Add update task to an existing profile.

> captive update-profile --profile-id=70a82dd2-5a5a-40cb-9575-aaff5b7414dc --update-id=84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
Name                  : TEST-devices
Profile ID            : 70a82dd2-5a5a-40cb-9575-aaff5b7414dc
Configuration version : 3
Firmware Update ID    : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
    Update version    : 1.2.0
Mode                  : secure-host
Wifi config           :
    id                : 9e3f2a2e-e2ef-4152-8fa3-44b40ad1d258
    domain            : 2607:8f80:8080::/48
    name              : Chicago-North-Wifi
    config version    : 1

As mentioned in the Router Card Profile article, an existing update task can be added to a profile in the create-profile command.

Modify the Update Task

In the example, we updated 10% of the devices to version 1.2.0. Once these are complete and have proven reliable, we might want to update 50% of the devices. Modify the JSON file to have "update_percentage" : 50. This update percentage is cumulative. In this example, we’re updating an additional 40% of the devices – 50% in total.

> captive modify-firmware-update --update-id=84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2 --update=/Users/jqpublic/update-test.json
Update Task ID               : 84d2cc7f-ce3c-40f7-8694-ce74e80dc2c2
Schedule ID                  : dc8a7576-51c9-4854-ac12-cac13024d836
Firmware Version             : 1.2.0
Percent of devices to update : 50.0

Since, in this example, the update task has already been added to an active profile, it is not neccessary to add it again.

Setting Up a New Card

The ENF Router Cards are shipped without a default password but with a default network. To allow the device to connect to the ENF, the customer must configure the new card by setting up a temporary configuration network. This network can be in a DMZ - completely outside of the corporate network - as long as it can reach the global internet. Because ENF traffic is always encrypted and the ENF and the device are both authenticated, the use of a default network does not diminish security.

Create the Default WiFi Network

The default network must be configured as follows:
    SSID: xaprc_default
    Password: password123!

As mentioned above, the network must have internet access.

Once the default network is set up, the device will connec to the ENF. This may take a few minutes but may be sped up by performing a reboot.

To verify that the device has connected, login to the Xaptum Control Panel webpage. For most cases,this will be similar to: https://.xaptum.io . Use the account credentials given. The new divice will show up as ONLINE in the appropriate network.

Configure the Router Card

  1. Follow the instructions in the Router Card Profile to create a profile

  2. Using the Router Card WiFi Configuration article as a guide, create and apply a WiFi configuration to the profile.

  3. If needed, create a firmware update schedule and an update task per the Updating Router Card Firmware article.

  4. Apply the new profile to the device as described in the Router Card Profile article.

Disable the Default WiFi Netowrk

Once all of the devices have been updated to the desired configuration, it is safe to disable the xaprc_default network.

Host Socket Sharing (HSS)

Every ENF Router Card comes with the HSS feature, allowing it to handle encryption while directing the encrypted traffic back into the gateway for transmission through another network device (Ethernet, LTE, ect).

Xaprc with WiFiXaprc with HSS
Figure 1: Data flow with WiFi Figure 2: Data flow with HSS

HSS requires the host to install a custom driver described in the section below. Once installed, this driver will automatically detect when the router card wants to direct traffic back into the host. The TCP traffic will follow all routing/iptables rules once directed back into the host.

Note: By default the router card will always connect over WiFi, and failing that will try HSS. There is currently no configuration to have the router card ignore a functional WiFi connection.

Configuring HSS on the host

HSS requires a custom driver to be built and loaded. The preferred install method is using DKMS. Otherwise, the driver would have to be manually rebuilt every time the kernel is updated.

Debian installation

Xaptum maintains a Debian package for the HSS driver. Use the following steps to install it.

Add Xaptums APT repo
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys c615bfaa7fe1b4ca
echo "deb http://dl.bintray.com/xaptum/deb <dist> main" | sudo tee /etc/apt/sources.list.d/xaptum.list
sudo apt-get update

Replace <dist> with your Debian distrobuation (Stretch, Buster, ect)

Install the HSS drivers
sudo apt-get install xaptum-hss-host
DKMS Installation

Systems that do not run Debian can still benefit from the management features that DKMS provides. DKMS will ensure that HSS is recompiled with new kernels and that future updates can be managed.

git clone git@github.com:xaptum/hss.git
cd hss/host
sudo ./dkms-install
Manual installation

If neither our APT repos or DKMS are available the module can be independently built and managed.

Note: Required packages: kernel-devel, git, build-essential, kernel-headers-$(uname -r), sudo

git clone git@github.com:xaptum/hss.git
cd hss/host/src
make
sudo make install

Routing

Routing IPv6 traffic works the same as a non-HSS setup. However, considerations will also have to be made to allow IPv4 traffic to be routed through the secondary network device. The router card will send IPv4 traffic to the ENF servers at 23.147.128.112:443.

Docker Container

Connecting a Container

This tutorial shows how to set up a Docker Container as an ENF endpoint. It follows the README file from the xaptum/enf-services github repository.

We will use the xaptum/enftun Docker Container published on Docker Hub. This container was created from the enftun dirctory of the enf-services repository on GitHub for more flexibility. For more flexibility in configuring the container, clone the repository.

Assumptions

This tutorial was created on a Linux device and makes some assumptions based on the environment. Installation on a Mac should be nearly identical. Using a Windows machine has not been attempted, but should be possible without much modification since all of the tools are available.

  • This tutorial was run for network CIDR: 2607:8f80:8080:b::/64
  • The commands were run on a Linux environment with user directory: jqpublic
  • Adjust commands and expected responses appropriately.

Environment Prerequisites

The following tools will need to be installed prior to running through the tutorial:

Configure Docker for IPv6

Docker images for the ENF require IPv6 support, which is not enabled by default in most Docker installations. To enable it, add the following options to the Docker daemon configuration file daemon.json.

  • "ipv6" : true
  • "fixed-cidr-v6" : "fd00:d0c::/64"

and restart the Docker daemon.

On Linux, daemon.json is located at /etc/docker/daemon.json.

On Mac OS, change it via the Docker Preferences->Daemon->Advanced menu.

The fixed-cidr-v6 option is required due to a bug in Docker. The fd00:d0c::/64 prefix is arbitary. Replace it as desired.

Generate keys

In order to securely communicate, the docker containers and the ENF must share a set of public/private keys. The ENF must also know the address to assign to the endpoints. This task is accomplished via the enfcli.

  1. Create a directory for the client keys and cd into it.
    > mkdir -p ~/enf-docker-container/enf0
    > cd ~/enf-docker-container/enf0
    
  2. Start the ENFCLI and login as a network administrator.
    This is the account that was created when the system created a demo account.
    > enfcli --host demo.xaptum.io --user johnqpublic@somecompany.com
    Connecting to 'https://demo.xaptum.io'.....
    Enter Password:
    
  3. Create the key files for the Server.
    > iam create-endpoint-key --key-out-file=enf0.key.pem --public-key-out-file=enf0.pub.pem
    Created enf0.key.pem
    Created enf0.pub.pem
    
  4. Create the ENF endpoint and assign an address.
    > iam create-endpoint-with-address --address=2607:8f80:8080:b::deb:2 --public-key-in-file=enf0.pub.pem
    Created new ipv6 endpoint 2607:8f80:8080:b::deb:3
    
  5. Create a certificate to be used by the endpoint from the private key.
    > iam create-endpoint-cert --cert-out-file=enf0.crt.pem --identity=2607:8f80:8080:b::deb:2 --key-in-file=enf0.key.pem
    Created /home/jqpublic/server-keys/enf0.crt.pem
    
  6. Exit the enfcli
    > exit
    
  7. Verify the existence of the new endpints.
    • Navigate to the control panel website at http://demo.xaptum.io and log in.
    • Click on the Network link. In this example, it is: 2607:8f80:8080:b::/64
    • The Endpoints list should show the new address and show that it is OFFLINE.

Run the Docker Client Container

Run the Client
  1. Download the demo client.
    > docker pull xaptum/enftun
    
  2. Switch to the client directory.
    > cd ~/enf-docker-container/
    
  3. Run the Docker container.
     > docker run                                        \
         --cap-add=NET_ADMIN                             \
         --device /dev/net/tun:/dev/net/tun              \
         --sysctl net.ipv6.conf.all.disable_ipv6=0       \
         --sysctl net.ipv6.conf.default.disable_ipv6=0   \
         --volume `pwd`/enf0:/data/enf0:ro               \
         -it xaptum/enftun:latest bash
    
    

The Docker container will run as an interactive shell.

Verify that the Docker Container is connected to the ENF

  1. Navigate to the control panel website at http://demo.xaptum.io and log in.
  2. Click on the Network link. In this example, it is: 2607:8f80:8080:b::/64
  3. The Endpoints list should now show the new address as ONLINE

Stopping the Docker Container

To stop the client, simply log out of the interactive shell:

> exit

Virtual Machine or Server

Connecting a Virtual Machine

The following steps were created with a Vagrant virtual machine.
The steps for setting up a server are very similar.

Start the Vagrant VM

  1. Clone the enftun repositoy from https://github.com/xaptum/enftun
  2. If desired, update the Vagrantfile to use your favorite debian flavor.
    This guide was written using bento/debian-9.11

  3. Start vagrant
    vagrant up

Create a certificate using ENFCLI

If using vagrant, create the files in the same directory where Vagrantfile resides.

  1. enfcli --host https://demo.xaptum.io --user xap@demo
  2. iam create-endpoint-key --key-out-file=enf0.key.pem --public-key-out-file=enf0.pubkey.pem
  3. iam create-endpoint-with-address --address=2607:8f80:8080:9::2 --public-key-in-file=enf0.pubkey.pem
    The chosen IP address must be in the desired /64 network.
    In this case, the network is one of Xaptum’s demo networks.

  4. iam create-endpoint-cert --cert-out-file=enf0.crt.pem --identity=2607:8f80:8080:9::2 --key-in-file=enf0.key.pem
  5. exit

Transfer keys to the VM

vagrant VM should be running.

  1. vagrant rsync
    This step may be unnecessary because vagrant may do this automatically.
    The files from the host machine’s directory will be visible in /vagrant/ on the VM

Install ENFTUN on the VM (or server)

  1. Connect to the VM or log into the server.
    vagrant ssh

  2. To install the ENFTUN, follow the directions in the ENFTUN README file in: https://github.com/xaptum/enftun/blob/master/README.md , but don’t start it yet.

    • Installing from the debian package is easiest.
    • It is least error-prone if you install using systemd. It isn’t necessary to configure systemd to start enf0 at boot.

Configure the ENFTUN

  1. sudo cp /usr/share/doc/enftun/example/server.conf /etc/enftun/enf0.conf
  2. sudo vi /etc/enftun/enf0.conf
    • Most of the settings can be left commented out, as they are the defaults.
    • Uncomment the line beginning with hosts = and remove the IPv6 address
    • save and exit
  3. sudo mkdir -p /etc/enftun/enf0
  4. sudo cp /vagrant/enf0.crt.pem /etc/enftun/enf0
  5. sudo cp /vagrant/enf0.key.pem /etc/enftun/enf0

Start enftun

  1. sudo systemctl start enftun@enf0

Test the connection

At this point, you should be able to ping a machine on the same ENF subnet.

  • ping 2607:8f80:8080:9::1
    PING 2607:8f80:8080:9::1(2607:8f80:8080:9::1) 56 data bytes
    64 bytes from 2607:8f80:8080:9::1: icmp_seq=1 ttl=58 time=33.7 ms
    64 bytes from 2607:8f80:8080:9::1: icmp_seq=2 ttl=58 time=28.7 ms
    64 bytes from 2607:8f80:8080:9::1: icmp_seq=3 ttl=58 time=31.5 ms
    ...
    

Connecting a Physical Server

This guide walks through setting up a physical, Linux server to connect to the ENF. The guide was created on an Ubuntu 18.04 (Bionic Beaver) machine, but should be compatible with most Debian-based distribution. NOTE: As of June 2020, this guide will not work on Ubuntu 20.04 (Focal Fossa)

Source code and detailed instructions are available in the Xaptum enftun repository on github.

Installation

  1. Install the Xaptum API Repository GPG signing key.
    > sudo apt install dirmngr
    > sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys c615bfaa7fe1b4ca
    
  2. Add the repository to your APT sources
    Since this how-to was run on Ubuntu 18.04 / Bionic Beaver, the distribution is bionic. Replace this with the appropriate distribution name.
    The following packages are available:
    • bionic (Bionic Beaver - Ubuntu 18.04)
    • buster (Debian 10)
    • stretch (Debian 9)
    • jessie (Debian 8)
      > echo "deb http://dl.bintray.com/xaptum/deb bionic main" | sudo tee /etc/apt/sources.list.d/xaptum.list
      > sudo apt update
      
  3. Install the enftun library.
    > sudo apt install enftun
    

Configure systemd Unit File

The enftun package includes sample systemd unit files. We will use the server sample as our example.

  1. Copy the the sample server.conf file into /etc
    > sudo cp /usr/share/doc/enftun/example/server.conf /etc/enftun/enf0.conf
    

We will start the enf services after generating the keys.

Generate ENF Access Keys

Each machine is one endpoint on the ENF and is identified by its IPv6 address. Each endpoint needs its own credentials.

The enftun-keygen utility helps in creating the credentials. The utility was installed with the enftun package.

  1. Create the directory that will hold the certificate files.
    > sudo mkdir -p /etc/enftun/enf0
    
  2. Create the Access Keys.
    Follow the prompts and enter the appopriate passwords.
    > sudo enftun-keygen -c /etc/enftun/enf0.conf       \
                      -u JohnQPublic@somecompany.com \
                      -a 2607:8f80:8080:b::deb:c002
    

Start ENF using systemd

  1. Enable enf0 to start on boot
    > sudo systemctl enable enftun@enf0
    
  2. Start enf0 manually. This avoids having to reboot.
    > sudo systemctl start enftun@enf0
    
  3. Verify that the new endpoint is connected to the ENF.
    At this point, the client machine should show up as ONLINE on the ENF dashboard.
    • Navigate to the control panel website and log in.
    • Click on the Network link. In this example, it is: 2607:8f80:8080:b::/64
    • The Endpoints list should show the new addresse as being ONLINE.

Additional Resources

II. Use and Management

Identity & Access Management

Managing Device Access

Direct Anonymous Attestation (DAA) allows the ENF to remotely authenticate a device as a trusted computer. DAA is made possible by the TPM, which supports and stores the secure DAA credentials. This Concepts article delineates how Xaptum’s Zero Touch Provisioning allows the ENF to seamlessly and securely provision new devices. This guide describes how to manage and provision devices that use the XTT protocol.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial.
  • User has a DOMAIN_ADMIN account.
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    

Create a Network

When devices are provisioned, they are assigned to a /64 network. If needed, create a new /64 network following the instructions in the How To Create a New Network article for guidance.

Assign a Default Network

The default network is the network to which a device will be assigned during the initial handshake. Once the device is assigned an IPv6 address, its identity and network cannot change.

The group ID can be entered directly into the enfcli command, or, with the aid of a barcode reader, can be scanned from the label provided when the router cards were shipped.

  1. List Current Groups
    > iam list-groups
    +-----------+-----------+-------------+-----------+-----------------+--------+
    | DAA Group | Base Name | Provisioned | Onboarded | Default Network | Domain |
    +-----------+-----------+-------------+-----------+-----------------+--------+
    +-----------+-----------+-------------+-----------+-----------------+--------+
    0 rows in set
    
  2. List Available Networks
    > network list-networks
    +----------+-----------------------+-------------------------+--------+
    | Name     | Cidr                  | Description             | Status |
    +----------+-----------------------+-------------------------+--------+
    | scranton | fd00:8f80:81c0::/64   | Scranton, PA office     | ACTIVE |
    | akron    | fd00:8f80:81c0:1::/64 | Akron, OH branch office | ACTIVE |
    +----------+-----------------------+-------------------------+--------+
    
  3. Assign Default Network
    This can be accomplished by either:

    1. Using Group ID
      > iam set-group-default-network --network=fd00:8f80:81c0::/64 --gid=8D5131E49A2BE9CA639035E3A2B9BACBDC003A328D0E3BBFB300D605E975BCFB
      Set fd00:8f80:81c0::/64 as default network for group 8D5131E49A2BE9CA639035E3A2B9BACBDC003A328D0E3BBFB300D605E975BCFB
      
    2. Scanning the barcode:
      > iam set-group-default-network --network=fd00:8f80:81c0:1::/64
      Scan DAA group information:
      

      Scan the barcode.

      Set fd00:8f80:81c0:1::/64 as default network for group 8D5131E49A2BE9CA639035E3A2B9BACBDC003A328D0E3BBFB300D605E975BCFB
      
  4. List the groups to check for the new group.
    > iam list-groups
    +------------------------------------------------------------------+----------------------------------+-------------+-----------+---------------------+---------------------+
    | DAA Group                                                        | Base Name                        | Provisioned | Onboarded | Default Network     | Domain              |
    +------------------------------------------------------------------+----------------------------------+-------------+-----------+---------------------+---------------------+
    | 8D5131E49A2BE9CA639035E3A2B9BACBDC003A328D0E3BBFB300D605E975BCFB | 58415054554D424153454E414D453031 | 50          | 0         | fd00:8f80:81c0::/64 | fd00:8f80:81c0::/48 |
    +------------------------------------------------------------------+----------------------------------+-------------+-----------+---------------------+---------------------+
    1 rows in set
    

Changing the Default Network

At any time, a domain administrator may change the default network by following the steps outlined above and selecting a different network. This will have the following effect:

  • Devices that have already been onboarded won’t be affected and will keep their existing network and identity.
  • Any device that has not yet been onboarded will be assigned to the new network upon its first boot.
Example Use Case

Acme Widget company manufactures 1000 IoT-Widgets in a single group. They initially deploy 700 IoT-Widgets to the scranton network and leave 300 on the warehouse shelves. The Acme Domain administrator takes the following steps:

  1. Sets the default network to the scranton network.
  2. Enables the 700 devices.

The selected 700 devices (which were chosen at random) will boot up, perform an XTT handshake with the ENF, and receive their identities (IPv6 addresses) from the ENF.

A few months later, Acme Widget wants to deploy the remaining IoT-Widgets in the akron network. The domain administrator proceeds as follows:

  1. Sets the default network to the akron network.
  2. Enables the remaining devices.

The newly activated devices will boot and be assigned identities on the akron network.

The end result is that there are 700 devices running on the scranton network and 300 running on the akron network.

Managing Server Access

Servers, whether on-prem, in the cloud, or virtual, are usually set up one at a time – either manually or via an orchestration tool such as Ansible or AWS Certificate manager. Equipped with Zero Touch Provisioning, the ENF supports these flows by allowing you to specify the access credentials (i.e., public key) for each server.

Each endpoint, whether a device or server, on the ENF is identified by a persistent IPv6 address . A public/private key pair is also created for each server. The public key is uploaded to the ENF as the authentication credential for the server. The private key remains on the server. Servers use self-signed X.509 certificates to authenticate to the ENF. The certificate is signed by the key pair and kept with the server. When connecting, the server uses the certificate and private key for authentication.

This guide walks through the tools used to create a server identity and manage its access credentials.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial.
  • User has either NETWORK_ADMIN or DOMAIN_ADMIN account.
  • Commands are issued from enfcli
    > enfcli --host <client-domain>.xaptum.io --user <admin@account>
    
  • ENFTUN needs to be installed. For help, see the Physical Server connection how-to article.

Connecting to the ENF

The three main steps to provisioning a server on the ENF are:

  • generating a public/private key pair
  • generating a certificate
  • assigning a server identity using the certificate

The enftun-keygen tool, described in how-to guides for connecting Docker containers, virtual machines, and physical servers combines these steps for an easy way to manually provision a server. It’s a great choice for manually provisioning a server, but it may not be well-suited for automated deployments. Some organizations have their own key-generation methods and will not use the Xaptum key generation tools.

This guide describes how to use the enfcli IAM commands to accomplish these same steps individually. These methods can be easily integrated into an existing workflow for managing server certificates and credentials.

This sequence is written for manual execution, but may be easily modified for automation.

Generate Keys

This tutorial will generate the keys in ~/enf0-keys and copy them into the correct location after creating the certificate. You can follow this example or generate the keys in a location appropriate for your internal procedures and policies.

  1. Run the enfcli.

  2. Create a new key pair in the local directory.

    > iam create-endpoint-key --key-out-file=enf0.key.pem --public-key-out-file=enf0.pubkey.pem
    Created enf0.key.pem
    Created enf0.pubkey.pem
    

Generate a Server Certificate

The common name (CN) in the certificate must be the identity (IPv6 address) of the server. If you haven’t already, pick an address for the server. The iam create-endpoint-cert command will create and sign the certificate.

> iam create-endpoint-cert --cert-out-file=enf0.crt.pem --identity=2607:8f80:8080:b::deb:c004 --key-in-file=enf0.key.pem
Created /home/jqpublic/enf0-keys/enf0.crt.pem

Assign a Server Identity & Associate Certificate

The next step is to create the new identity in the ENF and associate the newly generated certificate. The iam create-endpoint-from-cert command uses the information stored in the certificate to accomplish both of these tasks. If you are just updating the certificate for an existing server, skip ahead to the Updating Endpoint Certificates section.

> iam create-endpoint-from-cert --cert-in-file=enf0.crt.pem
Created new ipv6 endpoint 2607:8f80:8080:b::deb:c005

The newly created identity will be visible in the xaptum.io dashboard.

Install Private Key and Certificate

For the server to connect to the ENF, the private key and the generated certificate must be placed in /etc/enftun/enf0

Create the /etc/enftun/enf0 directory if it does not exist.

$ sudo mkdir -p /etc/enftun/enf0

Copy the private key and certificate

$ sudo cp ~/enf0-keys/enf0.key.pem /etc/enftun/enf0
$ sudo cp ~/enf0-keys/enf0.crt.pem /etc/enftun/enf0

Updating Endpoint Certificates

From time to time, it is necessary to update endpoint certificates. By default, the certificates created by the Xaptum tools expire one year from creation. Also, rotating passwords and renewing certificates is a security best-practice.

The following commands are executed from enfcli.

  1. Generate a new key pair and certificate as described above. Be sure to use the same identity (IPv6 address).

  2. Install the private key and certificate as described above.

  3. Update the endpoint certificate.
    > iam update-endpoint-cert --cert-in-file=enf0.crt.pem
    Updated 2607:8f80:8080:b::deb:c004 credentials!
    
  4. Verify that the server is connected to the ENF. For instructions, see the Verify Connection section of the Docker Container how-to.

Microsegmentation

Creating a New Network

Each Xaptum customer is alotted a single /48 domain (The first 48 bits of the domain address are set by Xaptum). From this domain, the customer is free to create up to 65,535 seperate /64 networks. This allows the customer to follow networking best-practices by creating networks as small as functionally feasible – if two devices never need to communicate, isolate them.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • Use must have an account with the domain administrator role.

Create a New Network

  1. Start enfcli and login with an account that has the domain administrator role.
    > enfcli --host test.xaptum.io --user <domain.admin@mycompany.com>
    
  2. Check existing networks
    > network list-networks
    +----------------------------+-----------------------+-----------------------------+--------+
    | Name                       | Cidr                  | Description                 | Status |
    +----------------------------+-----------------------+-----------------------------+--------+
    | BACnet Demo                | 2607:8f80:8080:7::/64 | Office BACnet Demo Network  | ACTIVE |
    | Testing Demo               | 2607:8f80:8080:a::/64 |                             | ACTIVE |
    | scranton                   | 2607:8f80:8080:b::/64 | Scranton, PA office         | ACTIVE |
    | Demonstration Network      | 2607:8f80:8080:c::/64 | Network for Demos           | ACTIVE |
    +----------------------------+-----------------------+-----------------------------+--------+
    
  3. Provision the network.
    > network provision-network --name=Rockford floor --description=Rockford factory floor
    Provisioned a network!
    +----------------+-----------------------+------------------------+--------+
    | Name           | Cidr                  | Description            | Status |
    +----------------+-----------------------+------------------------+--------+
    | Rockford floor | 2607:8f80:8080:e::/64 | Rockford factory floor | ACTIVE |
    +----------------+-----------------------+------------------------+--------+
    1 rows in set
    

Configuring Firewall Rules

By default, the ENF firewall blocks all network traffic. The firewall must be configured to allow any required traffic. It is network security best-practice to configure the firewall to be as strict as possible.

Configuring the ENF firewall should be familar to anyone experienced with network firewalls boxes or AWS network ACLs. The rules specify the source and destintation addresses (subnet or specific IP), transport protocol (TCP, UDP, or ICMP), and source and destination ports for allowed traffic. The firewall is stateless, so you must configure separate rules for inbound (ingress) and outbound (egress) traffic.

Prerequisites

  • enfcli needs to be installed. For help, see the Getting Started Tutorial
  • Use must have an account with the domain administrator role.

Create Firewall Rules

For this example, we will create rules that allow any device in a \64 subnet to communicate with a server and the server to respond to the requests. The server in the example is running on port 8080. Note that in this configuration, devices cannot directly communicate with each other

  1. Start enfcli and login with an account that has the domain administrator role.
    > enfcli --host test.xaptum.io --user <domain.admin@mycompany.com>
    
  2. Allow egress from any subnet IP to the server IP.
    > firewall add-firewall-rule --action=ACCEPT --direction=EGRESS --network=<enf /64 network> --protocol=TCP --priority=200 --source-ip=<enf /64 network> --dest-ip=<server enf address> --dest-port=8080
    

    This allows outbound traffic from the devices to port 8080 of the server, but, at this point, the firewall blocks the server from receiving any messages.

  3. Allow ingress from any subnet IP to the server IP
    > firewall add-firewall-rule --action=ACCEPT --direction=INGRESS --network=<enf /64 network> --protocol=TCP --priority=200 --source-ip=<enf /64 network> --dest-ip=<server enf address> --dest-port=8080
    

    Now the firewall allows the server to receive messages, but only from the designated /64 subnet.

  4. Allow egress from the server to any address on the subnet.
    > firewall add-firewall-rule --action=ACCEPT --direction=EGRESS --network=<enf /64 network> --protocol=TCP --priority=200 --dest-ip=<enf /64 network> --source-ip=<server enf address> --source-port=8080
    

    The firewall is now configured to allow a response from the server, on port 8080, to the subnet. As above, the firewall does not yet allow the subnet devices to receive communication from the server.

  5. Allow ingress to any device on the subnet from the server.
    > firewall add-firewall-rule --action=ACCEPT --direction=INGRESS --network=<enf /64 network> --protocol=TCP --priority=200 --dest-ip=<enf /64 network> --source-ip=<server enf address> --source-port=8080
    

Domain Name System (DNS)

Configuring Private DNS

Addressing ENF endpoints by IPv6 addresses can become tedious and error-prone as the network grows. Even with a handful of machines, using, memorizing, and entering sequences of numbers can be confusing. To minimize the necessity to use IPv6 addresses, the ENF provides a DNS (Domain Name Server) feature. It is much easier to remember punchpress1.scranton.prod than 2607:8f80:8080:b:bd32:eeb9:2085:b8cb.

The three main concepts to manage when dealing with the ENF DNS are as follows:

  • Zones - zones are the domain names that divide the domain namespace into distinctly administered areas. For example, example.com or internal.scranton.prod. The ENF DNS system is private to your account, so there are no restrictions on the zones you can use.
  • Records - each zone contains resource records that map domain names to values. For example, an AAAA record for punchpress1 in the internal.scranton.prod zone associates the hostname punchpress.internal.scranton.prod to its IPv6 address.
  • Servers - a DNS server is provisioned on a network to allow endpoints to look up records in any zones that have been associated with the network. The endpoints must be configured to use this server for DNS resolution.

DNS Zones

The first step in provisioning DNS services for your network is to define a DNS zone. The domain name of a zone sets the suffix shared by all DNS records in that zone. For example, in a zone named “foo.bar” we might have records “one.foo.bar” and “two.foo.bar” and “client.foo.bar” and “server.foo.bar”, etc.

The name of your zone can be anything you like, because it’s private to your network. For this example, we’ll use the name scranton.prod.

Privileged vs. Non-Privileged Zones

A DOMAIN_ADMIN user can create a privileged DNS Zone that can have multiple networks associated with it. A NETWORK_ADMIN user can use a privileged zone, but cannot modify it – only a DOMAIN_ADMIN can create, modify, or delete a privileged zone.

A non-privileged DNS Zone only has a single network associated with it and may be created by either a NETWORK_ADMIN or a DOMAIN_ADMIN.

Example use-case for a privileged DNS Zone:

The Acme Widget company has IIoT devices at three different location: Rockford, Cleveland, and Paducah. The IT department created a separate network for each factory floor but wants a unified set of names for all of the factory machines. To accomplish this, IT creates a privileged DNS Zone and adds each of the three networks to it.

Creating a Privileged DNS Zone

All commands must be issued by a DOMAIN_ADMIN account.

  1. Create a new zone
    > dns create-zone --zone-domain-name=factory.prod --description=Factory Floor Machines
    Created DNS zone factory.prod!
    +--------------------------------------+--------------+------------------------+------------+---------------------+
    | Id                                   | Zone         | Description            | Privileged | Enf Domain          |
    +--------------------------------------+--------------+------------------------+------------+---------------------+
    | a36de128-74ca-4673-bd29-e9db509f4368 | factory.prod | Factory Floor Machines | true       | 2607:8f80:8080::/48 |
    +--------------------------------------+--------------+------------------------+------------+---------------------+
    1 rows in set
    
  2. Attach one or more networks to the DNS Zone.
    Separate /64 networks with a comma.
    dns add-networks-to-zone --networks=2607:8f80:8080:b::/64,2607:8f80:8080:c::/64 --zone-id=a36de128-74ca-4673-bd29-e9db509f4368
    Added the following networks to zone with id: a36de128-74ca-4673-bd29-e9db509f4368
    +----+-----------------------+
    | Id | Network               |
    +----+-----------------------+
    | 73 | 2607:8f80:8080:c::/64 |
    | 74 | 2607:8f80:8080:b::/64 |
    +----+-----------------------+
    2 rows in set
    
Removing Networks from a DNS Zone

The command for removing networks from a zone is analogous to adding them:

> dns delete-networks-from-zone --networks=2607:8f80:8080:b::/64,2607:8f80:8080:c::/64 --zone-id=a36de128-74ca-4673-bd29-e9db509f4368
Deleted networks from DNS zone!
Creating a non-privileged DNS Zone

To create a non-privileged DNS Zone as a DOMAIN_ADMIN, specify the --enf-network option. Adding this option attaches the specified network to the zone in the same step.

> dns create-zone --zone-domain-name=scranton.prod --enf-network=2607:8f80:8080:b::/64 --description=Scranton Factory Floor

Created DNS zone scranton.prod!
+--------------------------------------+---------------+------------------------+------------+---------------------+
| Id                                   | Zone          | Description            | Privileged | Enf Domain          |
+--------------------------------------+---------------+------------------------+------------+---------------------+
| f45aca46-9c03-49f0-bdb9-81bdfdf778c8 | scranton.prod | Scranton Factory Floor | false      | 2607:8f80:8080::/48 |
+--------------------------------------+---------------+------------------------+------------+---------------------+
1 rows in set
Updating a DNS Zone

Only the description field of a DNS Zone may be updated.

> dns update-zone --zone-id=f45aca46-9c03-49f0-bdb9-81bdfdf778c8 --description=Scranton Warehouse
+--------------------------------------+---------------+--------------------+------------+---------------------+
| Id                                   | Zone          | Description        | Privileged | Enf Domain          |
+--------------------------------------+---------------+--------------------+------------+---------------------+
| f45aca46-9c03-49f0-bdb9-81bdfdf778c8 | scranton.prod | Scranton Warehouse | false      | 2607:8f80:8080::/48 |
+--------------------------------------+---------------+--------------------+------------+---------------------+
1 rows in set
Deleting a DNS Zone

When a zone is no longer needed, it should be deleted. If a field besides the description needs to be updated for a DNS Zone, it must be deleted and created from scratch.

> dns delete-zone --zone-id=f45aca46-9c03-49f0-bdb9-81bdfdf778c8
Deleted DNS Zone with id: f45aca46-9c03-49f0-bdb9-81bdfdf778c8

DNS Records

Once a DNS Zone is created, we can add DNS records that allow us to access an endpoint by name instead of by an IPv6 address. Names are much easier to remember and, therefore, much less error-prone.

Create a DNS Record in a Zone

For this example, we are using the DNS Zone, scranton.prod and machine name, server1.

> dns create-record --zone-id=f45aca46-9c03-49f0-bdb9-81bdfdf778c8 --name=server1 --type=AAAA --ttl=30 --value=2607:8f80:8080:b:bd32:eeb9:2085:b8cb

Created new DNS record!
+--------------------------------------+-----------------------+------+--------------------------------------+-----+
| Id                                   | Name                  | Type | Value                                | TTL |
+--------------------------------------+-----------------------+------+--------------------------------------+-----+
| 7cd23179-c2e4-4fb9-8024-8393b10f3125 | server1.scranton.prod | AAAA | 2607:8f80:8080:b:bd32:eeb9:2085:b8cb | 30  |
+--------------------------------------+-----------------------+------+--------------------------------------+-----+
1 rows in set

The --type option is the type of DNS record to create. The types are similar to DNS record-types on the public internet, but only some are supported. The supported record types are:

Type Description
AAAA This maps a host name to an IPv6 address
CNAME Is an alias from one name to another.
TXT Text record - usually some machine-readable data. See RFC-1464
SRV Server Locator Record
SOA Start of Authority record - authoritative info about a DNS Zone.
NS Name Server record - delegates a zone to use the provided name server

The --ttl option, or time to live determines how long a machine should cache a DNS result. The higher the value, the less load on the DNS Server, but the longer it will take a machine to realize that a record was updated.

The DNS entry is not yet ready to use – there is no server to respond to requests.

Delete a DNS Record

DNS Records cannot be modified – they must be deleted and recreated. If a server is no longer used, the DNS record should be deleted when the server is decommissioned.

> dns delete-record --id=7cd23179-c2e4-4fb9-8024-8393b10f3125
Deleted DNS record!

DNS Server

In the previous two steps, we’ve created a DNS Zone and added a DNS record. The DNS is not yet ready to use because we don’t have a server to respond to a DNS query.

Provision the DNS Server
> dns provision-server --network=2607:8f80:8080:b::/64 --description=Scranton DNS

+--------------------------------------+--------------------------------------+-----------------------+--------------+
| Id                                   | IPv6                                 | Network               | Description  |
+--------------------------------------+--------------------------------------+-----------------------+--------------+
| 1f716f4d-d0b6-4d8d-ae05-3a46bb55ae73 | 2607:8f80:8080:b:82b1:406e:2aac:fb29 | 2607:8f80:8080:b::/64 | Scranton DNS |
+--------------------------------------+--------------------------------------+-----------------------+--------------+
1 rows in set

The endpoints that are now going to use the DNS must be configured to use 2607:8f80:8080:b:82b1:406e:2aac:fb29 as the DNS server.

It is possible to configure a DNS Server’s address by adding the --ipv6 option. This could be used to have a consistent DNS Server address on every network.

> dns provision-server --network=2607:8f80:8080:e::/64 --description=Rockford DNS --ipv6=2607:8f80:8080:e::aaaa
+--------------------------------------+------------------------+-----------------------+--------------+
| Id                                   | IPv6                   | Network               | Description  |
+--------------------------------------+------------------------+-----------------------+--------------+
| f1938b7e-2dc8-42da-93ab-a0b69f0413e7 | 2607:8f80:8080:e::aaaa | 2607:8f80:8080:e::/64 | Rockford DNS |
+--------------------------------------+------------------------+-----------------------+--------------+
1 rows in set

Note that the network must already been associated with at least one DNS zone.

Delete the DNS Server

When deleting a server, both the network and DNS Server’s IPv6 address must be specified.

> dns delete-server --ipv6=2607:8f80:8080:e::aaaa --network=2607:8f80:8080:e::/64
Delete DNS server with ipv6 2607:8f80:8080:e::aaaa in 2607:8f80:8080:e::/64!

User Management

Adding a New User

The ENF uses roles to add & remove privileges from a specific user. A user may belong to more than one role, and the roles determine the actions that a user is allowed to perform.

The roles are:

  • DOMAIN_ADMIN - Has all privileges to a customer domain. A user with this role can add/delete/modify networks, devices, users at any level, etc.
  • DOMAIN_USER - Has read-only privileges to a customer domain.
  • NETWORK_ADMIN - Has administrator privileges at the Network level. A user with this role can add new devices, create firewall rules, and create DNS entries for the network.
  • NETWORK_USER - Has read-only access at the current network level.

Environment Prerequisites

The following tools will need to be installed.

Send the Invitation

  1. Start the enfcli.
    You must log in with an _ADMINISTRATOR role.
    enfcli --host demo.xaptum.io --user <admin@somecompany.com>
    
  2. Send an invite with the appropriate role.
    Example invitation to a NETWORK_USER role:
    > user send-invite --network=2607:8f80:8080:b::/64 --email=<johnqpublic@somecompany.com> --name=John Public --role=NETWORK_USER
    

    Example invitation to a DOMAIN_ADMIN role:

    > user send-invite --network=2607:8f80:8080:b::/64 --email=<johnqpublic@somecompany.com> --name=John Public --role=DOMAIN_ADMIN
    
  3. View Invitations
    > user list-invites
    
  4. List Users
    Since the user has not responded to the invitation yet, the user will not show up in the list.
    > user list-users --network=<2607:8f80:8080:b::/64>
    

Accept the Invitation

The user to whom the invitation was sent must now respond to the email to create an account.

Deactivating a User

Following network security best practices, it is often desireable to allow access to a user for only the time needed to perform a task. For example: an engineer may need to add a new network for a new facility, but that engineer does not usually need access to make such changes.
To accomodate this, a user may be deactivated after such tasks are complete.

Environment Prerequisites

The following tools will need to be installed.

Deactivate a User

  1. Start the enfcli.
    You must log in with an _ADMINISTRATOR role.
    enfcli --host demo.xaptum.io --user <admin@somecompany.com>
    
  2. List the users and find the user to deactivate.
    > user list-users --network=2607:8f80:8080:b::/64
    
  3. Deactivate the user.
    > user deactivate-user --email=<johnqpublic@somecompany.com>
    
  4. Listing the users again will show that the user has been deativated
    > user list-users --network=2607:8f80:8080:b::/64
    +-----+----------------+-----------------------------+---------------------+----------------------+----------+
    | Id  | Name           | Username                    | Domain              | Last Login           | Status   |
    +-----+----------------+-----------------------------+---------------------+----------------------+----------+
    | 79  | Customer Admin | admin@somecompany.com       | 2607:8f80:8080::/48 | 2020-07-02T19:27:37Z | ACTIVE   |
    | 80  | John Q Public  | johnqpublic@somecompany.com | 2607:8f80:8080::/48 | 2020-06-30T21:25:27Z | INACTIVE |
    +-----+----------------+-----------------------------+---------------------+----------------------+----------+
    

Didn't find what you were looking for?

Contact us and we’ll get back to you as soon as possible.

Contact Us