Configuration reference of the Navin Manager

This page lists every setting of the Navin Manager server, read from navin_manager/config.py (class Settings), the other environment variables the server reads, and the settings stored in the database. It is generated by navin-manager/docs/tools/generate_reference.py: do not edit it by hand.

Where the settings come from

Each setting is read, in this order of priority, from the environment variable NM_<KEY> (for example from /etc/navin-manager/server.env, loaded by the systemd unit), then from the YAML file named by NM_CONFIG_FILE (default /etc/navin-manager/server.yaml, keys written without the NM_ prefix, in lower case), then from the default of the table. Put secrets (NM_DATABASE_URL with its password, NM_ADMIN_PASSWORD, NM_METRICS_TOKEN, NM_CLICKHOUSE_PASSWORD) in server.env (mode 0640, owner root:navin-manager), never in server.yaml.

With environment: prod, navin-manager check and navin-manager serve refuse to start while one of these conditions holds (function check_production):

• NM_TLS_CERT_FILE or NM_TLS_KEY_FILE is empty.
• NM_AGENT_CLIENT_CERT_REQUIRED is false.
• NM_SESSION_COOKIE_SECURE is false.
• NM_METRICS_TOKEN is empty or shorter than 32 characters.
• NM_SCRYPT_N is lower than 16384.
• NM_MASTER_KEY is empty and the file NM_MASTER_KEY_FILE does not exist.
• NM_DATABASE_URL is not a local UNIX socket and has no sslmode=require, verify-ca or verify-full.
• NM_ADMIN_PASSWORD is set and weak: fewer than 12 characters, a known password (such as navin), the user name, letters only or no letter.

General

Key	Environment variable	Type	Default	Description
environment	NM_ENVIRONMENT	string	prod	Environment of the server. prod turns on the production checks (check_production); sandbox is the value of the sandbox.
log_level	NM_LOG_LEVEL	string	info	Log level of the HTTP servers (uvicorn): debug, info, warning or error.

Database

Key	Environment variable	Type	Default	Description
database_url	NM_DATABASE_URL	string	postgresql://navin_manager@localhost:5432/navin_manager	PostgreSQL URL of the Manager database. In production: sslmode=require, verify-ca or verify-full, or a local UNIX socket (?host=/run/postgresql). The package writes it in server.env with navin-manager-db local or navin-manager-db external.
database_pool_max	NM_DATABASE_POOL_MAX	integer	20	Maximum number of connections of the database pool.
restore_targets	NM_RESTORE_TARGETS	dict[str, dict[str, typing.Any]]	empty: no destination, restores support the dry run only	Restore destinations, keyed by name: {"name": {"environment": "isolated", "database_url_env": "NM_RESTORE_<NAME>_DATABASE", "pg_restore": "pg_restore", "versions": {"postgres": "16"}}}. The URL stays in the environment variable named by database_url_env (in server.env): an empty database (not postgres or a template) owned by a role without superuser, CREATEDB, CREATEROLE, replication, BYPASSRLS or role membership; sslmode=verify-full for a remote production server. Empty: restores support the dry run only.
restore_timeout_seconds	NM_RESTORE_TIMEOUT_SECONDS	integer	300	Timeout of the pg_restore subprocess and of each SQL statement, in seconds (1 to 3600). Not a total wall-clock bound for decryption and the row inventory. Bounds: >= 1, <= 3600.
restore_max_bytes	NM_RESTORE_MAX_BYTES	integer	268435456	Largest encrypted backup accepted by a restore, in bytes (1 KiB to 1 GiB); a larger artefact is refused before any write. Bounds: >= 1024, <= 1073741824.

Master key and password hashing

Key	Environment variable	Type	Default	Description
master_key	NM_MASTER_KEY	string or null	(none)	Master key given directly (it seals every stored secret). Prefer master_key_file.
master_key_file	NM_MASTER_KEY_FILE	string	/etc/navin-manager/master.key	File of the master key (32 random bytes, mode 0600, owner navin-manager), created by navin-manager init-key at install time. Back it up: every stored secret depends on it.
scrypt_n	NM_SCRYPT_N	integer	32768	Cost parameter N of scrypt for the password hashes. At least 16384 in production.

