🇬🇧 English · 🇫🇷 Français

Applies to Hydranos 4.4.

This page is for anyone who wants peers to reach their engines, or who opened Config › Advanced settings (default.toml) › Network and wants to know what those settings really do. By the end you will know what each of the five Network-tab modes does, which ports to open, what automatic port forwarding does, how to move a port without a restart, how IPv6, local peer discovery and the IP filter behave, and how to check what really leaves. The leak model, the kill switch and the daemon's own requests are on VPN and Egress; the tunnels Hydranos builds itself are on Managed WireGuard.

The Network sub-tab (the first tab of Advanced settings (default.toml)) shows five mode cards. You pick one, fill in its fields and click Save this mode. All five work in 4.4.

In every mode except Direct, the kill switch is armed by default. Which engine it then keeps off the network depends on the mode. In SOCKS5 proxy and SOCKS5 + PROXY-v2 relay modes: an engine with no interface, no proxy and no allow_direct. In WireGuard, managed by Hydranos mode: an engine with neither a tunnel nor Direct (default interface) (or allow_direct); an interface typed by hand does not count there. In Gluetun mode: only an engine pinned to an interface other than gluetun's; one with no interface counts as covered by gluetun's firewall. A blocked engine gets no listener, no dial, no announce, no DHT, no LSD. It does not fall back to the host's route. The tab's Kill switch and the daemon's own requests section and the startup log (kill switch: …) show each engine as covered, direct on purpose or blocked. Details are on VPN and Egress.

Known bug in 4.4: the SOCKS5 proxy card says "Nobody can connect to you from outside", and its settings section says the DHT "if on, still shows this host's address to DHT nodes". Both are wrong. The engines switch the DHT off behind the proxy, and incoming peers reach the host's own listen port if that port is open or forwarded. To avoid incoming peers on the host's address, do not forward or publish the listen ports.

If you save SOCKS5 + PROXY-v2 relay with no Proxy host, the save goes through with the warning "No SOCKS5 proxy is set: incoming peers come through the relay, but outgoing connections and announces leave directly." With the kill switch armed (the default in that mode), an engine with no interface is kept off the network instead, and a second warning says so.

The mode is stored in default.toml:

[network]
mode = "socks5"   # direct, wireguard, gluetun, socks5 or proxy_v2

GET /api/network/mode highlights that card. A file without the key (written before 4.4) or with an unknown value gets a mode deduced from the keys: Gluetun if gluetun_port_forward = true in [race] or [hoard], else SOCKS5 + PROXY-v2 relay if listen_port_proxy_v2 is not 0 in either, else SOCKS5 proxy if either has a socks5_outbound_host, else Direct. The deduction never gives WireGuard, managed by Hydranos, so save once from the tab after an upgrade.

The tab reads the daemon's in-memory configuration. That copy is loaded at start and replaced only when the UI or the API writes the file. A hand edit of default.toml does not show until a restart, or until any UI or API change rewrites the file (that reloads the whole file, hand edits included).

flowchart LR
    UI["Network tab<br/>Save this mode"] -->|"POST /api/network/mode"| F["default.toml<br/>[network] mode + this mode's keys<br/>other modes' keys removed"]
    F -->|"read when each engine starts"| E["Engines: listen_port, bind_interface,<br/>enable_ipv6, SOCKS5, announce proxy,<br/>PROXY-v2 listener, gluetun follower,<br/>WireGuard tunnel, kill switch verdict"]
    F -->|"GET /api/network/mode"| C["Highlighted card<br/>= [network] mode"]

