🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page est pour vous si vous voulez Hydranos sur un serveur Linux ou une seedbox sans Docker, géré par systemd. À la fin, vous aurez téléchargé et vérifié la version, l'aurez installée avec le script fourni ou à la main, l'aurez fait tourner sous l'unité systemd fournie, et saurez comment mettre à jour et désinstaller.

Chaque version publie une archive statique (musl) par architecture, chacune accompagnée d'un fichier SHA-256 :

<tag> garde son v (v4.4.0). Téléchargez, vérifiez, décompressez :

VER=v4.4.0
ARCH=amd64        # arm64 sur aarch64
curl -fLO https://github.com/Kheopsian/Hydranos/releases/download/$VER/hydranos-$VER-linux-$ARCH.tar.gz
curl -fLO https://github.com/Kheopsian/Hydranos/releases/download/$VER/hydranos-$VER-linux-$ARCH.tar.gz.sha256
sha256sum -c hydranos-$VER-linux-$ARCH.tar.gz.sha256
tar xzf hydranos-$VER-linux-$ARCH.tar.gz
cd hydranos-$VER-linux-$ARCH

Le dossier contient :

Les versions ne livrent plus hydranos-engine. ./hydranos --version (ou -V) affiche hydranos 4.x.y. La ligne de commande est :

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

--help l'affiche. Tout autre argument est signalé sur stderr (hydranos: ignoring unknown argument …; starting anyway (see hydranos --help)) et le démon démarre. Détails : Config : environnement, CLI & signaux.

Lancez-le en root depuis le dossier décompressé (il copie les fichiers par nom relatif) :

sudo ./install.sh

Ce qu'il fait, dans l'ordre :

1. Crée l'utilisateur système hydranos (sans shell de connexion, home /var/lib/hydranos) s'il n'existe pas.
2. Crée /opt/hydranos, /etc/hydranos et /var/lib/hydranos, appartenant à hydranos.
3. Copie hydranos et hydranos-update dans /opt/hydranos.
4. À la première installation seulement, copie default.toml.example vers /etc/hydranos/default.toml et y règle data_dir = "/var/lib/hydranos". Une configuration existante n'est jamais écrasée.
5. Installe hydranos.service dans /etc/systemd/system/ seulement si aucune unité n'y est encore. Si la vôtre diffère de celle fournie, la vôtre est conservée et celle fournie est placée à côté sous le nom hydranos.service.new (hydranos: kept your /etc/systemd/system/hydranos.service; the shipped one is at /etc/systemd/system/hydranos.service.new). Il lance ensuite systemctl daemon-reload et systemctl enable --now hydranos.

Le résultat :

flowchart LR
    UNIT["hydranos.service"] -->|"ExecStart --config"| BIN
    subgraph OPT["/opt/hydranos"]
        BIN["hydranos"]
        UPD["hydranos-update"]
    end
    subgraph ETC["/etc/hydranos = dossier de configuration"]
        CFG["default.toml"]
        LOG["hydranos.log"]
        RACE["race/state.db<br/>race/resume/"]
        HOARD["hoard/state.db<br/>hoard/resume/"]
    end
    subgraph VAR["/var/lib/hydranos = data_dir"]
        STORE["hydra.db"]
        BENCH["bench.db"]
    end
    BIN --> CFG
    BIN --> LOG
    BIN --> RACE
    BIN --> HOARD
    BIN --> STORE
    BIN --> BENCH
    BIN -->|"données des torrents"| SP["vos chemins de sauvegarde"]

Notez la séparation : l'état de reprise des moteurs et le journal vivent à côté du fichier de configuration dans /etc/hydranos, pas dans data_dir. Le store hydra.db (le catalogue, y compris chaque .torrent) et bench.db vivent dans /var/lib/hydranos. Sauvegardez les deux dossiers. Pourquoi cette séparation existe : Architecture.

À la fin, le script affiche comment terminer :

