Multi-WAN sites

Experimental: this setup depends on the configuration of the site's network. It has not been tested beyond the example below.

At a multi-WAN (wide area network) site, a router combines several Starlink terminals into one network. Every terminal answers at 192.168.100.1 on its own connection. A Nexus Telemetry Fleet collector runs in Docker for each terminal, on that terminal’s virtual local area network (VLAN).

Requirements

Requirement Detail
Switch A managed switch with each terminal’s cable on its own VLAN
Router Each terminal’s VLAN also reaches its WAN on the site’s router, through an access port to each WAN port or a trunk to VLAN-tagged WAN interfaces
Trunk 1 switch port with every terminal VLAN tagged, cabled to the collector host
Terminals In bypass mode. A terminal behind its own Starlink router requires a different container setup. That setup is not tested
Host A Linux host with Docker and Docker Compose. Checked with Docker Engine 29.8 and Docker Compose 5.5
Fleet server The host reaches the fleet server over its own network, through the site’s router
Token 1 enrolment token with Max uses at least the number of terminals, from the Add telemetry collector window. See Tokens for many collectors for a token with more than one use. To place every collector in the site’s group, set Group when generating the token. See Groups for group membership

Router modes

Each collector reads its terminal on the terminal’s VLAN, before the router. Load balancing, failover and bonding make no difference to the readings. The collector reads a terminal on standby in the same way as an active one. When no connection is available, each collector keeps reading its terminal. It sends the readings when a connection is available again.

Unsupported setups

The setup does not work for:

  • Terminals joined to the router over Wi-Fi, or with no Ethernet port.
  • Terminals cabled straight into the router with no switch. Insert a managed switch first.

Container

Each terminal has 1 container. It joins the terminal’s VLAN and the Docker network out, which reaches the fleet server through the host. At start, it sets 192.168.100.2 on the VLAN as root with NET_ADMIN. On that VLAN, 192.168.100.1 reaches that terminal only. The container then drops every capability and runs the collector as the unprivileged user nexus. A restart sets the address again.

Docker refuses two networks on the same subnet. The Compose file creates the VLAN networks with no Docker addressing, enable_ipv4: false. The container sets the address itself.

Compose file

The file covers 2 terminals. For each further terminal, add a service, a VLAN network and a volume with the next number.

yaml
name: nf-multi

x-collector: &collector
  image: registry.nexustelemetry.com/nf-collector:latest
  restart: always
  env_file: collector.env
  user: root
  cap_add: [NET_ADMIN]
  entrypoint: ["sh", "-c", "ip addr add 192.168.100.2/24 dev terminal && exec setpriv --reuid=nexus --regid=nexus --init-groups --inh-caps=-all --bounding-set=-all nf-collector"]

x-vars: &vars
  NF_SERVER: <your-address>
  NF_SOURCES: starlink,ping

services:
  t1:
    <<: *collector
    networks:
      out: {}
      vlan101: { interface_name: terminal }
    environment: { <<: *vars, NF_DEVICE_NAME: Terminal 1 }
    volumes: ["t1-data:/var/lib/nexus-fleet"]

  t2:
    <<: *collector
    networks:
      out: {}
      vlan102: { interface_name: terminal }
    environment: { <<: *vars, NF_DEVICE_NAME: Terminal 2 }
    volumes: ["t2-data:/var/lib/nexus-fleet"]

networks:
  out: {}
  vlan101: { driver: macvlan, enable_ipv4: false, driver_opts: { parent: eth0.101 } }
  vlan102: { driver: macvlan, enable_ipv4: false, driver_opts: { parent: eth0.102 } }

volumes:
  t1-data: {}
  t2-data: {}

Save the token in collector.env.

bash
NF_TOKEN=<token>
Value Set it to
parent The host’s trunk interface and the terminal’s VLAN ID, for example eth0.101. Docker creates the VLAN interface
<your-address> The fleet server’s address, as in the Add telemetry collector window
NF_DEVICE_NAME The terminal’s name on the dashboard. Required, because a token with more than one use names no terminal
<token> The enrolment token. Every collector enrols with it and receives its own device certificate

NF_SOURCES leaves out the connection source. Every collector in this setup connects out through the host. The connection source would describe the site’s connection, not the terminal’s. See Collector configuration for NF_SOURCES.

Run

  1. Save the Compose file as compose.yaml, in one folder on the host with collector.env.

  2. Start the containers in that folder.

    bash
    docker compose up -d

Each terminal appears on the dashboard as its own collector.

Warning: each volume holds that collector’s device certificate. A collector whose volume is deleted enrols as a new collector with a new record.

Readings per terminal

Reading Per terminal
Terminal status, history and obstructions Yes
Ping to the terminal Yes
Ping to the gateway No. Gateway in Reachability reaches the Docker network’s gateway, not the site’s router
Ping to the internet No. It uses the connection the site’s router chooses
On backup state Not reported

Update

To update, pull the new image in the folder and start the containers again. The dashboard cannot update a container. Each collector starts from the device certificate in its volume and reconnects to the same record with the same history.

bash
docker compose pull
bash
docker compose up -d

Remove

To run the collectors again later on this host, stop and remove the containers and networks. Docker keeps the volumes. The collectors reconnect to the same records when they start again.

bash
docker compose down

Purge

To remove a site permanently, decommission each collector on the dashboard first, while it is online. See Retire and revoke for decommissioning. Then remove the containers and the volumes.

bash
docker compose down -v