• Save this mode sends only the chosen mode's fields. The daemon writes [network] mode and that mode's keys, then removes the keys of the other modes from [race], [hoard] and every local extra engine's block: socks5_outbound_*, announce_proxy and announce_ip unless the mode is SOCKS5 or PROXY-v2; listen_port_proxy_v2, listen_addr_proxy_v2 and proxy_v2_trusted_sources unless it is PROXY-v2; gluetun_* unless it is Gluetun; wireguard_enabled, wireguard_config, wireguard_provider, wireguard_port and wireguard_port_forward unless it is WireGuard. Going back to Direct is just: click Direct, save.
• A client that posts only some fields (anything but the tab) keeps the others at their current values. A missing mode means the mode in force; an unknown one is refused (400 unknown network mode).
• Refusals, before anything is written: a race or hoard port outside 1–65535 (400); race and hoard on one port (409 race and hoard cannot share a listen port); an extra engine's port outside 1–65535 (400); SOCKS5 without a host (400 SOCKS5 mode needs the proxy host); a SOCKS5 port outside 1–65535 (400 the SOCKS5 port must be between 1 and 65535); in the two SOCKS5 modes, an Announce proxy that is not a proxy URL or an Address announced to trackers that is not an IP (400); PROXY-v2 without any PROXY-v2 port, with one outside 0–65535, with one equal to a listen port, or with race and hoard on the same one (400 race and hoard cannot share a PROXY-v2 port); a trusted source that is not an IP (400); WireGuard, managed by Hydranos on a host that cannot bring a tunnel up (409, with the reason); any bind_interface outside Linux (400). A SOCKS5 port of 0 is saved as 1080.
• The answer is {"status":"ok","mode":…,"restart_required":…,"warnings":[…],"tunnels_down":…}. restart_required is true only when a running engine was started with different network keys, or when the set of engines the kill switch blocks changes. The page then shows Saved. The engines need a restart to apply the new network settings. with an Apply & restart button, or Saved and applied, no restart needed. Apply & restart stops Hydranos cleanly and exits so that your container restart policy or service manager starts it again (see Operating Hydranos).
• Warnings are shown when you save and every time the tab opens. They cover UDP trackers not announced behind a proxy, the DHT switched off behind SOCKS5 (for an engine with the DHT on), a host that cannot run WireGuard (in that mode), PROXY-v2 mode with no SOCKS5 proxy, engines kept off the network by the kill switch, and, outside the two SOCKS5 modes, TYPHON_ANNOUNCE_PROXY set in the environment (that variable is listed under Set in the environment in every mode).
• Leaving WireGuard, managed by Hydranos takes the tunnels down at once (tunnels_down counts them). The engines pinned to them reach nobody until the restart; they never fall back to the host's route.
• GET /api/network/mode returns the SOCKS5 password and the gluetun API key as ******** (so does GET /api/network/egress for the [proxy] password); a save that sends the mask back keeps the stored value. The Announce proxy URL is not masked: a user:pass in it is returned in clear by GET /api/settings.

