opensense-docs/source/manual/how-tos/zerotier.rst

Zerotier Configuration
======================

.. Note::
    It is strongly recommended that the reader familiarise themselves with the
    `Zerotier Manual <https://www.zerotier.com/manual.shtml>`_, in order to further
    understand the concepts behind this plugin.

Prerequisites
--------------

Firstly, it is important that you have signed up to Zerotier at the `Zerotier
Portal <https://my.zerotier.com>`_. Second, you will need to create at least
one network on the portal in order to obtain a Network Id that this plugin
uses to **join** this node to the created Zerotier network. This network will
become your private network that by default is visible only to your nodes - in
other words, other nodes that are on that network can talk to each other, but
nothing else can talk to them - they are completely transparent to the
internet in general.  In effect you are layering a private network over the
public internet and all intra-node communication is encrypted and private
between them. This is further hinted at by the fact that the assigned IP
addresses are normally RFC1918 addresses, i.e., non-routable across the
internet.

Finally, in order to have a fully functioning private VPN between Zerotier
nodes, a combination of this plugin plus some configuration on the `portal
<https://my.zerotier.com>`_ **will** be required.

Installation
------------

From the Plugins view under ``System...Firmware``, install the os-zerotier
package. Once the new plugin has been installed, perform a page reload and a
new menu item should appear under VPN called Zerotier.

.. image:: images/zerotier-0.png

Clicking on the Zerotier menu item will reveal two further sub-menu items -
namely Settings and Overview.  Clicking on "Settings" will present a new view
with two named tabs. The first tab is called Settings and the second tab is
called Networks. These are further described below.

.. image:: images/zerotier-1.png

Settings
--------

This tab controls the overall operation of Zerotier. Anything changed here is
applied globally to all defined networks and to the Zerotier service itself.

:Enabled:
    Controls if the service should be running. If it is disabled, then access
    to the Networks tab will be disabled. If it is enabled, access to the
    Networks tab will be enabled and the service will also start at boot time.

:API Access Token (optional):
    This optional entry is for future use and further development of the
    Zerotier plugin. The API access token can be generated by logging into
    your `portal <https://my.zerotier.com>`__ and creating a new API Access Token.
    When the token has been generated, copy the value into this input box.

:local.conf settings (optional):
    As described in the Zerotier Manual, a local.conf can be created to enable
    or disable custom node-specific configuration overrides. Further details of
    permitted options can be found on the `ZeroTier Manual
    <https://www.zerotier.com/manual.shtml>`__. Please note that the local.conf
    **must** be a valid JSON document otherwise the service will fail to start.

Networks
--------

This table allows for the creation, modification and deletion of Zerotier
networks. Adding a Network here will join your OPNsense installation to the
specified Zerotier network.

.. Note::
    Remember, you **will** have to log into the Zerotier `portal
    <https://my.zerotier.com>`__, select the network and authorise the node before
    it can be assigned an IP address (or indeed, talk to other nodes on that
    network).

.. image:: images/zerotier-2.png


Adding a network is quite straight-forward. Simply click on the + symbol key
in the following:

:Network Id:
    This is the 64-bit (16 character hex) address that is generated on the
    portal when creating a Zerotier network.

:Local Description (optional):
    You may key in a description here that will help you remember what the
    network is for. Please note that this field is **not** the same as the
    name/description of the Zerotier network - it's simply an aide-mémoire to
    help you remember what the network is for.

Adding a network does **not** automatically cause your OPNsense installation
to join that network. In order to join that network it **must** be ``Enabled``
first. Likewise, to remove your OPNsense node from the configured network
simply deselect ``Enabled``, thus disabling the network.

Once a network has been added and enabled the node **must** be authorised to
join the network on the portal. Simply enabling the network on your OPNsense
installation marks that node as a member of that network. It now has to
request permission to talk to the other nodes on that network. To achieve
this, you log into the portal, select the network, find the node address (this
can found on the OPNsense Zerotier Overview menu item, under the Information
tab) and authorise it by clicking on the "Auth?" check box beside the node. It
should go from "red" to "green" to indicate that it has been authorised.

Some final "Network" operations:

If you wish to completely remove the network, simply select the network and
click on the ``Bin`` icon.

If you wish to edit the network, click on the ``Pencil`` icon.

To "clone" the network entry, click on the ``Copy`` icon. Please ensure you
change the Network Id, as having two networks with the same id is an invalid
configuration.

For a very quick overview of the Zerotier network information, click on the
``Information`` icon. A more detailed view of the network can be found under
the ``Overview...Networks`` menu item.

ZeroTier Overview
-----------------

The following 3 tabs reveal Global, Network and Peer information. They can
only be viewed if the Zerotier plugin is enabled, so please ensure that the
service is enabled first. For information on the terminology used, please
refer to the `Zerotier Manual <https://www.zerotier.com/manual.shtml>`__.

.. image:: images/zerotier-3.png

Information Overview
--------------------

This tab shows "Global" information concerning the overall health of the
Zerotier service.

Networks Overview
------------------

This tab shows each configured **and** enabled network that this OPNsense
installation has joined. If no networks are enabled, no information is shown.

Peers Overview
--------------

This tab shows the peers (leaf, planets and moons - Zerotier terminology) known
by this node.

Interface Assignment
--------------------

.. WARNING::
    It is **highly** recommended that the interface have auto-assignment of IP
    addresses turned off **for this particular node only**. You want to give
    the interface a statically assigned, stable IP address (from the Zerotier
    network IP range) and not have the Zerotier service auto-assign an IP
    address.  Auto-assignment of IP addresses for nodes is controlled on the
    `Zerotier Portal <https://my.zerotier.com>`_ 

After joining a Zerotier network (and authorising it on the portal) you may
now wish to assign the Zerotier virtual interface on OPNsense in order to
avail of OPNsense functionality such as firewalling and routing (using OSPF
for example).

.. image:: images/zerotier-4.png

To achieve this:

Click on the ``Interfaces`` menu item, then click on ``Assignments``. There
you should discover a new interface currently unassigned that begins with the
letters ``zt``. Next, click on the ``+`` symbol to assign it. In this example
it creates a new interface called ``OPT1``. Clicking on ``OPT1`` shows the
``Enable`` and ``Lock`` options. Check both options.

.. WARNING::
    It is **very** important that ``Lock`` (i.e., Prevent interface removal)
    is enabled. This is because Zerotier is a software interface and not
    guaranteed to be brought "up" whilst the system is booting. It could
    happen shortly afterwards, hence locking the interface tells OPNsense not
    to remove it, thinking it's gone bad.

Once the new interface has been enabled, it is recommended to change the
Description away from ``OPT1`` to something more descriptive for your needs.

For ``IPv4 Configuration Type``, choose ``Static IPv4`` then in the
appropriate input boxes, key in the IPv4 address that you have assigned to
this node via the ``Zerotier`` portal. Keep the ``IPv4 Upstream Gateway`` set
to ``None.``

.. image:: images/zerotier-5.png

You may choose to do the same for ``IPv6 Configuration Type``.

Once the interface has been assigned with an IP, it show now also show up on
``Firewall`` Rules etc...plus any other operations that be done on a
interfaces can also be applied to your assigned interface.