Zerotier Configuration ====================== .. Note:: It is strongly recommended that the reader familiarise themselves with the `Zerotier Manual `_, 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 `_. 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. 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 `__ 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. 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 `__, 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 `__. .. 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 `_ 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.