Install the Edge Agent

The URUFI Edge Agent runs on the Linux gateway at each location. It connects outbound to Manager, receives the location's desired configuration, and runs the enabled local services: DHCP, captive access, nftables firewall enforcement, metrics, and RADIUS/EAP-TLS.

This guide uses the supplied installer. A manual systemd installation is included for operators who need to review or reproduce every step.

Before you begin

Prepare the following:

• an x86-64 or ARM64 Linux gateway using systemd;
• two network interfaces: one client-facing LAN and one internet-facing WAN;
• root or sudo access;
• outbound TCP access from the gateway to Manager port 9090;
• a planned static IPv4 CIDR for the LAN, such as 10.10.0.1/24;
• reliable system time, preferably synchronized with NTP;
• the current urufi-agent release, install.sh, and Manager CA certificate from the Network Operations Console.

The published agent is a static Linux binary. The installer supports common package managers, but it requires systemd, nft, ip, and arping.

1. Confirm the network topology

The gateway must sit between the client network and the internet:

Internet ─ ISP router ─ WAN ─ [ Linux gateway + URUFI Edge Agent ] ─ LAN ─ switch ─ access points

• LAN is the client-facing interface. The Edge Agent binds DHCP here and applies captive-access rules to traffic arriving from this side.
• WAN is the upstream interface used for internet access and NAT masquerading.
• Access points bridge client traffic to the LAN. They must not run a competing DHCP server or NAT clients behind another gateway.

The LAN address entered during setup must match the gateway of the native logical network created later in NOC. It may already be owned by the operating system, or the agent can safely assign and restore it when Manage LAN Address is enabled.

Useful checks before installation:

ip -br address
ip route
timedatectl status

Record the exact LAN and WAN interface names. Do not assume they are eth0 and eth1; modern Linux systems often use names such as enp1s0.

2. Download the release and Manager CA

In the Network Operations Console:

1. Open Settings → Agent Software.
2. Download the latest Binary and its install.sh file.
3. In Settings → Transport CA, select Download manager CA.

The CA download is named urufi-manager-ca.pem. Copy all three files to the gateway, for example:

scp urufi-agent install.sh urufi-manager-ca.pem operator@gateway:/tmp/

If your release process provides a SHA-256 checksum, verify the binary before installing it:

sha256sum urufi-agent

3. Install the agent

From the directory containing the downloaded files:

chmod +x install.sh
sudo ./install.sh
sudo install -m 0644 urufi-manager-ca.pem /etc/urufi/agent/manager-ca.pem

The installer:

• installs nftables, iproute2, kmod, arping, and ca-certificates;
• enables IPv4 forwarding through /etc/sysctl.d/99-urufi.conf;
• installs the versioned binary under /var/lib/urufi-agent/releases/, points /var/lib/urufi-agent/current at it, and keeps /usr/local/bin/urufi-agent as a compatible command symlink;
• creates /etc/urufi/agent for configuration;
• installs a restricted systemd service;
• creates a private persistent state directory for the DHCP lease journal.

It does not start the service. Registration and first-run configuration come next. Running the installer again is safe: it replaces the binary and service definition but keeps an existing config.yaml.

Install from a URL

The installer can download the binary directly when you have a trusted release URL:

sudo AGENT_BINARY_URL="https://downloads.example.com/urufi-agent" \
  AGENT_BINARY_SHA256="expected-sha256" \
  ./install.sh

Omit AGENT_BINARY_SHA256 only when your release channel does not provide a checksum. TLS protects the download in transit; a checksum also verifies the exact artifact.

Manual installation

Skip this section if you used install.sh.

Install the required packages, enable forwarding, and place the binary:

sudo apt-get update
sudo apt-get install -y nftables iproute2 kmod iputils-arping ca-certificates

echo 'ifb' | sudo tee /etc/modules-load.d/urufi-ifb.conf
sudo modprobe ifb

echo 'net.ipv4.ip_forward = 1' | sudo tee /etc/sysctl.d/99-urufi.conf
sudo sysctl -p /etc/sysctl.d/99-urufi.conf

sudo install -m 0755 urufi-agent /usr/local/bin/urufi-agent
sudo install -d -m 0750 /etc/urufi/agent
sudo install -m 0644 urufi-manager-ca.pem /etc/urufi/agent/manager-ca.pem

For dnf or yum systems, install the equivalent nftables, iproute, iputils, and ca-certificates packages. Then create this unit:

# /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=/var/lib/urufi-agent/current/urufi-agent
Restart=on-failure
RestartSec=3

AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
NoNewPrivileges=true

ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/etc/urufi/agent
StateDirectory=urufi-agent
StateDirectoryMode=0750
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictAddressFamilies=AF_INET AF_INET6 AF_NETLINK AF_PACKET

[Install]
WantedBy=multi-user.target

Reload systemd after creating the file:

sudo chmod 0644 /etc/systemd/system/urufi-agent.service
sudo systemctl daemon-reload

4. Register the gateway in the NOC

1. Open Agents in the Network Operations Console.
2. Select Register Agent.
3. Choose the organization, enter a clear agent name, and enter the gateway address you want shown in inventory.
4. Open the registered agent and copy its Agent ID and Auth Key.

The Agent ID identifies this registration. The Auth Key is the secret used to prove the agent's identity during every Manager connection.

5. Run first-time setup

Start the terminal wizard:

sudo urufi-agent initial

Use Tab and Shift+Tab to move between fields. Use Space or the arrow keys for the TLS and LAN-address-management toggles. Use the arrow keys on an interface field to cycle through interfaces detected from the kernel.

Choose who owns the LAN address

