Maintenance#

Use this page to roll out agent releases and maintain an installed broker. For device access, recovery and retirement, see Operations. For a new installation, see Deployment.

Agent release rollout#

Publishing a release to GitHub or repo.exordos.com/exordos_nac does not open it to a deployment's devices. The operator stages the files and controls the broker's rollout cohort.

Stage and validate#

1. Download a versioned release, including installers, SHA256SUMS and the signed release.yaml. Avoid a moving latest path during staging.
2. Check the checksums, then validate the manifest using the release public key:

sha256sum -c SHA256SUMS
exordos-nac-broker release check release.yaml --public-key release.pub

1. Put installer files under /var/lib/exordos/exordos_nac/releases/ on the broker. The shipped nginx snippet serves them at https://<broker>/releases/<file> without a client certificate.
2. Keep the manifest outside that public directory, for example at /etc/exordos_nac/release.yaml, with share: 0 and enforcer_share: 0. Point the broker at it:

[nac]
agent_release_file = /etc/exordos_nac/release.yaml

1. Confirm broker_endpoints covers each enforced network and devices can fetch the files through those endpoints. A manifest's file is resolved against the broker endpoint the device is using. Without configured endpoints, such artifacts cannot be offered.

Keep the release version, platform, package format, digest and signatures from the published manifest. Changing cohort shares or package locations does not require signing again. An absolute artifact url is also supported; a separate host needs routes, policy access and TLS trust on every relevant network.

Open a cohort and observe#

Raise share gradually, for example 0.10, 0.25, then 1.0. Each device's cohort position is stable and derived from its UUID. After each increase:

exordos-nac-broker release status
exordos-nac-broker device versions

Compare arrived devices with the reachable cohort; offline machines cannot install an offer. Check successful proofs and access on upgraded devices before widening. Stop new offers by setting share: 0 or removing the manifest. There is no automatic health-based pause or automatic rollback; an already queued installation may still finish.

A released agent carries the public key needed to verify offers and applies updates by default. To opt a device out of installation while retaining offer reporting:

exordos-nac-agent configure --apply-updates=false

The agent installs after a successful proof, verifies the signature and download digest, and restarts through its service manager. A version gets at most three attempts, at least an hour apart. Inspect status for an unchecked, unsupported, failed or installed offer. Converted packages may report the wrong format; install the native package once to correct it. For agents too old to report format, set [nac] default_package_format to the fleet's deb, rpm or archlinux format.

macOS uses the package's root update helper, which verifies the offer again. A Mac on agent 0.0.7 or earlier needs one manual or MDM upgrade to a release with the helper. Its last decision appears in status as update helper; MDM may pre-approve its background item with com.apple.servicemanagement.

Gateway and manual device upgrades#

Enforcement points run enforce, not prove, and receive no update offers. Upgrade gateways one at a time and check enforcement after each:

dpkg -i exordos-nac-agent_<version>_amd64.deb   # Or rpm -U / pacman -U.
systemctl status exordos-nac-agent-enforce

Linux packages restart an active enforce unit. When upgrading a proving device by hand, also run systemctl restart exordos-nac-agent-prove: package scripts leave that unit running to avoid interrupting an agent-driven transaction. After a manual Windows MSI upgrade, run sc start exordos-nac-agent; the installer stops the service and does not start it. The agent-driven update path handles its own restart.

enforcer_share defaults to zero. It only controls devices tagged role:enforcer that also prove; it does not deliver updates to enforce-only gateways.

Intentional rollback#

A device newer than the target is offered nothing. To authorize a downgrade, sign the older release with rollback_from naming the newest version it may replace. Run signing on the release machine, not the broker:

# In exordos_nac_agent; dist contains the rollback installers.
go run ./cmd/release-sign -version <older-version> -rollback-from <newest-replaced-version> -dist dist -key release.key

Alternatively, add rollback_from to a custom manifest and sign it with exordos-nac-broker release sign release.yaml --key release.key on that machine. The bound prevents a signed rollback from downgrading later releases. Agents predating rollback support reject the signature. Windows MSI cannot replace a newer version; use a managed uninstall/install or publish the corrected code under a newer version. Native installer restrictions still apply.

Release keys for custom builds#

