paivana-httpd(1)

22.23. paivana-httpd(1)#

22.23.1. Name#

paivana-httpd - reverse-proxy paywall

22.23.2. Synopsis#

22.23.3. Description#

paivana-httpd is a reverse proxy that requires the client to make a payment using GNU Taler before forwarding the request. The reverse proxy uses a GNU Taler merchant backend to process payments and also learns which websites require payment and how much the prices are. Thus, the main configuration is done within the Taler merchant backend.

paivana-httpd will simply open an HTTP socket, listen for incoming requests, and if they are paid (or do not require payment) forward them to the respective webserver configured.

Its options are as follows:

-c FILENAME | –config=FILENAME

Use the configuration in FILENAME. Without this option $XDG_CONFIG_HOME/paivana.conf is read if that variable is set, and ~/.config/paivana.conf otherwise. See paivana.conf(5).

-f | –respect-forwarded-headers

Assert that the peer connecting to paivana-httpd is a reverse proxy whose forwarding headers may be believed. The client address is then derived from the “Forwarded” (RFC 7239) or “X-Forwarded-For” request header, and the chain that was received is forwarded upstream rather than replaced. “Forwarded” is preferred where both are present. The socket address is used when neither header is present, and when the element the chain resolves to names no address at all - RFC 7239’s unknown, an obfuscated identifier, a host name.

The flag extends trust exactly one hop, to that peer, and by itself no further: the client is then the rightmost element of the chain, the only one the peer wrote itself. TRUSTED_PROXIES and TRUSTED_PROXIES6 extend the walk leftwards, one element per trusted hop; see paivana.conf(5).

Only enable this when the server in front either replaces the client’s forwarding headers or appends its own element to them. One that passes “Forwarded” or “X-Forwarded-For” through unchanged - which nginx does with “Forwarded” unless told otherwise - leaves the rightmost element under the client’s control, and with it the identity the access cookie is bound to. Example configurations for nginx and Apache are shipped with Paivana.

When BASE_URL is unset, the scheme and authority of our own base URL are taken from the same headers. From “Forwarded” they come from the element the walk stopped at; from “X-Forwarded-Proto”, “X-Forwarded-Host” and “X-Forwarded-Port” they are the leftmost values received, which the walk does not vet.

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.

-g | –global-payment

Disable per-page payment, a single payment is always valid for the entire site.

-h | –help

Print short help on options.

-L LOGLEVEL | –log=LOGLEVEL

Specifies the log level to use. Accepted values are: DEBUG, INFO, WARNING, ERROR.

-l FILENAME | –logfile=FILENAME

Send logging output to FILENAME.

-n | –no-payment

Disable payment, only act as a reverse proxy that does nothing. Useful to temporarily disable the paywall or to test the reverse proxy itself.

-u BYTES | –max-upload=BYTES

Set how many bytes of a request body are held in memory at once while it is relayed upstream; the default is 262144. Equivalent to REQUEST_BUFFER_MAX in the configuration file, and like it a throughput knob rather than a limit: the largest body accepted is MAX_REQUEST_SIZE, and bodies above that are rejected with HTTP 413. Must be between 1 and 41943040.

This option used to set the limit, because a body that could not be held could not be forwarded. Passing it and leaving MAX_REQUEST_SIZE unset therefore still sets both, so an existing invocation keeps the limit it asked for; see paivana.conf(5).

-v | –version

Print version number.

22.23.4. See Also#

taler-merchant-httpd(1), paivana.conf(5)

22.23.5. Bugs#

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.