Référence de configuration du Navin Manager

Cette page liste chaque paramètre du serveur Navin Manager, relevé dans navin_manager/config.py (classe Settings), les autres variables d'environnement lues par le serveur et les paramètres enregistrés en base. Elle est générée par navin-manager/docs/tools/generate_reference.py : ne la modifiez pas à la main.

Origine des paramètres

Chaque paramètre est lu, par ordre de priorité, dans la variable d'environnement NM_<CLÉ> (par exemple dans /etc/navin-manager/server.env, chargé par l'unité systemd), puis dans le fichier YAML désigné par NM_CONFIG_FILE (par défaut /etc/navin-manager/server.yaml, clés écrites sans le préfixe NM_, en minuscules), puis dans la valeur par défaut du tableau. Placez les secrets (NM_DATABASE_URL avec son mot de passe, NM_ADMIN_PASSWORD, NM_METRICS_TOKEN, NM_CLICKHOUSE_PASSWORD) dans server.env (mode 0640, propriétaire root:navin-manager), jamais dans server.yaml.

Avec environment: prod, navin-manager check et navin-manager serve refusent de démarrer tant qu'une de ces conditions est vraie (fonction check_production) :

• NM_TLS_CERT_FILE ou NM_TLS_KEY_FILE est vide.
• NM_AGENT_CLIENT_CERT_REQUIRED vaut false.
• NM_SESSION_COOKIE_SECURE vaut false.
• NM_METRICS_TOKEN est vide ou fait moins de 32 caractères.
• NM_SCRYPT_N est inférieur à 16384.
• NM_MASTER_KEY est vide et le fichier NM_MASTER_KEY_FILE n'existe pas.
• NM_DATABASE_URL n'est pas un socket UNIX local et ne contient ni sslmode=require, ni verify-ca, ni verify-full.
• NM_ADMIN_PASSWORD est renseigné et faible : moins de 12 caractères, un mot de passe connu (comme navin), le nom d'utilisateur, uniquement des lettres ou aucune lettre.

Général

Clé	Variable d'environnement	Type	Défaut	Description
environment	NM_ENVIRONMENT	chaîne	prod	Environnement du serveur. prod active les contrôles de production (check_production) ; sandbox est la valeur du bac à sable.
log_level	NM_LOG_LEVEL	chaîne	info	Niveau de journalisation des serveurs HTTP (uvicorn) : debug, info, warning ou error.

Base de données

Clé	Variable d'environnement	Type	Défaut	Description
database_url	NM_DATABASE_URL	chaîne	postgresql://navin_manager@localhost:5432/navin_manager	URL PostgreSQL de la base du Manager. En production : sslmode=require, verify-ca ou verify-full, ou un socket UNIX local (?host=/run/postgresql). Le paquet l'écrit dans server.env avec navin-manager-db local ou navin-manager-db external.
database_pool_max	NM_DATABASE_POOL_MAX	entier	20	Nombre maximal de connexions du pool de la base.
restore_targets	NM_RESTORE_TARGETS	dict[str, dict[str, typing.Any]]	vide : aucune destination, les restaurations ne permettent que l'essai à blanc	Destinations de restauration, indexées par nom : {"name": {"environment": "isolated", "database_url_env": "NM_RESTORE_<NAME>_DATABASE", "pg_restore": "pg_restore", "versions": {"postgres": "16"}}}. L'URL reste dans la variable d'environnement nommée par database_url_env (dans server.env) : une base vide (ni postgres ni un modèle) appartenant à un rôle sans superutilisateur, CREATEDB, CREATEROLE, réplication, BYPASSRLS ni appartenance à un rôle ; sslmode=verify-full pour un serveur de production distant. Vide : les restaurations ne permettent que l'essai à blanc.
restore_timeout_seconds	NM_RESTORE_TIMEOUT_SECONDS	entier	300	Délai du sous-processus pg_restore et de chaque instruction SQL, en secondes (1 à 3600). Ce n'est pas une borne totale pour le déchiffrement et l'inventaire des lignes. Bornes : >= 1, <= 3600.
restore_max_bytes	NM_RESTORE_MAX_BYTES	entier	268435456	Taille maximale d'une sauvegarde chiffrée acceptée par une restauration, en octets (1 Kio à 1 Gio) ; un artefact plus grand est refusé avant toute écriture. Bornes : >= 1024, <= 1073741824.

