Installation on LANCOM R&S®Unified Firewall (Asset Mode)

This guide provides instructions for running the XplicitTrust agent as a container on a LANCOM R&S®Unified Firewall.

Asset mode means services (like SSH, HTTPS, remote desktop, etc) can be remotely accessed from an XplicitTrust client, or from another system running in asset mode.

Prerequisites

LCOS FX 11.2 or later. Docker container support was introduced in this release.
A SAG Basic or SAG Full licence (Secure Application Gateway). Container functionality is not available without it. Reboot the firewall after applying the licence, otherwise Docker does not start and the firewall creates no Docker network.
A Docker network on the firewall. Containers attach to a network you create; the agent container needs one with outbound access.

Two ways to deploy

Container management is available through the firewall's REST API and, more conveniently for more than one firewall, through a LANCOM Management Cloud add-in. The add-in is the recommended path and is described first.

Deployment with the LANCOM Management Cloud

XplicitTrust provides a ready-made LMC add-in that declares the agent container, its capabilities and volume, and optionally the firewall objects that give it outbound access.

1. Import the add-in

Download the add-in and import it into your LMC project under Add-ins:

https://dl.xplicittrust.com/xtna-agent-lancom-addin.json

The import creates the XTNA-Agent add-in along with the variables it uses.

2. Set the variables

Assign the variables under Add-ins → Variables, or per device under Devices → device → Variables. Values are layered global → network → site → device, most specific wins — so a tenant-wide token and domain can live at project level while each firewall gets its own asset name and bridge.

Variable	Set at	Description
`XTNA_TOKEN`	project	Required. Asset creation token from the admin console
`XTNA_DOMAIN`	project	Required. Your tenant domain
`XTNA_NAME`	device	Recommended. Asset name. Also sets `-ignore-hostname`, so the asset is identified by this name rather than the container ID
`XTNA_BRIDGE`	device only	Required. Name of this firewall's Docker bridge, e.g. `dockereaecd76f`. It differs on every firewall and only exists after the first rollout. Until it is set, the add-in declares no container. See below
`XTNA_INTERNET`	project or device	Name of the firewall's Internet object, exactly as shown in the desktop, e.g. `WAN DSL`. Default `WAN`
`XTNA_CREATE_NETWORK`		`on` (default) declares the Docker network. Set `off` only if the network is managed elsewhere on the firewall
`XTNA_NETWORK`		Docker network name. Default `Docker`
`XTNA_SUBNET`		That network's subnet. Default `10.238.238.0/24`
`XTNA_WAN_ACCESS`		`on` (default) declares the desktop object and its connection to the Internet object
`XTNA_SERVICES`		Outbound services, comma separated. Default `internet.https,standard.dns`
`XTNA_PORT_FORWARD`		`on` forwards the agent's WireGuard port from the Internet object to the container, so peers connect directly instead of through a relay. Default `off`. See Port forwarding for direct connections below
`XTNA_PORT`		The fixed WireGuard port, on the firewall and in the agent. Default `51899`
`XTNA_IP`	device	The container's fixed address, used with port forwarding. Must not be used by another container. Default: the 10th address of `XTNA_SUBNET`, e.g. `10.238.238.10`

Never set XTNA_BRIDGE at project level

Every firewall has a bridge of its own name. A project-wide value is wrong on all firewalls but one: they reject the configuration with err.desktop.invalid_interface. A firewall without a Docker network also skips the network-only first rollout and fails.

If XTNA_TOKEN and XTNA_DOMAIN are both unset on a device, the add-in does nothing there — so it is safe to allocate broadly and enable it per firewall.

Finding the bridge name

Nobody chooses this name. The firewall creates the bridge once the Docker network exists. In the firewall's web client it is listed under Network → Interfaces → Bridge Interfaces, named docker followed by eight hex characters.

Through the REST API, it is the first eight characters of the Docker network's uniqueId:

GET https://<firewall>:3438/model/docker-network-settings
-> "uniqueId": "eaecd76f-4a31-4e1a-bb75-262547e976e8"
                ^^^^^^^^
   bridge name:  dockereaecd76f

