Setup and manage ZeroTier

ZeroTier is a software-defined networking (SDN) platform and open-source networking tool that enables secure and seamless connectivity for devices and networks across the internet. It was designed to simplify the process of creating virtual LANs (Local Area Networks) and connecting devices and resources across the globe, making it an attractive option for various use cases, including remote work, IoT (Internet of Things), gaming, and more.

The benefits of using qbee to setup a ZeroTier deployment:

  • automatically deploy and configure an unlimited number of devices. Save time and hassle to do this manually
  • automatically change network configuration for a large number of devices with a few clicks
  • move devices seamlessly across ZeroTier SDNs
  • keep fleet up to date with ZeroTier and other updates

Probably you want to install other software in addition to ZeroTier. With qbee you can manage and update both the ZeroTier SDN as well, as any other software. This will help to save considerable time, especially if your fleet and subnets are constantly growing.

Although qbee.io offers its own remote access solution, it is for the time being designed for a per device configuration and troubleshooting purpose and does not currently have advanced SDN features available. This example will show how to augment both qbee.io and ZeroTier to configure and manage large fleets with SDN capabilities.

  1. Create the ZeroTier networks required through the ZeroTier UI. We create 2 networks called zerotier-net-1 and zerotier-net-2

    ZeroTier create networks

  2. Upload the necessary files to the qbee.io file manager.

    First of all we would need the gpg key to authenticate the ZeroTier deb packages.

    curl -s https://raw.githubusercontent.com/zerotier/ZeroTierOne/master/doc/contact%40zerotier.com.gpg | \
        gpg --dearmor > zerotier-gpg-key
    

    Also, we would need a script to control joining and leaving ZeroTier networks based on the configuration we set.

    qbee-zerotier-joiner.sh
    #!/usr/bin/env bash
    
    set -e
    
    # shellcheck disable=SC2046
    BASEDIR="$(cd $(dirname "$0") && pwd)"
    
    # shellcheck disable=SC1090,SC1091
    source "$BASEDIR/qbee-zerotier-joiner.conf"
    
    ZT_NETWORKS_DIR="/var/lib/zerotier-one/networks.d"
    
    if [[ -z $NETWORK_IDS ]]; then
        echo "ERROR not networks defined in \$NETWORKS"
        exit 1
    fi
    
    # shellcheck disable=SC2206
    NETWORKS=($NETWORK_IDS)
    ZT_CLI="/usr/sbin/zerotier-cli"
    
    for conf_file in "$ZT_NETWORKS_DIR"/[a-f0-9].conf; do
        conf_network=$(basename "$conf_file" .conf)
        if ! printf -- '%s\n' "${NETWORKS[@]}" | grep -q "$conf_network"; then
            $ZT_CLI leave "$conf_network"
            # remove any local configuration
            rm "$ZT_NETWORKS_DIR/$conf_network.local.conf" -f
        fi
    done
    
    for network in "${NETWORKS[@]}"; do
        if [[ ! -f "$ZT_NETWORKS_DIR/$network.conf" ]]; then
            $ZT_CLI join "$network"
        fi
    done
    

    This script reads a config file which holds environment variables. We would like to be able to use the same file across different networks, so we create the file as qbee template.

    qbee-zerotier-joiner.conf.template
    NETWORK_IDS="{{network_ids}}"
    

    Upload the resulting files to a path in the qbee.io File manager. We have chosen to put it under /zerotier

    Upload ZeroTier configuration templates

  3. Configure the file distribution to set up both the ZeroTier apt repo on the devices and the network joiner script. We are doing this by using 2 separate file sets. The configuration can be attached to a group depending on whether you want zerotier for a subset of your infrastructure. We are using the group zerotier-net.

    Distribute ZeroTier configuration templates

    Full json of the configuration (use the json import feature to copy/paste):

    {
        "enabled": true,
        "extend": true,
        "version": "v1",
        "files": [
            {
                "templates": [
                    {
                        "source": "/zerotier/zerotier-gpg-key",
                        "destination": "/etc/apt/trusted.gpg.d/zerotier-debian-package-key.gpg",
                        "is_template": false
                    }
                ],
                "command": "chmod go+r /etc/apt/trusted.gpg.d/zerotier-debian-package-key.gpg && echo \"deb http://download.zerotier.com/debian/$(lsb_release -cs) $(lsb_release -cs) main\"  | tee /etc/apt/sources.list.d/zerotier.list"
            },
            {
                "templates": [
                    {
                        "source": "/zerotier/qbee-zerotier-joiner.sh",
                        "destination": "/usr/local/bin/qbee-zerotier-joiner.sh",
                        "is_template": false
                    },
                    {
                        "source": "/zerotier/qbee-zerotier-joiner.conf.template",
                        "destination": "/usr/local/bin/qbee-zerotier-joiner.conf",
                        "is_template": true
                    }
                ],
                "parameters": [
                    {
                        "key": "network_ids",
                        "value": "$(zerotier_network_ids)"
                    }
                ],
                "command": "bash /usr/local/bin/qbee-zerotier-joiner.sh",
                "pre_condition": "test -x /usr/sbin/zerotier-cli"
            }
        ]
    }
    
    The first file set will set up the ZeroTier apt repos, while the other one will perform joining of networks based on configuration. Note that we are using a qbee.io secret for the template parameter network_ids. The joiner script works with a space separated list of network ids, but we will only define one network here. Remember to save the configuration before moving on to next item.
  4. Configure software management to install zerotier-one from the ZeroTier apt repos. Install ZeroTier package with software management

    Full json of the configuration:

    {
        "enabled": true,
        "extend": true,
        "version": "v1",
        "items": [
            {
                "package": "zerotier-one",
                "pre_condition": "test -f /etc/apt/sources.list.d/zerotier.list",
            }
        ]
    }
    

    We have a precondition here to check that the ZeroTier repo has been defined before attempting any installation. Remember to save the configuration before moving on to next item.

  5. Set up parameters for different groups of devices. The configuration for the parent group (zerotier-net in this case) contains a parameter ($(zerotier_network_ids)) To allow devices to use different parameter values in subgroups, effectively achieving devices registering to different virtual LANs. We create two subgroups mimicking our setup in the ZeroTier UI called zerotier-net-1 and zerotier-net-2 and create secrets for each of these groups called zerotier_network_ids with values corresponding to the network ids in the ZeroTier UI.

    Set configuration parameter for ZeroTier configuration templates

    Parameters and secrets

    The ZeroTier network id is effectively a secret, so we treat it as such in the qbee parameters. The secrets can only be written and never view through the UI once saved and will also be redacted from any configuration reports produced by qbee. Read more on parameters and secrets here

    Remember to save the configuration before moving on to next item.

  6. Commit and wait for the devices to apply their configuration. Once the configuration is run the devices will report on the results. Note that it will take 2 scheduled agent runs to finish: 1. Configure repo and install, 2. Join ZeroTier network.

    qbee-agent report - ZeroTier installed and ready

    You can now move over to the ZeroTier UI for the two networks to allow the registration.

    ZeroTier UI is ready

The devices can now be moved between the different qbee groups which will effectively mean that they will leave it's current ZeroTier network and join a new. It's also possible to define additional networks by changing the zerotier_network_ids parameter. The configuration will then be automatically applied by qbee with no manual intervention.