Référence de configuration de l'agent Navin

Cette page liste la configuration de l'agent Navin, relevée dans nm_agent/config.py (classe AgentConfig) et nm_agent/cli.py. L'agent Go lit le même fichier avec les mêmes clés. Elle est générée par navin-manager/docs/tools/generate_reference.py : ne la modifiez pas à la main.

Clés d'agent.json

Le fichier /etc/navin-manager-agent/agent.json contient un objet JSON. Les clés inconnues sont ignorées ; une liste ne doit contenir que des chaînes, un entier doit être positif, toute autre valeur doit être une chaîne, sinon l'agent s'arrête avec config_invalid. nm-agent register écrit server_url, agent_url et les intervalles envoyés par le Manager ; la tâche agent.config met le fichier à jour depuis le Manager. Le fichier est remplacé de façon atomique, en mode 0640.

Clé	Type	Défaut	Description
server_url	chaîne	""	Adresse de l'écoute console du Manager (port 8460), écrite par nm-agent register.
agent_url	chaîne	""	Adresse de l'API des agents (port 8461), écrite par nm-agent register depuis --agent-url, la valeur existante ou la réponse du Manager.
state_dir	chaîne	/var/lib/navin-manager-agent	Répertoire d'état (mode 0700) : bundle certificat/clé atomique agent.pem (0600), ca.crt, credentials.json, tâche en cours. Les anciens agent.crt et agent.key ne sont lus que si agent.pem est absent.
log_dir	chaîne	/var/log/navin-manager-agent	Répertoire des journaux : agent.log (20 Mo, 5 copies).
fs_prefix	chaîne	""	Préfixe de chaque chemin géré (bac à sable sans root). Vide : aucun.
allowed_roots	liste de chaînes	/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-*	Racines sous lesquelles les tâches de fichiers peuvent écrire ; un chemin hors racine, avec .. ou un lien symbolique échoue avec path_not_allowed.
allowed_commands	liste de chaînes	/bin/true, /usr/bin/true, /bin/false, /usr/bin/false, /bin/echo, /usr/bin/echo, /usr/bin/id, /usr/bin/hostname, /usr/bin/uname	Programmes absolus que command.run et les contrôles de commande peuvent lancer, en plus de ceux situés dans les racines autorisées ; jamais par un shell.
service_driver	chaîne	""	systemd ou process. Vide : systemd si /run/systemd/system existe, sinon process.
heartbeat_interval_s	entier	15	Secondes entre deux signaux de vie (le Manager peut le fixer à l'enregistrement).
poll_wait_s	entier	25	Secondes d'attente longue pour la tâche suivante.
health_interval_s	entier	30	Secondes entre deux tours de santé des composants.
stop_timeout_s	entier	10	Secondes laissées à un processus pour s'arrêter avant d'être tué (pilote process).
log_level	chaîne	INFO	Niveau de journalisation de l'agent.
ca_file	chaîne	""	Bundle d'autorités qui vérifie le TLS de l'écoute d'enregistrement (sinon le magasin du système).

Niveaux de journalisation

Valeurs acceptées pour log_level (sans tenir compte de la casse) : DEBUG, INFO, WARNING, ERROR.

Options de nm-agent

nm-agent [--config FICHIER] [--lang en|fr] <commande> [options]. Codes de sortie : 0 succès, 1 status d'un hôte non enregistré, 2 erreur (configuration invalide, enregistrement refusé, empreinte de l'autorité de certification incorrecte).

Commande	Option	Défaut	Description
nm-agent	--config	/etc/navin-manager-agent/agent.json	Fichier de configuration.
nm-agent	--lang	(aucune)	Langue des messages (en ou fr) ; par défaut depuis LC_ALL ou LANG.
nm-agent	--version	(aucune)	Affiche la version et quitte.
nm-agent register			Enregistre cet hôte : clé et demande de certificat produites sur l'hôte, appel POST /agent/v1/register, vérification de l'empreinte de l'autorité, identifiants rangés dans state_dir.
nm-agent register	--server	obligatoire	Adresse du Manager (écoute console, port 8460).
nm-agent register	--token	(aucune)	Jeton d'amorçage affiché dans la console.
nm-agent register	--token-env	(aucune)	Nom de la variable d'environnement qui contient le jeton d'amorçage (le garde hors de la ligne de commande).
nm-agent register	--ca-sha256	obligatoire	Empreinte sha256 de l'autorité du Manager ; une autre autorité arrête l'enregistrement avec ca_mismatch.
nm-agent register	--ca-file	(aucune)	Bundle d'autorités pour le TLS de l'écoute d'enregistrement.
nm-agent register	--fqdn	(aucune)	Nom complet de l'hôte (détecté par défaut).
nm-agent register	--hostname	(aucune)	Nom court de l'hôte (détecté par défaut).
nm-agent register	--ip	(aucune)	Adresse de l'hôte (par défaut celle de la route par défaut).
nm-agent register	--agent-url	(aucune)	Adresse de l'API des agents (par défaut celle envoyée par le Manager).
nm-agent run			Exécute l'agent : signaux de vie, faits, tâches, santé. Sort avec 2 et not_registered avant un enregistrement.
nm-agent status			Affiche l'enregistrement, les adresses, le pilote, la tâche en cours et le nombre de composants.
nm-agent facts			Affiche les faits de l'hôte en JSON.

Variables d'enroll.env

/etc/navin-manager-agent/enroll.env (mode 0600, propriétaire root) permet à l'unité navin-manager-agent-enroll.service d'enregistrer l'hôte sans taper nm-agent register. L'unité supprime le fichier une fois l'hôte enregistré, car le jeton ne sert qu'une fois.

Variable d'environnement	Description
NM_SERVER	Adresse du Manager, par exemple <manager-url>:8460.
NM_TOKEN	Jeton d'amorçage créé dans la console ou avec navin-manager enroll-token.
NM_CA_SHA256	Empreinte sha256 de l'autorité du Manager affichée à côté du jeton.
NM_REGISTER_ARGS	Options supplémentaires facultatives de nm-agent register, entre guillemets, par exemple --ca-file /etc/navin-manager-agent/manager-tls.pem ou --fqdn.