• Créez le compte admin dans le navigateur. L'écran de premier démarrage ne répond qu'aux appelants de la même machine ou d'un réseau privé (voir Installation & premier démarrage).
• Sur un hôte distant, définissez plutôt le mot de passe depuis le shell, en root : /opt/hydranos/hydranos reset-password '<newpassword>' /etc/hydranos/default.toml, puis systemctl restart hydranos. Le mot de passe doit faire au moins 8 caractères. La commande réécrit le fichier sur place, qui reste donc la propriété de hydranos ; le mot de passe reste dans l'historique de votre shell (déduit du code, non testé par le mainteneur).
• Son indication de mise à jour, /opt/hydranos/hydranos-update, est incomplète : lancé depuis un autre dossier, l'outil de mise à jour cherche dans le dossier courant et ne remplace rien. Utilisez la commande complète de Mise à jour (--dir et --config).

Le install.sh à la racine du dépôt (servi par une instance en marche à /install.sh) est un autre script : il enrôle une nouvelle machine comme nœud, à la version du contrôleur (HYDRANOS_VERSION_PIN la remplace). Quand docker est dans le PATH, il lance un conteneur, et ne remplace jamais qu'un conteneur qu'il a lui-même créé. Sinon, il télécharge la même archive de version et installe soit en root, dans /usr/local/bin avec sa propre unité système, soit, avec --user ou sur un compte qui n'est pas root, dans votre home avec une unité systemd --user (un compte de seedbox). Voir Nœuds & plusieurs machines.

Même organisation que le script, étape par étape. Seul hydranos est indispensable ; ajoutez hydranos-update si vous voulez l'outil de mise à jour.

sudo useradd --system --home-dir /var/lib/hydranos --shell /usr/sbin/nologin hydranos
sudo install -d -o hydranos -g hydranos /opt/hydranos /etc/hydranos /var/lib/hydranos
sudo install -m 0755 hydranos hydranos-update /opt/hydranos/
sudo install -m 0644 -o hydranos -g hydranos default.toml.example /etc/hydranos/default.toml
sudo sed -i 's#^data_dir = .*#data_dir = "/var/lib/hydranos"#' /etc/hydranos/default.toml

À savoir :

• Le fichier de configuration doit être modifiable par l'utilisateur du service. Au premier démarrage, Hydranos génère la clé API et l'écrit dans [daemon] api_key ; les réglages enregistrés depuis l'interface y sont aussi écrits. Si le fichier est en lecture seule, la clé reste vide et tout appel API est refusé.
• Pas de fichier de configuration ? hydranos --config /some/dir/default.toml y écrit lui-même le modèle et règle data_dir sur /some/dir/data. Sans --config, il utilise /config/default.toml, qui existe rarement sur un hôte Linux : passez toujours --config.
• Chemins de sauvegarde. Il n'y a pas de dossier de téléchargement par défaut. Chaque torrent a besoin d'un chemin de sauvegarde, généralement fourni par sa catégorie, et l'utilisateur hydranos doit pouvoir y écrire :

  sudo install -d -o hydranos -g hydranos /srv/torrents

• Pare-feu. Ouvrez les ports d'écoute des moteurs, en TCP et UDP (16171 pour race, 16172 pour hoard). Gardez le port 8199 sur votre réseau local ou derrière un tunnel. Le tableau complet des ports se trouve sur Installation & premier démarrage.
• Essayer d'abord sans root : ./hydranos --config "$HOME/hydranos/default.toml" tourne au premier plan avec tout sous ~/hydranos. Arrêtez-le avec Ctrl+C (c'est un arrêt propre, voir plus bas).

Installez ensuite l'unité de la section suivante.

L'unité livrée dans l'archive (et installée par le script) est celle à utiliser. Si vous installez à la main, copiez-la telle quelle :

sudo install -m 0644 hydranos.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hydranos