Listeners and URLs

Key	Environment variable	Type	Default	Description
listen_host	NM_LISTEN_HOST	string	127.0.0.1	Address both listeners bind to. The packaged server.yaml sets 0.0.0.0 (agents connect from other hosts); a checkout listens on the loopback.
port	NM_PORT	integer	8460	Port of the console, the REST API /api/v1 and the agent registration.
agent_port	NM_AGENT_PORT	integer	8461	Port of the agent API /agent/v1 and of the local mirror /repo/ (TLS with client certificate).
public_url	NM_PUBLIC_URL	string or null	(none)	Public URL of the console. Empty: https://<fqdn>:<port> (http without TLS).
agent_url	NM_AGENT_URL	string or null	(none)	URL of the agent API sent to the agents at registration. Empty: https://<fqdn>:<agent_port>.
session_cookie_secure	NM_SESSION_COOKIE_SECURE	boolean	true	Session cookie sent over HTTPS only. Must stay true in production.
cors_origins	NM_CORS_ORIGINS	string	""	Origins allowed by CORS, comma separated. Empty: none.

TLS

Key	Environment variable	Type	Default	Description
tls_cert_file	NM_TLS_CERT_FILE	string or null	(none)	Certificate (PEM) of the console listener. The package creates a self-signed one in /etc/navin-manager/tls/server.crt; replace it with a certificate of your PKI. Required in production.
tls_key_file	NM_TLS_KEY_FILE	string or null	(none)	Private key (PEM) of tls_cert_file. Required in production.
agent_client_cert_required	NM_AGENT_CLIENT_CERT_REQUIRED	boolean	true	The agent listener requires the client certificate issued at registration (mutual TLS). Must stay true in production.

Catalog, console, mirror and registry

Key	Environment variable	Type	Default	Description
catalog_dir	NM_CATALOG_DIR	string	<checkout>/catalog when it exists, else /usr/share/navin-manager/catalog	Directory of the stack catalog (one descriptor per service).
ui_dir	NM_UI_DIR	string	<checkout>/ui/dist when it exists, else /usr/share/navin-manager/ui	Directory of the built web console.
docs_dir	NM_DOCS_DIR	string	<checkout>/../website/docs-site/build when it exists, else /usr/share/navin-manager/docs	Directory of the built documentation site, served without sign in on /docs/ (French) and /docs/en/ (English).
agent_templates_dir	NM_AGENT_TEMPLATES_DIR	string	<checkout>/agent-templates when it exists, else /usr/share/navin-manager/agent-templates	Directory of the agent templates registry (one descriptor per template of the Navin products, prepared or published), read by GET /api/v1/agent-templates.
agent_sources_dir	NM_AGENT_SOURCES_DIR	string	the repository root in a checkout, else /usr/share/navin-manager/agent-sources	Directory the source and docs paths of the registry descriptors are relative to: the product manifest and the service definition copied when an administrator publishes a template (POST /api/v1/agent-templates/{template_id}/publish). Never written.
published_templates_dir	NM_PUBLISHED_TEMPLATES_DIR	string	/var/lib/navin-manager/published-templates	Directory of the agent templates published on this Manager (services/<name>.yaml and templates/<name>/ of every validated agent), loaded with the catalog of catalog_dir as an overlay; catalog_dir itself is never written.
mirror_dir	NM_MIRROR_DIR	string	/var/lib/navin-manager/mirror	Directory of the local mirror (offline bundle unpacked, manifest.json), served on /repo/ of the agent listener.
mirror_url	NM_MIRROR_URL	string or null	(none)	URL of an external mirror (Nexus, Artifactory) holding the mirror tree. Empty: <agent_url>/repo.
mirror_signature	NM_MIRROR_SIGNATURE	string	required	Detached Ed25519 signature of the mirror manifest.json (manifest.json.sig, written by build-bundle.py --sign-key). required: an unsigned or wrongly signed manifest is refused at load and at delivery to the agents. unsigned-allowed: explicit migration mode of an existing unsigned mirror, every load is audited with the signature status unsigned.
mirror_trusted_keys_file	NM_MIRROR_TRUSTED_KEYS_FILE	string or null	(none)	PEM file of the Ed25519 public keys trusted for the mirror manifest signature, added to the hub.trusted_keys_pem setting of the Navin Trusted Hub. Empty: the keys of the hub setting only.
registry	NM_REGISTRY	string or null	(none)	Container registry (Harbor, Quay, Nexus) holding the images. Empty: the images of the mirror are loaded on the hosts.

