🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page s'adresse à vous si vous ouvrez default.toml ou l'onglet Config et voulez savoir ce que fait vraiment un réglage avant de le modifier. À la fin, vous saurez où se trouve le fichier, comment il est organisé, quand une modification prend effet, ce que l'éditeur web peut changer, quelles clés absentes changent le comportement, et quelles clés ne font rien en 4.4 (Hydranos les nomme au démarrage). La référence clé par clé se trouve sur trois sous-pages : Config : démon, auth & global, Config : moteurs & drain race et Config : environnement, CLI & signaux.

Hydranos lit un seul fichier TOML, default.toml, indiqué par --config <path>. Sans --config, le chemin est /config/default.toml, sauf sous Windows, où c'est le default.toml à côté de hydranos.exe.

Détails par plateforme : Docker, Linux (bare metal), Windows. Sous Windows, modifiez soit depuis Config › Paramètres avancés (default.toml) (Advanced settings (default.toml)), soit quittez Hydranos depuis la zone de notification, modifiez le fichier dans le Bloc-notes, puis relancez Hydranos. Quels fichiers Hydranos conserve à côté de la configuration (store, état de reprise, journal) : Architecture.

Quand le fichier est absent, Hydranos l'écrit à partir du modèle compilé dans le binaire (le même texte que configs/default.toml dans le dépôt) et remplace data_dir = "/config" par le dossier data voisin du fichier de configuration. L'entrypoint Docker fait la même chose avant le démarrage du binaire, mais règle data_dir sur le dossier de configuration lui-même. Une installation Docker garde donc tout dans /config, et une installation binaire a un sous-dossier data/.

Quand le fichier ne peut pas être analysé, Hydranos s'arrête au démarrage avec l'erreur d'analyse. Une valeur du mauvais type (api_port = "8199" au lieu de api_port = 8199) est aussi une erreur d'analyse.

Règles du fichier :