The official release key is embedded in published agents. Only custom-build maintainers need to provision their own key pair:

openssl genpkey -algorithm ed25519 -out release.key
openssl pkey -in release.key -pubout -out release.pub

In exordos_nac_agent, store the public key in the RELEASE_PUBLIC_KEY repository variable and the private key in the RELEASE_PRIVATE_KEY secret of the release environment. Restrict that environment to release tags and required reviewers. Keep a recoverable private-key backup outside GitHub. The tag build checks that the keys match and publishes the signed manifest with installers.

Keep the private key off the broker. A custom agent may use configure --release-key <public-key-file> to override its built-in key. Losing the private key requires distributing a new trusted public key to existing agents; the broker cannot authorize that change. For signature fields and trust boundaries, see agent updates.

Broker backup and restore#

Back up these together at a consistent point, with protected storage appropriate to the secrets they contain:

Keep policies and non-secret deployment files under version control. Store the CA key backup under secret-storage controls, separately from database dumps. Losing the original CA or device records can require fleet re-enrollment. Keep release-signing key backups separate from the broker backup.

Track the device CA expiry printed at broker startup and by init-ca. Its default lifetime is ten years. There is no automatic CA rotation; plan the manual replacement and fleet enrollment transition before expiry. Do not generate a new CA over an existing installation as a backup recovery step.

Set NAC_DB_BACKUP_DIR to the database backup destination and NAC_SECRET_BACKUP_DIR to separate protected secret storage. The configuration archive contains the CA private key; write it directly to that storage:

pg_dump --format=custom "$DATABASE_URI" > "$NAC_DB_BACKUP_DIR/nac-$(date +%F).dump"
tar -C /etc -czf "$NAC_SECRET_BACKUP_DIR/nac-config-$(date +%F).tar.gz" exordos_nac

Include TLS files stored outside that directory and separately save deployment configuration. Rehearse restoring both data and configuration before relying on the backup. Before restarting the broker, restore the installers referenced by the manifest and verify their checksums. If they are unavailable, set both share and enforcer_share to zero until the files have been staged again:

systemctl stop exordos-nac-broker-api
pg_restore --clean --if-exists --dbname "$DATABASE_URI" <database-backup>
tar -C /etc -xzf <configuration-backup>
# Restore staged installers, or close both rollout cohorts in the manifest.
systemctl start exordos-nac-broker-api

Restore matching schema/code and nginx configuration, including server TLS trust. Devices whose identities and original CA were restored can resume proofs; lost sessions are rebuilt. Reconcile all blocks and deletions made after the backup: old data can bring those devices back. Keep that change record outside the backup being restored.

Broker upgrades#

Take a database and configuration backup first. Rehearse policy and schema changes on a copy. Use the broker's installation virtualenv:

systemctl stop exordos-nac-broker-api
pip install --upgrade './exordos_nac-<version>-py3-none-any.whl[attestation]'
ra-apply-migration --config-dir /etc/exordos_nac/ --path "$(exordos-nac-broker migrations-path)"
exordos-nac-broker policy check /etc/exordos_nac/policy.yaml
systemctl start exordos-nac-broker-api

Verify device proofs, gateway pulls and resource access afterwards. Session and nftables lifetimes are separate: available downtime depends on their remaining leases. Once access expires, devices recover through successful proofs after the broker and gateways return.

Compatibility with older installations#

Apply these checks when crossing the corresponding feature boundary:

Do not infer schema rollback from reinstalling an old wheel. Use the migration and backup plan for the specific version boundary.

Retention#

Set limits in /etc/default/exordos-nac-broker:

NAC_SESSION_RETENTION_DAYS=90
NAC_AUDIT_RETENTION_DAYS=400
NAC_TOKEN_RETENTION_DAYS=30

These are examples, not defaults. Unset limits keep all records. The daily prune timer applies them; spent and expired tokens are eligible, live tokens are not. Preview deletion first:

exordos-nac-broker session prune --older-than 90 --dry-run
exordos-nac-broker audit prune --older-than 400 --dry-run
exordos-nac-broker token prune --older-than 30 --dry-run

The reap timer closes expired sessions every five minutes. Enforcement does not wait for housekeeping: gateway elements have their own timeouts. Audit events retain device snapshots after device delete until their retention removes them.