Clé maîtresse et hachage des mots de passe

Clé	Variable d'environnement	Type	Défaut	Description
master_key	NM_MASTER_KEY	chaîne ou null	(aucune)	Clé maîtresse donnée directement (elle scelle chaque secret enregistré). Préférez master_key_file.
master_key_file	NM_MASTER_KEY_FILE	chaîne	/etc/navin-manager/master.key	Fichier de la clé maîtresse (32 octets aléatoires, mode 0600, propriétaire navin-manager), créé par navin-manager init-key à l'installation. Sauvegardez-le : chaque secret enregistré en dépend.
scrypt_n	NM_SCRYPT_N	entier	32768	Paramètre de coût N de scrypt pour le hachage des mots de passe. Au moins 16384 en production.

Écoutes et adresses

Clé	Variable d'environnement	Type	Défaut	Description
listen_host	NM_LISTEN_HOST	chaîne	127.0.0.1	Adresse d'écoute des deux serveurs. Le server.yaml du paquet indique 0.0.0.0 (les agents se connectent depuis d'autres hôtes) ; un dépôt de sources écoute sur l'interface locale.
port	NM_PORT	entier	8460	Port de la console, de l'API REST /api/v1 et de l'enregistrement des agents.
agent_port	NM_AGENT_PORT	entier	8461	Port de l'API des agents /agent/v1 et du miroir local /repo/ (TLS avec certificat client).
public_url	NM_PUBLIC_URL	chaîne ou null	(aucune)	Adresse publique de la console. Vide : https://<fqdn>:<port> (http sans TLS).
agent_url	NM_AGENT_URL	chaîne ou null	(aucune)	Adresse de l'API des agents envoyée aux agents à l'enregistrement. Vide : https://<fqdn>:<agent_port>.
session_cookie_secure	NM_SESSION_COOKIE_SECURE	booléen	true	Cookie de session envoyé uniquement en HTTPS. Doit rester à true en production.
cors_origins	NM_CORS_ORIGINS	chaîne	""	Origines autorisées par CORS, séparées par des virgules. Vide : aucune.

TLS

Clé	Variable d'environnement	Type	Défaut	Description
tls_cert_file	NM_TLS_CERT_FILE	chaîne ou null	(aucune)	Certificat (PEM) de l'écoute de la console. Le paquet en crée un autosigné dans /etc/navin-manager/tls/server.crt ; remplacez-le par un certificat de votre PKI. Obligatoire en production.
tls_key_file	NM_TLS_KEY_FILE	chaîne ou null	(aucune)	Clé privée (PEM) de tls_cert_file. Obligatoire en production.
agent_client_cert_required	NM_AGENT_CLIENT_CERT_REQUIRED	booléen	true	L'écoute des agents exige le certificat client délivré à l'enregistrement (TLS mutuel). Doit rester à true en production.

Catalogue, console, miroir et registre

