Configuration Environment and CLI FR

🇬🇧 English · 🇫🇷 Français

Configuration : variables d'environnement, CLI et signaux

S'applique à Hydranos 4.4.

Cette page couvre tout ce qui n'est pas dans le fichier de configuration : les options de ligne de commande de hydranos et hydranos-update, chaque variable d'environnement que lit le code, et les signaux qui arrêtent proprement le démon. Elle s'adresse à vous si vous écrivez un fichier compose, une unité systemd ou un raccourci Windows. Pour le fichier TOML lui-même, commencez par Configuration : vue d'ensemble.

Aucune variable d'environnement ni option ne remplace une clé de configuration. Le seul moyen de changer un réglage comme un port ou un chemin est le fichier de configuration.

Ligne de commande de hydranos

hydranos --help affiche l'usage exact :

usage: hydranos [--config <path/to/default.toml>] [--console]
       hydranos --version
       hydranos reset-password <password> [path/to/default.toml]
       hydranos hash-password <password>

Option	Effet	Par défaut
--config <path> ou --config=<path>	Chemin du fichier de configuration. Si le fichier n'existe pas, hydranos en écrit un à partir du modèle intégré, avec data_dir réglé sur un dossier data voisin.	Linux et macOS : /config/default.toml. Windows : default.toml à côté de hydranos.exe (une installation 4.3 qui n'a que \config\default.toml sur le lecteur courant continue de l'utiliser).
--console	Windows : ouvre une nouvelle fenêtre de console quand le processus n'a pas été lancé depuis une console (le rattachement à un terminal parent a lieu de toute façon). Sans effet sous Linux.	désactivée
--version, -V	Affiche hydranos 4.x.y (le numéro de version) et quitte.	—
--help, -h	Affiche l'usage ci-dessus et quitte.	—

Deux sous-commandes agissent sur le fichier de configuration sans démarrer le démon. Elles doivent être le premier argument :

Sous-commande	Effet	Code de sortie
reset-password <password> [path]	Hache le mot de passe (bcrypt) et l'écrit comme [auth] password_hash dans le fichier, puis vérifie que le fichier s'analyse toujours et affiche hydranos: password set in <path>. Restart Hydranos for it to apply. Le chemin est le premier argument après le mot de passe autre que --config (donc reset-password '<pw>' --config /etc/hydranos/default.toml fonctionne aussi) ; sans chemin, le chemin par défaut ci-dessus. username n'est pas modifié. Un démon en cours garde l'ancien hash jusqu'à son redémarrage.	0 ; 2 pour un mot de passe manquant ou trop court ; 1 si le fichier ne peut pas être lu, écrit, ou ne s'analyserait plus
hash-password <password>	Affiche le hash bcrypt, à coller à la main dans password_hash.	0 ; 2 pour un mot de passe manquant ou trop court

Les deux refusent un mot de passe de moins de 8 caractères (hydranos: the password must be at least 8 characters). Le mot de passe est un argument de ligne de commande : il est visible des autres utilisateurs dans la liste des processus pendant que la commande tourne, et reste dans l'historique de votre shell. Procédures de récupération : Sécurité & accès.

Tout autre argument est signalé et sauté, et le démon démarre normalement. La ligne va sur stderr (la console, ou le journal du conteneur ; pas hydranos.log) :

hydranos: ignoring unknown argument "--foo"; starting anyway (see hydranos --help)

Les options de la séparation en processus de la 3.x (tout ce qui commence par --agent- ou --front-, aussi avec un seul tiret ou sous la forme --flag=value) reçoivent une ligne plus longue : ignoring <flag>: the agent/front split was removed in 4.x and Hydranos now runs as one process. Starting a normal instance. …, qui renvoie vers l'enrôlement de nœud. La valeur de --agent-addr, --agent-token, --agent-tls-cert, --agent-tls-key et --front-addr est sautée avec son option.

Un --config donné sans valeur affiche hydranos: --config needs a path; using <default path> et le chemin par défaut est utilisé.

hydranos --config /etc/hydranos/default.toml
hydranos --version
hydranos reset-password 'a-long-new-password' /etc/hydranos/default.toml

