Install the Edge Agent

The Edge Agent is a DHCP server, NAT gateway, firewall and RADIUS/EAP-TLS authenticator in one static binary. It runs natively on the site's gateway box and dials home to the Manager over an outbound TLS connection — so a site behind NAT needs no public IP and no inbound firewall rules.

There are two ways to install it: the automatic installer (recommended) or a manual setup.

1. The box must be the gateway

The agent hands out DHCP leases and enforces the walled garden, so it must sit inline as the site's gateway with two interfaces:

Internet ─ [ISP modem] ─ WAN(eth0) ─ [ EDGE BOX · urufi-agent ] ─ LAN(eth1) ─ switch ─ WiFi APs
                                                                                        (Open + Secure SSID)

• LAN — the DHCP interface. Clients get their lease here and the captive redirect fires here.
• WAN — the uplink, masqueraded out.
• Access points are dumb bridges broadcasting the SSIDs. For the secure SSID they point RADIUS at the agent's LAN IP.

Hardware. A small 2-NIC mini-PC (for example an Intel N100 with dual LAN) running Debian or Ubuntu is plenty for one site.

2. Get the files

Sign in to the Network Operations Console → Agents and Download agent to get the urufi-agent binary — a static x86-64 Linux build with no dependencies. The install.sh script ships with your URUFI deployment (deployment/install.sh); it's generic and doesn't change between agent versions. Copy both to the edge box.

3. Install

Option A — Automatic (recommended)

Copy install.sh and the urufi-agent binary to the box (side by side) and run:

sudo ./install.sh

The installer does everything the agent needs on a fresh Linux box:

• installs nftables and ca-certificates,
• enables IPv4 forwarding (/etc/sysctl.d/99-urufi.conf),
• installs the binary to /usr/local/bin/urufi-agent,
• creates /etc/urufi/agent/ for configuration,
• installs and reloads the systemd unit.

It does not start the agent — you register and configure it first (steps 4–6).

Option B — Manual

If you'd rather not use the installer, do the same steps by hand.

# 1. Dependencies
sudo apt-get install -y nftables ca-certificates   # or: dnf / apk

# 2. Enable IPv4 forwarding (the agent is the NAT gateway)
echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-urufi.conf
sudo sysctl -p /etc/sysctl.d/99-urufi.conf

# 3. Install the binary
sudo install -m 0755 urufi-agent /usr/local/bin/urufi-agent

# 4. Configuration directory
sudo mkdir -p /etc/urufi/agent && sudo chmod 750 /etc/urufi/agent

Then create the systemd unit below and run sudo systemctl daemon-reload.

The systemd unit

Both options install this unit. It runs the agent with only the capabilities it needs (raw DHCP sockets, nftables, the privileged RADIUS port) and sandboxes everything else:

# /etc/systemd/system/urufi-agent.service
[Unit]
Description=URUFI Edge Agent (DHCP · RADIUS/EAP-TLS · firewall)
Documentation=https://urufi.net/docs
After=network-online.target nftables.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/urufi-agent
Restart=on-failure
RestartSec=3

# Only the capabilities the agent actually needs
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
NoNewPrivileges=true

# Sandboxing
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/etc/urufi/agent
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_PACKET

[Install]
WantedBy=multi-user.target

The agent finds /etc/urufi/agent/config.yaml automatically — no working directory or arguments required.

4. Register the agent in the NOC

In the Network Operations Console → Agents, add an agent for the site. Open its detail panel and copy the Agent ID and Auth Key — the first-run wizard needs both. This is also where you later toggle the agent's services and restart it.

5. First-run setup

Copy the Manager's CA certificate to the box (needed for the TLS link):

scp you@manager:/path/to/ca.pem /etc/urufi/agent/manager-ca.pem

Then run the first-run wizard, which writes /etc/urufi/agent/config.yaml:

sudo urufi-agent initial

Fill each field (use Tab / Shift+Tab to move, Backspace to edit, Space to toggle TLS):

The wizard produces a config like this:

# /etc/urufi/agent/config.yaml
agent:
  id: "…Agent ID from the NOC…"
  hostname: "cafe-downtown-01"
  auth_secret: "…Auth Key from the NOC…"
  manager:
    host: "manager.example.com"   # must match the server certificate
    port: 9090
    reconnect_interval: 5
    heartbeat_interval: 30

dhcp:
  interface: "eth1"               # LAN side
  server_ip: "10.10.0.1"

radius:
  bind: "0.0.0.0:1812"

firewall:
  lan_interface: "eth1"
  wan_interface: "eth0"           # masqueraded uplink

tls:
  enabled: true
  ca_cert: "/etc/urufi/agent/manager-ca.pem"
  server_name: "manager.example.com"

logging:
  level: "info"

You can change the interfaces later from the NOC — these are just the first-run seeds.

6. Start and verify

sudo systemctl enable --now urufi-agent
journalctl -u urufi-agent -f

The agent connects to the Manager and, in the NOC, turns online. Then enable its services from the agent's panel — DHCP, RADIUS, EAP-TLS, firewall — and, for secure WiFi, initialize the tenant EAP certificate authority. The Manager pushes the EAP server certificate, client CA and CRL down automatically.

7. Point the access point at the agent (secure SSID)

Access happens over two SSIDs:

• Open SSID — the captive-portal network. The access point just bridges it to the agent's LAN; no RADIUS is involved.
• Secure SSID — WPA2/WPA3-Enterprise (802.1X). The Edge Agent is the RADIUS server, so the access point authenticates devices against the agent.

To wire up the secure SSID:

1. In the NOC, register the access point as a RADIUS client (NAS) and set a shared secret.
2. On the access point, create the secure SSID as WPA2/WPA3-Enterprise and set:

Devices authenticate with EAP-TLS using the per-device certificate they downloaded from the captive portal. The agent's RADIUS verifies each certificate against the tenant's certificate authority — there is no shared WiFi password.

8. Upgrades

The agent is a single binary, and its configuration is untouched by upgrades:

sudo install -m 0755 urufi-agent /usr/local/bin/urufi-agent
sudo systemctl restart urufi-agent

Roll back by restoring the previous binary and restarting. See the System Overview for how the agent fits into the platform.