• Les clés de premier niveau viennent avant le premier en-tête [table]. En 4.4, il n'y en a qu'une, auto_port_forward. Ajoutée en fin de fichier, elle atterrit dans la dernière table et est ignorée sans message.
• Les clés que Hydranos sait mortes sont nommées au démarrage, une ligne WARN chacune (voir Clés qui ne font rien en 4.4). Toute autre clé inconnue est encore acceptée sans avertissement : une faute de frappe (enable_dth = true) n'est pas une erreur, la clé n'est simplement jamais lue. Vérifiez l'orthographe sur les sous-pages.
• Chemins Windows : TOML traite \ entre guillemets doubles comme un échappement. Écrivez "C:/Hydranos/data" ou 'C:\Hydranos\data'.
• Les blocs de moteur utilisent la syntaxe TOML de tableau de tables (un bloc engine, voir l'exemple plus bas). C'est le seul moyen d'ajouter un moteur en plus de race et hoard ; leurs clés sont sur Config : moteurs & drain race.

Tous les réglages ne sont pas dans default.toml. Beaucoup de choses que vous configurez dans l'interface web sont enregistrées dans le store, <data_dir>/hydra.db, et certaines uniquement dans votre navigateur.

flowchart LR
    subgraph FILE["default.toml (dossier de configuration)"]
        F1["daemon : adresse, port, clé API, data_dir,<br/>sortie réseau, kill switch"]
        F2["auth : compte admin"]
        F3["race, hoard, blocs engine : réglages des moteurs,<br/>file, limites de partage et de débit"]
        F4["race_drain"]
        F5["tables par hôte de tracker : passkeys, famille IP,<br/>seed minimum, muet, masqué"]
        F6["mode réseau, proxy"]
        F7["dedup, mcp, rss, vpn_speedtest, auto_port_forward"]
    end
    subgraph STORE["hydra.db (data_dir)"]
        S1["catégories"]
        S2["nœuds et jetons d'enrôlement"]
        S3["workflows"]
        S4["dossiers surveillés"]
        S5["listes et bannissements du filtre IP"]
        S6["politique de drain par volume"]
        S7["jobs"]
        S8["flux RSS, règles et leur historique"]
        S9["limites de partage par torrent"]
        S10["plafond de débit global du client"]
    end
    subgraph BROWSER["localStorage du navigateur"]
        B1["langue, thème, onglets masqués"]
        B2["unités d'affichage"]
        B3["copie de la clé API"]
    end
    UI["Interface web et API REST"] --> FILE
    UI --> STORE
    UI --> BROWSER

Conséquences :

• Sauvegarder default.toml seul ne suffit pas. Catégories, nœuds, workflows, dossiers surveillés, filtre IP, flux et règles RSS sont dans hydra.db, et les fichiers de fournisseur WireGuard gérés dans <data_dir>/wireguard (WireGuard géré). Sauvegardez ensemble le dossier de configuration et le dossier de données : Exploiter Hydranos.
• Chaque navigateur a sa propre langue, son thème et ses unités. Les changer dans un navigateur ne change rien ailleurs.
• Les variables d'environnement et les options de ligne de commande sont une quatrième source, hors du fichier : Config : environnement, CLI & signaux.

Hydranos lit default.toml une seule fois, au démarrage. Ensuite, le fichier n'est relu que lorsque Hydranos l'écrit lui-même (l'éditeur web, l'onglet Réseau, l'onglet Trackers, la carte Duplicate data, l'ajout ou la suppression d'un moteur, les routes de débit et de limites de partage, un changement de port à chaud, Changer le mot de passe (Change password), une rotation de clé API de nœud, Revenir aux valeurs par défaut (Reset to defaults), la configuration du premier lancement). Chacune de ces écritures recharge tout le fichier en mémoire, et les réglages utilisés par la couche web et API s'appliquent aussitôt. La plupart des réglages des moteurs attendent un redémarrage, car les moteurs sont construits au démarrage ; les plafonds de débit, le choker, peer_timeout, la file et les limites de partage font exception et sont appliqués aux moteurs en marche à l'enregistrement.

Appliquer et redémarrer (Apply & restart) (ainsi que le redémarrage après Revenir aux valeurs par défaut (Reset to defaults) ou la carte Duplicate data) arrête Hydranos de la même façon propre qu'un SIGTERM (départs envoyés aux trackers, état de reprise enregistré), puis quitte avec le code 75 pour que le superviseur le relance : un conteneur Docker avec restart: unless-stopped, le hydranos.service livré (Restart=on-failure) et l'unité d'enrôlement de nœud (Restart=always) le font tous. Sous Windows, Hydranos lance lui-même son successeur avant de partir. Un binaire lancé à la main dans un shell reste arrêté. Détails : Exploiter Hydranos et Config : environnement, CLI & signaux.

Config › Paramètres avancés (default.toml) affiche le fichier. Il est construit à partir de GET /api/settings, qui renvoie tout le fichier en JSON, secrets compris (api_key, password_hash, passkeys).

À part Réseau et Import, un sous-onglet n'apparaît que si l'une de ses sections existe dans le fichier. listen_port, bind_interface, enable_ipv6, allow_direct et les clés de proxy et d'annonce de [race]/[hoard] sont masquées dans Session Race et Session Hoard : c'est le sous-onglet Réseau qui les gère. Les clés gluetun_* et wireguard_* ne sont pas masquées : le sous-onglet Réseau les écrit, mais elles restent affichées (et modifiables) dans les deux sous-onglets. Ce masquage ne vaut que pour [race]/[hoard] : [daemon] egress, bind_interface, kill_switch apparaissent sous Général, et [proxy] sous Other (avec une description héritée de la 3.x, « utilisé par l'orchestrateur (IP publique et test de débit) » (used by the orchestrator (public IP + speedtest)) ; la section est le proxy propre du démon). Chaque clé et section de la liste d'avertissements de démarrage ci-dessous est masquée. Les clés de premier niveau (auto_port_forward) et les blocs de moteur ne sont jamais affichés ; les blocs de moteur se gèrent depuis Nodes › This node › + Add an engine.

Bug connu en 4.4 : l'éditeur masque aussi [vpn_speedtest] iperf3_port, interval_secs et duration_secs, que la 4.4 lit. Modifiez-les à la main dans default.toml : Config : démon, auth & global.

Comment Enregistrer les réglages (Save settings) écrit le fichier :

flowchart TD
    A["Enregistrer les réglages"] --> B["POST /api/settings<br/>clés modifiées uniquement"]
    B --> C{"clé déjà présente dans<br/>cette section du fichier ?"}
    C -- non --> L{"clé race ou hoard<br/>de la liste à chaud, ou enable_lsd ?"}
    L -- non --> X["erreur : key not found<br/>fichier inchangé"]
    L -- oui --> K["clé ajoutée à cette section"]
    C -- oui --> D["valeur remplacée sur place<br/>commentaires et ordre conservés"]
    K --> E
    D --> E{"fichier toujours en TOML valide ?"}
    E -- non --> Y["erreur<br/>fichier inchangé"]
    E -- oui --> F["fichier écrit<br/>tout le fichier rechargé en mémoire"]
    F --> G["réglages web et API : à chaud<br/>si le fichier se charge toujours comme configuration"]
    F --> H["clés moteur à chaud : appliquées<br/>aux moteurs en marche tout de suite"]
    F --> I["autres réglages des moteurs : au prochain redémarrage"]

Ce qui en découle :

• L'éditeur ne change que les clés déjà présentes dans le fichier, à une exception près, et n'ajoute jamais de section. L'exception : dans [race] et [hoard], les clés à chaud (upload_rate_limit, download_rate_limit, peer_timeout, choking, max_uploads_per_torrent, active_downloads, queueing, active_seeds, active_limit, dont_count_slow_torrents, slow_torrent_dl_rate_threshold, slow_torrent_ul_rate_threshold, slow_torrent_inactive_timer, max_ratio, max_seeding_time, max_inactive_seeding_time, share_limit_action) et enable_lsd peuvent être ajoutées par un enregistrement. L'éditeur affiche la plupart d'entre elles à leur valeur par défaut quand le fichier ne les contient pas (toutes sauf peer_timeout, max_uploads_per_torrent et active_downloads), donc en enregistrer une l'ajoute. Pour régler toute autre clé que le fichier ne contient pas (enable_webseed, enable_udp_trackers, aio_threads, add_block_enabled, reserve_free_gb, update_check_disabled, auto_port_forward, la section [mcp] ou [rss]…), modifiez default.toml à la main et redémarrez. Mettre à jour Hydranos n'ajoute jamais de nouvelles clés à un fichier existant non plus. Les exceptions sont les formulaires dédiés, qui créent ce dont ils ont besoin : le sous-onglet Réseau, l'onglet Trackers, la carte Duplicate data et + Add an engine.
• Seule la syntaxe TOML est vérifiée, pas les types ni les plages. api_port = 70000 ou max_connections = 4000.5 est écrit sur le disque ; le rechargement en mémoire est alors sauté sans message, et Hydranos refuse de démarrer au prochain lancement. Vérifiez une valeur sur sa sous-page avant d'enregistrer.
• Les tableaux sont en lecture seule (infobulle « Array — edit in default.toml »). Modifiez-les dans le fichier.
• Les tables par hôte de tracker ([announce_passkeys], [announce_ip_modes] sous Trackers et réseau (Trackers & Network), les trois autres sous Other) sont modifiables ici : leurs noms d'hôte entre guillemets sont reconnus. L'ajout d'un tracker se fait depuis l'onglet Trackers : Trackers & annonces.
• api_key a deux boutons : ↻ génère une nouvelle clé aléatoire dans le navigateur (rien ne change avant Enregistrer les réglages) et ⧉ la copie. Enregistrer une nouvelle clé met aussi à jour la copie stockée dans ce navigateur ; les autres navigateurs, Sonarr/Radarr et les nœuds qui utilisent l'ancienne clé doivent être mis à jour à la main.
• Descriptions et indications « défaut : » (default:) sous chaque ligne : deux décrivent encore des clés qui ne font rien (inactivity_timeout, announce_rate_limit, tableau ci-dessous). Certaines indications « défaut : » sont fausses aussi : [hoard] max_connections affiche 8000 (modèle : 12000), [hoard] max_uploads_per_torrent 20 (modèle : -1), [daemon] create_torrent_folder true (modèle et code : false). Les sous-pages donnent les vraies valeurs par défaut.
• Revenir aux valeurs par défaut (en haut à droite de l'éditeur, pas celui de Personnalisation (Personalisation)) réécrit le modèle, ne garde que [auth] username, [auth] password_hash, [daemon] api_key et [daemon] data_dir, enregistre l'ancien fichier sous default.toml.bak-reset-<unix seconds> à côté, et redémarre. Tout le reste est perdu, y compris les blocs de moteur, les tables par hôte de tracker (vos passkeys et heures de seed minimum), [network] mode, [proxy], [daemon] egress et kill_switch, allow_direct, les clés wireguard_*, [rss], [dedup] et [mcp]. Une installation qui tournait en mode WireGuard, SOCKS5 ou gluetun revient en mode Direct, kill switch désactivé. Recopiez depuis la sauvegarde ce dont vous avez besoin.

Statut : lue = chaque clé fait quelque chose (exceptions nommées) ; ignorée = rien ne lit la section en 4.4 ; nommée au démarrage = présente dans le fichier, elle reçoit une ligne WARN à chaque démarrage.

Plusieurs clés ont une valeur dans le modèle livré et une autre dans le code quand la clé est absente. Une installation standard reçoit la valeur du modèle. Une configuration écrite à la main, par une ancienne version ou par le script d'enrôlement de nœud reçoit la valeur du code, sans aucun avertissement (seul listen_port avertit). Détail complet : Config : moteurs & drain race.

Un bloc de moteur hérite de [race] ou de [hoard] (selon son role) chaque clé qu'il ne règle pas, sauf allow_direct, wireguard_enabled, gluetun_port_forward et listen_port_proxy_v2, qu'un moteur supplémentaire n'obtient qu'en les réglant dans sa propre session ; les autres valeurs par défaut se reportent sur les moteurs supplémentaires.

Un fichier écrit par le script d'enrôlement de nœud n'a ni max_connections ni [race_drain] : un tel nœud tourne donc sans plafond de connexions et sans drain race tant que vous n'y recopiez pas les lignes (Nœuds & plusieurs machines). DHT, PEX et webseeds y sont activés, comme partout.

Hydranos 4.4 lit le fichier brut à chaque démarrage et journalise une ligne WARN pour chaque clé qu'il sait morte, avec la raison et le remplacement :

config: race.custom_choking is ignored: a 3.x choking strategy; the engine has one built-in choker and no strategy to pick. Instead: choking = true and max_uploads_per_torrent = <slots> (off by default; read their help first).
config: [[agent]] "de-1" addr is ignored: a 3.x remote agent: 4.x has no agent channel, so this block starts nothing here and reaches nothing there. Instead: enrol that machine as a node: install.sh --register-to <url> --token <token> (the Nodes page gives the full command).

L'avertissement n'est jamais fatal et la clé reste dans le fichier (un retour à la 3.x la retrouve). Un fichier qui ne se lit pas ne reçoit aucun avertissement : c'est l'erreur de lecture que vous voyez. Le modèle livré ne contient aucune de ces clés, et Paramètres avancés les masque toutes.

Accepté mais ignoré en 4.4 : chaque clé ci-dessous est acceptée sans erreur et n'a aucun des effets que son nom suggère — le premier tableau est nommé dans le journal de démarrage, le second non — utilisez le remplacement de la dernière colonne, ou supprimez la clé.

Deux clés ne reçoivent aucun avertissement, car une version ultérieure pourrait les lire :

Toutes les autres lacunes de la 4.4 sont listées sur Limites connues.

Le départ sûr le plus simple est de laisser Hydranos écrire le modèle, puis de le modifier. Si vous écrivez un fichier vous-même, gardez au moins les lignes ci-dessous. Chaque ligne porte la valeur d'une installation standard, pour qu'aucune ne retombe sur une valeur par défaut de « clé absente ».

# Les clés de premier niveau d'abord, avant toute [table].
auto_port_forward = true          # NAT-PMP / UPnP pour les ports d'écoute (par défaut si absente : true)

[daemon]
api_host = "0.0.0.0"              # interface web et API sur toutes les interfaces
api_port = 8199
api_key = ""                      # gardez cette ligne : Hydranos y écrit une clé générée au premier démarrage
data_dir = "/config"              # contient hydra.db (le store) et bench.db

[auth]
username = "admin"
password_hash = ""                # vide = l'interface web vous demande de créer le compte

[race]
listen_port = 16171
bind_interface = ""               # Linux uniquement : épingle tout le trafic de ce moteur à une interface, ex. "wg0"
enable_ipv6 = false
enable_dht = true                 # absente = true aussi
enable_pex = true
enable_lsd = true                 # absente = true pour race, false sinon
max_connections = 4000            # absente = 0 = aucun plafond

[hoard]
listen_port = 16172
bind_interface = ""
enable_ipv6 = false
enable_dht = true
enable_pex = true
enable_lsd = false
max_connections = 12000
active_downloads = 10             # torrents en téléchargement simultané dans hoard ; 0 = aucune limite ; appliqué à chaud

[race_drain]
enabled = true                    # absente = false
check_interval_seconds = 60
high_watermark_pct = 95
low_watermark_pct = 85

# Facultatif : un troisième moteur, ici un moteur de rôle hoard épinglé à sa propre interface.
# Toute clé absente de [engine.session] est reprise de [hoard].
# [[engine]]
# name = "vpn1"
# role = "hoard"
# engine_id = "vpn1"
# [engine.session]
# listen_port = 16473
# bind_interface = "wg1"

Les webseeds (BEP 19) sont activés sans aucune ligne ; ajoutez enable_webseed = false pour les désactiver. Les clés de file, de limites de partage, de plafonds de débit et du choker sont omises : leurs valeurs par défaut sont « désactivé » (File d'attente, limites de partage et de débit). Le bloc de moteur commenté est le format qu'écrit + Add an engine. Sous Linux, bind_interface épingle tout le trafic de ce moteur (écouteur, uTP, pairs sortants, annonces, DHT, webseeds) à wg1 ; un socket qui ne peut pas être épinglé n'est pas ouvert, donc une interface absente au démarrage signifie ni écouteur ni uTP, jamais la route par défaut. L'épinglage d'interface est refusé sous Windows et macOS. Lisez VPN & sortie réseau avant de vous y fier.

• Chaque clé de [daemon], [auth], [mcp], [dedup], [vpn_speedtest], des tables par hôte de tracker et des sections ignorées : Config : démon, auth & global.
• Chaque clé de [race], [hoard], des blocs de moteur et de [race_drain] : Config : moteurs & drain race.
• La file, les limites de partage, les plafonds de débit et le choker de chaque moteur : File d'attente, limites de partage et de débit.
• [network], les clés réseau des moteurs et [daemon] egress/kill_switch/[proxy] : Réseau : ports & redirection, VPN & sortie réseau, WireGuard géré.
• [rss] : RSS et téléchargements automatiques.
• Options de ligne de commande, variables d'environnement et signaux : Config : environnement, CLI & signaux.