# /etc/systemd/system/hydranos.service (as shipped)
[Unit]
Description=Hydranos BitTorrent client
Documentation=https://github.com/Kheopsian/Hydranos/wiki
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hydranos
Group=hydranos
ExecStart=/opt/hydranos/hydranos --config /etc/hydranos/default.toml
# A restart asked from the UI exits with 75, which on-failure brings back.
Restart=on-failure
RestartSec=5
# On SIGTERM Hydranos tells the trackers it is leaving (5 s at most), then
# flushes every engine's resume data, in parallel, within
# HYDRANOS_STOP_TIMEOUT (120 s by default). Keep this above both, or systemd
# kills the flush and the next start re-checks what was already complete.
TimeoutStopSec=150
# Peer connections and files at scale -> raise the fd limit.
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

Restart=on-failure suffit. Les boutons Redémarrer maintenant (Restart now) et Appliquer et redémarrer (Apply & restart) de l'interface, l'enregistrement de Duplicate data et la réinitialisation des réglages arrêtent proprement le démon et le font sortir avec le code 75, que systemd compte comme un échec et redémarre. systemctl stop hydranos (sortie 0) l'arrête pour de bon.

TimeoutStopSec=150. Sur SIGTERM, Hydranos vide l'API (5 s au plus ; le flux d'événements de l'interface web et le suivi en direct du journal se ferment d'eux-mêmes, un onglet ouvert ne retient donc plus l'arrêt), annonce aux trackers qu'il s'en va (5 s au plus), puis écrit l'état de reprise de chaque moteur en parallèle, dans la limite de HYDRANOS_STOP_TIMEOUT (120 s par défaut ; 120, 90s, 2m, 1m30s, 1h). Ce budget écoulé, il s'en va avec ce qui est écrit. Si systemd tue le processus avant, le démarrage suivant revérifie les pièces dont la progression a été perdue (jusqu'à cinq minutes de progression, l'intervalle de la sauvegarde périodique). Le pire cas est 5 + 5 + 120 = 130 s. Pour voir ce que prend réellement votre instance :

journalctl -u hydranos | grep "shutdown flush"

shutdown flush complete took_s=… donne la durée ; shutdown flush hit HYDRANOS_STOP_TIMEOUT; leaving with what is saved signifie que le budget est épuisé. Si vous augmentez HYDRANOS_STOP_TIMEOUT, augmentez TimeoutStopSec avec (gardez-le au moins 10 s au-dessus), dans un drop-in.

LimitNOFILE=1048576 : chaque connexion de pair et chaque fichier de données ouvert consomme un descripteur de fichier.

L'unité ne donne aucune capacité au service : le mode réseau WireGuard, managed by Hydranos est refusé sous cette unité (la raison est affichée sur l'onglet Réseau (Network)) tant que vous n'accordez pas CAP_NET_ADMIN dans un drop-in et n'installez pas ip et wg (iproute2, wireguard-tools). Voir WireGuard géré.

install.sh conserve une unité existante (une unité fournie plus récente est déposée à côté sous le nom hydranos.service.new), mais les modifications se reportent plus facilement d'une mise à jour à l'autre dans un drop-in, auquel rien ne touche. Par exemple, un budget d'écriture plus long pour une grosse bibliothèque :

sudo mkdir -p /etc/systemd/system/hydranos.service.d
sudo tee /etc/systemd/system/hydranos.service.d/override.conf >/dev/null <<'EOF'
[Service]
Environment=HYDRANOS_STOP_TIMEOUT=5m
TimeoutStopSec=330
# WireGuard géré seulement (non testé par le mainteneur) :
# AmbientCapabilities=CAP_NET_ADMIN
EOF
sudo systemctl daemon-reload
sudo systemctl restart hydranos

journalctl -u hydranos -f affiche la sortie du démon. Les mêmes lignes sont aussi ajoutées à /etc/hydranos/hydranos.log, qui tourne d'elle-même à 128 Mio en gardant quatre anciens fichiers (hydranos.log.1 à .4). Pour ne garder que le journal systemd, ajoutez Environment=HYDRANOS_LOG_STDOUT=1 à la section [Service] : la seule présence de la variable (n'importe quelle valeur, même 0) désactive le fichier. Plus de détails : Supervision & journaux.

