CHALLENGER.CONF(5)

📦 version 1.3.0, in nixos 26.05, nixpkgs unstable

💅 challenger.conf — the configuration file glow-up

Okay bestie, welcome to the challenger.conf page from GNU Taler (that's the challenger.conf(5) situation, section 5, iykyk). This is literally the config file for Challenger, and I'm gonna walk you through it like we're texting at 1am. 🫶

✨ DESCRIPTION ✨

So the config file is line-oriented. That means: blank lines are ignored, and so is whitespace at the beginning and end of a line (after any beginning-of-line whitespace, that is). Comments start with # or % in the first column and just keep going to the end of the line. 💅

The file is split into sections. Every section begins with [SECTIONNAME] and contains a bunch of options shaped like OPTION=VALUE. There may be whitespace around the = (equal sign) — she's flexible like that. Section names and options are case-insensitive.

The values, though? case-sensitive, periodt. In particular, boolean values are exactly one of YES or NO. You can include whitespace in a value by wrapping the whole value in " (double quote). But heads up: there are no escape characters in such strings — every character between the double quotes (including other double quotes) is taken verbatim. No cap. 😭

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

Values that represent an amount use 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. Simple like $TMPDIR/foo, or complex like ${TMPDIR:-${TMP:-/tmp}}/foo. The variables get 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 — 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. ⭐

Files containing default values for many of the options described below are installed under $PREFIX/share/challenger/config.d/. The configuration file given with -c to Challenger binaries overrides these defaults.

A configuration file may include another one 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. 🎀

⚠️ Be extra careful when using challenger-config -V VALUE to change configuration values: it will destroy all uses of @INLINE@ and furthermore remove all comments from the configuration file! Like, gone gone. 💀

🌈 GLOBAL OPTIONS 🌈

The following options are from the [challenger] section. This is normally the only section in a challenger.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"). Pick your fighter. 🥊
  • 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. 🔐
  • DB — Plugin to use for the database, e.g. "postgres".
  • VALIDATION_DURATION — How long is a validation challenge valid. After this time period, a fresh random challenge code will be generated and the retry limit counter (against guessing attacks) will be reset (to 3). ⏳
  • VALIDATION_EXPIRATION — How long is a validation allowed to take (time from /setup to /token). After this time, the garbage collection process can delete all associated data. (Note that tokens will always allow access to 1h after they have been issued, regardless of when the validation expires). 🕐
  • AUTH_COMMAND — Which command should we execute to transmit the challenge code to the address. The address is given as the first argument, while the message to send is provided on stdin. Templates (possibly without the necessary credentials) for such commands are provided as challenger-send-email.sh, challenger-send-post.sh and challenger-send-sms.sh. 📨
  • ADDRESS_TYPE — Type of the address that is being collected, returned as part of the address_type in the /info endpoint. Examples include email or phone. 📧
  • ADDRESS_HINT — Hint to show to users for entering the address. Should be an example address in the right format.
  • ADDRESS_RESTRICTIONS — JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a "regex" (string) containing an extended Posix regular expression for allowed address field values, and a "hint"/"hint_i18n" giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be '{"email":{"hint":"valid e-mail address required","regex":"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$"}' or '{"zip":{"hint":"numeric zip code required","regex":"^[0-9]+$"}'. 🔍
  • MESSAGE_TEMPLATE_FILE — Name of a file with a Mustach template to use to generate the challenge message for the customer. The template will be provided the PIN/TAN under {{pin}}, the customer's address in JSON format under {{address}} and the URL of the challenger backend under {{challenger_url}}. 🧚
  • BASE_URL — The base URL under which the challenger can be reached. Provided to message templates to remind users where they need to enter the challenge. 🔗

🦋 SEE ALSO 🦋

challenger-dbinit(1), challenger-httpd(1), challenger-config(1). Go read those too, bestie, they're the supporting cast. 💜

💀 BUGS 💀

Report bugs by using https://bugs.taler.net/ or by sending electronic mail to <taler@gnu.org>. They wanna hear from you fr fr. 🐛

👑 AUTHOR 👑

GNU Taler contributors ✨

2014-2025 Taler Systems SA (GPLv3+ or GFDL 1.3+)

Stay hydrated, keep your [PATHS] tidy, and remember: no escape characters, no regrets. 🍓 Version 1.0, dated Dec 22, 2025 — challenger.conf(5), signing off! 💖

📦 where this page comes from