15. DynFi Connection Agent

15.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 such devices. This might be problematic in some cases, because such connection many times enforces one of the following scenarios:

  • opening incoming SSH and HTTP connection on WAN
  • installing and configuring a VPN between the server running the Manager and each managed device.

This is caused by the fact that the connection is initiated from the Manager to the devices.

The DynFi Connection Agent reverses the initiating party and therefore eliminates the scenarios listed above.

The Connection Agent is a plugin / module developed by DynFi. It can be installed in open source firewalls (e.g. OPNsense™).

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.

15.2. Steps needed to start using the Agent

  1. 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 Configuration, e.g. adding to /etc/dynfi.conf the following line:

    connectionAgentPort=2222
    

    and restarting the Manager.

  2. 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.

  3. The plugin needs to be installed first. This can be done in the firewall’s terminal by running the following line:

    curl https://{server-address-here}/dfconag-installer.sh | /bin/sh
    
  4. 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, select “DynFi Connection Agent” menu entry.
    4. 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.

15.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.

15.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 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.