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.
| Variable | Required | Description |
|---|---|---|
XTNA_TOKEN |
yes | Asset creation token from the admin console |
XTNA_DOMAIN |
yes | Your tenant domain |
XTNA_NAME |
recommended | Asset name. Also sets -ignore-hostname, so the asset is identified by this name rather than the container ID |
XTNA_NETWORK |
Docker network name on the firewall. Default Docker |
|
XTNA_SUBNET |
That network's subnet | |
XTNA_CREATE_NETWORK |
on to have the add-in declare the Docker network too. Leave off when it already exists. While XTNA_BRIDGE is empty, only the network is declared |
|
XTNA_BRIDGE |
yes | Name of the Docker bridge interface, e.g. dockereaecd76f. Per firewall; on a new one it only exists after the first rollout. Without it the add-in declares no container. See below |
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_INTERNET |
Name of the Internet object. Default WAN |
|
XTNA_IP |
Fixed address inside the Docker network. Leave blank to let Docker assign one | |
XTNA_CONTAINER, XTNA_DESKTOP, XTNA_IMAGE |
Object names and image, if the defaults do not suit |
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.
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: using existing docker network 'Docker' (XTNA_CREATE_NETWORK is off)
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'
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 that already has a Docker network. On a new one, set XTNA_CREATE_NETWORK to on and roll out twice.
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 the bridge name (see Finding the bridge name above) and set XTNA_BRIDGE on that device. |
| 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.
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.
Troubleshooting
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.