Navin agent

The Navin agent runs on every managed host. It registers the host with the Navin Manager, sends heartbeats, facts and metrics, and runs the tasks of the Manager one at a time: users, directories, files, artifacts, container images, systemd units, health checks, commands. This section explains how it works and how to install, configure, secure, operate and troubleshoot it.

Page	Content
Install the Navin agent	Packages for every system, registration by command, by enroll.env or by SSH
Configuration reference	Every key of agent.json, every option of nm-agent, enroll.env (generated)
Security of the Navin agent	Identity, mutual TLS, request signature, path guard, allowed commands
Operate the Navin agent	Start, stop, status, logs, upgrade, decommission
Troubleshoot the Navin agent	Symptoms, causes, fixes
Host agent	Facts, corporate proxy, which agent to install
Kubernetes cluster agent	The agent of a Kubernetes cluster (separate component)

Architecture

Item	Value
Programs	Go agent navin-manager-agent-go (shipped, one static binary) and Python agent navin-manager-agent (reference). Both install /usr/bin/nm-agent.
Configuration	/etc/navin-manager-agent/agent.json (reference)
State	/var/lib/navin-manager-agent (mode 0700): key, certificates, credentials, registry of the components
Logs	/var/log/navin-manager-agent/agent.log (20 MB, 5 backups) and the journal of navin-manager-agent.service
Units	navin-manager-agent.service (runs as root, KillMode=process), navin-manager-agent-enroll.service and .timer (registration from enroll.env)
Network	Outgoing only: to the Manager on 8460/tcp (registration) and 8461/tcp (agent API and mirror). No listening port on the host.
Drivers	systemd (units navin-<service>-<component>.service) or process (supervised processes, rootless sandbox)

The agent opens every connection. It polls the Manager for the next task (long poll of poll_wait_s seconds), runs it, streams its logs and reports the result; meanwhile it sends a heartbeat every heartbeat_interval_s seconds and runs the health checks of its components every health_interval_s seconds. The task types are listed in the operations reference.

The managed services keep running when the agent stops or restarts: the unit stops the agent process only.

Trust and enrollment

1. Bootstrap token. An operator creates a token in the console (Hosts > Add hosts) or with navin-manager enroll-token --cluster <name> --uses <n> --hours <h>. The token allows a given number of hosts to register during a given time, in one cluster.
2. Registration. nm-agent register --server <url> --token <token> --ca-sha256 <fingerprint> creates an EC P-256 key and a certificate request on the host (the key never leaves the host) and calls POST /agent/v1/register on port 8460 with the token, the facts and the request.
3. CA pinning. The Manager answers with the host id, a client certificate, the CA certificate and a secret. The agent computes the sha256 of the CA certificate and stops with ca_mismatch if it differs from --ca-sha256: nothing is stored.
4. Credentials. The agent atomically stores the certificate chain and private key in agent.pem (0600), with ca.crt and credentials.json (0600) in its state directory, and writes server_url and agent_url in agent.json. Legacy agent.crt and agent.key are read only when agent.pem is absent. See the migration and rollback contract.

Mutual TLS and signatures

After the registration, every call goes to the agent API (port 8461) with:

• mutual TLS: the agent presents its client certificate, issued by the internal CA of the Manager; the Manager refuses a connection without it while agent_client_cert_required is true (always in production);
• a request signature: Authorization: NM-HMAC <host_id>:<unix ts>:<hex hmac>, an HMAC-SHA256 of the method, the path, the timestamp and the sha256 of the body with the agent secret. A timestamp more than 300 seconds away, an unknown or decommissioned host or a wrong signature is refused with 401 agent_signature_invalid.

The agent renews its certificate with POST /agent/v1/renew (a new certificate request); the Manager revokes the previous certificate. The direct transport refreshes its CRL and verifies peer identity for API and mirror requests. Task delivery now requires protocol 2, including an ACK and attempt-bound logs/results; migration is coordinated with V093/V094 and current agent binaries. Details are in Security of the Navin agent.