Configuration reference of the Navin agent
This page lists the configuration of the Navin agent, read from nm_agent/config.py (class AgentConfig) and nm_agent/cli.py. The Go agent reads the same file with the same keys. It is generated by navin-manager/docs/tools/generate_reference.py: do not edit it by hand.
Keys of agent.json
The file /etc/navin-manager-agent/agent.json holds one JSON object. Unknown keys are ignored; a list must hold strings only, an integer must be positive, any other value must be a string, else the agent stops with config_invalid. nm-agent register writes server_url, agent_url and the intervals sent by the Manager; the task agent.config updates the file from the Manager. The file is replaced atomically with mode 0640.
| Key | Type | Default | Description |
|---|---|---|---|
server_url | string | "" | URL of the Manager console listener (port 8460), written by nm-agent register. |
agent_url | string | "" | URL of the agent API (port 8461), written by nm-agent register from --agent-url, the existing value or the answer of the Manager. |
state_dir | string | /var/lib/navin-manager-agent | State directory (mode 0700): atomic certificate/key bundle agent.pem (0600), ca.crt, credentials.json, running task. Legacy agent.crt and agent.key are read only when agent.pem is absent. |
log_dir | string | /var/log/navin-manager-agent | Log directory: agent.log (20 MB, 5 backups). |
fs_prefix | string | "" | Prefix of every managed path (rootless sandbox). Empty: none. |
allowed_roots | list of strings | /etc/navin, /opt/navin, /var/lib/navin, /var/log/navin, /run/navin, /etc/systemd/system/navin-*, /etc/sysctl.d/90-navin-*, /etc/security/limits.d/90-navin-*, /etc/containers/systemd/navin-* | Roots the file tasks may write below; a path outside, with .. or a symbolic link fails with path_not_allowed. |
allowed_commands | list of strings | /bin/true, /usr/bin/true, /bin/false, /usr/bin/false, /bin/echo, /usr/bin/echo, /usr/bin/id, /usr/bin/hostname, /usr/bin/uname | Absolute programs command.run and the command checks may start, besides those inside the allowed roots; never through a shell. |
service_driver | string | "" | systemd or process. Empty: systemd when /run/systemd/system exists, else process. |
heartbeat_interval_s | integer | 15 | Seconds between two heartbeats (the Manager may set it at registration). |
poll_wait_s | integer | 25 | Seconds of the long poll for the next task. |
health_interval_s | integer | 30 | Seconds between two health rounds of the components. |
stop_timeout_s | integer | 10 | Seconds given to a process to stop before it is killed (process driver). |
log_level | string | INFO | Log level of the agent. |
ca_file | string | "" | CA bundle that verifies the TLS of the registration listener (else the system trust store). |
Log levels
Accepted values of log_level (case insensitive): DEBUG, INFO, WARNING, ERROR.
Options of nm-agent
nm-agent [--config FILE] [--lang en|fr] <command> [options]. Exit codes: 0 success, 1 status of a host that is not registered, 2 error (invalid configuration, refused registration, wrong CA fingerprint).
| Command | Option | Default | Description |
|---|---|---|---|
nm-agent | --config | /etc/navin-manager-agent/agent.json | Configuration file. |
nm-agent | --lang | (none) | Language of the messages (en or fr); default from LC_ALL or LANG. |
nm-agent | --version | (none) | Print the version and exit. |
nm-agent register | Register this host: key and certificate request made on the host, call POST /agent/v1/register, check of the CA fingerprint, credentials stored in state_dir. | ||
nm-agent register | --server | required | URL of the Manager (console listener, port 8460). |
nm-agent register | --token | (none) | Bootstrap token shown in the console. |
nm-agent register | --token-env | (none) | Name of the environment variable that holds the bootstrap token (keeps it out of the command line). |
nm-agent register | --ca-sha256 | required | sha256 fingerprint of the Manager CA; a different CA stops the registration with ca_mismatch. |
nm-agent register | --ca-file | (none) | CA bundle for the TLS of the registration listener. |
nm-agent register | --fqdn | (none) | Fully qualified name of the host (default detected). |
nm-agent register | --hostname | (none) | Short host name (default detected). |
nm-agent register | --ip | (none) | Address of the host (default the address of the default route). |
nm-agent register | --agent-url | (none) | URL of the agent API (default the one sent by the Manager). |
nm-agent run | Run the agent: heartbeats, facts, tasks, health. Exits 2 with not_registered before a registration. | ||
nm-agent status | Show the registration, the URLs, the driver, the running task and the number of components. | ||
nm-agent facts | Print the facts of the host as JSON. |
Variables of enroll.env
/etc/navin-manager-agent/enroll.env (mode 0600, owner root) lets the unit navin-manager-agent-enroll.service register the host without typing nm-agent register. The unit deletes the file once the host is registered, since the token is used once.
| Environment variable | Description |
|---|---|
NM_SERVER | URL of the Manager, for example <manager-url>:8460. |
NM_TOKEN | Bootstrap token created in the console or with navin-manager enroll-token. |
NM_CA_SHA256 | sha256 of the Manager CA shown next to the token. |
NM_REGISTER_ARGS | Optional extra options of nm-agent register, quoted, for example --ca-file /etc/navin-manager-agent/manager-tls.pem or --fqdn. |