Enable Manage LAN Address on a native gateway when URUFI should own the address. Before assignment, the wizard performs an ARP duplicate-address check. It then adds the exact CIDR and records ownership in config.yaml. Every subsequent agent start restores that address if it is missing.

Leave the toggle disabled when NetworkManager, netplan, systemd-networkd, OpenWrt, or Docker already configures the address. In this mode, setup requires the exact CIDR to already exist and the agent never removes or replaces it.

The Manager host does not need to match the generated certificate's DNS name. The agent verifies the fixed URUFI Manager identity against the downloaded CA. Deployments using a custom Manager certificate can set tls.server_name manually in the generated file.

The wizard writes /etc/urufi/agent/config.yaml and exits. It does not start the systemd service. Tighten the file permissions before continuing:

sudo chmod 0600 /etc/urufi/agent/config.yaml

The generated configuration has this structure:

agent:
  id: "agent-uuid-from-the-noc"
  hostname: "cafe-downtown-01"
  manager:
    host: "manager.example.com"
    port: 9090
    reconnect_interval: 5
    heartbeat_interval: 30
    metrics_interval: 10
  auth_secret: "agent-auth-key-from-the-noc"

network:
  wan_interface: "enp1s0"
  lan:
    interface: "enp2s0"
    mode: "trunk"
    native_address: null
    manage_native_address: false
    allowed_vlan_ids:
      - "100-299"

radius:
  bind: "0.0.0.0:1812"

logging:
  level: "info"

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

The NOC cannot override physical LAN/WAN, port mode, or the allowed VLAN list. These are local safety controls from config.yaml; changing them requires an agent restart. The NOC manages only logical native/VLAN networks inside that boundary. Older dhcp and firewall blocks remain readable when they agree, but conflicting old/new topology fails startup.

6. Check configuration before starting

Confirm all of the following:

• the native LAN CIDR is present, or manage_native_address is true so the agent owns it;
• the LAN and WAN interfaces are different and their IPv4 networks do not overlap;
• the WAN has a working default route;
• no other service is listening on DHCP UDP port 67 on the LAN;
• Manager is reachable on TCP port 9090;
• every managed VLAN is carried tagged by the switch/AP uplink;
• logical network gateways and pools are in the same bounded subnet and do not overlap.

Example connectivity checks:

ip -br address
ip route
nc -vz manager.example.com 9090
sudo nft list ruleset

If nc is unavailable, use another TCP connectivity tool provided by your distribution.

7. Start and verify the agent

Enable and start the service:

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

A successful connection includes these log messages:

UFP: connecting to manager.example.com:9090 (tls=true)
UFP: authenticated with manager
UFP: received config update from manager

The agent should now appear under the NOC's Connected tab. Open its details to confirm the reported version, interfaces, status, and metrics.

When manage_native_address: true, startup first verifies that the configured LAN CIDR is safe and restores it before DHCP, firewall, or captive services can start. When it is false, a missing address is a startup error rather than an invitation to modify an OS-owned interface.

Service selection remains centrally controlled. Review the switches in the agent details and enable each service only after its network and policy prerequisites are ready.

8. Enable guest access

Before enabling HotSpot for this agent:

1. Create and converge the native or VLAN networks, including DHCP pools, DNS, MTU, and Captive portal access policy.
2. Configure the tenant's HTTPS captive destination in HotSpot.
3. Configure free-trial, OTP, package, and branding policy in the Business Portal.
4. Open Agents, select this agent, and verify its read-only LAN and WAN interfaces.
5. Enable HotSpot and save the service settings.

Enabling HotSpot also enables its required DHCP and firewall services. Connect a test device to the open SSID and verify that it receives the expected address, gateway, and DNS values before testing the portal.

9. Enable secure WiFi

Configure the central side first:

1. Open EAP-TLS → Certificates and select Initialize EAP-TLS.
2. Switch to RADIUS & SSID and save the organization's secure SSID.
3. In the same tab, add the access point as a NAS client for this Edge Agent. Enter the access point's source IP and a strong RADIUS shared secret.
4. Open the agent details, enable EAP-TLS, and save. RADIUS is enabled with it.

Then configure the access point's secure SSID:

The RADIUS shared secret authenticates the access point to the Edge Agent. Client devices use their individual EAP-TLS certificates instead of this secret.

An account must be active before it can download a device profile from the captive portal. Complete the open-SSID flow first, install the downloaded profile, and then join the secure SSID.

10. Troubleshooting

Start with the current boot logs:

sudo journalctl -u urufi-agent -b --no-pager

After editing /etc/urufi/agent/config.yaml, restart the service explicitly:

sudo systemctl restart urufi-agent

11. Upgrade or roll back

The agent reports its version and build target to NOC. Upload a verified release in Settings → Agent Software, then choose Update from the agent details. The running agent streams the candidate, verifies its size and SHA-256, confirms the candidate's reported version and architecture, installs a versioned release slot, and asks systemd to restart into it.

The process restart causes a brief packet-service interruption but does not lose durable network state. The new process restores the last-known-good snapshot before reconnecting, then reports health. If the candidate does not become healthy, the updater restores the previous current slot and restarts it.

For the first upgrade from an agent installed before managed release slots existed, run the current install.sh once with the new binary. Future releases can then use the NOC update flow.

Manual fallback is simply a verified installer rerun:

sha256sum urufi-agent
sudo ./install.sh
sudo systemctl restart urufi-agent
sudo systemctl status urufi-agent

The installer preserves /etc/urufi/agent/config.yaml and the durable state directory. Do not roll back across an explicitly incompatible release without checking its release notes and configuration requirements.