Clé	Variable d'environnement	Type	Défaut	Description
catalog_dir	NM_CATALOG_DIR	chaîne	<dépôt>/catalog s'il existe, sinon /usr/share/navin-manager/catalog	Répertoire du catalogue de services (un descripteur par service).
ui_dir	NM_UI_DIR	chaîne	<dépôt>/ui/dist s'il existe, sinon /usr/share/navin-manager/ui	Répertoire de la console web construite.
docs_dir	NM_DOCS_DIR	chaîne	<dépôt>/../website/docs-site/build s'il existe, sinon /usr/share/navin-manager/docs	Répertoire du site de documentation construit, servi sans connexion sur /docs/ (français) et /docs/en/ (anglais).
agent_templates_dir	NM_AGENT_TEMPLATES_DIR	chaîne	<dépôt>/agent-templates s'il existe, sinon /usr/share/navin-manager/agent-templates	Répertoire du registre des gabarits d'agents (un descripteur par gabarit des produits Navin, préparé ou publié), lu par GET /api/v1/agent-templates.
agent_sources_dir	NM_AGENT_SOURCES_DIR	chaîne	la racine du dépôt dans un clone, sinon /usr/share/navin-manager/agent-sources	Répertoire auquel les chemins source et docs des descripteurs du registre sont relatifs : le manifeste du produit et la définition de service copiés quand un administrateur publie un gabarit (POST /api/v1/agent-templates/{template_id}/publish). Jamais écrit.
published_templates_dir	NM_PUBLISHED_TEMPLATES_DIR	chaîne	/var/lib/navin-manager/published-templates	Répertoire des gabarits d'agents publiés sur ce Manager (services/<nom>.yaml et templates/<nom>/ de chaque agent validé), chargé avec le catalogue de catalog_dir par-dessus celui-ci ; catalog_dir lui-même n'est jamais écrit.
mirror_dir	NM_MIRROR_DIR	chaîne	/var/lib/navin-manager/mirror	Répertoire du miroir local (archive hors ligne dépaquetée, manifest.json), servi sur /repo/ de l'écoute des agents.
mirror_url	NM_MIRROR_URL	chaîne ou null	(aucune)	Adresse d'un miroir externe (Nexus, Artifactory) contenant l'arborescence du miroir. Vide : <agent_url>/repo.
mirror_signature	NM_MIRROR_SIGNATURE	chaîne	required	Signature Ed25519 détachée du manifest.json du miroir (manifest.json.sig, écrite par build-bundle.py --sign-key). required : un manifeste non signé ou mal signé est refusé au chargement et à la livraison aux agents. unsigned-allowed : mode de migration explicite d'un miroir existant non signé, chaque chargement est audité avec le statut de signature unsigned.
mirror_trusted_keys_file	NM_MIRROR_TRUSTED_KEYS_FILE	chaîne ou null	(aucune)	Fichier PEM des clés publiques Ed25519 de confiance pour la signature du manifeste du miroir, ajoutées au paramètre hub.trusted_keys_pem du Navin Trusted Hub. Vide : seulement les clés du paramètre du hub.
registry	NM_REGISTRY	chaîne ou null	(aucune)	Registre de conteneurs (Harbor, Quay, Nexus) contenant les images. Vide : les images du miroir sont chargées sur les hôtes.

Moteur d'opérations

Clé	Variable d'environnement	Type	Défaut	Description
engine_enabled	NM_ENGINE_ENABLED	booléen	true	Exécute le moteur d'opérations et le planificateur dans ce processus.
engine_tick_seconds	NM_ENGINE_TICK_SECONDS	nombre	1.0	Intervalle en secondes du cycle du moteur (démarrage des opérations en attente, tâches serveur, délais, étapes).

Installation sur les hôtes

Clé	Variable d'environnement	Type	Défaut	Description
podman_quadlet	NM_PODMAN_QUADLET	booléen	true	Exécute les composants Podman depuis des fichiers Quadlet (/etc/containers/systemd, tâche agent quadlet.unit) au lieu d'une unité systemd qui lance podman run (ADR-0171) : même nom d'unité et mêmes options d'isolation, unité démarrée et non activée. S'applique à tout hôte systemd dont Podman est en version 4.9 ou plus récente et dont l'agent annonce quadlet.unit dans ses faits (task_types) ; les autres hôtes gardent l'unité podman run. false : podman run partout.

Connexion et administrateur initial

