NAS Device States

Reference for the NAS state machine in ISP-OS. A NAS represents a MikroTik router managed through the ISP-OS control plane.

Status vs health

Persisted NAS status is stored in nas_devices.status. Heartbeat freshness is a separate UI concern.

Surface	Values	Notes
Persisted status	`pending`, `online`, `offline`, `disabled`, `removing`, `removed`	Canonical database state
UI health label	Connected, Degraded, Offline	`Degraded` is not its own database enum

Connected: router is online and the latest WireGuard handshake is 120 seconds old or newer
Degraded: router is still online, but the UI turns amber once the handshake is older than 120 seconds
Offline: the heartbeat job flips the NAS to offline only after the handshake is older than 300 seconds for 3 consecutive 10-second checks

In practice, a router turns Offline after about 5.5 minutes of sustained misses.

Important

NAS going Offline does not suspend subscribers. The management plane can fail while PPPoE sessions on the router continue normally.

Status	Meaning	WireGuard	RADIUS	Subscriber impact
Pending	Router onboarding is in progress	Peer not yet fully active for steady-state management	Not available for normal auth	No live subscriber services should depend on it
Online	Router is connected and manageable	Peer active, handshake healthy enough for service	Registered	Full provisioning and reconciliation work
Offline	Router heartbeat is stale long enough to fail liveness	Peer exists but handshake is stale	Still registered	Existing sessions continue; new management actions may pause or fail
Disabled	Admin intentionally took the router out of active management	Peer removed	Excluded	Existing sessions may continue until re-auth; new auth is rejected
Removing	Router deletion cascade is running	Peer removed during teardown	Blocked	Subscriber services are being deprovisioned or reassigned
Removed	Terminal soft-deleted state	Peer removed	Not registered	None

Pending routers also carry nas_devices.onboarding_phase.

Phase	UI meaning	Canonical route	Notes
`preflight_pending`	Inspect waiting or inspect attention	`/routers/onboarding/{router}?phase=inspect`	Runs the read-only inspect script and records network claims
`install_ready_bridge`	Bridge	`/routers/onboarding/{router}?phase=bridge`	Inspection completed; operator reviews the chosen `/29` before installation
`install_pending`	Install awaiting or install registering	`/routers/onboarding/{router}?phase=install`	Install token issued; `setup_script_fetched_at` marks the first successful fetch

For the full onboarding surface, routes, and action semantics, see Router Onboarding Reference.

Status	Allowed actions
Pending	Resume onboarding, regenerate token, restart preflight, cancel onboarding
Online	Review snapshot, capture a fresh snapshot, disable, delete, open reconciliation surfaces
Offline	Review snapshot, capture a fresh snapshot, delete
Disabled	Enable, delete
Removing	None
Removed	None

From	To	Trigger	Automated actions
Pending	Online	Router finishes install and claims successfully	Add WireGuard peer, clear claim token, stamp `claimed_at`, capture a router snapshot
Pending	Pending	Operator regenerates token or restarts preflight	Preserve or reset phase depending on action
Online	Offline	Heartbeat stale for the Offline threshold	Pause management-plane work that depends on router reachability
Offline	Online	WireGuard handshake resumes	Reconciliation can resume
Online	Disabled	Admin disables the router	Remove peer and exclude from active RADIUS use
Disabled	Online or Offline	Admin enables the router	Re-add peer and evaluate current reachability
Online	Removing	Admin deletes the router	Begin async teardown cascade
Offline	Removing	Admin deletes the router	Begin teardown without relying on live router calls
Disabled	Removing	Admin deletes the router	Same DB-side teardown path as Offline
Removing	Removed	Teardown completes	Soft-delete the router record

From	To	Reason
Pending	Disabled	There is nothing steady-state to disable yet
Pending	Offline	Router has not reached a managed online state yet
Removed	Any	Terminal state
Removing	Online	Teardown is in progress and cannot be cancelled back to service