HYPHApar S33D
Documentation › Installer l'agent

Référence de configuration de l'agent

Un fichier principal, des compléments dans conf.d, et une commande qui vérifie le tout avant de redémarrer.

Où se trouve la configuration

SystèmeFichier principalCompléments
Linux/etc/hypha/hypha.yaml (600)/etc/hypha/conf.d/*.yaml
WindowsC:\ProgramData\Hypha\hypha.yamlC:\ProgramData\Hypha\conf.d\*.yaml
Docker/etc/hypha/hypha.yaml dans le conteneur/etc/hypha/conf.d/ monté

Règles de lecture :

Avant chaque redémarrage :

sudo hypha-agent check-config

La commande affiche la configuration fusionnée, secrets masqués, et nomme le fichier d'origine de chaque erreur.

Clés générales

CléDéfautRôle
api_key(obligatoire)clé d'ingestion, hph_ suivi de 40 caractères
urlhttps://hypha.s33d.frserveur de collecte ; votre adresse en auto-hébergement
hostnamenom systèmenom de l'hôte dans HYPHA
tags{}étiquettes ajoutées à tout ce que l'agent envoie ; clés a-z 0-9 _ . - /
interval15scadence des mesures et des contrôles (1 s au moins)
tls_skip_verifyfalsene coupez la vérification du certificat que pour un serveur auto-hébergé à certificat interne
proxy(vide)mandataire HTTP ; vide = variables HTTPS_PROXY et NO_PROXY
buffer.dir, buffer.max_mb/var/lib/hypha/buffer, 256tampon disque des envois en échec ; les plus anciens partent au-delà

Journaux

logs:
  enabled: true
  journald: true                       # Linux : journal systemd
  windows_eventlog: [System, Application]
  files:
    - {path: /var/log/nginx/*.log, service: nginx, source: nginx}
    - {path: /srv/app/logs/*.json, service: boutique}
  exclude_patterns: ["GET /health"]    # expressions régulières, lignes jamais envoyées

Une ligne JSON est décodée : message ou msg devient le message, level ou severity le statut, le reste part en attributs. Un message est tronqué à 32 Kio. Pour réduire le volume côté serveur, voir aussi les filtres d'exclusion.

Processus, réseau, conteneurs

processes:
  enabled: true
  include: ["^java", "gunicorn"]   # toujours relevés, en plus des 30 premiers par CPU et par mémoire
network:
  enabled: true
  # exclude_interfaces: [lo, "docker*", "veth*", "br-*", "virbr*", "cali*", "flannel*", "cni*"]
containers:
  enabled: auto                     # auto = si /var/run/docker.sock existe

Contrôles

checks:
  systemd_units: [nginx.service]    # suivies ; une unité en échec est TOUJOURS signalée
  windows_services: [W3SVC]         # suivis ; un service automatique arrêté est signalé
  windows_services_exclude: ["^Veeam"]
  windows_auto_services: auto       # auto, always, never
  http:
    - {name: site, url: "https://exemple.fr/", expect_status: 200, timeout: 5s}
  tcp:
    - {name: base, address: "192.0.2.5:5432", timeout: 3s}
  processes:
    - {name: nginx}
    - {name: gunicorn, match: contains, min: 2}
    - {name: "^php-fpm[0-9.]*$", match: regex, min: 1, max: 1}

Les contrôles HTTP et TCP partent de l'hôte : ils voient les adresses internes. Pour des tests planifiés avec historique et assertions, voir les tests synthétiques.

Intégrations

Chaque intégration s'active seule quand son logiciel est détecté (enabled: auto), ou se force (true) et se coupe (false). Son état apparaît dans Réglages › Agents : ok, absent, coupée, ou l'erreur rencontrée. Le détail de chacune est sur les pages Intégrations, Bases de données, SNMP, Clouds, Virtualisation, Kubernetes, IA et GPU et Collecte générique (integrations.openmetrics, integrations.nagios : des listes, qui s'additionnent elles aussi d'un fichier conf.d à l'autre).

Plusieurs instances

Pour lire plusieurs cibles d'une même intégration (ovhcloud, mysql, redis, memcached, rabbitmq, mongodb, opensearch, kubernetes, libvirt, proxmox, aws, scaleway, azure, gcp, ollama, phpfpm, varnish, squid, lighttpd, supervisord, pgbouncer, proxysql, clickhouse, couchdb, couchbase, zookeeper, ceph, openldap, powerdns, powerdns_recursor, keycloak, nexus, harbor, fluentd, wazuh, suricata), donnez une liste instances. Chaque entrée porte un name (minuscules, chiffres, - et _), reprend les valeurs par défaut de l'intégration et s'additionne d'un fichier conf.d à l'autre. Ses données portent l'étiquette instance_name.

integrations:
  redis:
    instances:
      - {name: sessions, address: "127.0.0.1:6379"}
      - {name: file, address: "127.0.0.1:6380", password: "…"}

Métriques applicatives et traces

statsd:
  enabled: true
  listen: 127.0.0.1:8125     # format DogStatsD : nom:valeur|g|c|ms|h|s|#etiquette:valeur
otlp:
  enabled: false
  listen: 127.0.0.1:4318     # OTLP/HTTP : l'agent relaie vers HYPHA en ajoutant la clé

Une écoute hors de la boucle locale déclenche un avertissement : elle ouvre le port au réseau.

La réception syslog (syslog:, coupée par défaut) est décrite dans Collecte générique.

Canal de contrôle, mises à jour, actions

control:
  enabled: true
  interval: 30s            # l'agent interroge le serveur ; aucun port ouvert sur l'hôte
auto_update: false         # suivre la version cible fixée dans Réglages › Agents
actions:
  enabled: false
  allow: [restart_service, start_service, stop_service]   # aussi : run_script, update_agent
  services: ["*"]
  deny_services: ["sshd*", "ssh*", "hypha-agent*", "systemd-*"]
  scripts:
    vider-cache: /etc/hypha/scripts/vider-cache.sh
  timeout: 120s
synthetics:
  enabled: false           # emplacement privé de tests synthétiques
  max_concurrent: 4
inventory:
  enabled: true
  interval: 6h
  packages: true

Les actions sont coupées par défaut. Le service de l'agent n'est jamais touché, quelle que soit la liste. Un script nommé doit avoir un chemin absolu, appartenir à root et n'être modifiable ni par le groupe ni par les autres ; il est lancé sans argument et sa sortie est bornée à 64 Kio. Voir Explication et réparation et Flotte et mises à jour.

SNMP

snmp:
  enabled: true
  interval: 60s
  devices:
    - {name: switch-baie-1, address: 192.0.2.10, version: 2c, community: lecture, tags: {role: switch}}
  traps: {enabled: false, listen: "0.0.0.0:162", community: public}

Le détail des versions, des profils et des réglages SNMPv3 est sur la page SNMP. Les secrets SNMP restent dans la configuration de l'agent : ils ne partent jamais vers le serveur.

Mise à jour : 20 novembre 2026