🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page covers everything that is not in the config file: the command-line options of hydranos and hydranos-update, every environment variable the code reads, and the signals that stop the daemon cleanly. It is for people writing a compose file, a systemd unit or a Windows shortcut. For the TOML file itself, start at Configuration Reference.

No environment variable or flag overrides a config key. The only way to change a setting such as a port or a path is the config file.

hydranos --help prints the exact usage:

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

Two subcommands work on the config file without starting the daemon. They must be the first argument:

Both refuse a password shorter than 8 characters (hydranos: the password must be at least 8 characters). The password is a command-line argument: it is visible to other users in the process list while the command runs and stays in your shell history. Recovery procedures: Security and Access.

Any other argument is reported and skipped, and the daemon starts normally. The line goes to stderr (the console, or the container log; not hydranos.log):

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

The 3.x split-process flags (anything starting with --agent- or --front-, also with one dash or as --flag=value) get a longer line: ignoring <flag>: the agent/front split was removed in 4.x and Hydranos now runs as one process. Starting a normal instance. …, pointing to node enrolment. The value of --agent-addr, --agent-token, --agent-tls-cert, --agent-tls-key and --front-addr is skipped with its flag.

A --config given without a value prints hydranos: --config needs a path; using <default path> and the default path is used.

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

On Windows, hydranos.exe is a windowed program: the output of --version, --help, reset-password and hash-password is printed before it attaches to any console, so it does not appear even in a terminal (read from the code, not tested on Windows). reset-password still writes the file and sets the exit code ($LASTEXITCODE in PowerShell); check the version in the web UI header instead. The unknown-argument lines and the log do appear in the terminal that started it.

The Docker image does not seed the file the same way: its entrypoint copies the template itself and sets data_dir to the config dir (/config, not /config/data). See Install with Docker.

hydranos-update replaces the binaries with a published release from github.com/Kheopsian/Hydranos. It ships in the Windows zip and the Linux tarball, not in the Docker image (update the image instead).

Unknown options are ignored. Behaviour, from the code:

• Nothing is replaced unless the archive downloads and its SHA-256 matches the .sha256 file published beside it.
• Only binaries already present in --dir are replaced; default.toml, the data folder and hydranos.log are not in the archive and are never touched.
• If the installed version already equals the latest and no --tag is given, it stops there.
• Windows: if hydranos.exe is running, it sets the daemon's stop event (Local\HydranosStop), which gives the same clean stop as the tray's Quit Hydranos, and waits up to 60 s. A daemon older than 4.4 has no such event: the updater then falls back to taskkill /IM hydranos.exe /T without /F, which does not stop it, so quit from the tray first. If it is still running after 60 s (a very large flush), the updater ends with hydranos is still running after 60s -- stop it yourself, nothing was replaced. Once hydranos.exe is gone, it swaps the files. See Install on Windows. The tray's Check for updates runs hydranos-update.exe --dir <its own folder> in a cmd window.
• Linux: it does not stop anything. It swaps the files and prints note: restart the service for the new binaries to take effect.

# packaging/install.sh installs it in /opt/hydranos; the config is in /etc/hydranos, so name it
/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

Releases no longer ship hydranos-engine (hydranos-engine.exe): every engine runs inside the hydranos process, and the only binaries in the archives are hydranos and hydranos-update. A copy left in /opt/hydranos by an older install is never started and can be deleted. History: Upgrading from 3.x.

These are read by the daemon itself, on every platform unless noted. They are read once, at startup (or the first time the code path runs): changing them needs a restart.

In all integer variables above, a value that does not parse (or is 0) is ignored and the default applies. HYDRANOS_STOP_TIMEOUT follows its own rules (table above).

Test-only variables HYDRANOS_INTEROP_* exist in the source but are compiled only into the test suite.

The image's entrypoint.sh reads these before it starts hydranos. They have no effect on a bare-metal or Windows install.

The entrypoint also raises the open-file limit (ulimit -n 1000000, falling back to 200000, silently skipped if not allowed), and always starts hydranos with --config "$HYDRANOS_CONFIG_DIR/default.toml".

It refuses the 3.x variables HYDRANOS_ENGINE_ID and HYDRANOS_ENGINES: when either is non-empty it prints, on 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., then seeds and starts as usual.

The image itself sets one variable:

The shipped docker-compose.yml sets stop_grace_period: 150s and offers HYDRANOS_STOP_TIMEOUT: 120 in a comment (see Install with Docker).

The enrolment script install.sh reads HYDRANOS_VERSION_PIN (a release tag) on every path, Docker image tag included; without it, the node takes the controller's version from its /health. That is the script, not the daemon. See Nodes and Multiple Machines.

A shortcut cannot set an environment variable. Without --config, hydranos.exe uses the default.toml beside it, so the --config below is only needed for a config elsewhere. Either set it for one start in PowerShell ($env:RUST_LOG = "debug"; & "C:\Hydranos\hydranos.exe" --config "C:\Hydranos\default.toml"), or for your account with setx RUST_LOG debug or Start › type environment › Edit environment variables for your account. A running Hydranos keeps the old values: quit from the tray and start it again (sign out and back in if a Startup-folder shortcut still does not see it). Details: Install on Windows.

Things to know:

• The SIGTERM/SIGINT handler is installed with the HTTP listener, in the first second of startup, before the torrents are loaded. A stop that arrives during the load is heard: the load finishes, nothing more starts, and the departures and the flush run (stop requested during startup; flushing and leaving).
• The worst case is about 5 s (drain) + 5 s (departures) + HYDRANOS_STOP_TIMEOUT, 130 s by default. Give your supervisor more than that (stop_grace_period / docker stop -t, systemd TimeoutStopSec; the shipped files use 150 s): sizing is on Operating Hydranos.
• Restart from the web UI or the API (Apply & restart, POST /api/settings/restart) is not a signal but takes the same path (logged restart request received, …), then exits with code 75 (EX_TEMPFAIL) instead of 0, so that Restart=on-failure, restart: unless-stopped or any policy that restarts on failure brings Hydranos back. A process started by hand stays stopped. See Operating Hydranos.
• Every 300 s (Linux only) the daemon also logs one jemalloc allocated=… resident=… line.

Windows has no signals. Each of these gives the same clean stop as SIGTERM (drain, departures, bounded flush), logged as <trigger>: draining the API and flushing resume data:

• Quit Hydranos in the tray icon menu (tray quit);
• Ctrl+C or Ctrl+Break in the console the process is attached to (started from a terminal, or with --console);
• closing that console window (console closed), signing out (sign-out), shutting Windows down (system shutdown);
• hydranos-update, through the stop event (an info line stop requested by the updater, then the drain logged as tray quit: …); the event, like the tray icon, exists once the torrents are loaded.

Windows allows only a few seconds after a console close, a sign-out or a shutdown, so the flush may be cut short there: quit from the tray before shutting down. How these console events reach a windowed hydranos.exe started without a console has not been tested. taskkill /F and End task in Task Manager never run the flush; taskkill without /F does nothing. A restart from the web UI saves the same way, then hydranos.exe starts its successor itself (same arguments) and exits with code 75. SIGUSR1/SIGUSR2 and the memory stats line do not exist on Windows (no jemalloc there). Service wrappers and start-up options: Install on Windows.

• Configuration Reference — the config file and where each section is documented
• Operating Hydranos — stop, restart, backup, updates
• Monitoring and Logs — hydranos.log, the Logs tab, /health, /metrics
• VPN and Egress — TYPHON_ANNOUNCE_PROXY and what leaves through where
• Install with Docker — the compose file and the /config volume