Skip to content

Installation with Docker / Podman (Asset Mode)

XplicitTrust provides an official container image for running the agent in containerized environments such as Docker, Podman, or Kubernetes.

The container image is available at cr-public.xplicittrust.com/xtna-agent and supports amd64, arm64, and armhf architectures.

Prerequisites

Network capabilities

The container must run with elevated network capabilities:

  • NET_ADMIN — required for WireGuard tunnel management and firewall rules
  • NET_RAW — required for raw socket operations

Rootful mode required

The container must run in rootful mode (e.g. with sudo). Rootless Docker/Podman cannot grant real network capabilities outside the user namespace.

The /dev/net/tun device

The agent builds a WireGuard tunnel and therefore needs access to the host's TUN device, /dev/net/tun. Without it the agent starts but fails to bring up the tunnel, logging:

CreateTUN("xt0") failed; /dev/net/tun does not exist

This applies even though the agent uses a userspace WireGuard implementation — the userspace tunnel still attaches to a kernel TUN interface. A missing TUN device is the most common cause of an agent that registers successfully but never connects (and, as a side effect, installs no firewall rules, since those rules are scoped to the tunnel interface).

Two things are required:

  1. The tun kernel module must be loaded on the host. It usually is, but on minimal hosts you may need to load it (and persist it across reboots):

    sudo modprobe tun
    echo tun | sudo tee /etc/modules-load.d/tun.conf
    
  2. The device must be passed into the container with --device /dev/net/tun (Docker/Podman) or the equivalent in your orchestrator. This is included in all the run commands below.

--device requires the host device to already exist

--device /dev/net/tun passes through an existing host device node. If the tun module isn't loaded on the host, /dev/net/tun doesn't exist and the container fails to start with an error like error gathering device information ... no such file or directory. Always ensure the host module (step 1) before relying on --device (step 2).

Network mode

Which network mode the container needs depends on what you expect the agent to do.

Client-only asset. If the agent only makes the container itself reachable over XplicitTrust Network Access, the default bridge/NAT network is sufficient. The agent opens outbound connections, so no inbound reachability on the LAN is required. All the examples in this guide use the default network.

Gateway asset. If the agent should route traffic to other devices on the local subnet, the default bridge network is not enough. The container needs its own presence on the physical LAN — its own MAC address and its own IP in the LAN subnet — so that it can answer ARP for the subnet it serves and so return traffic from local devices finds its way back.

Use macvlan, not ipvlan

For gateway assets, attach the container with the macvlan driver. The ipvlan driver (in its default L2 mode) gives every container the host's MAC address rather than one of its own. The agent then cannot act as a distinct layer-2 endpoint for the subnet it routes, and traffic to and from local devices fails in ways that look like a routing problem but are not. Symptoms: the asset registers and the tunnel comes up, remote clients can reach the container itself, but nothing behind it on the LAN responds.

Create a macvlan network whose parent is the host's LAN interface (or a bridge on top of it), then attach the container to it:

sudo docker network create -d macvlan \
  -o parent=br0 \
  --subnet 192.168.1.0/24 \
  --gateway 192.168.1.1 \
  xtna-lan

sudo docker run -d --restart unless-stopped \
  --network xtna-lan --ip 192.168.1.240 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain>

Replace br0 with the actual parent interface — it differs per host, and on appliance platforms it is often a virtual switch rather than the physical NIC.

Addressing

