docs(deploy): trust the reverse proxy's own fixed address, never a Docker subnet

The compose comments, the releases README and the Unraid template told
users to list the Docker network's subnet (172.17.0.0/16 on Unraid) in
TITANO_TRUSTED_PROXIES. That range holds the gateway, from which Docker
relays IPv6 clients and the host's own connections to published ports,
and on the default bridge every other container: each could again pick
its X-Forwarded-For and X-Forwarded-Proto. The guidance now names the
proxy container's fixed address on a shared user-defined network, warns
against subnets, the gateway and the default bridge, and sends a proxy
on the Docker host to network_mode: host (loopback). The server's
parse error no longer suggests a /12 network.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-12 15:52:01 +00:00
1 parent 1dc93932cc
commit e252dcd35c
4 files changed
+17 -8

No files matched your search

+7 -3
View File
@@ -24,10 +24,14 @@ services:
TITANO_DB_NAME: titano
TITANO_DB_USER: titano
TITANO_DB_PASSWORD: ${TITANO_DB_PASSWORD:?set TITANO_DB_PASSWORD in .env}
# auto (self-signed), pem or proxy; behind a proxy, set TITANO_TRUSTED_PROXIES to its address or network (for a
# proxy container on this network, the network's subnet; only loopback is trusted otherwise)
# auto (self-signed), pem or proxy. Behind a proxy, set TITANO_TRUSTED_PROXIES to the proxy's own address (only
# loopback is trusted otherwise). Give a proxy container a fixed one (ipv4_address, on a network with an ipam
# subnet that this service joins too) and let it reach Titano on that network, not through a published port.
# Never list a subnet or the network's gateway (.1): Docker relays connections to the published ports (IPv6
# clients, the host) from the gateway, and each of them could then choose its client address. For a proxy on the
# host itself, run this service with network_mode: host; the proxy then reaches Titano over loopback.
TITANO_TLS_MODE: auto
# TITANO_TRUSTED_PROXIES: "172.18.0.0/16"
# TITANO_TRUSTED_PROXIES: "172.30.0.10"
# TITANO_PUBLIC_HTTPS_PORT: "8443"
TITANO_SERVER_NAME: Titano Server
# Trace, Debug, Information, Warning or Error
+8 -3
View File
@@ -91,9 +91,14 @@ admin panel shows under Settings so you can compare them.
and set `TITANO_DB_HOST: 127.0.0.1`.
- Behind a reverse proxy (`TITANO_TLS_MODE=proxy`), only the proxies listed in `TITANO_TRUSTED_PROXIES` may set
`X-Forwarded-*` headers. By default that is loopback only: other machines on your network reach the HTTP port
directly, so they must not choose the address the sign-in limit and the audit log see. List your proxy's address,
or the subnet of the Docker network it shares with Titano (for example `172.18.0.0/16`). The admin panel shows *Not
via proxy* when a page did not come through a trusted proxy over HTTPS.
directly, so they must not choose the address the sign-in limit and the audit log see. List your proxy's own
address. Give a proxy container a fixed IP on a user-defined Docker network it shares with Titano (`ipv4_address` in
compose, *Fixed IP address* on Unraid), for example `172.30.0.10`, and let it reach Titano on that network rather
than through a published port. Never list a subnet, the network's gateway (`.1`) or Docker's default bridge
(`172.17.0.0/16`): Docker relays connections to published ports from the gateway (IPv6 clients, the host itself),
and on the default bridge every other container would count as your proxy too. For a proxy running on the Docker
host itself, run Titano with `network_mode: host`: the proxy then reaches it over loopback. The admin panel shows
*Not via proxy* when a page did not come through a trusted proxy over HTTPS.
## Titano Server on Unraid
+1 -1
View File
@@ -35,7 +35,7 @@
<Config Name="Database password" Target="TITANO_DB_PASSWORD" Default="" Mode="" Description="PostgreSQL password." Type="Variable" Display="always" Required="true" Mask="true"/>
<Config Name="Database TLS" Target="TITANO_DB_SSLMODE" Default="prefer" Mode="" Description="disable, prefer, require or verify-full." Type="Variable" Display="advanced" Required="false" Mask="false">prefer</Config>
<Config Name="TLS mode" Target="TITANO_TLS_MODE" Default="auto" Mode="" Description="auto (self-signed), pem (own certificate) or proxy (behind a reverse proxy)." Type="Variable" Display="advanced" Required="false" Mask="false">auto</Config>
<Config Name="Trusted proxies" Target="TITANO_TRUSTED_PROXIES" Default="" Mode="" Description="TLS mode proxy: IP address or network of your reverse proxy (for example 172.17.0.0/16); only loopback is trusted otherwise." Type="Variable" Display="advanced" Required="false" Mask="false"/>
<Config Name="Trusted proxies" Target="TITANO_TRUSTED_PROXIES" Default="" Mode="" Description="TLS mode proxy: the fixed IP address of your reverse proxy container (put both containers on a custom Docker network and give the proxy a Fixed IP address there). Never a range, the network gateway or the default bridge 172.17.0.0/16: other containers and connections Docker relays would count as the proxy. Only loopback is trusted otherwise." Type="Variable" Display="advanced" Required="false" Mask="false"/>
<Config Name="Server name" Target="TITANO_SERVER_NAME" Default="Titano Server" Mode="" Description="Name shown to clients." Type="Variable" Display="advanced" Required="false" Mask="false">Titano Server</Config>
<Config Name="Log level" Target="TITANO_LOG_LEVEL" Default="Information" Mode="" Description="Trace, Debug, Information, Warning or Error." Type="Variable" Display="advanced" Required="false" Mask="false">Information</Config>
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="User id that owns files." Type="Variable" Display="advanced" Required="true" Mask="false">99</Config>
@@ -234,7 +234,7 @@ public sealed class ServerOptions
}
catch (FormatException ex)
{
throw new InvalidOperationException($"TITANO_TRUSTED_PROXIES must list IP addresses or networks such as 172.16.0.0/12: {ex.Message}", ex);
throw new InvalidOperationException($"TITANO_TRUSTED_PROXIES must list IP addresses (such as 172.30.0.10) or networks in CIDR form: {ex.Message}", ex);
}
if (ChunkSizeBytes is < 64 * 1024 or > 64 * 1024 * 1024)
throw new InvalidOperationException("The chunk size must be between 64 KiB and 64 MiB.");