challenger.conf.5.rst (4915B)
1 challenger.conf(5) 2 ################## 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **challenger.conf** - Challenger configuration file 10 11 12 Description 13 =========== 14 15 .. include:: ../frags/common-conf-syntax.rst 16 17 Files containing default values for many of the options described below 18 are installed under ``$PREFIX/share/challenger/config.d/``. 19 The configuration file given with **-c** to Challenger binaries 20 overrides these defaults. 21 22 A configuration file may include another, by using the ``@INLINE@`` directive, 23 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 24 include the entirety of ``sub.conf`` at that point in ``main.conf``. 25 26 Be extra careful when using ``challenger-config -V VALUE`` to change configuration 27 values: it will destroy all uses of ``@INLINE@`` and furthermore remove all 28 comments from the configuration file! 29 30 31 GLOBAL OPTIONS 32 -------------- 33 34 The following options are from the “[challenger]” section. 35 This is normally the only section in a challenger.conf file. 36 37 SERVE 38 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"). 39 40 PORT 41 Port on which the HTTP server listens, e.g. 9967. 42 Only used if ``SERVE`` is ``tcp``. 43 44 BIND_TO 45 Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1`` 46 for loopback. Can also be given as a hostname. We will bind to 47 the wildcard (dual-stack) if left empty. 48 Only used if ``SERVE`` is ``tcp``. 49 50 UNIXPATH 51 Which unix domain path should we bind to? 52 Only used if ``SERVE`` is ``unix``. 53 54 UNIXPATH_MODE = 660 55 What should be the file access permissions for ``UNIXPATH``? 56 Only used if ``SERVE`` is ``unix``. 57 58 DB 59 Plugin to use for the database, e.g. “postgres”. 60 61 VALIDATION_DURATION 62 How long a pending validation process may take, starting with ``/setup`` 63 and ending with ``/token``. After this time the process can no longer be 64 authorized or exchanged for a token, and garbage collection may delete the 65 associated process data. Optional, defaults to 1 day if not given. 66 67 VALIDATION_EXPIRATION 68 How long a successfully validated address is considered valid. This 69 validity is reported by ``/info`` after the client exchanges the 70 authorization code at ``/token``. Optional, defaults to 365 days if not 71 given. 72 73 TOKEN_EXPIRATION 74 How long is the access token valid after it was issued. 75 Optional, defaults to 1 hour if not given. 76 77 PIN_RETRANSMISSION_FREQUENCY 78 Minimum time that must pass before the same challenge code (TAN) is (re)transmitted to the same address again. Users may ask the challenger to re-send the challenge, but such requests are ignored if the last transmission happened more recently than this. Should be (much) smaller than ``VALIDATION_DURATION``. Optional, defaults to 5 minutes if not given. 79 80 AUTH_COMMAND 81 Command to execute to transmit the challenge code to the address. The value 82 may include arguments separated by spaces. Quoting and escaping are not 83 supported. The address is appended as the final argument, while the message 84 to send is provided on standard input. Templates (possibly without the 85 necessary credentials) for such commands are provided as 86 challenger-send-email.sh, challenger-send-post.sh and 87 challenger-send-sms.sh. 88 89 ADDRESS_TYPE 90 Type of the address that is being collected, returned as part of the ``address_type`` in the ``/info`` endpoint. Examples include ``email`` or ``phone``. 91 92 ADDRESS_HINT 93 Hint to show to users for entering the address. Should be an example address in the right format. 94 95 ADDRESS_RESTRICTIONS 96 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]+$"}'. 97 98 MESSAGE_TEMPLATE_FILE 99 Name of a file with a Mustach template to use to generate the challenge message for the customer. The template will be provided the TAN under ``{{pin}}``, the customer's address in JSON format under ``{{address}}`` and the URL of the challenger backend under ``{{challenger_url}}``. 100 101 BASE_URL 102 The base URL under which the challenger can be reached. 103 Provided to message templates to remind users where they 104 need to enter the challenge. 105 106 107 SEE ALSO 108 ======== 109 110 challenger-dbinit(1), challenger-httpd(1), challenger-config(1). 111 112 113 BUGS 114 ==== 115 116 Report bugs by using https://bugs.taler.net/ or by sending electronic 117 mail to <taler@gnu.org>.