Docker's macvlan driver does not run a DHCP client: the --ip above — and any address Docker picks if you omit it — comes from Docker's own address management using the --subnet you gave at network-creation time. The container never requests a lease from the LAN's DHCP server. There are three ways to handle addressing:

  • Fixed IP with a DHCP reservation (recommended for a gateway asset). Keep --ip, pin the container's MAC with --mac-address, and add a reservation for that MAC on your DHCP server. The address stays centrally managed but never changes. A gateway asset needs a stable address — local devices route through it, so an address that changed on lease renewal would break their routing.

  • Docker auto-assignment. Omit --ip and Docker assigns an address itself from the network's range. This is not DHCP, and it collides with the DHCP pool unless you restrict Docker to a block carved out of that pool with --ip-range — for example --ip-range 192.168.1.224/27 for a network whose DHCP pool ends at .223.

  • Genuine DHCP leases. A container only obtains a real lease from the LAN DHCP server through a third-party driver such as docker-net-dhcp, or on a platform that provides it natively (QNAP's Qnet driver has a DHCP mode, for instance). Both are outside plain Docker and Podman.

Reserve the address either way

Whichever option you choose, exclude the container's address from the DHCP pool — as a static reservation or a pool boundary — so the DHCP server never leases it to another device.

Host isolation

macvlan deliberately prevents the container and its own host from talking to each other: traffic between them never reaches the physical network where it could be switched back. This is a property of macvlan itself, not a misconfiguration.

It matters whenever the NAS or hypervisor running the agent also hosts services that XplicitTrust clients should reach, since those are exactly the packets that get dropped.

Some platforms expose a setting for this — on Unraid it is Settings → Docker → Host access to custom networks, which must be enabled. Where no such setting exists, create a macvlan shim interface on the host:

sudo ip link add xtna-shim link br0 type macvlan mode bridge
sudo ip addr add 192.168.1.250/24 dev xtna-shim
sudo ip link set xtna-shim up

The shim gives the host a second address on the LAN that can reach macvlan containers. Use an address outside your DHCP pool and distinct from both the host's own LAN address and the container's.

The shim does not survive a reboot

ip link changes are not persistent. Add the commands to whatever the platform provides for boot-time scripting (/etc/rc.local, a systemd unit, or the appliance's startup-script hook), or host access breaks again on the next restart.

IP forwarding

A gateway asset routes packets between its tunnel interface and the LAN, and the Linux kernel only does that when forwarding is enabled in the container's own network namespace:

sudo docker exec <container-name> cat /proc/sys/net/ipv4/ip_forward

1 is what you want. If it reads 0, the container is not routing anything and no amount of firewall or policy configuration will change that.

Usually it already reads 1. A new network namespace inherits the value from the host's net.ipv4.conf.all.forwarding when the container is created, and any host that already routes has it set — a NAS, a router, a firewall appliance, or simply a host running Docker, which enables forwarding when the daemon starts. Hosts that do not already route are where this bites: a plain server, or one where a hardening baseline turned forwarding off.

Set it explicitly to make the container independent of the host:

sudo docker run -d --restart unless-stopped \
  --sysctl net.ipv4.ip_forward=1 \
  --network xtna-lan --ip 192.168.1.240 \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain>
sysctls:
  - net.ipv4.ip_forward=1
securityContext:
  sysctls:
    - name: net.ipv4.ip_forward
      value: "1"

net.ipv4.ip_forward is namespaced but not in the kubelet's default allow-list, so the node's kubelet needs it permitted with --allowed-unsafe-sysctls=net.ipv4.ip_forward.

The sysctl must be set when the container is created — it cannot be added to a running container, and the agent cannot set it for you. /proc/sys is mounted read-only inside every non-privileged container in both Docker and Podman, so the agent's attempt fails with read-only file system. No capability changes this: a read-only mount is rejected before any capability is considered, and NET_ADMIN is already granted. --sysctl works because the container runtime sets the value from outside the namespace, before /proc/sys is remounted read-only.

Client-only assets do not need this

Forwarding only matters when the agent routes for other devices. An asset that merely makes itself reachable over XplicitTrust Network Access neither needs nor uses it.

Installation

sudo docker pull cr-public.xplicittrust.com/xtna-agent:latest
sudo podman pull cr-public.xplicittrust.com/xtna-agent:latest

The run commands on this page use docker. With Podman, replace docker with podman and --restart unless-stopped with --restart always.

Podman: starting the agent after a host reboot

Podman has no daemon that restarts containers when the host boots. That is done by podman-restart.service, which only starts containers with the restart policy always. Containers with unless-stopped are not started again after a reboot. Enable the service once:

sudo systemctl enable podman-restart.service

Configuration

See the xtna-util reference for a complete list of available flags.

The container accepts registration flags directly — no separate xtna-util step is needed.

Use token-based registration for headless or automated deployments:

  1. Go to the Admin Console settings page

  2. Create a new "Asset Creation Token", configure it, download and store it in a secure place

  3. Run the container with the token:

sudo mkdir -p /opt/xtna/my-asset
sudo docker run -d --name xtna-agent --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain>

Registration flags are only used on first start. Once the asset is registered, its configuration is stored in the mounted directory and the flags are ignored on subsequent runs.

Use device flow registration for interactive setups:

sudo mkdir -p /opt/xtna/my-asset
sudo docker run -it --name xtna-agent --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -user <admin email address>

Open the URL shown in the terminal to authenticate. After successful registration, the container continues running in the foreground.

  1. Go to the Admin Console assets page

  2. Click Create new, fill out the form, click Apply

  3. Click the Download Config icon at the top of the form box:

    Download

  4. Place the configuration file in a host directory and mount it:

sudo mkdir -p /opt/xtna/my-asset
sudo cp xtna-*.xtconfig /opt/xtna/my-asset/
sudo docker run -d --name xtna-agent --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest

Persistent Configuration

Always mount a host directory to /etc/XplicitTrust, as all examples on this page do. It holds the asset's configuration, certificates and registration.

Without the mount, the configuration lives only inside the container. Removing the container deletes it, and the asset has to be registered again as a new asset. Since a new image only takes effect when the container is recreated (see Updates), an agent without the mount cannot be updated to a new image without losing its registration.

Existing containers without a mount

To move an existing container to a mounted directory, copy its configuration out before recreating it:

sudo mkdir -p /opt/xtna/my-asset
sudo docker cp <container-name>:/etc/XplicitTrust/. /opt/xtna/my-asset/

Then stop and remove the old container and start a new one with -v /opt/xtna/my-asset:/etc/XplicitTrust.

The configuration directory contains credentials

The mounted directory holds the asset's authentication secret. Anyone with a copy can authenticate as this asset, so keep it root-only and never copy it into images, templates or shared snapshots. On AWS, see Persistent configuration for ECS, EFS and EKS.

Running multiple agents on one host

Each container needs its own configuration directory. Use a unique path per instance:

sudo docker run -d --name office-gw \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/office-gw:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token-1> -domain <tenant-domain>

sudo docker run -d --name lab-gw \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/lab-gw:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token-2> -domain <tenant-domain>

Registration Flags

Flag Description
-token <token> API key/token for unattended registration
-user <email> Admin email for interactive device flow registration
-domain <domain> Tenant domain (required with -token, optional with -user)
-name <name> Asset name (defaults to container hostname)
-ignore-hostname Do not use the container's real hostname during registration
-api <url> API URL override (for on-premise deployments)

Give the asset a stable name

A container's hostname is its short container ID unless you set one with --hostname, which makes for a meaningless asset identity in the Admin Console and in peer listings. Combine -name with -ignore-hostname so the asset is identified only by the name you choose:

sudo docker run -d --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest \
  -token <token> -domain <tenant-domain> \
  -name edge-gw-01 -ignore-hostname

Docker Compose

services:
  xtna-agent:
    image: cr-public.xplicittrust.com/xtna-agent:latest
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    devices:
      - /dev/net/tun:/dev/net/tun
    volumes:
      - ./xtna-config:/etc/XplicitTrust
    # Only needed on first run for registration:
    # command: ["-token", "YOUR_TOKEN", "-domain", "your-domain.com"]

Updates

The launcher in the container updates itself and the agent service automatically. You do not need a new image for agent updates.

The rest of the image is the Alpine Linux base system and iptables. These are only updated when you run a new image, so new image versions carry security fixes for them. Update the image regularly, and promptly when a new image is announced for a security issue.

Restarting a container does not update its image

docker pull only downloads the new image. A container keeps running the image it was created from, also after docker restart and after a host reboot. To switch to the new image, the container has to be removed and created again. Its configuration survives this only if /etc/XplicitTrust is mounted from the host (see Persistent Configuration).

sudo docker pull cr-public.xplicittrust.com/xtna-agent:latest
sudo docker stop xtna-agent
sudo docker rm xtna-agent
sudo docker run -d --name xtna-agent --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest

Use the same options you created the container with (--network, --ip, --sysctl, -name, …). Registration flags such as -token can be left out: they are ignored once the asset is registered.

sudo podman pull cr-public.xplicittrust.com/xtna-agent:latest
sudo podman stop xtna-agent
sudo podman rm xtna-agent
sudo podman run -d --name xtna-agent --restart always \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  cr-public.xplicittrust.com/xtna-agent:latest

Use the same options you created the container with (--network, --ip, --sysctl, -name, …). Registration flags such as -token can be left out: they are ignored once the asset is registered.

sudo docker compose pull
sudo docker compose up -d

up -d recreates the container when its image has changed.

With the :latest tag and no imagePullPolicy set, Kubernetes pulls the image whenever it starts a new pod. Restart the deployment to roll out a new image:

kubectl rollout restart deployment/xtna-agent

To check which image a container is running, compare its image ID with the newest pulled one:

sudo docker inspect --format '{{ .Image }}' xtna-agent
sudo docker image inspect --format '{{ .Id }}' cr-public.xplicittrust.com/xtna-agent:latest

Kubernetes

For Kubernetes deployments, use a DaemonSet or Deployment with the required security context:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: xtna-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: xtna-agent
  template:
    metadata:
      labels:
        app: xtna-agent
    spec:
      containers:
        - name: xtna-agent
          image: cr-public.xplicittrust.com/xtna-agent:latest
          securityContext:
            capabilities:
              add:
                - NET_ADMIN
                - NET_RAW
          volumeMounts:
            - name: config
              mountPath: /etc/XplicitTrust
            - name: tun
              mountPath: /dev/net/tun
      volumes:
        - name: config
          persistentVolumeClaim:
            claimName: xtna-config
        - name: tun
          hostPath:
            path: /dev/net/tun
            type: CharDevice

Provide the registration token via a Kubernetes Secret or environment variable in your deployment pipeline.

TUN device on Kubernetes

Kubernetes has no direct equivalent of --device, so the example above exposes /dev/net/tun via a hostPath volume of type CharDevice. The node must have the tun kernel module loaded (modprobe tun) and /dev/net/tun present, otherwise the pod will fail to mount the volume. Alternatively, use a TUN/TAP device plugin to avoid hostPath.

Remote desktop applications

A gateway asset that serves remote desktop applications of a portal needs guacd, which opens the RDP, SSH and VNC sessions for the browser. guacd is not in the agent image, since most assets serve no such application, and there is no second container to run: when the first configuration with a remote desktop application reaches the asset, the agent downloads guacd (about 12 MB from dl.xplicittrust.com, for amd64 and arm64), checks it against the checksum built into the agent, and starts it inside the agent container. Assets that serve no remote desktop application never download it.

The agent keeps guacd on the configuration volume, under /etc/XplicitTrust/guacd-bundle/. With the configuration in a volume or host directory, as in Persistent Configuration, guacd is downloaded once and survives container updates; without one, every new container downloads it again.

While guacd is downloading, the portal is already served and its remote desktop sessions show The gateway is still installing the remote desktop service. Try again in a minute. The console shows the state on the portal's detail page, under Gateway status.

guacd is updated with the agent: a new agent image that brings a newer guacd downloads it while the old one keeps serving, and switches once no remote desktop session is open.

Without internet access. Mirror the file the agent downloads and point the agent to it with an environment variable; the agent still checks the checksum, so only the exact file is accepted. The agent log (/etc/XplicitTrust/logs/xtna-service.log) names the file, in the line web app: downloading guacd (bundle ...) from https://dl.xplicittrust.com/guacd/...:

sudo docker run -d --name xtna-agent --restart unless-stopped \
  --cap-add NET_ADMIN --cap-add NET_RAW \
  --device /dev/net/tun \
  -v /opt/xtna/my-asset:/etc/XplicitTrust \
  -e XTNA_GUACD_BUNDLE_URL=https://mirror.example.com/xtna-guacd_1.6.0-1_amd64-0123456789ab.tar.gz \
  cr-public.xplicittrust.com/xtna-agent:latest

guacd is guacamole-server and FreeRDP, built from their release sources, with the Alpine Linux libraries they need, among them LibVNCServer's client library for VNC. Its license texts and notices are in /opt/xtna-guacd/share/licenses/ once it is installed; THIRD-PARTY.txt there names the archive with the complete corresponding source, on dl.xplicittrust.com. Its SBOM is published next to it, for example https://dl.xplicittrust.com/xtna-guacd_amd64.tar.gz.cyclonedx.json.

Open Source Licenses and Source Code

Besides the XplicitTrust agent, the image contains open source software: the Alpine Linux base system, iptables with its libraries, and the Go modules built into the agent. Some of it is licensed under the GNU General Public License (GPL) and the GNU Lesser General Public License (LGPL).

The license texts and notices are part of the image, in /usr/share/licenses/xtna-agent/:

  • THIRD-PARTY.txt: an overview, and the name of the matching source image
  • alpine-packages.txt: every Alpine package with its version and license
  • go-modules.txt: the license and copyright notices of the Go modules
  • one file per license with its full text, e.g. GPL-2.0.txt

To read them:

sudo docker run --rm --entrypoint cat cr-public.xplicittrust.com/xtna-agent:latest /usr/share/licenses/xtna-agent/THIRD-PARTY.txt
sudo podman run --rm --entrypoint cat cr-public.xplicittrust.com/xtna-agent:latest /usr/share/licenses/xtna-agent/THIRD-PARTY.txt

The complete source code of these packages, in exactly the versions in the image (the Alpine build recipes with their patches, and the upstream sources), is published in the same registry. Every image tag has a source image tag with the suffix -source, e.g. latest-source for latest. The source image only contains files, under /sources, and is not meant to be run. To copy them out:

sudo docker create --name xtna-agent-source cr-public.xplicittrust.com/xtna-agent:latest-source true
sudo docker cp xtna-agent-source:/sources ./xtna-agent-sources
sudo docker rm xtna-agent-source
sudo podman create --name xtna-agent-source cr-public.xplicittrust.com/xtna-agent:latest-source true
sudo podman cp xtna-agent-source:/sources ./xtna-agent-sources
sudo podman rm xtna-agent-source

latest-source moves along with latest. For the source of an image you already run, use the source image named in its THIRD-PARTY.txt, or in its label:

sudo docker inspect --format '{{ index .Config.Labels "com.xplicittrust.source-image" }}' cr-public.xplicittrust.com/xtna-agent:latest

/sources/SOURCES.txt lists each source package with its version and the Alpine aports commit it was built from.

Troubleshooting

Container exits immediately

  • Ensure NET_ADMIN and NET_RAW capabilities are granted
  • Ensure the container runs in rootful mode (sudo)
  • Check logs: sudo docker logs <container-name>

"No configuration found" error

  • Provide registration flags (-token or -user) on first run, or mount a directory containing a valid configuration

Tunnel not working / CreateTUN("xt0") failed; /dev/net/tun does not exist

This means the agent registered but cannot create its WireGuard tunnel because the TUN device isn't available inside the container.

  • Confirm the device is present inside the container:
    sudo docker exec <container-name> ls -l /dev/net/tun
    
  • If it's missing, ensure both halves of the TUN prerequisite:
    1. The tun module is loaded on the host: sudo modprobe tun
    2. The container is started with --device /dev/net/tun (recreate the container — devices cannot be added to a running container):
      sudo docker run -d --name xtna-agent --restart unless-stopped \
        --cap-add NET_ADMIN --cap-add NET_RAW \
        --device /dev/net/tun \
        -v /opt/xtna/my-asset:/etc/XplicitTrust \
        cr-public.xplicittrust.com/xtna-agent:latest
      
  • If docker run itself fails with error gathering device information ... no such file or directory, the host is missing /dev/net/tun — load the tun module on the host first (step 1).

Reading the agent log

The container's launcher writes a combined log file at /etc/XplicitTrust/logs/xtna-service.log inside the container. This often shows the underlying cause more clearly than docker logs:

sudo docker exec <container-name> tail -f /etc/XplicitTrust/logs/xtna-service.log

Gateway asset: the container is reachable but nothing behind it responds

The asset is Online, remote clients can reach the container itself, and its policies look right — but traffic to other devices on the LAN goes nowhere. If macvlan is already in place, check forwarding:

sudo docker exec <container-name> cat /proc/sys/net/ipv4/ip_forward

If this reads 0, the kernel is discarding forwarded packets before they reach any firewall rule, which is why nothing in the agent's configuration appears wrong. The giveaway is that the agent's own rules sit at zero packets:

sudo docker exec <container-name> iptables -t nat -L xt-postrouting -n -v
sudo docker exec <container-name> iptables -L xt-forward -n -v

A correct-looking MASQUERADE rule that has never matched a single packet means the traffic never got as far as being forwarded.

The container log records the agent's failed attempt to fix this itself:

[ERROR] enableForwarding: Writing to /proc/sys/net/ipv4/ip_forward failed,
open /proc/sys/net/ipv4/ip_forward: read-only file system

Recreate the container with --sysctl net.ipv4.ip_forward=1 — see IP forwarding. It cannot be added to a running container, and adding capabilities does not help. To confirm the diagnosis before recreating anything, set it on the running container from the host:

sudo nsenter -t $(docker inspect -f '{{.State.Pid}}' <container-name>) -n \
  sysctl -w net.ipv4.ip_forward=1

Traffic starts flowing immediately if this was the cause. The change is lost on the next container restart, so make it permanent with --sysctl.

Remote desktop: "The gateway is still installing the remote desktop service."

  • The agent is downloading guacd, which takes seconds on a usual connection: see Remote desktop applications.
  • When it stays, the agent cannot download it. The portal's Gateway status in the console shows the reason, and the agent log (/etc/XplicitTrust/logs/xtna-service.log) the lines starting with web app: downloading guacd. The container needs HTTPS access to dl.xplicittrust.com, or a mirror (XTNA_GUACD_BUNDLE_URL). The agent tries again after 1 minute, then at growing intervals up to 30 minutes; restarting the container tries at once.

Remote desktop: "The remote desktop service is not available on the gateway."

  • guacd did not start. The agent log (/etc/XplicitTrust/logs/xtna-service.log) names the reason.

VM or container templates

  • When cloning a VM or container that has XplicitTrust installed, make sure to exclude /etc/XplicitTrust/ and /etc/xt-machine-id from the template. Each instance must have its own identity.