7. DFM Connection Agent

7.1. What is the DynFi Connection Agent

DynFi® Connection Agent is a plugin / module which allows initiating a connection from an open-source firewall to DynFi® Manager.

In order to manage firewall devices, DynFi Manager needs to be able to establish SSH and HTTP(S) connections to a remote firewall device (DynFi® Firewall, pfSense®, OPNsense®). However, this might be problematic in some cases, because these devices might be:

  • unreacheable because inbound connections are filtered

  • unreacheable because they are behind two firewalls

  • unreacheable due to complex NAT scenarios

  • unreacheable due to 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).

DynFi Connection Agent initiates the connection directly from the remote firewall, bypassing most of the 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 is available as a third party plugin 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

7.2.1. Install the plugin

DynFi® Firewall

Connection Agent is preinstalled on DynFi Firewall, so this step can be skipped.

pfSense®

The recommended method is to copy and paste the command below as root on your pfSense® device. This will download and install the latest version of Connection Agent and autossh package.

curl https://dynfi.com/files/connection-agent/pfsense/dfconag-latest-installer.sh --output /tmp/dfconag-installer.sh && sh /tmp/dfconag-installer.sh

Once the Agent is installed, a new menu will appear under: Services » DynFi Connection Agent.

Note

Please note that DFConAg is known to work with pfSense® v.2.4 and up and pfSsense-Plus v.22.05.

OPNsense®

The recommended method is to copy and paste the command below as root on your OPNsense® device. This will download and install the latest version of Connection Agent and autossh package.

curl https://dynfi.com/files/connection-agent/opnsense/dfconag-latest-installer.sh --output /tmp/dfconag-installer.sh && sh /tmp/dfconag-installer.sh

Note

Please note that DFConAg is known to work with OPNsense v.19.0 and up.

7.2.2. Make sure that Connection Agent is enabled in the Manager

You need to ensure that your DynFi manager configuration file (located in /etc/dynfi.conf) contains the following line:

connectionAgentPort=2222

This entry defines the port number for incoming connections and it should be present in the config file by default. The port can be changed if needed. Do not use the same SSH port for DynFi Manager and your standard SSH Server. For more details about managing configuration, see the DFM Configuration section.

If you make any changes in dynfi.conf, please remember to restart the Manager:

systemctl restart dynfi

Note

Please make sure the selected port will accept incoming connections from the devices. This may require adding an appropriate PASS rule in the firewall protecting the Manager. See Tunnels example for more details on the ports related to Connection Agent.

7.2.3. Attach a device

The easiest way to attach a device to the Manager using the Agent is as follows:

  1. In the Manager: go to Connection Agent settings (⚙️ -> Connection Agent).

  2. Generate a Connection Agent Token and copy it.

  3. Go to device’s Web User Interface and select the “DynFi Connection Agent” menu entry.

  4. Click the [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 device can reach it (i.e. no firewalls are blocking it), the Connection Agent will:

  • connect to the Manager right after being configured,

  • reconnect after each restart of the Manager or the device,

  • reestablish the connection if it drops due to any other reason.

The bond between the Manager and the Agent can be canceled at any time. The other party (if possible) will be notified, so normally (with a working link) there should be no need to disconnect the device twice - once in the Manager and once in the Agent.

There is no strict requirement to use the Connection Agent to attach devices to the Manager. However, in many situations it is the easiest way. It is also possible to attach a 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 simplest way to attach devices to the Manager using the Connection Agent. They carry some information but also authenticate permitted usages. They only work with the Manager they were created for (i.e. ‘they can only call home’).

A Token is essentially a piece of text which encodes the following:

  • the Manager’s host and port

  • the Manager’s public key

  • the expiration date

Tokens can be generated by the Manager’s operators and passed to firewall operators (which may be the same person or someone else) without revealing any passwords. They remain active until used or expired, or deactivated (whichever comes first) and allow attaching devices only to the instance of the Manager they were issued for, not any other instance.

By default, Tokens are valid for one hour and can be used only once. This can be adjusted before creating a token. For example, it may be useful in scenarios where the operator wants a single token to allow attaching 10 devices within the next 24h.)

Token is issued for a specific Device Group, and the device will be added to that group upon attachment. After creation, Tokens cannot be modified (e.g. their expiration date cannot change).

Tokens are issued by operators with sufficient permissions, and for Device Groups they have access to. If the operator’s account is deleted, the Device Group is deleted, or the operator loses access to the Device Group, the token will no longer work when attaching device.

If a token (for any reason) carries invalid Manager hostname or port (e.g. a FQDN cannot be used and must be replaced with an explicit IP address), it can be manually overwritten in the ‘Advanced options’ section. In this case, the Token will still authenticate the attachment process.

7.4. How connections work

Setting the Connection Agent port in the DynFi Manager enables an embedded SSH server/daemon. THis server is part of the Manager’s Java process, and no other processes are started (e.g. with a separate PID). The SSH server does not depend on the operating system, and has no access to the file system or any OS programs. Its role and capabilities are limited to the process of attaching a device and responding to the Connection Agent’s requests. It cannot be used to access the Manager’s files or run other programs.

The Connection Agent operates on firewall devices. In a way it is a wrapper for the autossh program. It allows the device (on which it is installed and configured) to attach to an instance of the DynFi Manager.

Once configured, the connection established by the Agent:

  • is made from the firewall to the Manager’s SSH subsystem

  • establishes two reverse SSH tunnels

  • is secured by EdDSA SSH keys on both ends

  • is re-established after being dropped and re-configured when necessary (e.g. if the SSH service on the device changes its port)

7.4.1. Reverse SSH tunnels

The SSH connection established by autossh serves one primary purpose: running two reverse SSH tunnels. Using these tunnels, DynFi Manager can contact the device by initiating SSH connections (using the so-called main or SSH tunnel) and DirectView connections (using the so-called DV or HTTPS tunnel). Therefore, from the perspective of various Manager’s services (apart from the 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 subsystems.

Tunnels Example

_images/connection.png

On the above diagram, Connection Agent (pre-installed on DynFi Firewall) has established two reverse SSH tunnels to DynFi Manager (which listens for agent’s connections on port 2222):

  • Main (SSH) tunnel on ports 40000->22

  • DirectView (HTTPS) tunnel on ports 40001->443.

With these tunnels established, DynFi Manager sends SSH requests (e.g. to fetch the firewall’s status) on port 40000. The requests are then redirected to port 22 on DynFi Firewall via the tunnel. Similarly, DirectView requests are redirected from port 40001 to port 443 on DynFi Firewall. If we compare this to a direct SSH connection (without the Connection Agent, initiated by DFM), the only difference from the perspective of most DynFi Manager services is the port number.

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.

The Connection agent status page (⚙️ -> Connection Agent -> Status) shows all devices using the Connection Agent, along with the version of the currently installed plugin and the latest available plugin for each firewall type. DynFi Manager fetches the latest available version once a day from https://dynfi.com. Please ensure that the manager can reach https://dynfi.com, as the update won’t be possible otherwise. If the Manager cannot reach the website, the Connection Agent plugin has to be reinstalled manually, as described in the Install the plugin section.

Agent status column indicates whether the plugin on a given device is up to date or requires an update. It’s possible to update the plugin for multiple devices by selecting them from the list. Once requested, the update will be run as a background task and be logged in the Manager logs. During the update, the device will be disconnected and then reconnected once the update is finished.

Temporary connection errors are normal during this operation, which may take up to a few minutes.

_images/update.png