Troubleshoot the Navin agent
This page lists the messages of the Navin agent and of the Manager about agents, with their cause and fix. Start
with sudo nm-agent status and sudo navinctl logs agent 200.
Registration
| Symptom | Cause | Fix |
|---|---|---|
The CA returned by the manager has the fingerprint <a>, expected <b> (ca_mismatch) | wrong --ca-sha256, or another server answers (interception) | copy the fingerprint shown next to the token; if it matches, check the address of the Manager |
The manager address <url> does not use https: ... (insecure_server) | the command uses http toward another host | use the https address of the Manager (https://<fqdn>:8460) shown next to the token |
Registration refused by the manager (401): ... (register_failed) | token expired, used up or revoked | create a new token (Hosts > Add hosts or navin-manager enroll-token) |
The manager cannot be reached: ... (network_error) | DNS, firewall, port 8460 closed, or TLS not trusted | curl -v https://<manager-fqdn>:8460/api/v1/version; with the self-signed certificate add --ca-file |
The openssl command is missing (openssl_missing) | Python agent without openssl | install openssl |
enroll.env stays on the host | registration from enroll.env refused | sudo navinctl logs enroll shows the reason; the timer retries every minute |
Run
| Symptom | Cause | Fix |
|---|---|---|
This host is not registered: run nm-agent register first. (not_registered) | no credentials in the state directory | register the host |
Invalid configuration file ... (config_invalid) | invalid JSON, wrong type, service_driver other than systemd or process, unknown log_level | fix agent.json (reference) |
The unit does not start and systemctl status shows a condition failed | /etc/navin-manager-agent/agent.json is missing (ConditionPathExists) | register the host, which writes the file |
The Manager answers 401 agent_signature_invalid | clock skew over 300 seconds, host decommissioned or revoked | synchronize the clock (chronyd, systemd-timesyncd); register again if the host was decommissioned |
The host is lost in Hosts | no heartbeat received | check the unit, the network to port 8461 and the logs |
Tasks
| Symptom | Cause | Fix |
|---|---|---|
path_not_allowed | the task writes outside allowed_roots, or through a symbolic link or .. | fix the path of the catalog, or add the root to allowed_roots |
command_not_allowed | the program is neither in allowed_commands nor below an allowed root, or a shell is used | add the absolute program to allowed_commands |
checksum_mismatch | the downloaded file differs from the sha256 of the manifest | reload the mirror from a verified bundle (Mirror) |
archive_unsafe | the archive holds absolute names, .., devices or escaping links | rebuild the bundle from the official release |
archive_too_large | the archive declares more than 200 000 members or 64 GiB | rebuild the bundle from the official release |
download_too_large | the mirror sends more than 64 GiB for one file | check the URL of the mirror and the manifest of the bundle |
disk_space_low | less than 1 GiB would stay free in the cache (/var/lib/navin) or the destination | free disk space on the host, then retry the operation |
| A task needing root fails in the sandbox | the rootless agent refuses system packages, kernel parameters, limits, firewall and units | run the agent as root, or use a sandbox cluster where the planner does not send them |