The uniqueId is generated locally by each firewall, so this value differs per device and there is no project-wide setting for it. The add-in cannot work it out either: an add-in script cannot read device state. It only checks the format, docker followed by eight lowercase hex characters, and ignores any other value.

Finding the Internet object

The connection that gives the container outbound access ends at the firewall's Internet object. In the web client it is the Internet icon on the desktop that the existing LAN rules connect to. Set XTNA_INTERNET to its name exactly, including spaces and case. If all your firewalls use the same name, set it once at project level.

3. Allocate and roll out

Assign the add-in under Add-ins → Allocation, either globally with a variable condition or to a network. Then roll the configuration out from the Geräte / Devices list — devices showing Nicht aktuell are rolled out from the three-dot menu.

The add-in logs what it declared to the device log:

xtna-agent: declared docker network 'Docker' (10.238.238.0/24, gateway chosen by the firewall)
xtna-agent: declared container 'xtna-agent' from cr-public.xplicittrust.com/xtna-agent:latest as asset 'edge-gw-01'
xtna-agent: declared desktop object 'XTNA container' on bridge 'dockereaecd76f' (10.238.238.0/24)
xtna-agent: declared connection 'XTNA container' <-> 'WAN' allowing internet.https, standard.dns outbound. ...

A failed configuration upload is discarded whole

The firewall applies a configuration transactionally. If one declared object is rejected, the entire upload is rolled back, including objects that were accepted. Check the device log for the rejected object rather than assuming a partial result.

A firewall without a Docker network needs two rollouts

The example above is a firewall whose Docker network and bridge already exist. On a new one, roll out twice, leaving XTNA_CREATE_NETWORK at on both times.

The firewall cannot create the Docker network and the container in the same rollout, and the bridge name only exists once the network has been applied. So the first rollout creates only the network:

	What happens
Rollout 1	`XTNA_BRIDGE` is empty, so the add-in declares only the Docker network. The firewall creates the bridge.
In between	Read this firewall's bridge name (see Finding the bridge name above) and set `XTNA_BRIDGE` under *Devices → device* → Variables**.
Rollout 2	The container, the desktop object and the connection to the Internet object are declared.
After rollout 2	In the firewall's web client, open the connection between the XTNA container object and the Internet object and save it unchanged. Until then the container has no outbound access. The container then enrols.

After the first rollout the device log says what to do next:

xtna-agent: declared docker network 'Docker' (10.238.238.0/24, gateway chosen by the firewall)
xtna-agent: XTNA_BRIDGE is empty, so this rollout declares only the docker network ...

If the firewall's outbound access for the container network is already managed elsewhere in its configuration, set XTNA_WAN_ACCESS to off. The add-in then declares no desktop object or connection, but still needs XTNA_BRIDGE set before it declares the container.

Port forwarding for direct connections

Without it, the firewall lets the agent out but not in, so peer connections often go through a relay. With XTNA_PORT_FORWARD set to on, the add-in also declares:

the container with a fixed address (XTNA_IP) and a fixed WireGuard port (XTNA_PORT)
a UDP service XTNA WireGuard for that port
a host object XTNA agent for the container's address
a connection from the Internet object to that host, forwarding the port

The external and internal port are the same. Make sure nothing else on the firewall forwards that port, and that an upstream router, if any, forwards it to the firewall.

The container's address must be free on the Docker network. Before switching port forwarding on, look up the addresses of the containers on the firewall in its web client, or with GET /api/docker/containers-info. To keep the agent container at its current address, set XTNA_IP to that address.

Switching it on updates the container

The container gets a fixed address and a new start command, so the firewall recreates it. It keeps its volume, and with it the asset. If the asset does not come back Online after the rollout, open the connection between the XTNA container object and the Internet object in the web client and save it unchanged.

Agents that are already enrolled

The agent takes the fixed port only when it enrols. For a container that is already enrolled, fixate the asset to the same port first: in the Admin Console, open the asset's actions and choose Fixate Port.

