commit c7f53151b340da89feb1c669071cf22c7f200407
parent 66169fa01f2886ca6b70e8be4214557880d9c6b5
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 4 Aug 2026 23:44:57 +0200
document new config options
Diffstat:
2 files changed, 78 insertions(+), 5 deletions(-)
diff --git a/manpages/paivana-httpd.1.rst b/manpages/paivana-httpd.1.rst
@@ -37,11 +37,30 @@ them to the respective webserver configured.
Its options are as follows:
**-f** | **--respect-forwarded-headers**
- If set, derive the client address from the leftmost entry of the
- "X-Forwarded-For" request header (falling back to the socket
- address only when the header is absent). Only enable this when
- paivana-httpd is itself behind a trusted reverse proxy that
- sanitizes that header - otherwise clients can spoof their address.
+ If set, derive the client address from the "Forwarded" (RFC 7239)
+ or "X-Forwarded-For" request header, falling back to the socket
+ address when neither is present, and forward upstream the chain
+ that was received rather than replacing it. "Forwarded" is
+ preferred where both are present.
+
+ Only enable this when paivana-httpd is itself behind a reverse
+ proxy that **overwrites** those headers rather than appending to
+ whatever the client sent - otherwise clients can spoof their
+ address and so choose the identity their access cookie is bound to.
+ Note that nginx does not set "X-Forwarded-For" at all unless told
+ to, and that Apache's ``ProxyAddHeaders`` appends to a
+ client-supplied value; example configurations for both are shipped
+ with Paivana.
+
+ Which entry of the chain names the client depends on
+ ``TRUSTED_PROXIES`` and ``TRUSTED_PROXIES6``; see paivana.conf(5).
+ Without those options every hop is believed, including the leftmost
+ entry, and correctness rests entirely on the server in front.
+
+ This option is required when ``SERVE`` is ``unix``: a UNIX domain
+ peer has no address of its own, so without it there is no client
+ address at all, the access cookie cannot be bound to a client, and
+ payment callbacks fail.
**-h** | **--help**
Print short help on options.
diff --git a/manpages/paivana.conf.5.rst b/manpages/paivana.conf.5.rst
@@ -52,6 +52,60 @@ UNIXPATH_MODE = 660
What should be the file access permissions for ``UNIXPATH``?
Only used if ``SERVE`` is ``unix``.
+TRUSTED_PROXIES
+ IPv4 networks whose members are reverse proxies trusted to report
+ the client address in the ``X-Forwarded-For`` or ``Forwarded``
+ request headers. Only consulted if paivana-httpd is started with
+ **-f**; see paivana-httpd(1).
+
+ Without this option, **-f** believes every hop of the forwarding
+ chain, including its leftmost entry — which is whatever the client
+ itself wrote, unless the server in front overwrites the header. A
+ client could then choose the address its access cookie is bound to,
+ and share one paid cookie with arbitrarily many others. Naming the
+ proxies here removes that dependency on the front server's
+ configuration: the chain is walked from the right with listed
+ proxies skipped, and the first entry that is not one of them is the
+ client. Entries a client prepended cannot be promoted this way,
+ because the walk stops at the address the trusted proxy actually
+ reported. If the peer that connected is not itself listed, the
+ forwarding headers are ignored entirely.
+
+ A peer on a UNIX domain socket is always trusted: it has no address
+ to match, is by construction on the local machine, and access to the
+ socket is governed by ``UNIXPATH_MODE``.
+
+ The syntax is that of GNUnet's network policies, which has three
+ properties worth stating:
+
+ * entries are separated **and terminated** by ``;``, so a missing
+ trailing semicolon means nothing is parsed at all;
+ * ``0.0.0.0/0`` cannot be expressed, being indistinguishable from
+ the end of the list;
+ * a netmask may be given in CIDR (``/8``) or dotted-decimal
+ (``/255.0.0.0``) notation, and may be omitted to name a single
+ host.
+
+ Anything that parses to an empty list aborts startup rather than
+ silently trusting nobody. Example::
+
+ TRUSTED_PROXIES = 10.0.0.0/8;192.168.0.0/16;
+
+ This setting is optional.
+
+TRUSTED_PROXIES6
+ As ``TRUSTED_PROXIES``, but for IPv6 networks. Note that unlike the
+ IPv4 option, this one does **not** tolerate whitespace between
+ entries, and that ``::/0`` cannot be expressed. Example::
+
+ TRUSTED_PROXIES6 = 2001:db8::/32;fe80::/10;
+
+ Put IPv4 proxies in ``TRUSTED_PROXIES``, not here as
+ ``::ffff:a.b.c.d``: addresses are reduced to their IPv4 form before
+ being matched, so an IPv4-mapped entry would never be reached.
+
+ This setting is optional.
+
BASE_URL
Our own Base URL, used if we cannot learn our own base
URL from "Host" or other HTTP headers. Optional but recommended.