Sous Windows, hydranos.exe est un programme fenêtré : la sortie de --version, --help, reset-password et hash-password est écrite avant qu'il se rattache à une console, elle n'apparaît donc même pas dans un terminal (lu dans le code, non testé sous Windows). reset-password écrit quand même le fichier et règle le code de sortie ($LASTEXITCODE dans PowerShell) ; vérifiez plutôt la version dans l'en-tête de l'interface web. Les lignes d'argument inconnu et le journal apparaissent bien dans le terminal qui l'a lancé.

L'image Docker ne crée pas le fichier de la même façon : son entrypoint copie lui-même le modèle et règle data_dir sur le dossier de configuration (/config, pas /config/data). Voir Docker.

hydranos-update

hydranos-update remplace les binaires par une version publiée sur github.com/Kheopsian/Hydranos. Il est livré dans le zip Windows et l'archive Linux, pas dans l'image Docker (mettez plutôt l'image à jour).

Option	Effet	Par défaut
--check	Affiche la dernière version publiée et quitte	—
--dir <path>	Dossier qui contient hydranos / hydranos.exe	. (dossier courant)
--tag <vX.Y.Z>	Installe cette version au lieu de la dernière	dernière
--config <file>	Le fichier de configuration du démon, lu seulement pour faire passer les téléchargements de l'outil de mise à jour par le même chemin que les requêtes du démon ([daemon] egress, le kill switch, le mode réseau). Un fichier qui ne s'analyse pas arrête l'outil ; un fichier absent signifie la route par défaut. Quand la route n'est pas le direct simple, ou que le kill switch est armé, il affiche d'abord une ligne network: ….	<dir>/default.toml
--yes, -y	Ne demande pas de confirmation avant de remplacer	demande [y/N]
--help, -h	Affiche l'aide et quitte	—

Les options inconnues sont ignorées. Comportement, d'après le code :

• Rien n'est remplacé à moins que l'archive soit téléchargée et que son SHA-256 corresponde au fichier .sha256 publié à côté.
• Seuls les binaires déjà présents dans --dir sont remplacés ; default.toml, le dossier de données et hydranos.log ne sont pas dans l'archive et ne sont jamais touchés.
• Si la version installée est déjà la dernière et qu'aucun --tag n'est donné, il s'arrête là.
• Windows : si hydranos.exe tourne, il déclenche l'événement d'arrêt du démon (Local\HydranosStop), qui donne le même arrêt propre que Quit Hydranos dans la zone de notification, et attend jusqu'à 60 s. Un démon antérieur à la 4.4 n'a pas cet événement : l'outil se rabat alors sur taskkill /IM hydranos.exe /T sans /F, qui ne l'arrête pas ; quittez donc d'abord depuis la zone de notification. S'il tourne encore au bout de 60 s (un très gros vidage), l'outil de mise à jour se termine par hydranos is still running after 60s -- stop it yourself, nothing was replaced. Une fois hydranos.exe arrêté, il remplace les fichiers. Voir Windows. Check for updates dans la zone de notification lance hydranos-update.exe --dir <its own folder> dans une fenêtre cmd.
• Linux : il n'arrête rien. Il remplace les fichiers et affiche note: restart the service for the new binaries to take effect.

# packaging/install.sh l'installe dans /opt/hydranos ; la config est dans /etc/hydranos, nommez-la donc
/opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml --check
sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml --yes && sudo systemctl restart hydranos

hydranos-engine (disparu)

Les versions publiées ne livrent plus hydranos-engine (hydranos-engine.exe) : chaque moteur tourne dans le processus hydranos, et les seuls binaires des archives sont hydranos et hydranos-update. Une copie laissée dans /opt/hydranos par une installation plus ancienne n'est jamais lancée et peut être supprimée. Historique : Mettre à jour depuis la 3.x.

Variables d'environnement lues par hydranos

Elles sont lues par le démon lui-même, sur toutes les plateformes sauf mention contraire. Elles sont lues une seule fois, au démarrage (ou la première fois que le chemin de code s'exécute) : les changer demande un redémarrage.

Pour les utilisateurs

Variable	Valeurs	Par défaut	Effet
RUST_LOG	un filtre tracing : warn, info, debug, ou par module, ex. info,typhon_engine::tracker=debug	info	Niveau de journalisation pour la console, hydranos.log et l'onglet Journaux (Logs) à la fois.
HYDRANOS_LOG_STDOUT	n'importe quelle valeur	non définie	Quand la variable existe (n'importe quelle valeur, même 0 ou false), aucun hydranos.log n'est écrit. La sortie console est toujours active ; cette variable ne fait que supprimer le fichier. Sans elle, le fichier est écrit à côté du fichier de configuration et tourne de lui-même à 128 MiB, en gardant quatre anciens fichiers (hydranos.log.1 à .4) (voir Supervision & journaux).
HYDRANOS_STOP_TIMEOUT	une durée : 120 (secondes), 60s, 2m, 1m30s, 1h (unités de la plus grande à la plus petite, chacune une fois ; pas de signe, pas de fraction)	120	Borne le vidage des données de reprise lors d'un arrêt propre. Au-delà, Hydranos part avec ce qui est écrit et journalise shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved ; sinon shutdown flush complete. 0 signifie : ne pas attendre le vidage. Une valeur qui ne s'analyse pas (30s1m, 1.5m, -5, vide) journalise au démarrage HYDRANOS_STOP_TIMEOUT="…" is not a duration (use 120, 60s, 2m or 1m30s); using 120 s et utilise 120. Gardez le délai d'arrêt de votre superviseur au-dessus : Exploiter Hydranos.
TYPHON_ANNOUNCE_PROXY	une URL de proxy, ex. socks5h://192.0.2.10:1080	non définie	Proxy de repli pour les annonces HTTP/HTTPS aux trackers et les téléchargements de webseed de chaque moteur qui n'a pas de proxy à lui (pas d'announce_proxy, pas de proxy SOCKS5 pour les pairs), ainsi que pour les flux RSS et les téléchargements de .torrent faits pour un tel moteur. Pour un tel moteur, les trackers UDP ne reçoivent pas d'annonce tant qu'elle est définie. Une URL qui ne s'analyse pas fait échouer ces annonces ; elles ne partent jamais en direct à la place. Une valeur vide équivaut à non définie. Le sous-onglet Réseau (Network) la liste sous Défini dans l'environnement (Set in the environment). Clés par moteur : VPN & sortie réseau.
TYPHON_DISABLE_UTP	1 ou true (casse indifférente)	non définie	Pas de socket uTP : pairs en TCP uniquement, pour tous les moteurs.
HYDRANOS_WORKER_THREADS	entier > 0	nombre de cœurs CPU, plafonné à 32	Taille du pool principal de threads de travail.

Réglage fin et diagnostic (laissez non définies sauf si vous savez pourquoi)

Variable	Valeurs	Par défaut	Effet
HYDRANOS_ENGINE_NET	0, false ou off	activée	Chaque moteur charge ses torrents mais reste hors du réseau : pas d'écouteur, pas de pairs, pas d'annonces, pas de DHT, et aucun tunnel WireGuard géré n'est monté. La redirection de port (NAT-PMP/UPnP) est quand même demandée pour les ports des moteurs, sauf si auto_port_forward = false. Toute autre valeur, ou l'absence de la variable, signifie activé. Sert à inspecter une copie d'un catalogue sans prévenir ses trackers.
HYDRANOS_LINK_SCAN_THREADS	entier > 0, plafonné à 256	16	Vérifications de fichiers en parallèle de l'analyseur de liens physiques en arrière-plan (utilisé par les workflows, voir Workflows).
TYPHON_SESSION_RUNTIMES	entier > 0	nombre de cœurs CPU (sans plafond)	Nombre de runtimes qui portent les connexions aux pairs.
TYPHON_RECHECK_TORRENTS	entier > 0	4	Nombre de torrents vérifiés (hash) en même temps.
TYPHON_RECHECK_CONCURRENCY	entier > 0	16	Lectures de pièces en parallèle au sein d'une revérification.
TYPHON_NO_MSE	1	non définie	Les connexions sortantes vers les pairs n'essaient pas le repli chiffré (MSE/PE).
TYPHON_DIAL_TRACE_IH	un info hash hexadécimal de 40 caractères	non définie	Journalise chaque décision de connexion sortante pour ce seul torrent. Toute autre longueur est ignorée.
TYPHON_RESUME_JSON	1	non définie	Écrit aussi l'état de reprise sous forme de fichiers JSON à côté du state.db de chaque moteur.
TYPHON_STATE_DB	0	activée	Désactive le state.db de chaque moteur et ne garde que les fichiers de reprise JSON. Débogage uniquement : ne la définissez pas sur une instance à laquelle vous tenez.

Pour toutes les variables entières ci-dessus, une valeur qui ne s'analyse pas (ou qui vaut 0) est ignorée et la valeur par défaut s'applique. HYDRANOS_STOP_TIMEOUT suit ses propres règles (tableau ci-dessus).

Des variables de test HYDRANOS_INTEROP_* existent dans le source mais ne sont compilées que dans la suite de tests.

Variables lues uniquement par l'entrypoint Docker

Le entrypoint.sh de l'image les lit avant de lancer hydranos. Elles n'ont aucun effet sur une installation bare metal ou Windows.

Variable	Valeurs	Par défaut	Effet
HYDRANOS_CONFIG_DIR	un chemin	/config	Dossier où l'entrypoint cherche default.toml, le crée au premier lancement (avec data_dir réglé sur ce dossier) et le passe en --config. C'est aussi le dossier qui reçoit un chown quand PUID/PGID sont définies.
PUID / PGID	identifiants numériques	non définies (exécution en root)	Quand l'une des deux est définie, le démon tourne avec cet uid/gid (l'autre vaut 1000 par défaut). Ignorées si le conteneur tourne déjà avec un utilisateur non root.
HYDRANOS_SKIP_CHOWN	1	non définie	Avec PUID/PGID : saute le chown récursif du dossier de configuration. Les dossiers de charge utile ne reçoivent jamais de chown.
HYDRANOS_CAP_NET_ADMIN	1	non définie	Avec PUID/PGID : garde CAP_NET_ADMIN après l'abandon des privilèges (comme capability ambiante, pour que les commandes ip et wg en héritent), si le conteneur l'a reçue (cap_add: [NET_ADMIN]). WireGuard géré en a besoin dans cette configuration ; le routage par fwmark aussi. Sans cette autorisation, il affiche hydranos: CAP_NET_ADMIN not available, add --cap-add=NET_ADMIN for managed WireGuard and fwmark routing et démarre sans. Sans PUID/PGID, le démon tourne en root et garde de toute façon la capability accordée. Voir WireGuard géré.