Deployment with the REST API

For a single firewall, or to inspect what the add-in produces, containers can be managed directly. Authenticate against POST /auth/login and pass the returned token as the X-Gateprotect-Auth-Token header.

Endpoint	Purpose
`GET /model/docker-network-settings`	The Docker networks and their IDs
`POST /model/docker-container-settings`	Create the container
`GET /api/docker/containers-info`	Inspect state, addresses, mounts
`GET /api/docker/container-logs/{uniqueId}`	The container's log output

A minimal container object:

{
  "active": true,
  "name": "xtna-agent",
  "image": "cr-public.xplicittrust.com/xtna-agent:latest",
  "command": "-token <token> -domain <tenant domain> -name <asset name> -ignore-hostname",
  "capabilities": ["NET_ADMIN", "NET_RAW"],
  "volumes": ["/etc/XplicitTrust"],
  "networks": [{ "uniqueId": "<docker network uniqueId>" }],
  "policy": { "restart": { "condition": "always" } }
}

Keep the volume

/etc/XplicitTrust holds the asset identity and certificates. Without it, every recreation of the container enrols a new asset. With it, re-passing -token is harmless: the agent only registers when no configuration is present.

Outbound access

The container needs to reach the XplicitTrust infrastructure:

TCP 443 to the API, the update server and the broker
UDP 53 for name resolution
outbound UDP for direct peer-to-peer connections. Without it the agent still works, but every peer connection falls back to a relay

There is no predefined service on LCOS FX covering the WireGuard and peering UDP ports, so allowing direct peering needs a user-defined service. Predefined service names are category-prefixed — internet.https and standard.dns, not HTTPS and DNS.

The connection between the container network object and the Internet object must masquerade the container side (natactive: "left"). The Docker subnet is not routable upstream, so without it packets leave with a private source address and nothing returns.

Open source licenses

The container image contains open source software, some of it under the GPL. Its license texts are in the image, and its source code is published in the same registry. See Open Source Licenses and Source Code.

Troubleshooting

The rollout fails with err.desktop.invalid_interface. The firewall has no bridge named like XTNA_BRIDGE. Usually the value was set at project level and belongs to another firewall. Set it on the device to the name this firewall lists under Bridge Interfaces.

The rollout fails with "objb": null and err.general.required on /model/desktop-connections. No Internet object on the firewall is named like XTNA_INTERNET (default WAN). Set it to the exact name, e.g. WAN DSL.

The rollout fails with "networks": [{"uniqueId": null}]. The Docker network named in XTNA_NETWORK does not exist. Leave XTNA_CREATE_NETWORK at on, empty XTNA_BRIDGE on the device and start again with rollout 1.

The rollout fails with err.docker.duplicate_ip on /model/docker-container-settings. Another container on the firewall already has the address in XTNA_IP, or the default 10th address of XTNA_SUBNET when it is empty. The error names that container. Set XTNA_IP on the device to a free address.

Peer connections still go through a relay with port forwarding on. Check that the asset uses XTNA_PORT: an agent enrolled before port forwarding was switched on keeps its old port until the asset is fixated to it with Fixate Port. If the firewall sits behind another router, that router has to forward the port to the firewall too.

The asset never appears in the console. The container cannot reach the API. Check that XTNA_BRIDGE matches the name under Bridge Interfaces, and read the container log via GET /api/docker/container-logs/{uniqueId}.

The container has no outbound access after the rollout that created or updated it. Creating or updating a container gives it a new virtual interface, and the outbound rule does not pick it up in the same rollout. A device restart does not repair it, and another rollout from the LANCOM Management Cloud does not either, since it has no changes to send. Open the connection between the XTNA container object and the Internet object in the web client and save it unchanged.

The asset registers but does not come Online. Usually the tunnel cannot establish. Check that outbound UDP is permitted, and look in the container log for bind or relay errors.

The agent's own log is written inside the container to /etc/XplicitTrust/logs/xtna-service.log, which is on the volume and therefore survives a restart.

Consult the FAQ to learn more about troubleshooting firewalls.