paivana.conf(5)

24.30. paivana.conf(5)#

24.30.1. Name#

paivana.conf - Paivana configuration file

24.30.2. Description#

The configuration file is line-oriented. Blank lines and whitespace at the beginning and end of a line are ignored. Comments start with # or % in the first column (after any beginning-of-line whitespace) and go to the end of the line.

The file is split into sections. Every section begins with [SECTIONNAME] and contains a number of options of the form OPTION=VALUE. There may be whitespace around the = (equal sign). Section names and options are case-insensitive.

The values, however, are case-sensitive. In particular, boolean values are one of YES or NO. Values can include whitespace by surrounding the entire value with " (double quote). Note, however, that there are no escape characters in such strings; all characters between the double quotes (including other double quotes) are taken verbatim.

Values that represent a time duration are represented as a series of one or more NUMBER UNIT pairs, e.g. 60 s, 4 weeks 1 day, 5 years 2 minutes.

Values that represent an amount are in the usual amount syntax: CURRENCY:VALUE.FRACTION, e.g. EUR:1.50. The FRACTION portion may extend up to 8 places.

Values that represent filenames can begin with a /bin/sh-like variable reference. This can be simple, such as $TMPDIR/foo, or complex, such as ${TMPDIR:-${TMP:-/tmp}}/foo. The variables are expanded either using key-values from the [PATHS] section (see below) or from the environment (getenv()). The values from [PATHS] take precedence over those from the environment. If the variable name is found in neither [PATHS] nor the environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if FOO=$BAR and BAR=buzz then the result is FOO=buzz. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if BAR=$FOO in the example above.

The [PATHS] section is special in that it contains paths that can be referenced using $ in other configuration values that specify filenames. Note that configuration options that are not specifically retrieved by the application as filenames will not see “$”-expressions expanded. To expand $-expressions when using taler-config, you must pass the -f command-line option.

The system automatically pre-populates the [PATHS] section with a few values at run-time (in addition to the values that are in the actual configuration file and automatically overwriting those values if they are present). These automatically generated values refer to installation properties from GNU autoconf. The values are usually dependent on an INSTALL_PREFIX which is determined by the --prefix option given to configure. The canonical values are:

  • LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/

  • DOCDIR = $INSTALL_PREFIX/share/doc/taler/

  • ICONDIR = $INSTALL_PREFIX/share/icons/

  • LOCALEDIR = $INSTALL_PREFIX/share/locale/

  • PREFIX = $INSTALL_PREFIX/

  • BINDIR = $INSTALL_PREFIX/bin/

  • LIBDIR = $INSTALL_PREFIX/lib/taler/

  • DATADIR = $INSTALL_PREFIX/share/taler/

Note that on some platforms, the given paths may differ depending on how the system was compiled or installed, the above are just the canonical locations of the various resources. These automatically generated values are never written to disk.

Paivana is configured from the file named with -c; without that option, $XDG_CONFIG_HOME/paivana.conf is read if that variable is set, and ~/.config/paivana.conf otherwise. Files under $PREFIX/share/paivana/config.d/ are read first and overridden by it, but Paivana installs none: every option below is either required or has the default stated with it.

A configuration file may include another, by using the @INLINE@ directive, for example, in main.conf, you could write @INLINE@ sub.conf to include the entirety of sub.conf at that point in main.conf.

24.30.2.1. GLOBAL OPTIONS#

The following options are from the “[paivana]” section. This is normally the only section in a paivana.conf file.

SERVE

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”).

PORT

Port on which the HTTP server listens, e.g. 9967. Only used if SERVE is tcp.

BIND_TO

Which IP address should we bind to? E.g. 127.0.0.1 or ::1 for loopback. Can also be given as a hostname. We will bind to the wildcard (dual-stack) if left empty. Only used if SERVE is tcp.

UNIXPATH

Which unix domain path should we bind to? Only used if SERVE is unix.

UNIXPATH_MODE = 660

What should be the file access permissions for UNIXPATH? Only used if SERVE is unix.

CONNECTION_LIMIT

Total number of concurrent client connections to accept, default 512. Divided evenly over the listen sockets that come up - one per address bound, typically two when BIND_TO is empty - so this is the process-wide total. Outbound requests spend file descriptors from the same table, so leave headroom below the process limit. This setting is optional.

PER_IP_CONNECTION_LIMIT

Concurrent connections accepted from any one peer address, default 32; 0 disables the check. This is the address of the peer that connected, not the client address recovered from the forwarding headers, so set it to 0 wherever the two differ: under SERVE unix or systemd every client shares one peer, and behind a reverse proxy or a NAT many clients do. This setting is optional.

MAX_REQUEST_SIZE

Largest request body accepted, default 1048576. A body above this is answered with HTTP 413; where the client declared a Content-Length the refusal is immediate, and otherwise it follows as soon as the body actually exceeds the limit. Only the body is counted – the request header block has its own limit. This setting is optional.

This is a policy limit and not a memory one. Bodies are streamed, so the amount Paivana holds at once is REQUEST_BUFFER_MAX regardless of how large this is.

REQUEST_BUFFER_MAX

