Configurer l'Agent Watchflare

Tous les champs de agent.conf expliqués : connexion Hub, TLS, intervalles heartbeat et métriques, Write-Ahead Log, journaux, et redéfinitions par variables d'environnement.

L’agent est configuré via un fichier TOML écrit à l’enrôlement. Vous avez rarement besoin de l’éditer à la main, car la plupart des champs sont définis par la commande register. Le fichier est rechargé au redémarrage du service.

Plateforme	Chemin
Linux	`/etc/watchflare/agent.conf`
macOS (Apple Silicon)	`/opt/homebrew/etc/watchflare/agent.conf`
macOS (Intel)	`/usr/local/etc/watchflare/agent.conf`

Attention

agent.conf contient agent_key, traitez-le donc comme un mot de passe. Le fichier est en mode 0640 (root:watchflare sous Linux). N’exposez jamais son contenu.

Exemple complet

# Hub connection
server_host = "hub.example.com"
server_port = "50051"

# Credentials (written at registration, do not edit manually)
agent_id  = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
agent_key = "base64encodedkey..."

# TLS
ca_cert_file = "/etc/watchflare/ca.pem"
server_name  = "watchflare"

# Collection intervals
heartbeat_interval = 5    # seconds
metrics_interval   = 30   # seconds

# Write-Ahead Log
wal_enabled    = true
wal_path       = "/var/lib/watchflare/metrics.wal"
wal_max_size_mb = 10

# Logging
log_file  = "/var/log/watchflare-agent.log"
log_level = "info"

# Container metrics (opt-in)
container_metrics = false

Champs

Connexion

Champ	Type	Défaut	Description
`server_host`	string	Aucun	Nom d’hôte ou adresse IP du Hub
`server_port`	string	`"50051"`	Port gRPC du Hub

Identifiants

Ces champs sont écrits automatiquement par register. Ne les éditez pas.

Champ	Type	Description
`agent_id`	string	UUID attribué par le Hub à l’enrôlement
`agent_key`	string	Clé HMAC utilisée pour signer les requêtes gRPC

TLS

Champ	Type	Défaut	Description
`ca_cert_file`	string	Aucun	Chemin du certificat CA du Hub, écrit à l’enrôlement
`server_name`	string	`"watchflare"`	Nom du serveur pour la validation du certificat TLS. Écrit à l’enrôlement d’après la réponse du Hub. Doit correspondre au CN du certificat.

Intervalles de collecte

Champ	Type	Défaut	Description
`heartbeat_interval`	int	`5`	Secondes entre deux pings heartbeat
`metrics_interval`	int	`30`	Secondes entre la collecte et l’envoi des métriques

Write-Ahead Log

Champ	Type	Défaut	Description
`wal_enabled`	bool	`true`	Active la mise en tampon locale des métriques lorsque le Hub est injoignable
`wal_path`	string	`{data_dir}/metrics.wal`	Chemin du fichier WAL
`wal_max_size_mb`	int	`10`	Taille maximale du WAL en Mo. Les enregistrements les plus anciens sont jetés (FIFO) lorsque la limite est atteinte.

Journaux

Champ	Type	Défaut	Description
`log_file`	string	`""`	Chemin du fichier de journal. Vide signifie stdout (capturé par le gestionnaire de services).
`log_level`	string	`"info"`	Verbosité des journaux : `debug`, `info`, `warn`, `error`. Redéfinissez à l’exécution avec `WATCHFLARE_DEBUG=1`.

Métriques conteneurs

Champ	Type	Défaut	Description
`container_metrics`	bool	`false`	Active les métriques par conteneur (Docker et Podman). Sous Linux, l’utilisateur `watchflare` doit être dans le groupe `docker`. Voir Métriques de conteneurs Docker.

Variables d’environnement

Quatre variables d’environnement peuvent redéfinir les chemins et le comportement par défaut. Elles sont utilisées en interne par le wrapper du service Homebrew sous macOS et n’ont généralement pas besoin d’être définies à la main.

Variable	Description
`WATCHFLARE_CONFIG_DIR`	Redéfinit le dossier de config (`/etc/watchflare` sous Linux)
`WATCHFLARE_DATA_DIR`	Redéfinit le dossier de données (`/var/lib/watchflare` sous Linux)
`WATCHFLARE_LOG_FILE`	Redéfinit le chemin du fichier de journal
`WATCHFLARE_DEBUG`	Mettez `1` pour forcer le niveau de journal debug, quel que soit `log_level`

Emplacement des fichiers

Linux

Chemin	Rôle	Propriétaire	Mode
`/usr/local/bin/watchflare-agent`	Binaire	root:root	755
`/etc/watchflare/agent.conf`	Config	root:watchflare	640
`/etc/watchflare/ca.pem`	Certificat CA	root:watchflare	640
`/var/lib/watchflare/`	Dossier de données	watchflare:watchflare	750
`/var/lib/watchflare/metrics.wal`	WAL	watchflare:watchflare	640
`/var/lib/watchflare/packages.state.json`	État des paquets	watchflare:watchflare	640
`/var/log/watchflare-agent.log`	Journaux	watchflare:watchflare	644
`/etc/systemd/system/watchflare-agent.service`	Service	root:root	644

macOS

$(brew --prefix) vaut /opt/homebrew sur Apple Silicon et /usr/local sur Intel.

Chemin	Rôle
`$(brew --prefix)/bin/watchflare-agent`	Binaire
`$(brew --prefix)/etc/watchflare/agent.conf`	Config
`$(brew --prefix)/etc/watchflare/ca.pem`	Certificat CA
`$(brew --prefix)/var/watchflare/`	Dossier de données
`$(brew --prefix)/var/watchflare/metrics.wal`	WAL
`$(brew --prefix)/var/watchflare/packages.state.json`	État des paquets
`$(brew --prefix)/var/log/watchflare-agent.log`	Journaux