Operations engine

Key	Environment variable	Type	Default	Description
engine_enabled	NM_ENGINE_ENABLED	boolean	true	Runs the operations engine and the scheduler in this process.
engine_tick_seconds	NM_ENGINE_TICK_SECONDS	number	1.0	Interval in seconds of the engine tick (start pending operations, server tasks, timeouts, stages).

Installation on the hosts

Key	Environment variable	Type	Default	Description
podman_quadlet	NM_PODMAN_QUADLET	boolean	true	Run the Podman components from Quadlet files (/etc/containers/systemd, agent task quadlet.unit) instead of a systemd unit running podman run (ADR-0171): same unit name and isolation options, unit started rather than enabled. Used on every systemd host whose Podman is 4.9 or later and whose agent announces quadlet.unit in its facts (task_types); the other hosts keep the podman run unit. false: podman run everywhere.

Sign in and initial administrator

Key	Environment variable	Type	Default	Description
mfa_enabled	NM_MFA_ENABLED	boolean	false	Second factor (TOTP) at sign in, forced enrollment of the policy roles and self service MFA. Off: user name and password only.
admin_username	NM_ADMIN_USERNAME	string	navin	User name of the initial local administrator, created at the first start of navin-manager serve.
admin_password	NM_ADMIN_PASSWORD	string or null	(none)	One-time password of the initial administrator, to change at the first sign in; never set again by a restart (navin-manager reset-admin sets it again). Put it in server.env. Nothing is created while it is empty.

Monitoring

Key	Environment variable	Type	Default	Description
metrics_token	NM_METRICS_TOKEN	string or null	(none)	Bearer token that Prometheus sends to read /metrics. At least 32 characters in production; the package writes a random one.
service_health_retention_days	NM_SERVICE_HEALTH_RETENTION_DAYS	integer	30	Days of service health samples (nm.service_health_samples) kept by the job retention.purge. Bounds: >= 1, <= 3650.

Telemetry to ClickHouse

Key	Environment variable	Type	Default	Description
clickhouse_url	NM_CLICKHOUSE_URL	string or null	(none)	URL of ClickHouse receiving the real-time telemetry. Empty: telemetry off.
clickhouse_user	NM_CLICKHOUSE_USER	string	navin_manager	ClickHouse user.
clickhouse_password	NM_CLICKHOUSE_PASSWORD	string or null	(none)	ClickHouse password (in server.env).
clickhouse_password_file	NM_CLICKHOUSE_PASSWORD_FILE	string or null	(none)	File holding the ClickHouse password.
clickhouse_database	NM_CLICKHOUSE_DATABASE	string	navin_manager	ClickHouse database.
clickhouse_ca_file	NM_CLICKHOUSE_CA_FILE	string or null	(none)	CA file (PEM) used to verify the certificate of ClickHouse.
clickhouse_timeout_seconds	NM_CLICKHOUSE_TIMEOUT_SECONDS	number	10.0	Timeout in seconds of a ClickHouse request. Bounds: > 0, <= 120.
clickhouse_flush_seconds	NM_CLICKHOUSE_FLUSH_SECONDS	number	5.0	Interval in seconds between two writes of the buffer. Bounds: > 0, <= 300.
clickhouse_buffer_rows	NM_CLICKHOUSE_BUFFER_ROWS	integer	200000	Maximum rows kept in memory while ClickHouse cannot be reached. Bounds: >= 1000, <= 10000000.
clickhouse_retention_days	NM_CLICKHOUSE_RETENTION_DAYS	integer	90	Days of telemetry kept in ClickHouse. Bounds: >= 1, <= 3650.