Clé	Variable d'environnement	Type	Défaut	Description
mfa_enabled	NM_MFA_ENABLED	booléen	false	Second facteur (TOTP) à la connexion, enrôlement imposé pour les rôles de la politique et MFA en libre service. Désactivé : nom d'utilisateur et mot de passe seulement.
admin_username	NM_ADMIN_USERNAME	chaîne	navin	Nom d'utilisateur de l'administrateur local initial, créé au premier démarrage de navin-manager serve.
admin_password	NM_ADMIN_PASSWORD	chaîne ou null	(aucune)	Mot de passe à usage unique de l'administrateur initial, à changer à la première connexion ; jamais réappliqué par un redémarrage (navin-manager reset-admin le réapplique). Placez-le dans server.env. Rien n'est créé tant qu'il est vide.

Supervision

Clé	Variable d'environnement	Type	Défaut	Description
metrics_token	NM_METRICS_TOKEN	chaîne ou null	(aucune)	Jeton porteur que Prometheus envoie pour lire /metrics. Au moins 32 caractères en production ; le paquet en écrit un aléatoire.
service_health_retention_days	NM_SERVICE_HEALTH_RETENTION_DAYS	entier	30	Jours d'échantillons de santé des services (nm.service_health_samples) conservés par la tâche retention.purge. Bornes : >= 1, <= 3650.

Télémétrie vers ClickHouse

Clé	Variable d'environnement	Type	Défaut	Description
clickhouse_url	NM_CLICKHOUSE_URL	chaîne ou null	(aucune)	Adresse de ClickHouse qui reçoit la télémétrie en temps réel. Vide : télémétrie désactivée.
clickhouse_user	NM_CLICKHOUSE_USER	chaîne	navin_manager	Utilisateur ClickHouse.
clickhouse_password	NM_CLICKHOUSE_PASSWORD	chaîne ou null	(aucune)	Mot de passe ClickHouse (dans server.env).
clickhouse_password_file	NM_CLICKHOUSE_PASSWORD_FILE	chaîne ou null	(aucune)	Fichier contenant le mot de passe ClickHouse.
clickhouse_database	NM_CLICKHOUSE_DATABASE	chaîne	navin_manager	Base ClickHouse.
clickhouse_ca_file	NM_CLICKHOUSE_CA_FILE	chaîne ou null	(aucune)	Fichier d'autorité de certification (PEM) qui vérifie le certificat de ClickHouse.
clickhouse_timeout_seconds	NM_CLICKHOUSE_TIMEOUT_SECONDS	nombre	10.0	Délai maximal en secondes d'une requête ClickHouse. Bornes : > 0, <= 120.
clickhouse_flush_seconds	NM_CLICKHOUSE_FLUSH_SECONDS	nombre	5.0	Intervalle en secondes entre deux écritures du tampon. Bornes : > 0, <= 300.
clickhouse_buffer_rows	NM_CLICKHOUSE_BUFFER_ROWS	entier	200000	Nombre maximal de lignes gardées en mémoire tant que ClickHouse est injoignable. Bornes : >= 1000, <= 10000000.
clickhouse_retention_days	NM_CLICKHOUSE_RETENTION_DAYS	entier	90	Jours de télémétrie conservés dans ClickHouse. Bornes : >= 1, <= 3650.

Registre MCP

Clé	Variable d'environnement	Type	Défaut	Description
mcp_internal_hosts	NM_MCP_INTERNAL_HOSTS	chaîne ou liste de chaînes	""	Hôtes internes qu'une adresse de serveur MCP du registre peut nommer : une chaîne séparée par des virgules ou une liste d'hôtes exacts, hôte:port, *.suffixe ou CIDR. Vide : seules les adresses IP des plages privées (RFC 1918, IPv6 ULA).
mcp_validated_presets	NM_MCP_VALIDATED_PRESETS	chaîne ou liste de chaînes	""	Préréglages de la bibliothèque Navin validés par l'entreprise et publiés dans son catalogue MCP (chaîne séparée par des virgules ou liste de noms de préréglages). Un serveur stdio créé depuis l'un d'eux, commande et arguments inchangés, est fiable et peut être hébergé par un mcp-host dont l'isolation est process ; tout autre serveur est non fiable et n'est hébergé que par un mcp-host dont l'isolation est container (409 mcp_untrusted_needs_container). Vide : aucun serveur n'est fiable.