L'entrypoint relève aussi la limite de fichiers ouverts (ulimit -n 1000000, avec repli sur 200000, sauté sans message si ce n'est pas permis), et lance toujours hydranos avec --config "$HYDRANOS_CONFIG_DIR/default.toml".

Il refuse les variables 3.x HYDRANOS_ENGINE_ID et HYDRANOS_ENGINES : quand l'une d'elles n'est pas vide, il affiche sur stderr hydranos: ignoring <VAR>: the 3.x agent mode was removed in 4.x and Hydranos now runs as one process. Starting a normal instance on <config dir>/default.toml. … Remove <VAR> from the container's environment to silence this., puis crée la configuration et démarre comme d'habitude.

L'image elle-même définit une variable :

Variable	Valeur	Effet
MALLOC_CONF	prof:true,prof_active:true,lg_prof_sample:19,prof_prefix:/config/jeprof	Active l'échantillonnage du tas de jemalloc, pour que SIGUSR1 puisse écrire un profil de tas (voir Signaux). Les profils vont dans /config/jeprof.* même si vous avez déplacé HYDRANOS_CONFIG_DIR.

Variables qui ne font rien en 4.4

Variable	Où vous avez pu la voir	Ce qui se passe réellement
HYDRANOS_ENGINE_BIN	unités systemd d'avant la 4.4	Lue par rien (retirée de l'unité livrée).
HYDRANOS_DATA_DIR	entrypoints d'avant la 4.4	Jamais lue par hydranos, plus exportée ; le dossier de données vient uniquement de [daemon] data_dir.
HYDRANOS_ENGINE_ID, HYDRANOS_ENGINES	installations 3.x	Refusées par l'entrypoint avec un message (ci-dessus) ; le conteneur démarre normalement sur sa configuration. Supprimez-les.
HYDRANOS_CONFIG_DIR hors Docker	unités systemd écrites par le script d'enrôlement avant la 4.4 (les unités 4.4 ne la définissent plus)	Lue uniquement par entrypoint.sh ; le démon utilise --config.
HYDRANOS_AGENT_TOKEN, HYDRANOS_ENGINE_ROLE, HYDRANOS_ENGINE_LISTEN_PORT, HYDRANOS_ENGINE_ENABLE_IPV6	commentaires d'anciens modèles de default.toml	Lues par rien.
TYPHON_SELF_IPS	anciennes documentations	Lue uniquement par le hydranos-engine autonome, qui n'est plus livré ; jamais par hydranos.
Toute variable HYDRA_* (HYDRA_LOG_STDOUT, HYDRA_STOP_TIMEOUT, HYDRA_CONFIG_DIR, …)	anciennes pages du wiki	Aucun code ne lit un préfixe HYDRA_. Utilisez le nom HYDRANOS_* quand il en existe un dans les tableaux ci-dessus.
TYPHON_ANNOUNCE_PASSKEY, TYPHON_ANNOUNCE_V6_PROXY	anciennes pages du wiki	N'existent pas. Les passkeys par tracker se règlent dans l'onglet Trackers : Trackers & annonces.