Fields: Take the listen port from gluetun, Gluetun control server (empty means http://127.0.0.1:8000), Gluetun API key, Engine that takes the port (Hoard or Race). A provider forwards one port, so only that engine gets gluetun_port_forward = true; the other is written false and keeps its own port. Extra engines never inherit it.

• The engine asks GET /v1/portforward (or /v1/openvpn/portforwarded when that answers 404), with the key in X-API-Key. It asks every 10 s until it has a port, then every 60 s. A 401 or 403 is logged as … set the gluetun API key, with GET /v1/portforward allowed.
• Its announces are held until its listener holds gluetun's port. Without an answer from gluetun, that engine announces nothing. A port that cannot be bound keeps them held.
• A new port is applied live (TCP and uTP, announces follow). It is not written to default.toml.
• In this mode Hydranos asks the home router for nothing, and the live listen-port routes refuse that engine (409). The kill switch counts an engine with no interface as covered by gluetun's firewall. Hydranos does not check that it really runs inside gluetun's network.

Fields under Incoming relay: Race PROXY-v2 port and Hoard PROXY-v2 port (0 = no PROXY-v2 listener for that engine), Bind address (empty = every address) and Trusted sources (comma separated). Loopback and private addresses are always trusted. A relay on a public address must be listed, or every peer it forwards is refused. The listener is pinned to the engine's interface. An extra engine does not inherit its role's PROXY-v2 port: name listen_port_proxy_v2 in its own block.

The SOCKS5 proxy section of both proxy modes also has Announce proxy (optional) (announce_proxy: a proxy URL for announces, webseeds and magnets, used instead of the SOCKS5 proxy) and Address announced to trackers (optional) (announce_ip, sent as ip=). Both are removed when you save another mode.

Each engine has one listen port, used for both:

• TCP: the peer listener, and
• UDP: the uTP socket, on the same port number (IPv4 only).

Ports must differ between engines. The Network tab refuses the same port for race and hoard (HTTP 409 "race and hoard cannot share a listen port") and any port outside 1–65535 (HTTP 400), extra engines included. It does not compare extra engines' ports with race and hoard; + Add an engine on the Nodes tab (POST /api/engines) does, and refuses a port already taken (409).

A section without listen_port gets 16171 (race role) or 16172 (hoard role). An engine whose port is already taken by another engine (an extra engine that inherits its role's port, for example) gets the next free port at start, with the warning listen_port missing or taken: using a free one. That port is not written to the file, so set listen_port explicitly for every extra engine. See Configuration: Engines.

The Ports section of the Network tab has Race listen port, Hoard listen port, one {id} listen port per extra engine, and Listen over IPv6 too. A change saved there needs a restart; to move a port live, use the routes in Changing the port without a restart below. In WireGuard, managed by Hydranos mode, an engine whose port comes from its provider is not listed: its port is shown with its tunnel.

Open these ports on your firewall for both TCP and UDP. In Docker, publish them on the container (the canonical compose on Docker Install publishes 16171/tcp, 16171/udp, 16172/tcp, 16172/udp). The full ports table, including the web port 8199, is on Installation and First Run.

Published and forwarded ports must equal the engine's listen_port. Trackers are told the port the engine listens on, so map the same number on both sides (16172:16172, never 47000:16172). When you change listen_port, change the router forward and the published ports to match: a port published or forwarded to a number no engine listens on reaches nothing. The one exception is a managed WireGuard tunnel whose gateway grants another external port by NAT-PMP: the engine keeps listening on its listen_port inside the tunnel and announces the external port (Managed WireGuard). Behind a VPN container (Docker network_mode: "service:gluetun", Unraid network type Container) the port rows go on the VPN container, not on hydranos; the gluetun recipe is on VPN and Egress.

flowchart LR
    P["Remote peer"] --> R["Home router"]
    M["Home-router mapper in hydranos<br/>one per engine, NAT-PMP then UPnP"] -.->|"asks for a TCP and a UDP mapping<br/>1-hour lease, renewed every 30 min"| R
    R -->|"16171 TCP and UDP"| RL["race: TCP listener<br/>and uTP socket"]
    R -->|"16172 TCP and UDP"| HL["hoard: TCP listener<br/>and uTP socket"]
    P --> G["WireGuard tunnel's gateway"]
    F["Tunnel port follower in hydranos<br/>per tunnelled engine whose provider forwards a port, NAT-PMP only"] -.->|"asks for a TCP and a UDP mapping<br/>60 s lease, renewed at half"| G
    G -->|"port granted by the provider"| TL["tunnelled engine: TCP listener<br/>and uTP socket on its listen_port"]
    Relay["Your PROXY-v2 relay"] -->|"PROXY-v2 port"| PV["PROXY-v2 listener<br/>(SOCKS5 + PROXY-v2 mode)"]

The top-level key auto_port_forward (not present in the shipped default.toml; default true) asks your home router to forward each engine's listen port. At start, one mapper runs per engine that leaves by the home router's network:

1. NAT-PMP to the default gateway read from /proc/net/route (Linux only; skipped on Windows and macOS). Four attempts, 3 s each.
2. Else UPnP IGD: SSDP discovery on 239.255.255.250:1900, then AddPortMapping on a WANIPConnection (v2 or v1) or WANPPPConnection service, with the description Hydranos.

Then:

• TCP and UDP are both mapped, on the same port. A UDP refusal does not undo TCP: it is logged as UDP not forwarded, uTP and DHT peers cannot reach this engine: … with forward UDP <port> by hand.
• It asks for the same external port as the internal one and a 1-hour lease, and renews it every 30 minutes (half the lease it asked for, whatever the router grants).
• If both protocols fail, it logs at INFO no automatic port forward; if you are not reachable, forward <port> (TCP and UDP) by hand and tries again 15 minutes later.
• On success it logs port forwarded by NAT-PMP or port forwarded by UPnP. The outcome per engine is also in GET /api/port-forward (see Checking reachability).
• It follows the engine's live port: after a live port change (below), the new port is mapped within about 5 seconds, and the old lease simply expires.
• If a NAT-PMP home router grants a different external port, that port shows in /api/port-forward (external_port) but trackers are still told the internal port.
• It never changes the listen port.

An engine kept off the network by the kill switch gets no mapping either, silently: no log line, and its /api/port-forward row stays at forward.by: "pending" (or "gluetun" if it carries gluetun_port_forward = true). For the others, no home-router mapping is asked (the log says port mapping: no UPnP/NAT-PMP request to the home router: <why>) for an engine:

• with a managed WireGuard tunnel (a NAT-PMP provider's port is asked of the tunnel's gateway; for a manual or no-forward provider nothing is asked; see Managed WireGuard);
• in Gluetun mode (the port comes from the VPN provider);
• behind a SOCKS5 proxy;
• pinned to an interface other than the one that holds the default route.

A port on the home router would publish the host's address for an engine that does not leave that way.

Turn it off when you forward by hand:

# top of default.toml, outside any [section]
auto_port_forward = false

With Docker's default bridge network the router is usually out of reach of NAT-PMP and UPnP, so expect the "forward by hand" log line every 15 minutes; forward the ports on the router (see Docker Install).

In Gluetun mode the home-router mapper stays out of the way by itself. In WireGuard, managed by Hydranos mode it stays away from every tunnelled engine, but an engine set to Direct (default interface) is still mapped on the home router. In both modes the VPN's port is followed when there is one to follow (a NAT-PMP tunnel, or gluetun_port_forward = true; see above and Managed WireGuard). If you run Hydranos inside some other VPN that is the process's default route while the tab says Direct, set auto_port_forward = false. Left on, the NAT-PMP request goes to the VPN side, and any different port the provider grants that way is never announced. Set listen_port to the provider's port instead.

Three routes move an engine's listen port live and keep it, without dropping torrents or connected peers:

• Body: JSON {"port": <1-65535>}. The body is parsed as JSON whatever the Content-Type.
• Auth: like every API route: header X-Api-Key: YOUR_API_KEY, or ?apikey=YOUR_API_KEY in the URL, or a logged-in session cookie. Without it: 401.
• Answers (sent after the new port is bound): 200 {"ok":true,"engine":"hoard","port":51413,"previous_port":16172,"persisted":true}; 400 for a missing or 0 port, a port above 65535 or a malformed body; 409 when the port is another engine's listen port, when it cannot be bound (the engine keeps listening on its old port, named in the answer, and nothing is written), or when the engine takes its port from gluetun or from its WireGuard tunnel; 503 when the engine is not on the network (kept off by the kill switch, or HYDRANOS_ENGINE_NET=0).

curl -X POST -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"port": 51413}' http://127.0.0.1:8199/api/hoard/listen-port
# {"ok":true,"engine":"hoard","port":51413,"previous_port":16172,"persisted":true}

What changes: the new TCP sockets (and the [::] one when enable_ipv6 = true) and the new uTP socket are bound first, then the old ones are released. If any of them cannot be bound, nothing moves. From then on, announces send the new port, peers are told it in the extension handshake, and the home-router mapper maps it. The port is written to the engine's listen_port (persisted: false means the move worked but the file could not be written; the log says listen port moved but not saved). The log shows [peer] hot rebind requested -> port 51413. GET /api/port-forward and the header's Network panel show the port the engine holds now.

Change the router forward and the published ports to match (see Listen ports above). A VPN provider's rotating port is followed for you in Gluetun mode and by a managed WireGuard tunnel; for any other setup, call this route with the new port.

enable_ipv6 (in [race] and [hoard], default false in the shipped file) adds a TCP listener on [::]:<listen_port> next to the IPv4 one and lets the engine use IPv6 peers learned by PEX. uTP stays IPv4-only. The Network tab's Listen over IPv6 too writes the same value into [race] and [hoard] only (not into extra engines' blocks), and shows race's value.

