paivana-httpd.1.rst (4766B)
1 paivana-httpd(1) 2 ################ 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **paivana-httpd** - reverse-proxy paywall 10 11 12 Synopsis 13 ======== 14 15 **paivana-httpd** 16 [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] 17 [**-f** | **--respect-forwarded-headers**] 18 [**-g** | **--global-payment**] 19 [**-h** | **--help**] 20 [**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] 21 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] 22 [**-n** | **--no-payment**] 23 [**-u** *BYTES* | **--max-upload=**\ \ *BYTES*] 24 [**-v** | **--version**] 25 26 Description 27 =========== 28 29 **paivana-httpd** is a reverse proxy that requires the client to 30 make a payment using GNU Taler before forwarding the request. 31 The reverse proxy uses a GNU Taler merchant backend to process 32 payments and also learns which websites require payment and how 33 much the prices are. Thus, the main configuration is done within 34 the Taler merchant backend. 35 36 paivana-httpd will simply open an HTTP socket, listen for incoming 37 requests, and if they are paid (or do not require payment) forward 38 them to the respective webserver configured. 39 40 Its options are as follows: 41 42 **-c** *FILENAME* | **--config=**\ \ *FILENAME* 43 Use the configuration in *FILENAME*. Without this option 44 ``$XDG_CONFIG_HOME/paivana.conf`` is read if that variable is set, 45 and ``~/.config/paivana.conf`` otherwise. See paivana.conf(5). 46 47 **-f** | **--respect-forwarded-headers** 48 Assert that the peer connecting to paivana-httpd is a reverse proxy 49 whose forwarding headers may be believed. The client address is 50 then derived from the "Forwarded" (RFC 7239) or "X-Forwarded-For" 51 request header, and the chain that was received is forwarded 52 upstream rather than replaced. "Forwarded" is preferred where both 53 are present. The socket address is used when neither header is 54 present, and when the element the chain resolves to names no 55 address at all - RFC 7239's ``unknown``, an obfuscated identifier, 56 a host name. 57 58 The flag extends trust exactly one hop, to that peer, and by itself 59 no further: the client is then the **rightmost** element of the 60 chain, the only one the peer wrote itself. ``TRUSTED_PROXIES`` and 61 ``TRUSTED_PROXIES6`` extend the walk leftwards, one element per 62 trusted hop; see paivana.conf(5). 63 64 Only enable this when the server in front either replaces the 65 client's forwarding headers or appends its own element to them. 66 One that passes "Forwarded" or "X-Forwarded-For" through unchanged 67 - which nginx does with "Forwarded" unless told otherwise - leaves 68 the rightmost element under the client's control, and with it the 69 identity the access cookie is bound to. Example configurations for 70 nginx and Apache are shipped with Paivana. 71 72 When ``BASE_URL`` is unset, the scheme and authority of our own 73 base URL are taken from the same headers. From "Forwarded" they 74 come from the element the walk stopped at; from 75 "X-Forwarded-Proto", "X-Forwarded-Host" and "X-Forwarded-Port" they 76 are the leftmost values received, which the walk does not vet. 77 78 This option is required when ``SERVE`` is ``unix``: a UNIX domain 79 peer has no address of its own, so without it there is no client 80 address at all, the access cookie cannot be bound to a client, and 81 payment callbacks fail. 82 83 **-g** | **--global-payment** 84 Disable per-page payment, a single payment is always valid 85 for the entire site. 86 87 **-h** | **--help** 88 Print short help on options. 89 90 **-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL* 91 Specifies the log level to use. Accepted values are: ``DEBUG``, 92 ``INFO``, ``WARNING``, ``ERROR``. 93 94 **-l** *FILENAME* | **--logfile=**\ \ *FILENAME* 95 Send logging output to *FILENAME*. 96 97 **-n** | **--no-payment** 98 Disable payment, only act as a reverse proxy that does nothing. 99 Useful to temporarily disable the paywall or to test the 100 reverse proxy itself. 101 102 **-u** *BYTES* | **--max-upload=**\ \ *BYTES* 103 Set how many bytes of a request body are held in memory at once 104 while it is relayed upstream; the default is 262144. Equivalent to 105 ``REQUEST_BUFFER_MAX`` in the configuration file, and like it a 106 throughput knob rather than a limit: the largest body accepted is 107 ``MAX_REQUEST_SIZE``, and bodies above that are rejected with HTTP 108 413. Must be between 1 and 41943040. 109 110 This option used to set the limit, because a body that could not be 111 held could not be forwarded. Passing it and leaving 112 ``MAX_REQUEST_SIZE`` unset therefore still sets both, so an 113 existing invocation keeps the limit it asked for; see 114 paivana.conf(5). 115 116 **-v** | **--version** 117 Print version number. 118 119 See Also 120 ======== 121 122 taler-merchant-httpd(1), paivana.conf(5) 123 124 Bugs 125 ==== 126 127 Report bugs by using https://bugs.taler.net or by sending electronic 128 mail to <taler@gnu.org>.