Le docker-compose.yml livré règle stop_grace_period: 150s et propose HYDRANOS_STOP_TIMEOUT: 120 en commentaire (voir Docker).

Le script d'enrôlement install.sh lit HYDRANOS_VERSION_PIN (un tag de version) dans tous ses chemins, tag de l'image Docker compris ; sans elle, le nœud prend la version du contrôleur dans son /health. C'est le script, pas le démon. Voir Nœuds & plusieurs machines.

Définir une variable sous Windows

Un raccourci ne peut pas définir de variable d'environnement. Sans --config, hydranos.exe utilise le default.toml placé à côté de lui : le --config ci-dessous n'est donc nécessaire que pour une configuration ailleurs. Définissez-la soit pour un seul démarrage dans PowerShell ($env:RUST_LOG = "debug"; & "C:\Hydranos\hydranos.exe" --config "C:\Hydranos\default.toml"), soit pour votre compte avec setx RUST_LOG debug ou Démarrer › tapez environment › Edit environment variables for your account (intitulé Windows ; en français « Modifier les variables d'environnement pour votre compte »). Un Hydranos en cours garde les anciennes valeurs : quittez depuis la zone de notification et relancez-le (déconnectez-vous puis reconnectez-vous si un raccourci du dossier Démarrage ne la voit toujours pas). Détails : Windows.

Signaux (Linux)

Signal	Effet
SIGTERM	Arrêt propre. Le serveur web cesse d'accepter des requêtes (le flux d'événements et le suivi en direct du journal de l'interface se ferment d'eux-mêmes ; ce qui est encore ouvert au bout de 5 s est laissé de côté), chaque moteur envoie stopped à ses trackers (5 s au plus), l'état de reprise de chaque moteur est écrit, un thread par moteur, dans la limite de HYDRANOS_STOP_TIMEOUT, les tunnels WireGuard gérés sont démontés, puis le processus se termine avec le code 0. Journalisé sous la forme SIGTERM received, draining the API and flushing resume data.
SIGINT (Ctrl+C)	Même arrêt propre.
SIGUSR1	Écrit un profil de tas jemalloc vers le prof_prefix de MALLOC_CONF (/config/jeprof.* sous Docker). Sans prof:true dans MALLOC_CONF (bare metal, par défaut), aucun profil n'est attendu (non testé en bare metal) ; si jemalloc refuse le vidage, le journal affiche jemalloc prof.dump failed: …. N'arrête rien.
SIGUSR2	Règle à 0 la décroissance dirty/muzzy de jemalloc sur chaque arène, ce qui rend tout de suite au système la mémoire libérée, et journalise la taille résidente avant/après. Le réglage reste actif jusqu'au prochain redémarrage (plus de CPU, moins de mémoire retenue). N'arrête rien.
SIGHUP, SIGQUIT, autres	Pas de gestionnaire : comportement système par défaut (le processus se termine sans vidage ; en PID 1 dans un conteneur, ils sont ignorés). Il n'y a pas de rechargement de configuration sur SIGHUP.
SIGKILL	Fin immédiate. L'état de reprise retombe sur la dernière sauvegarde périodique (toutes les 300 s) : la progression depuis est perdue et revérifiée au démarrage suivant.