With enable_ipv6 = true, the address family of each announce is set per tracker host. In the Trackers tab, a tracker's Announce setting has auto, v4 only and v6 only (stored in [announce_ip_modes], applied at once, no restart). auto is the default and sends one announce over IPv4 and one over IPv6 with the same peer id. How to edit it: Trackers and Announces.

With enable_ipv6 = false, every announce of that engine goes over IPv4 only, whatever the tracker's setting (v6 only included), so no tracker lists an IPv6 address the engine does not listen on.

enable_lsd (per engine; absent means on for the race role, off otherwise; the shipped file has true in [race] and false in [hoard]) turns on Local Service Discovery (BEP 14). It is set in Advanced settings (default.toml), not on the Network tab, and applies at the next start of the engine.

• The engine multicasts on 239.192.152.143:6771 and [ff15::efc0:988f]:6771: one round a minute, at most 60 messages of 20 info hashes each, each torrent at most once every 5 minutes. Only torrents that are downloading or have peers are announced.
• LAN peers heard announcing a hash the engine holds go into that engine's dial queue, like tracker peers.
• Never for a private torrent, in either direction.
• Off behind a SOCKS5 proxy, and on an engine kept off the network. Inside an interface or a WireGuard tunnel it is pinned to that device and never reaches the host's LAN. If it cannot join the group there, LSD stays off with a log line.

bind_interface pins sockets with SO_BINDTODEVICE, which only Linux has. On Windows and macOS since 4.4:

• the Network tab hides the interface fields and shows the reason;
• POST /api/network/mode and POST /api/engines refuse a non-empty bind_interface (400, bind_interface is Linux-only: this platform cannot pin every socket of an engine to an interface (TCP peers would leave by the default route). Run the VPN client system-wide instead);
• an engine whose file still has the key stays off the network (no listener, dial, announce, DHT, LSD or uTP), with that warning at start.