bind_interface (tout le trafic d'un moteur sur, disons, wg0 : écoute, uTP, connexions sortantes, annonces, DHT, webseeds) ne fonctionne que sous Linux, et ce qu'il épingle ou non est expliqué sur VPN & sortie réseau. Il utilise SO_BINDTODEVICE ; sur les noyaux antérieurs à 5.7, un utilisateur non privilégié a besoin de CAP_NET_RAW pour cela. Si un moteur refuse d'ouvrir son écoute après que vous avez réglé bind_interface, ajoutez AmbientCapabilities=CAP_NET_RAW au drop-in (non testé par le mainteneur). Pour laisser plutôt Hydranos monter les tunnels lui-même, voir WireGuard géré.

Ouvrez http://<server>:8199/. Sur un serveur sans écran, passez le port par un tunnel au lieu de l'ouvrir :

ssh -L 8199:127.0.0.1:8199 [email protected]

puis allez sur http://localhost:8199/. Les étapes du premier démarrage (compte admin, clé API, première catégorie) sont les mêmes sur toutes les plateformes : voir Premier démarrage sur Installation & premier démarrage.

Lisez d'abord les notes de version sur la page des versions. Deux méthodes, qui conservent toutes deux votre configuration et vos données :

Avec hydranos-update (installé dans /opt/hydranos par le script) :

sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml --check   # ce qui est installé, ce qui est disponible
sudo /opt/hydranos/hydranos-update --dir /opt/hydranos --config /etc/hydranos/default.toml           # télécharger, vérifier, remplacer
sudo systemctl restart hydranos

--config permet à ses téléchargements de sortir comme le font les requêtes du démon lui-même ([daemon] egress, le kill switch, le mode réseau) ; il affiche alors une ligne network: … quand cette route n'est pas la route directe ou que le kill switch est armé. Sans lui, l'outil de mise à jour cherche default.toml dans --dir, qui n'existe pas dans cette organisation, et utilise la route par défaut. Une configuration qui ne s'analyse pas est refusée. Il prend l'archive linux-amd64 ou linux-arm64 de la dernière version GitHub (--tag v4.4.0 pour une version précise, --yes pour sauter la confirmation), refuse d'installer si le .sha256 manque ou ne correspond pas, et ne remplace que les binaires déjà présents dans --dir. Sous Linux, il ne redémarre rien : l'ancienne version continue de tourner jusqu'au systemctl restart.

Avec une nouvelle archive : téléchargez-la et vérifiez-la comme plus haut, lancez sudo ./install.sh depuis le nouveau dossier, puis sudo systemctl restart hydranos (le enable --now du script ne redémarre pas un service en marche). Le script conserve votre fichier d'unité ; si celle fournie a changé, comparez-la avec hydranos.service.new.

Vous venez de la 3.x : les chemins, les noms et l'unité ont changé ; suivez Mettre à jour depuis la 3.x. Sauvegardes et détails de l'arrêt propre : Exploiter Hydranos.

sudo systemctl disable --now hydranos
sudo rm -rf /etc/systemd/system/hydranos.service /etc/systemd/system/hydranos.service.d
sudo systemctl daemon-reload
sudo rm -rf /opt/hydranos
# Seulement si vous ne voulez garder ni la configuration, ni le catalogue, ni l'état de reprise :
sudo rm -rf /etc/hydranos /var/lib/hydranos
sudo userdel hydranos

Vos données de torrents dans les chemins de sauvegarde ne sont pas touchées. Supprimer /var/lib/hydranos/hydra.db fait perdre le catalogue (chaque .torrent y est stocké, et nulle part ailleurs).

Faites maintenant le Premier démarrage sur Installation & premier démarrage.