How many bytes of a request body Paivana holds in memory at once while relaying it upstream, default 262144. Also settable with -u; see paivana-httpd(1). Must be between 1 and 41943040. This setting is optional.

A throughput knob rather than a limit: it bounds how far the client may run ahead of the upstream before Paivana stops reading from it, not how large a body may be. Larger means fewer suspend/resume round trips on a fast link and more memory per request in flight; the worst case is this times CONNECTION_LIMIT.

Before request bodies were streamed this key did both jobs, because a body that could not be held could not be forwarded. For the sake of configurations written then, setting this and not setting MAX_REQUEST_SIZE still sets both: such a file keeps the limit it asked for, at the cost of a correspondingly large buffer. Set both explicitly to separate them.

RESPONSE_BUFFER_MAX

As REQUEST_BUFFER_MAX, for the response body travelling the other way, default 262144. This setting is optional.

There is deliberately no MAX_RESPONSE_SIZE to go with it. A response is relayed as it arrives and never assembled, so its size is bounded by nothing in Paivana; an operator who wants a ceiling on what their own upstream serves can impose it at the upstream.

UPSTREAM_TIMEOUT

How long the upstream has to produce its response headers before the request is answered with HTTP 504, default 60 s. This setting is optional.

Not a bound on how long a request may take: a large download runs for as long as it runs. The clock stops the moment the header section ends, and this is the only one of the two upstream timeouts that can still produce a status code – after it, the status has already gone to the client. A stalling upstream is caught by UPSTREAM_STALL_TIMEOUT instead.

UPSTREAM_STALL_TIMEOUT

How long the upstream may move no bytes at all, in either direction, before Paivana gives up on the request, default 60 s. This setting is optional.

The clock does not run while Paivana is itself the reason nothing is moving – that is, while it has stopped reading from the upstream because the client has not drained what already arrived. A client on a slow link is therefore never mistaken for a slow upstream.

What expiry does to the client depends on how far the response had got. Before the upstream’s headers were relayed, the client gets HTTP 504. After them the status has already been sent and cannot be retracted, so the response is truncated instead: a declared Content-Length is left unmet, or a chunked response is closed without its terminating chunk. The Paivana manual has the details.

TRUSTED_PROXIES

IPv4 networks whose members are reverse proxies trusted to report the client address in the Forwarded or X-Forwarded-For request headers. Only consulted if paivana-httpd is started with -f; see paivana-httpd(1).

-f trusts the peer that connected, and by itself nothing beyond it: the client is then the rightmost element of the chain, the only one that peer wrote itself. Each network named here lets the walk step one element further left, past a node it matches. The chain is walked from the right and the first element that is not a listed proxy is the client, so entries a client prepended cannot be promoted: the walk stops at the address the trusted proxy actually reported. This is what makes a chain longer than one hop usable without trusting whatever the client wrote at its head.

The peer itself is not matched against these lists; -f is the statement that it may be believed. A peer on a UNIX domain socket is therefore trusted like any other: 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. Required unless -f or -n is given: paivana-httpd refuses to start without it, because a client’s own “Host” header cannot identify this site unless a reverse proxy vouches for it, and with -n there is no paywall to identify it for. When it is unset, the base URL is reconstructed per request from the forwarding headers and “Host”; see paivana-httpd(1). Write it with a trailing ‘/’, as usual; the trailing slashes are removed before the request path is appended, so the resulting URL never contains a doubled ‘/’.

DESTINATION_BASE_URL

Base URL of the target HTTP server we forward requests to once they have passed the paywall check. As with BASE_URL, trailing slashes are removed before the request path is appended.

DESTINATION_UNIXPATH

Unix domain socket to connect to when forwarding requests. Used when the target REST service (behind the paywall) is running on a UNIX domain socket. DESTINATION_BASE_URL must still be set. This setting is optional.

MERCHANT_BACKEND_URL

Base URL of our Taler merchant backend.

MERCHANT_BACKEND_UNIX_PATH

UNIX path of our Taler merchant backend. Optional. Only set this option if the backend is reachable on the local machine via a UNIX domain socket.

MERCHANT_ACCESS_TOKEN

Access token to use when accessing the merchant backend. This is a secret value.

SECRET

Secret used to determine the Paivana cookie for access control. Should be set to ensure cookies remain valid across restarts. Optional, generated at random at every startup if not set. This is a secret value. It is hashed once, unsalted and without stretching, to derive the cookie key, so a short or guessable value can be recovered offline from a single observed cookie: use at least 128 bits from a cryptographic random source, as shown in the Paivana manual.

WHITELIST

Posix extended regular expression whitelisting some paths. Whitelisted paths are never subject to the paywall. Should be used to whitelist resources such as images or style sheets. Paths matched against the whitelist always start with ‘/’. The expression must match the path in its entirety: it is anchored at both ends before it is compiled, so /assets/ whitelists nothing and /assets/.* is needed to whitelist that subtree. Paths longer than 16384 bytes are rejected with HTTP 414 rather than matched. This setting is optional.

24.30.3. SEE ALSO#

paivana-httpd(1), taler-merchant-httpd(1)

24.30.4. BUGS#

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