Operate URUFI from edge to subscriber
The practical entry point for installing gateways, creating networks, and composing access policy in URUFI.
URUFI is a software-defined access platform. Central services hold desired network and business state; a native Edge Agent turns each Linux gateway into the local DHCP, firewall, bandwidth, captive-access, and EAP-TLS enforcement point.
Client packets do not cross the cloud. The gateway keeps enforcing its last known good state when the control plane is temporarily unavailable.
Architecture at a glance
| Component | Authority |
|---|---|
| NOC | Agents, logical networks, firewall, bandwidth profiles, service classes, EAP, releases, and operational state |
| Business Portal | Packages, PIN inventory, subscribers, free-trial policy, and captive branding |
| Core API | Account entitlement, activation, plan ownership, PIN redemption, OTP, and durable device-state delivery |
| Manager + Controller | Authenticated control plane between NOC/Core and connected agents |
| Edge Agent | Local address allocation and kernel enforcement through DHCP, nftables, tc, IFB, captive bootstrap, and RADIUS |
Keep the layers separate
URUFI deliberately separates where a device connects, what it purchased, and how its traffic is treated.
| Layer | Object | Meaning |
|---|---|---|
| Physical topology | Agent local config | LAN parent, WAN uplink, access/trunk/hybrid mode, allowed VLANs |
| Logical addressing | Edge network | Native/VLAN attachment, CIDR, gateway, MTU, DNS, DHCP pools, access mode |
| Technical policy | Service class | Optional bandwidth profile plus service-scoped firewall behavior |
| Business entitlement | Package and account | Product, duration, payment/free state, expiry, and effective service class |
A DHCP pool never represents a package. The receiving network assigns the address before the portal knows what a subscriber will buy. Entitlement changes authorization and policy membership without forcing the client onto another IP or VLAN.
Captive access flow
- The client joins an untagged or VLAN-backed network and receives a locally durable DHCP lease from the edge.
- An unauthorized client can reach only the captive listener and configured walled garden. Ordinary HTTP is redirected locally.
- The edge maps source IP to its own current lease, derives the router-observed MAC, and asks Manager for a signed portal session.
- Core verifies the signed tenant/MAC context and processes login, free trial, or PIN.
- The entitlement and durable outbox commit before success is returned.
- Manager delivers the current device state; the edge atomically updates authorization and service-class membership.
URUFI does not intercept HTTPS. Captive detection starts with HTTP and redirects to the real HTTPS portal.
Desired state and convergence
Saving a NOC form commits desired state. It does not prove the kernel accepted it. For network policy, the agent validates the full snapshot, applies interfaces, firewall, DHCP, captive, and shaping as one transaction, verifies runtime state, persists its last known good snapshot, then acknowledges the exact revision and checksum.
| Status | Meaning |
|---|---|
| Pending | Desired state exists but the connected edge has not acknowledged it |
| Failed | The edge rejected or could not apply the candidate; the previous good state remains |
| Converged | Desired and applied revision/checksum match after runtime verification |
Treat Converged as the completion condition. A structured apply error identifies the failed boundary, such as VLAN permission, subnet overlap, active-lease safety, root-qdisc ownership, or unavailable interface.
Local continuity is intentional
The edge restores its checksum-validated last-known-good network, lease, firewall, authorization, and shaping input at boot. Reconnection sends a complete current snapshot, so a missed transient event does not become permanent drift.
Failure boundaries
| Unavailable component | Continues locally | Waits for recovery |
|---|---|---|
| Manager connection | Current leases, expiry enforcement, firewall, shaping, and EAP material | New portal sessions and uncached central classification |
| Controller API | Manager-to-agent runtime | NOC changes and immediate Core control-plane calls |
| Core API | Existing access and NOC operations | New portal activation, PIN redemption, and profile download |
| One Edge Agent | Other sites and central business state | Packet services only at that site |
Recommended first deployment
- Install and enroll the Edge Agent.
- Enable the required edge services.
- Create and converge the site's networks.
- Author and test firewall policy.
- Create bandwidth profiles.
- Compose service classes and select them from Business Portal packages.
- Activate one test client and verify DHCP, captive access, expiry, firewall, download, upload, reconnect, and agent restart before onboarding the site.
The documentation is English-only so operator terminology, screenshots, error codes, and support procedures remain consistent across every deployment.