Deploying#
Order: broker → policy → gateway → devices → routes → verification. Use IPv4 segments without source NAT; route protected resources through their NAC gateway. See network requirements.
1. Broker#
Deploy the broker image (exordos build . from this repository), or follow the
manual installation below. The image prepares Postgres, nginx, CA and services
at first boot. Set these installation-specific values:
| Setting | Value |
|---|---|
/etc/exordos_nac/policy.yaml |
Your resource sets, tags and posture checks; see step 2. |
[nac] broker_endpoints |
Every broker URL reachable from office and VPN segments. |
[nac] broker_cert_file |
Server TLS trust anchor used in join tickets. |
| nginx server certificate | SANs covering all endpoints; replace the bootstrap certificate. |
Keep the API on loopback behind nginx, inside the private network on a host without untrusted local users. Keep the original device CA; record its expiry and back it up using Maintenance.
Manual broker installation
Requires Postgres, nginx and libtss2-dev. Install the release wheel with
[attestation] and take etc/ from its sdist or matching checkout.
Create the Postgres database and account.
sha256sum -c SHA256SUMS
apt-get install -y libtss2-dev
pip install './exordos_nac-<version>-py3-none-any.whl[attestation]'
install -d /etc/exordos_nac
exordos-nac-broker init-ca --cert-out /etc/exordos_nac/device-ca.crt --key-out /etc/exordos_nac/device-ca.key
Record the printed CA expiry (--valid-years changes its ten-year default).
Write /etc/exordos_nac/exordos_nac.conf:
[db]
connection_url = postgresql://exordos_nac:...@127.0.0.1:5432/exordos_nac
[nac]
bind_host = 127.0.0.1
bind_port = 11080
ca_cert_file = /etc/exordos_nac/device-ca.crt
ca_key_file = /etc/exordos_nac/device-ca.key
policy_file = /etc/exordos_nac/policy.yaml
broker_endpoints = https://broker.corp, https://10.20.0.10
broker_cert_file = /etc/exordos_nac/broker.crt
Install etc/nginx/exordos-nac-broker.conf. Its two map and two
limit_req_zone directives belong at nginx's http level. Use a server
certificate whose SANs cover every broker endpoint.
nginx -t && systemctl reload nginx
useradd --system --home /var/lib/exordos/exordos_nac --shell /usr/sbin/nologin nac
install -d -o nac -g nac /var/lib/exordos/exordos_nac /var/lib/exordos/exordos_nac/releases
chown root:nac /etc/exordos_nac/device-ca.key
chmod 0640 /etc/exordos_nac/device-ca.key
cp etc/systemd/exordos-nac-broker-*.{service,timer} /etc/systemd/system/
cp etc/default/exordos-nac-broker /etc/default/exordos-nac-broker
systemctl daemon-reload
systemctl enable --now exordos-nac-broker-api exordos-nac-broker-reap.timer exordos-nac-broker-prune.timer
Air-gapped installation
Prepare dependencies with pip download on a compatible architecture and
distribution; install with --no-index --find-links. Include a built
tpm2-pytss wheel or the compiler and libtss2-dev needed to build it.
2. Policy#
Copy etc/policy.example.yaml to /etc/exordos_nac/policy.yaml. Replace the
example resources, tags and DNS names, then check:
exordos-nac-broker policy check /etc/exordos_nac/policy.yaml --no-resolve
exordos-nac-broker policy check /etc/exordos_nac/policy.yaml --emit | nft -c -f -
The first check needs no DNS; compilation resolves actual resource names.
Run nftables validation with the required privileges. Broker bootstrap access
comes from broker_endpoints; do not add the broker to a resource set.
See policy matching.
3. Enforcement point#
Install the Linux package from step 4, plus nftables and conntrack if absent.
Issue a ticket on the broker, then enroll the gateway:
# Broker: use the gateway's endpoint and actual client segment.
exordos-nac-broker token new --for-user <iam-subject> --broker https://broker.corp \
--tag role:enforcer --enforces 10.20.0.0/24
# Gateway: run enforce only; do not start the prove service.
exordos-nac-agent join --start=false --ticket -
systemctl enable --now exordos-nac-agent-enforce
Set --enforces to exactly the segment this gateway sees. Always specify it.
Use the default polling and refresh intervals unless the deployment requires
otherwise; gateways are upgraded manually.
Router image or broker acting as a gateway
The router image accepts /etc/exordos-nac-agent/join-ticket, or join.env
containing BROKER_URL, BROKER_CA and TOKEN. Supply one and run:
On the broker image, fill /etc/exordos_nac/enforcer.env from
enforcer.example.env with owner and enforces, then run the same script.
It issues and consumes the token locally; without that file it skips enrollment.
IAM lookup
--for-user accepts a username or UUID. With IAM configured, usernames are
resolved; otherwise the value is stored as supplied. Owner identity is for
attribution; policy grants use device tags and posture.
[nac]
iam_endpoint = https://core.corp/v1/
iam_username = nac-broker
iam_password = <the account's password>
Use an account with read access to users. Non-default clients also need
iam_client, iam_client_id and iam_client_secret.
4. Devices#
Download a versioned release from
repo.exordos.com/exordos_nac, verify
SHA256SUMS, and install the native package:
Issue the device ticket on the broker:
exordos-nac-broker token new --for-user <iam-subject> --broker https://broker.corp \
--tag type:full --tag dept:engineering
Paste it into stdin on the device:
join configures, enrolls and starts the agent. Linux and Windows need
administrative rights. On macOS, run it as the logged-in user without sudo;
enroll one account per Mac. See macOS.
--require-hardware refuses software keys; use the approved settings for the
device class.
Bare-token enrollment or Windows fleet configuration
For a separately distributed broker CA and bare token:
exordos-nac-agent configure --broker https://broker.corp --ca /etc/exordos-nac-agent/broker-ca.crt
exordos-nac-agent enroll --start --token -
On macOS, sudo configure writes machine-wide configuration; enrollment
runs as the user. Machine-wide configuration takes precedence.
Windows MSI properties BROKER_URL and BROKER_CA write the same settings;
deploy the CA file separately. Keep tokens out of MSI properties and logs.
Deploy the publisher CA root if Windows should trust the internal signing CA.
In-person enrollment without server-verifiable attestation
On a known, managed machine, require hardware protection before enrollment.
Issue a short-lived ticket with the approved tags plus
--tag enrolled-in-person --ttl-minutes 10, then run join as above.
Check the backend is tpm2 or secure-enclave-user, with no degradation,
and verify the broker's record using device show <device>.
This tag records an operator's check, not attestation. Never issue it remotely. Policy must explicitly admit this class and narrow the software-grant prohibition while keeping high-value sets prohibited. See macOS.
5. Routes#
Apply routes to every protected prefix, including split-tunnel destinations:
exordos-nac-broker policy routes /etc/exordos_nac/policy.yaml --format dhcp-121 --via 10.20.0.254
exordos-nac-broker policy routes /etc/exordos_nac/policy.yaml --format openvpn-push
Install the output in DHCP or VPN configuration. Wired and wireless segments also need client isolation, DHCP snooping and IP source guard; VPN transport must bind traffic to assigned source addresses.
6. Verify, once, per network#
For a device in each office and VPN segment:
ip route get <resource> # Device: next hop is the NAC gateway.
conntrack -L -s <device-address> # Gateway: both tuples preserve the source.
tcpdump -ni any host <resource> # Resource: source is the device's address.
exordos-nac-broker device show <device>
exordos-nac-broker session list --device <device> --active
Confirm a successful proof, access to an allowed resource and refusal of a forbidden one. Test block and recovery. Investigate any source NAT or address conflicts; enforced traffic is IPv4, and the ruleset drops IPv6. See first-session checks.
After installation: 7. Device operations, 8. Agent rollout, 9. Backup and server maintenance.