On Linux, an interface that is missing at start means no listener for that engine and no uTP (uTP disabled rather than leak the default route) until a restart finds it. What else the pin covers is on VPN and Egress.

Config › IP filter blocks addresses in both directions: no connection is accepted from or made to them, and a peer already connected is dropped when it becomes blocked. It applies to every engine.

• The status line shows ranges filtered and the counts refused in, refused out and disconnected, plus each source's ranges or error.
• A source that fails to load keeps its last good copy.
• Settings and bans live in the store (hydra.db), not in default.toml.
• Every peer row in the detail panel's peer table has a Ban button: the address is disconnected now and refused from then on; it then appears under Bans.
• Windows paths such as C:\lists\level1.dat are refused; use a URL there.
• List downloads are the daemon's own requests: they leave the way [daemon] egress says (see VPN and Egress).

API: GET/PUT /api/ipfilter, POST/DELETE /api/ipfilter/bans, POST /api/ipfilter/reload (see REST API).

The header: Exit IP and the Network panel

• Every 180 s Hydranos asks an outside echo service (api.ipify.org, api6.ipify.org) which address it sees. It asks once for the daemon's own requests (the way [daemon] egress says), and once per engine through that engine's interface. An engine with no interface is measured separately only when the daemon leaves another way, and never while the kill switch is armed. An engine kept off the network is not measured. Clicking Exit IP re-measures now. With several distinct exits, the header shows {n} exits and lists them in its tooltip.
• The Network polygon has one dot per engine. Clicking it opens the Network panel, with one row per engine named by its engine id: role, interface or default route, port {port} (the port it holds now), exit IPv4/IPv6.
• The colour is the outbound probe only: green exit probe answered, amber no answer yet from its interface, red exit probe got no answer, grey offline. Green does not mean peers can connect to you.

Known bug in 4.4: the panel's dot tooltip says "whether peers can reach this engine is the health dot's tooltip", but the page draws no health dot. Inbound reachability is shown nowhere in the web UI. Read it from GET /api/port-forward or from Check what actually happens (below).

GET /api/port-forward

One row per engine: engine, role, listening, listen_port (live), inbound_peers (peers from outside that connected since start), reachable and forward. reachable is yes once such a peer has connected, no when nothing listens, and unproven otherwise. forward.by names who forwards the port: upnp or natpmp (home router, with tcp, udp, udp_error, external_port), wireguard (the tunnel), gluetun, none (with refused or error), off (auto_port_forward = false) or pending. The top level adds listen_healthy, all_connectable, ipv6_wanted, public_ip and public_ip_v6. A connected outside peer is proof; unproven is not a failure.

Check what actually happens

The button at the bottom of the Network tab (POST /api/network/check, up to a minute) shows a What actually happens list:

1. Address of the default route, measured with no interface and no proxy: what a leak would show.
2. For each local engine, Address trackers see (id) and Address peers see (id), measured the way that traffic leaves (announce proxy or SOCKS5, interface, tunnel DNS). The row fails with LEAK: … when an engine set to leave another way shows the default route's address, and fails with no answer: … when its tunnel or proxy does not answer. An engine kept off the network is not probed.
3. Address the daemon's own requests use, compared the same way.
4. Inbound reachability (id), from the peers that actually connected (as /api/port-forward), with what forwards the port.

While the kill switch is armed (every mode except Direct by default), the default route is not measured. The engine rows then show warn ("a leak cannot be ruled out") instead of a verdict. For a leak test, use Direct mode, or measure from outside as below.

Checking the inbound port from outside

unproven only means no peer has connected yet. To test the port yourself:

1. Check the engine really listens: GET /api/port-forward shows listening: true and the expected listen_port for it.
2. Find the public address peers must use: your router's WAN address or, behind a VPN, the VPN exit address and the port your provider forwards.
3. From a machine outside your network and outside the VPN (a phone on mobile data, a remote server), run nc -vz 203.0.113.5 16172 with that address and port, or use an online port checker. "succeeded"/"open" means the forward and the listener line up. A refusal or timeout means the forward, the published port or listen_port do not match (see Listen ports above).

Two environment variables, read at start:

All environment variables: Configuration: Environment Variables, CLI and Signals.

• VPN and Egress: what bind_interface pins, the kill switch, the daemon's own requests, gluetun and per-interface setups.
• Managed WireGuard: one tunnel per engine, providers, NAT-PMP port, DNS in the tunnel.
• Engines: Race and Hoard: adding extra engines with their own port and interface.
• Trackers and Announces: announce timing and the Trackers tab.
• Configuration: Engines and Configuration: Daemon, Auth and Global Sections: every key and its default.
• Docker Install: published ports.