À savoir :

• Le gestionnaire SIGTERM/SIGINT est installé avec l'écoute HTTP, dans la première seconde du démarrage, avant le chargement des torrents. Un arrêt qui arrive pendant le chargement est entendu : le chargement se termine, rien de plus ne démarre, et les départs et le vidage ont lieu (stop requested during startup; flushing and leaving).
• Le pire cas est d'environ 5 s (vidange) + 5 s (départs) + HYDRANOS_STOP_TIMEOUT, soit 130 s par défaut. Laissez plus que cela à votre superviseur (stop_grace_period / docker stop -t, systemd TimeoutStopSec ; les fichiers livrés utilisent 150 s) : le dimensionnement est sur Exploiter Hydranos.
• Redémarrer depuis l'interface web ou l'API (Appliquer et redémarrer (Apply & restart), POST /api/settings/restart) n'est pas un signal mais prend le même chemin (journalisé restart request received, …), puis quitte avec le code 75 (EX_TEMPFAIL) au lieu de 0, pour que Restart=on-failure, restart: unless-stopped ou toute politique qui redémarre sur échec relance Hydranos. Un processus lancé à la main reste arrêté. Voir Exploiter Hydranos.
• Toutes les 300 s (Linux uniquement), le démon journalise aussi une ligne jemalloc allocated=… resident=….

