Operations after installation#
This page covers enrolled devices and the network that enforces their access.
For installation and initial enrollment, see Deployment.
Broker commands below run on the broker; agent commands run on the device.
Replace <device> with the UUID shown by device list or the agent's status.
Use an administrator session on Linux and Windows when reading protected state
or changing enrollment. On macOS use the enrolled user's session.
Check the first working session#
On the device:
Check the device UUID, certificate expiry, broker address, last proof and next
proof time. On Linux the exordos-nac-agent-prove service must keep running;
Windows uses the exordos-nac-agent service. On macOS the LaunchAgent runs in
the enrolled user's session: run status as that user, without sudo.
On the broker:
Confirm the expected tags, claimed and verified key protection, source address, grants and recent events. Then test an allowed resource and a forbidden one from the device. A successful proof records the broker's decision; the gateway still has to apply it, and traffic must pass through that gateway. Use the per-network verification procedure to check that path.
What changes during a device's life#
The device_uuid identifies an enrollment, not an IP address or a certificate.
It stays the same during normal certificate renewal, network changes and agent
upgrades. On macOS, each enrolled user account has its own identity.
| Situation | Broker record and access | Operator action |
|---|---|---|
| Enrolled, not yet proven | The record is ACTIVE; enrollment alone grants no corporate resources. |
Start the proof service and check its first decision. |
| Working normally | Proofs refresh the network session; the gateway installs grants with expiry timers. | Monitor decisions, certificate renewal and gateway health. |
| Disconnected or powered off | The record remains ACTIVE; sessions and installed grants age out. |
Reconnect and let the running agent prove again. |
| Policy requirements not met | An ACTIVE device can receive fewer grants or none. |
Read the failed checks and fix their cause. |
| Blocked | The record is BLOCKED; authenticated operations are refused and grants disappear from fresh gateway state. |
Investigate; unblock only when the device is allowed back. |
| Key lost or certificate expired | The existing enrollment cannot authenticate. | Register again with a new token and a new UUID; retire the old record separately. |
| Retired | The operator blocks or deletes the broker record and removes local identity material. | Keep the audit history according to retention policy. |
ACTIVE means the broker permits the identity to authenticate with a valid
certificate. It does not mean
that the device is online, compliant or currently has network access.
Normal operation and the three lifetimes#
Keep the agent running after enrollment. prove --loop refreshes the device's
network session and renews its certificate when due. An enforcement gateway
runs enforce, which also renews its own certificate.
| Mechanism | Default lifetime | How it is maintained |
|---|---|---|
| Device certificate | 60 days | Renewal with the same key starts at renew_after, normally after 40 days. |
| Broker session | 15 minutes after the latest decision | Repeated session proofs. |
| Gateway grant | 15 minutes after its last installation or refresh | Successful gateway state application. |
A normal device proves again at roughly two thirds to three quarters of its lease. Certificate renewal keeps the identity usable; session proofs keep access current. These are separate operations.
For fleet checks:
exordos-nac-broker device list --stale 24
exordos-nac-broker device list --verified software
exordos-nac-broker device versions
exordos-nac-broker release status
Treat stale records as investigation candidates, not automatic deletion targets.
last_seen uses the device record's update time, which operator changes also
advance; compare it with session and audit timestamps. Verified level software
does not by itself establish a fault: macOS has no server-verifiable Secure
Enclave attestation. Compare protection levels with the requirements for that
device class.
Switching networks or returning after an outage#
The agent uses the source address visible to the broker for a session. On a network change it checks the attachment and proves again; successful proof from a new address closes the device's old attachment. No new enrollment is needed while its key and certificate remain usable.
VPN or wireless connectivity must come up independently. The device then needs an address in an enforced range and a reachable broker endpoint. During recovery the agent spreads the first proof across a fixed three-second window derived locally from its UUID. It retries while the network or broker is unavailable.
During a broker outage the gateway does not reinstall cached grants. Installed elements expire within their lease after the gateway's last successful refresh, not necessarily after the device's last proof. Kernel element expiry restricts originating traffic, but immediate termination of all tracked reply traffic also depends on conntrack cleanup in the gateway's application loop. See the three lifetimes.
When connectivity returns, the running agent retries with its existing identity. Check certificate expiry before assuming that a long absence is only a network problem.
Changing access and responding to posture failures#
Policy uses operator-assigned tags and the device's measured signals. An owner is retained for attribution; changing IAM group membership does not by itself change NAC grants.
For an ordinary device, change one tag without replacing unrelated tags:
exordos-nac-broker device tag-remove <device> dept:engineering
exordos-nac-broker device tag-add <device> dept:support
The values must match your deployment's policy. device tag replaces the entire
tag set. A change to tags or posture takes effect through the next session
decision; it does not immediately recompute all existing grants. Use blocking
when access must be withdrawn during an investigation.
The agent's status shows failed checks and the policy's fix text, when supplied.
Inspect the corresponding decision and events before changing policy just to
make the device pass.
A legitimate firmware, kernel or Secure Boot change can produce
boot_chain_changed. After verifying the expected update and device integrity:
This clears the old boot-chain pin; the next verified quote establishes the new one. It does not restore lost keys or override other policy checks. The command asks for confirmation and records the operator's decision.
Blocking and allowing a device back#
For a lost device, suspected compromise or temporary access suspension:
The broker refuses further authenticated requests, including certificate renewal and update offers. A working gateway withdraws grants after receiving fresh state, normally on its three-second polling cadence. If it cannot reach the broker, existing element timers and the limits described above apply. The policy's bootstrap path remains available; blocking does not disconnect the VPN or wireless network.
After resolving the reason for blocking:
The record becomes ACTIVE, and access requires another successful proof.
Unblocking preserves the UUID and history; it cannot repair an expired
certificate or a missing key. Revoking an unused enrollment token prevents that
token from being spent and does not block a device that already enrolled.
Certificate expiry, key loss and reinstallation#
The agent retries a failed renewal while its current certificate is still valid. If it expires, renewal cannot authenticate with it. Clearing the TPM, losing local state or losing access to the user's keychain can also make the old identity unusable.
- Record the old UUID and inspect its sessions and audit events.
- Block the old record if it should no longer have access.
- Fix the keystore problem and obtain a new enrollment ticket with the intended owner and tags.
- Reset local enrollment state and enroll again:
- Verify the new UUID, first proof and gateway enforcement. Keep or delete the old record according to your incident and retention requirements.
reset destroys the local enrollment. Check its output: deletion of key material
is best effort, and a cleanup failure is reported. The new device does not inherit the old
UUID, certificate history or pinned keys. A hardware fingerprint cannot authorize
a replacement key for the old UUID. --require-hardware refuses a software
fallback; use the enrollment settings approved for that device class.
Replacing the agent package alone normally preserves identity. An OS reinstall that removes state or its keystore does not. Package removal, purge and macOS uninstallation have different effects; check the removal procedure before removing them.
Updating agents#
Agent packages and documentation archives are available in the
public release mirror.
Each tag directory carries SHA256SUMS and the signed release.yaml;
latest/VERSION identifies the current mirrored release. Publication does not
open a rollout in your deployment.
Stage the selected release on the broker, verify it, then expand the rollout
cohort gradually. Watch release status, device versions and the device's
status, including signature trust and installation errors. A device needs
apply_updates enabled and a trusted release key to install offers. The broker
distributes releases but does not hold their private signing key.
Enforcement gateways are upgraded by the operator: they run enforce rather
than the proof loop that consumes offers. Verify gateway service and enforcement
after the upgrade. Follow the rollout procedure
for staging, pauses, signed rollback and platform-specific restart behavior.
Investigating access problems#
Collect the UUID, current source address and approximate failure time first.
On the device, run status in the correct account and inspect its service log.
On the broker:
exordos-nac-broker device show <device>
exordos-nac-broker session list --device <device>
exordos-nac-broker audit list --device <device> --since 12h
exordos-nac-broker session who <address>
| Observation | Check next |
|---|---|
waiting for network or unreachable broker |
VPN, routes, source address, enforced range, broker endpoint and TLS trust. |
device_blocked |
The block's reason and whether unblocking is authorized. |
device_unknown |
Whether the record was deleted or lost in a database restore. |
| Expired certificate or unusable key | Renewal errors and keystore health; follow the new-enrollment procedure when identity is lost. |
| Failed checks or fewer grants | Policy decision, measured signals, assigned tags and the displayed remedy. |
| Successful proof, resource still unreachable | Gateway polling and service health, grants, nftables, routes and address conflicts. |
The saved last-proof report is a snapshot, not proof of current gateway state. Check its time and next-proof deadline. Avoid resetting a working identity to diagnose a routing or policy problem. See protocol errors for the response codes.
Recover a stale network plan#
If broker endpoints or gateway ranges were wrong, correct them on the broker first. Once failures have lasted 30 seconds, the next proof attempt uses the broker URL in local configuration instead of its cached attachment plan. A successful proof refreshes that plan. To try immediately from the device:
Use a reachable, trusted broker endpoint. Check device enforces <gateway>
--set <segment> and broker_endpoints rather than resetting the device key.
Logs and durable audit#
The broker emits NAC AUDIT: <event> <ok|failed> device=<uuid> addr=<ip>
reason=<code> ... to stdout/stderr. Under the shipped service, read it in the
journal:
Successes are INFO and refusals WARNING. Ship this stream to the deployment's
monitoring system; audit list reads the separate durable database trail for
investigating a device. Client certificates rejected by nginx never reach the
broker: also inspect nginx's error log for TLS verification failures.
Taking a device out of service#
Block the broker record before wiping or handing over the device. Stop its agent and reset local identity in the account that owns it. Then remove the package using its platform-specific procedure. On macOS, the supplied uninstall script performs reset and removes the agent; each other enrolled account needs its own key cleanup.
| Platform | Removal and identity |
|---|---|
| Debian/Ubuntu | dpkg -r exordos-nac-agent keeps identity; dpkg -P exordos-nac-agent destroys state and configuration. |
| RPM / Arch | rpm -e exordos-nac-agent / pacman -R exordos-nac-agent keep identity; run reset first when retiring it. |
| Windows | msiexec /x <installer.msi> keeps ProgramData state; run reset first. |
| macOS | Run sh "/Library/Application Support/exordos_nac/uninstall.sh" in the owning user's session, without sudo; it requests elevated rights for machine-wide cleanup. |
reset clears local identity, not configuration or the broker record. On macOS,
perform key cleanup in each enrolled account before removing the bundle: only
that account can delete its keychain key. Normal package upgrades retain identity.
For a handover to another owner, use the new-enrollment procedure with a ticket issued for that owner after removing the previous identity.
Keep a blocked record while it is needed for investigation. When the record itself should be removed:
Deletion asks for confirmation and removes the record, its certificates and
sessions. Audit events retain their device snapshots until audit retention
removes them. The device is not remotely wiped: a certificate left on it can
still pass nginx TLS verification until expiry, but the broker refuses it as
device_unknown.
Keep the database, device CA and deployment configuration recoverable. After restoring an older backup, reconcile blocks and deletions made after that backup: restoration can bring those records back. See backup and retention.