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.
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
`XTNA_BRIDGE`	for outbound rules	Name of the Docker bridge interface, e.g. `dockereaecd76f`. 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

LCOS FX names the Docker bridge docker followed by the first eight characters of the Docker network's ID. Read it from the firewall's REST API:

GET https://<firewall>:3438/model/interfaces

Look for the entry with "type": "bridge" and a name starting with docker. The add-in cannot determine this itself, because 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.

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 the outbound rule for the Docker network, and read the container log via GET /api/docker/container-logs/{uniqueId}.

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 container was updated and lost outbound access. Recreating a container gives it a new virtual interface. Firewall rules bound to the previous one no longer match, and a device restart does not repair it — only a configuration apply re-renders them. Roll the configuration out again after any container update.

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.