Autres variables d'environnement du serveur

Ces variables sont lues directement par le code du serveur, hors de la classe Settings. Elles n'ont pas de clé dans server.yaml.

Variable d'environnement	Défaut	Description
NM_CONFIG_FILE	/etc/navin-manager/server.yaml	Fichier YAML des paramètres (défini par l'unité systemd).
NM_PKI_DIR	/var/lib/navin-manager/pki	Répertoire où le serveur écrit l'autorité de certification et le certificat de l'écoute des agents (défini par l'unité systemd).
NM_AGENT_TLS_SANS	(aucune)	Noms supplémentaires du certificat de l'écoute des agents, séparés par des virgules, ajoutés au FQDN de l'hôte (par exemple une IP virtuelle ou un alias DNS).
NM_BACKUP_KEYS	(aucune)	Clés de garde des sauvegardes chiffrées : <réf>:<base64 de 32 octets>, séparées par des virgules. Une sauvegarde scellée avec une référence inconnue échoue avec backup_key_unknown.

Paramètres enregistrés en base

Ces paramètres se modifient dans la console (Administration > Paramètres) ou avec PUT /api/v1/settings, et sont enregistrés dans la table nm.settings (navin_manager/settings_store.py). Les champs secrets sont scellés avec la clé maîtresse et jamais renvoyés par l'API.

Groupe	Champ	Défaut	Description
general	site_name	Navin Manager	Nom affiché dans l'en-tête de la console.
general	default_language	en	Langue par défaut de la console (en ou fr).
install	preferred_method	binary	Méthode d'installation présélectionnée par l'assistant (binary, podman, python, package).
install	registry	""	Registre de conteneurs utilisé par les installations.
install	mirror_url	""	Adresse du miroir externe utilisé par les installations.
install	mirror_ca_pem	""	Autorité de certification (PEM) du miroir externe.
smtp	host	""	Serveur SMTP des notifications par courriel.
smtp	port	587	Port SMTP.
smtp	starttls	true	Utiliser STARTTLS.
smtp	username	""	Nom d'utilisateur SMTP.
smtp	from	""	Adresse de l'expéditeur.
syslog	host	""	Serveur syslog des notifications.
syslog	port	514	Port syslog.
syslog	protocol	udp	udp ou tcp.
syslog	facility	local0	Catégorie (facility) syslog.
retention	metrics_days	30	Jours de métriques des hôtes conservés.
retention	task_logs_days	90	Jours de journaux de tâches conservés.
retention	operations_days	365	Jours d'opérations conservés.
proxy	http_proxy	""	Proxy HTTP des hôtes gérés (http:// ou https://, sans identifiants ni chemin).
proxy	https_proxy	""	Proxy HTTPS des hôtes gérés.
proxy	no_proxy	""	Hôtes joints sans le proxy ; localhost, 127.0.0.1, ::1 et le Manager sont toujours ajoutés.
hub	url	""	Adresse du Navin Trusted Hub.
hub	expected_hub	""	Identité du Navin Trusted Hub acceptée par ce Manager (champ hub du document signé) ; obligatoire avant toute ingestion de document. Elle ne peut pas être remplacée par un autre hub une fois un document accepté ; la vider arrête l'ingestion.
hub	customer	""	Identifiant client auprès du Hub.
hub	trusted_keys_pem	""	Clés publiques Ed25519 épinglées (PEM) qui signent le catalogue du Hub.
hub	enforce	false	N'installer que les artefacts (images, binaires, archives, fichiers wheel) dont le document signé du Hub approuve l'empreinte ; exigé par le profil banking-secure.
hub	ca_pem	""	Autorité de certification (PEM) du Hub.
smtp	password	(secret, scellé)	Mot de passe SMTP.
hub	token	(secret, scellé)	Jeton d'accès au Hub.