MCP registry

Key	Environment variable	Type	Default	Description
mcp_internal_hosts	NM_MCP_INTERNAL_HOSTS	string or list of strings	""	Internal hosts an MCP server URL of the registry may name: a comma separated string or a list of exact hosts, host:port, *.suffix or CIDR. Empty: only the IP literals of the private ranges (RFC 1918, IPv6 ULA).
mcp_validated_presets	NM_MCP_VALIDATED_PRESETS	string or list of strings	""	Presets of the Navin library validated by the company and published in its MCP catalogue (comma separated string or list of preset names). A stdio server created from one of them, command and arguments unchanged, is trusted and may be hosted by an mcp-host whose isolation is process; every other server is untrusted and is hosted only by an mcp-host whose isolation is container (409 mcp_untrusted_needs_container). Empty: no server is trusted.

Other environment variables of the server

These variables are read directly by the server code, outside the Settings class. They have no server.yaml key.

Environment variable	Default	Description
NM_CONFIG_FILE	/etc/navin-manager/server.yaml	YAML file of the settings (set by the systemd unit).
NM_PKI_DIR	/var/lib/navin-manager/pki	Directory where the server writes the CA and the certificate of the agent listener (set by the systemd unit).
NM_AGENT_TLS_SANS	(none)	Extra names of the agent listener certificate, comma separated, added to the FQDN of the host (for example a virtual IP or a DNS alias).
NM_BACKUP_KEYS	(none)	Custody keys of the encrypted backups: <ref>:<base64 of 32 bytes>, comma separated. A backup sealed with an unknown reference fails with backup_key_unknown.

Settings stored in the database

These settings are edited in the console (Administration > Settings) or with PUT /api/v1/settings, and stored in the table nm.settings (navin_manager/settings_store.py). Secret fields are sealed with the master key and never returned by the API.

Group	Field	Default	Description
general	site_name	Navin Manager	Name shown in the console header.
general	default_language	en	Default language of the console (en or fr).
install	preferred_method	binary	Installation method preselected by the install wizard (binary, podman, python, package).
install	registry	""	Container registry used by the installations.
install	mirror_url	""	URL of the external mirror used by the installations.
install	mirror_ca_pem	""	CA (PEM) of the external mirror.
smtp	host	""	SMTP server of the email notifications.
smtp	port	587	SMTP port.
smtp	starttls	true	Use STARTTLS.
smtp	username	""	SMTP user name.
smtp	from	""	Sender address.
syslog	host	""	Syslog server of the notifications.
syslog	port	514	Syslog port.
syslog	protocol	udp	udp or tcp.
syslog	facility	local0	Syslog facility.
retention	metrics_days	30	Days of host metrics kept.
retention	task_logs_days	90	Days of task logs kept.
retention	operations_days	365	Days of operations kept.
proxy	http_proxy	""	HTTP proxy of the managed hosts (http:// or https://, without credentials or path).
proxy	https_proxy	""	HTTPS proxy of the managed hosts.
proxy	no_proxy	""	Hosts reached without the proxy; localhost, 127.0.0.1, ::1 and the Manager are always added.
hub	url	""	Address of the Navin Trusted Hub.
hub	expected_hub	""	Identity of the Navin Trusted Hub this Manager accepts (the hub field of the signed document); required before any document is ingested. It cannot be changed to another hub once a document was accepted; emptying it stops the ingestion.
hub	customer	""	Customer identifier at the Hub.
hub	trusted_keys_pem	""	Pinned Ed25519 public keys (PEM) that sign the Hub catalog.
hub	enforce	false	Install only the artifacts (images, binaries, archives, wheels) whose digest the signed Hub document approves; required by the banking-secure profile.
hub	ca_pem	""	CA (PEM) of the Hub.
smtp	password	(secret, sealed)	SMTP password.
hub	token	(secret, sealed)	Access token of the Hub.