Windows

Windows n'a pas de signaux. Chacun de ces déclencheurs produit le même arrêt propre que SIGTERM (vidange, départs, vidage borné), journalisé sous la forme <trigger>: draining the API and flushing resume data :

• Quit Hydranos dans le menu de l'icône de la zone de notification (tray quit) ;
• Ctrl+C ou Ctrl+Break dans la console à laquelle le processus est rattaché (lancé depuis un terminal, ou avec --console) ;
• la fermeture de cette fenêtre de console (console closed), la déconnexion (sign-out), l'arrêt de Windows (system shutdown) ;
• hydranos-update, via l'événement d'arrêt (une ligne d'information stop requested by the updater, puis la vidange journalisée comme tray quit: …) ; l'événement, comme l'icône de la zone de notification, existe une fois les torrents chargés.

Windows ne laisse que quelques secondes après une fermeture de console, une déconnexion ou un arrêt du système, donc le vidage peut y être écourté : quittez depuis la zone de notification avant d'éteindre. La façon dont ces événements de console atteignent un hydranos.exe fenêtré lancé sans console n'a pas été testée. taskkill /F et Fin de tâche (End task) dans le Gestionnaire des tâches ne lancent jamais le vidage ; taskkill sans /F ne fait rien. Un redémarrage depuis l'interface web enregistre de la même façon, puis hydranos.exe lance lui-même son successeur (mêmes arguments) et quitte avec le code 75. SIGUSR1/SIGUSR2 et la ligne de statistiques mémoire n'existent pas sous Windows (pas de jemalloc). Lanceurs de service et options de démarrage : Windows.

Voir aussi

• Configuration : vue d'ensemble — le fichier de configuration et où chaque section est documentée
• Exploiter Hydranos — arrêt, redémarrage, sauvegarde, mises à jour
• Supervision & journaux — hydranos.log, l'onglet Journaux, /health, /metrics
• VPN & sortie réseau — TYPHON_ANNOUNCE_PROXY et ce qui sort par où
• Docker — le fichier compose et le volume /config