paivana.conf.5.rst (10696B)
1 paivana.conf(5) 2 ############### 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **paivana.conf** - Paivana configuration file 10 11 12 Description 13 =========== 14 15 .. include:: ../frags/common-conf-syntax.rst 16 17 Paivana is configured from the file named with **-c**; without that 18 option, ``$XDG_CONFIG_HOME/paivana.conf`` is read if that variable is 19 set, and ``~/.config/paivana.conf`` otherwise. Files under 20 ``$PREFIX/share/paivana/config.d/`` are read first and overridden by 21 it, but Paivana installs none: every option below is either required 22 or has the default stated with it. 23 24 A configuration file may include another, by using the ``@INLINE@`` directive, 25 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 26 include the entirety of ``sub.conf`` at that point in ``main.conf``. 27 28 29 30 GLOBAL OPTIONS 31 -------------- 32 33 The following options are from the “[paivana]” section. 34 This is normally the only section in a paivana.conf file. 35 36 SERVE 37 Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd"). 38 39 PORT 40 Port on which the HTTP server listens, e.g. 9967. 41 Only used if ``SERVE`` is ``tcp``. 42 43 BIND_TO 44 Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1`` 45 for loopback. Can also be given as a hostname. We will bind to 46 the wildcard (dual-stack) if left empty. 47 Only used if ``SERVE`` is ``tcp``. 48 49 UNIXPATH 50 Which unix domain path should we bind to? 51 Only used if ``SERVE`` is ``unix``. 52 53 UNIXPATH_MODE = 660 54 What should be the file access permissions for ``UNIXPATH``? 55 Only used if ``SERVE`` is ``unix``. 56 57 CONNECTION_LIMIT 58 Total number of concurrent client connections to accept, default 59 512. Divided evenly over the listen sockets that come up - one per 60 address bound, typically two when ``BIND_TO`` is empty - so this is 61 the process-wide total. Outbound requests spend file descriptors 62 from the same table, so leave headroom below the process limit. 63 This setting is optional. 64 65 PER_IP_CONNECTION_LIMIT 66 Concurrent connections accepted from any one peer address, default 67 32; 0 disables the check. This is the address of the peer that 68 connected, not the client address recovered from the forwarding 69 headers, so set it to 0 wherever the two differ: under ``SERVE`` 70 ``unix`` or ``systemd`` every client shares one peer, and behind a 71 reverse proxy or a NAT many clients do. This setting is optional. 72 73 MAX_REQUEST_SIZE 74 Largest request body accepted, default 1048576. A body above this 75 is answered with HTTP 413; where the client declared a 76 ``Content-Length`` the refusal is immediate, and otherwise it 77 follows as soon as the body actually exceeds the limit. Only the 78 body is counted -- the request header block has its own limit. 79 This setting is optional. 80 81 This is a policy limit and not a memory one. Bodies are streamed, 82 so the amount Paivana holds at once is ``REQUEST_BUFFER_MAX`` 83 regardless of how large this is. 84 85 REQUEST_BUFFER_MAX 86 How many bytes of a request body Paivana holds in memory at once 87 while relaying it upstream, default 262144. Also settable with 88 **-u**; see paivana-httpd(1). Must be between 1 and 41943040. 89 This setting is optional. 90 91 A throughput knob rather than a limit: it bounds how far the client 92 may run ahead of the upstream before Paivana stops reading from it, 93 not how large a body may be. Larger means fewer suspend/resume 94 round trips on a fast link and more memory per request in flight; 95 the worst case is this times ``CONNECTION_LIMIT``. 96 97 Before request bodies were streamed this key did both jobs, because 98 a body that could not be held could not be forwarded. For the sake 99 of configurations written then, setting this and **not** setting 100 ``MAX_REQUEST_SIZE`` still sets both: such a file keeps the limit it 101 asked for, at the cost of a correspondingly large buffer. Set both 102 explicitly to separate them. 103 104 RESPONSE_BUFFER_MAX 105 As ``REQUEST_BUFFER_MAX``, for the response body travelling the 106 other way, default 262144. This setting is optional. 107 108 There is deliberately no ``MAX_RESPONSE_SIZE`` to go with it. A 109 response is relayed as it arrives and never assembled, so its size 110 is bounded by nothing in Paivana; an operator who wants a ceiling on 111 what their own upstream serves can impose it at the upstream. 112 113 UPSTREAM_TIMEOUT 114 How long the upstream has to produce its response *headers* before 115 the request is answered with HTTP 504, default ``60 s``. This 116 setting is optional. 117 118 Not a bound on how long a request may take: a large download runs 119 for as long as it runs. The clock stops the moment the header 120 section ends, and this is the only one of the two upstream timeouts 121 that can still produce a status code -- after it, the status has 122 already gone to the client. A stalling upstream is caught by 123 ``UPSTREAM_STALL_TIMEOUT`` instead. 124 125 UPSTREAM_STALL_TIMEOUT 126 How long the upstream may move no bytes at all, in either 127 direction, before Paivana gives up on the request, default 128 ``60 s``. This setting is optional. 129 130 The clock does not run while Paivana is itself the reason nothing is 131 moving -- that is, while it has stopped reading from the upstream 132 because the client has not drained what already arrived. A client 133 on a slow link is therefore never mistaken for a slow upstream. 134 135 What expiry does to the client depends on how far the response had 136 got. Before the upstream's headers were relayed, the client gets 137 HTTP 504. After them the status has already been sent and cannot be 138 retracted, so the response is truncated instead: a declared 139 ``Content-Length`` is left unmet, or a chunked response is closed 140 without its terminating chunk. The Paivana manual has the details. 141 142 TRUSTED_PROXIES 143 IPv4 networks whose members are reverse proxies trusted to report 144 the client address in the ``Forwarded`` or ``X-Forwarded-For`` 145 request headers. Only consulted if paivana-httpd is started with 146 **-f**; see paivana-httpd(1). 147 148 **-f** trusts the peer that connected, and by itself nothing beyond 149 it: the client is then the rightmost element of the chain, the only 150 one that peer wrote itself. Each network named here lets the walk 151 step one element further left, past a node it matches. The chain is 152 walked from the right and the first element that is not a listed 153 proxy is the client, so entries a client prepended cannot be 154 promoted: the walk stops at the address the trusted proxy actually 155 reported. This is what makes a chain longer than one hop usable 156 without trusting whatever the client wrote at its head. 157 158 The peer itself is not matched against these lists; **-f** is the 159 statement that it may be believed. A peer on a UNIX domain socket 160 is therefore trusted like any other: it has no address to match, is 161 by construction on the local machine, and access to the socket is 162 governed by ``UNIXPATH_MODE``. 163 164 The syntax is that of GNUnet's network policies, which has three 165 properties worth stating: 166 167 * entries are separated **and terminated** by ``;``, so a missing 168 trailing semicolon means nothing is parsed at all; 169 * ``0.0.0.0/0`` cannot be expressed, being indistinguishable from 170 the end of the list; 171 * a netmask may be given in CIDR (``/8``) or dotted-decimal 172 (``/255.0.0.0``) notation, and may be omitted to name a single 173 host. 174 175 Anything that parses to an empty list aborts startup rather than 176 silently trusting nobody. Example:: 177 178 TRUSTED_PROXIES = 10.0.0.0/8;192.168.0.0/16; 179 180 This setting is optional. 181 182 TRUSTED_PROXIES6 183 As ``TRUSTED_PROXIES``, but for IPv6 networks. Note that unlike the 184 IPv4 option, this one does **not** tolerate whitespace between 185 entries, and that ``::/0`` cannot be expressed. Example:: 186 187 TRUSTED_PROXIES6 = 2001:db8::/32;fe80::/10; 188 189 Put IPv4 proxies in ``TRUSTED_PROXIES``, not here as 190 ``::ffff:a.b.c.d``: addresses are reduced to their IPv4 form before 191 being matched, so an IPv4-mapped entry would never be reached. 192 193 This setting is optional. 194 195 BASE_URL 196 Our own base URL. Required unless **-f** or **-n** is given: 197 paivana-httpd refuses to start without it, because a client's own 198 "Host" header cannot identify this site unless a reverse proxy 199 vouches for it, and with **-n** there is no paywall to identify it 200 for. When it is unset, the base URL is reconstructed per request 201 from the forwarding headers and "Host"; see paivana-httpd(1). 202 Write it with a trailing '/', as usual; the trailing slashes are 203 removed before the request path is appended, so the resulting 204 URL never contains a doubled '/'. 205 206 DESTINATION_BASE_URL 207 Base URL of the target HTTP server we forward requests to once 208 they have passed the paywall check. As with BASE_URL, trailing 209 slashes are removed before the request path is appended. 210 211 DESTINATION_UNIXPATH 212 Unix domain socket to connect to when forwarding requests. 213 Used when the target REST service (behind the paywall) is 214 running on a UNIX domain socket. DESTINATION_BASE_URL must 215 still be set. This setting is optional. 216 217 MERCHANT_BACKEND_URL 218 Base URL of our Taler merchant backend. 219 220 MERCHANT_BACKEND_UNIX_PATH 221 UNIX path of our Taler merchant backend. Optional. Only set this 222 option if the backend is reachable on the local machine via a 223 UNIX domain socket. 224 225 MERCHANT_ACCESS_TOKEN 226 Access token to use when accessing the merchant backend. 227 This is a secret value. 228 229 SECRET 230 Secret used to determine the Paivana cookie for access control. 231 Should be set to ensure cookies remain valid across restarts. 232 Optional, generated at random at every startup if not set. 233 This is a secret value. It is hashed once, unsalted and without 234 stretching, to derive the cookie key, so a short or guessable value 235 can be recovered offline from a single observed cookie: use at least 236 128 bits from a cryptographic random source, as shown in the Paivana 237 manual. 238 239 WHITELIST 240 Posix extended regular expression whitelisting some paths. 241 Whitelisted paths are never subject to the paywall. Should 242 be used to whitelist resources such as images or style sheets. 243 Paths matched against the whitelist always start with '/'. 244 The expression must match the path in its **entirety**: 245 it is anchored at both ends before it is compiled, so 246 ``/assets/`` whitelists nothing and ``/assets/.*`` is 247 needed to whitelist that subtree. Paths longer than 248 16384 bytes are rejected with HTTP 414 rather than matched. 249 This setting is optional. 250 251 SEE ALSO 252 ======== 253 254 paivana-httpd(1), taler-merchant-httpd(1) 255 256 257 BUGS 258 ==== 259 260 Report bugs by using https://bugs.taler.net/ or by sending electronic 261 mail to <taler@gnu.org>.