7. DFM Connection Agent
7.1. What is the DynFi Connection Agent
DynFi® Connection Agent is a plugin / module which allows initiating connection from an open source firewall to the DynFi® Manager.
In order to manage firewall devices, the DynFi Manager needs to be able to establish SSH and HTTP(S) connections to a remote firewall device (DynFi® Firewall, pfSense®, OPNsense®). This might be problematic in some cases, because these devices might be:
unreacheable because inbound connexion are filtered
unreacheable because they are behind two firewalls
unreacheable because we have to deal with complex NAT scenarios
unreacheable because of limited ability to open incoming SSH and HTTPS connection on WAN
This is caused by the fact that the connection is initiated from the Manager, most frequently through the WAN interface(s).
The DynFi Connection Agent initiate the connexion directly from the remote firewall, allowing to bypass most restrictions listed above.
The Connection Agent is a plugin / module developed by DynFi which can be installed on open source firewalls. It comes pre-installed on DynFi® Firewalls and as a third party pluggin for pfSense® and OPNsense® devices.
Once installed, the Connection Agent:
allows attaching the device it’s running on to an instance of DynFi Manager in a simple and streamlined process,
establishes and monitors the connection from the device to the Manager.
7.2. Steps needed to start using the Agent
Enable the Connection Agent Service in the Manager by setting a port number for incoming connections. Do not use the same SSH port for DynFi Manager and your standard SSH Server. This can be done by setting connectionAgentPort in configuration, as described in DFM Configuration, e.g. adding to /etc/dynfi.conf the following line:
connectionAgentPort=2222
and restarting the Manager.
Please make sure the selected port will accept incoming connections from the devices. This may require adding a proper PASS rule in the firewall protecting the Manager.
The plugin needs to be installed first. Please refer to this document for up to date informations on how to deploy the Connection Agent.
The easiest way to attach a device to the Manager using the Agent is as follows:
In the Manager: go to Connection Agent settings (⚙️ -> Connection Agent).
Generate a Connection Agent Token and copy it.
Go to device’s Web User Interface, select “DynFi Connection Agent” menu entry.
Click [Connect] button, paste the Token into the Token field and follow the wizard.
If the Connection Agent port is set in the Manager and the devices can reach it (i.e. no firewalls are blocking it), the Connection Agent will:
connect to the Manager right after being configured,
after each restart of the Manager or the device,
the connection will also be reestablished if it drops due to any other reason.
The bond between the Manager and the Agent can be canceled any time. The other party (if possible) is notified about that, so normally (with working link) there should be no need to disconnect the device twice (once in the Manager, once in the Agent).
There is no need or strict requirement of using the Connection Agent to attach devices to the Manager. However, in many situations (also thanks to the Tokens) it is the easiest way. It is also possible to attach device without a Token, by manually providing the server’s host and port in the ‘Advanced options’. However, this process requires providing username and password of the Manager’s operator account as one of the steps and therefore it is not recommended.
7.3. How Tokens work
Connection Agent Tokens are the most simple way of attaching devices to the Manager using the Connection Agent. They carry some information but also authenticate permitted usages. They work only with the Manager they were created at (i.e. ‘they can only call home’).
Basically, a Token is a piece of text which has a few things encoded:
the Manager’s host and port
the Manager’s public key
the expiration date
They can be generated by the Manager’s operators and passed to firewall operators (which can be the same person, but can be another person as well) without revealing any passwords. They remain active until used or expired, or deactivated (whatever comes first) and allow attaching devices only to the instance of the Manager there were issued at, not any other.
By default Tokens are valid for one hour and can be used only once. This can be tuned before creating a token. (It may be useful in scenarios when e.g. the operator wants one token to allow attaching 10 devices in next 24h.) Token is issued for a selected Device Group, the device will be added to the the selected group. After being created, Tokens cannot be modified (e.g. their expiration date cannot change).
Tokens are issued by operators who have sufficient permissions and for Device Group they can access. If the operator’s account gets deleted, if the Device Group gets deleted or if the operator loses access to the Device Group, the token will not work when attaching device.
In case a token (due to whatever reason) carries invalid Manager’s hostname or port (e.g. a FQDN cannot be used and must be replaced by explicit IP address), they can be manually overwritten in the ‘Advanced options’ section. In such scenario the Token still authenticates the attach usage.
7.4. How connections work
Setting the Connection Agent port in the DynFi Manager enables an embedded SSH server/daemon. It is a part of the Manager’s Java process, no other processes are started (e.g. with a separate PID). The SSH server does not depend on the operating system, it has no access to the file system or any OS programs. Its role an capabilities are limited to the process of attaching device and answering Connection Agent’s requests. It cannot be used to access Manager’s files or run other programs.
The Connection Agent operates on firewall devices. In a way it is a wrapper of autossh program. It allows attaching the device (it is installed and configured on) to an instance of the DynFi Manager.
The connection established by the Agent (once configured):
is made to the Manager’s SSH subsystem
establishes on two reverse tunnels
is secured by EdDSA SSH keys from both ends
is re-established after being dropped and re-configured when needed (e.g. SSH service on the device has the port changed, etc.)
The SSH connection established by autossh actually has one purpose only: running two reverse tunnels. Using these tunnels the DynFi Manager can contact the device by initiating SSH connections (using so called main tunnel) and DirectView connections (using so called DV tunnel). Therefore, from various Manager’s services point of view (apart from Connection Agent service) the connection is still established by the Manager. The fact, that the reverse tunnels are established by the Agent, remains transparent to other Manager’s subsystems.
7.5. Updating Connection Agent
DynFi® Firewall supports Connection Agent natively, but there might be a need to update the plugin on pfSense® and OPNsense® firewalls.
Connection agent status page (⚙️ -> Connection Agent-> Status) shows all devices using Connection Agent, along with version of currently installed plugin and the newest available plugin for each firewall type. DynFi Manager fetches the newest available version once a day from https://dynfi.com. Please, make sure that the manager can reach https://dynfi.com, as the update won’t be possible otherwise. In such case Connection Agent plugin has to be reinstalled manually, as described in this document.
Agent status column indicates whether the plugin on given device is up to date or needs an update. It’s possible to update the plugin for a group of devices (using “Update plugin on group of devices button”) or a single device. Once requested, the update will be run as a background task and logged in Manager logs. During the update the device gets disconnected and reconnected when the update is finished.
Temporary connection errors are normal during this operation, which might take up to a few minutes.
