Architecture

Central control, local enforcement.

How desired state reaches a site, what the Edge Agent is allowed to refuse, and what keeps running when a component fails.

Planes

Three planes with different authority.

URUFI separates commercial decisions, network intent, and packet enforcement. Each plane owns decisions the others must not make.

URUFI control plane
identity · entitlement · policy · desired state · releases
Access decisionsnftables firewallService classesVLAN networksDHCP poolsEAP-TLS and RADIUSCaptive accessDurable edge state
Authenticated Edge Agent on each Linux gateway
desired state delivered · validated locally · exact revision acknowledged
Responsibilities

Two workflows, separated permissions.

Network teams decide how a site operates. Business teams decide who receives access. Neither needs the other's console area.

Network operations

Owns networks, edge services, and technical policy.

  1. 01Create client networks, VLANs, DHCP pools, gateways, DNS, and MTU
  2. 02Define firewall rules and reusable upload and download tiers
  3. 03Send one versioned configuration to the selected gateway
  4. 04The Edge Agent validates the change, applies it, and confirms the exact revision

Business access

Owns subscribers, plans, PINs, trials, and organization branding.

  1. 01Create an access plan and choose the service class it receives
  2. 02Grant access through an account, PIN, trial, or trusted-device credential
  3. 03Entitlement and expiry are delivered to the correct site
  4. 04Access applies or revokes automatically, with no network settings exposed

At each site the Edge Agent validates and applies VLAN, DHCP, firewall, captive access, RADIUS, MTU, and bandwidth policy as one transaction, then verifies the result before reporting success. The Linux gateway itself stays in the packet path and enforces the resulting kernel state.

State

Four kinds of state, never confused.

"Saved" is not "running". URUFI keeps these separate so the console can tell you which one you are looking at.

Desired state

What an operator committed centrally, identified by a revision and a checksum. Saving a form commits desired state and nothing more — it does not make it live.

Applied state

The exact desired generation an authenticated gateway reported it reconciled and persisted. A database write or a delivered message never advances it.

Runtime and observed state

What the kernel currently holds — interfaces, nftables sets, qdiscs, DHCP leases — and what the gateway reports about it. Use it to diagnose; never treat it as authority for a change.

Last-known-good state (LKG)

The most recent complete configuration the gateway validated, applied, verified, and persisted, so it can keep running when a new one cannot be applied. A candidate that fails any of those steps does not replace LKG.

Treat converged as the completion condition: desired and applied revision and checksum match after the gateway verified runtime state. Pending means the gateway has not acknowledged. Failed names the boundary that rejected the candidate, and the previous good state stays in force.

Failure boundaries

What keeps working when something breaks.

There is no single fail-open or fail-closed rule. Each component has a defined boundary, and offline continuity never extends a lease, authorization, certificate, or licence past its original lifetime.

UnavailableContinuesWaits for recovery
Platform connection Last validated configuration, unexpired leases, firewall, bandwidth, and EAP material New central lookups, signed captive sessions, and configuration updates
Central database Every edge service already applied New transactions and fresh central queries
Controller API Platform-to-gateway runtime Console commands and immediate central delivery
One gateway Every other site, and all central business state Packet services at that site only
An invalid configuration The previously validated state at that site The rejected revision, with the failed boundary reported

Implementation detail lives in the documentation

Protocol internals, revision and checksum handling, lease journals, nftables composition, and the full recovery matrix are documented for operators.

Read the operator documentation