It is strongly recommended that the reader familiarise themselves with the Zerotier Manual, in order to further understand the concepts behind this plugin.
Firstly, it is important that you have signed up to Zerotier at the Zerotier Portal. 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 will be required.
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.
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.
This tab controls the overall operation of Zerotier. Anything changed here is applied globally to all defined networks and to the Zerotier service itself.
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 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. Please note that the local.conf must be a valid JSON document otherwise the service will fail to start.
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.
Remember, you will have to log into the Zerotier portal, select the network and authorise the node before it can be assigned an IP address (or indeed, talk to other nodes on that network).
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
first. Likewise, to remove your OPNsense node from the configured network
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
If you wish to edit the network, click on the
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
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
Overview...Networks menu item.
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.
This tab shows “Global” information concerning the overall health of the Zerotier service.
This tab shows each configured and enabled network that this OPNsense installation has joined. If no networks are enabled, no information is shown.
This tab shows the peers (leaf, planets and moons - Zerotier terminology) known by this node.
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
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).
To achieve this:
Click on the
Interfaces menu item, then click on
you should discover a new interface currently unassigned that begins with the
zt. Next, click on the
+ symbol to assign it. In this example
it creates a new interface called
OPT1. Clicking on
OPT1 shows the
Lock options. Check both options.
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.
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
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.