donau.conf.5.rst (8962B)
1 .. 2 This file is part of GNU TALER. 3 Copyright (C) 2025 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3.0, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 16 @author Christian Grothoff 17 18 19 donau.conf(5) 20 ############# 21 22 .. only:: html 23 24 Name 25 ==== 26 27 **donau.conf** - Donau configuration file 28 29 30 Description 31 =========== 32 33 .. include:: ../frags/common-conf-syntax.rst 34 35 Files containing default values for many of the options described below 36 are installed under ``$DONAU_PREFIX/share/donau/config.d/``. 37 The configuration file given with **-c** to Donau binaries 38 overrides these defaults. 39 40 A configuration file may include another, by using the ``@INLINE@`` directive, 41 for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to 42 include the entirety of ``sub.conf`` at that point in ``main.conf``. 43 44 Be extra careful when using ``donau-config -V VALUE`` to change configuration 45 values: it will destroy all uses of ``@INLINE@`` and furthermore remove all 46 comments from the configuration file! 47 48 49 GLOBAL OPTIONS 50 -------------- 51 52 The “[PATHS]” section is special in that it contains paths that can be 53 referenced using “$” in other configuration values that specify 54 filenames. For Taler exchange, it commonly contains the following paths: 55 56 DONAU_HOME 57 Home directory of the user, usually “${HOME}”. Can be overwritten by 58 testcases by setting ${DONAU_TEST_HOME}. 59 60 DONAU_DATA_HOME 61 Where should Taler store its long-term data. 62 Usually “${DONAU_HOME}/.local/share/donau/”. 63 64 DONAU_CONFIG_HOME 65 Where is the Taler configuration kept. 66 Usually “${DONAU_HOME}/.config/donau/”. 67 68 DONAU_CACHE_HOME 69 Where should Taler store cached data. 70 Usually “${DONAU_HOME}/.cache/donau/”. 71 72 DONAU_RUNTIME_DIR 73 Where should Taler store system runtime data (like UNIX domain 74 sockets). Usually “${TMP}/donau-runtime”. 75 76 77 DONAU OPTIONS 78 ------------- 79 80 The following options are from the “[donau]” section and used by most 81 Donau components. 82 83 ADMIN_BEARER_TOKEN 84 Bearer access token used to access the REST API to manage charities. 85 Should begin with "secret-token:". 86 87 CURRENCY 88 Name of the currency, e.g. “EUR” for Euro. 89 90 DB 91 Plugin to use for the database, e.g. “postgres”. 92 93 SERVE 94 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"). 95 96 UNIXPATH 97 Path to listen on if we "SERVE" is set to "unix". 98 99 UNIXPATH_MODE 100 Access permission mask to use for the "UNIXPATH". 101 102 PORT 103 Port on which the HTTP server listens, e.g. 8080. 104 105 BIND_TO 106 Hostname to which the exchange HTTP server should be bound to, e.g. "localhost". 107 108 BASE_URL 109 The base URL under which the exchange can be reached. 110 Added to wire transfers to enable tracking by merchants. 111 Used by the KYC logic when interacting with OAuth 2.0. 112 113 TERMS_DIR 114 Directory where the terms of service of the exchange operator can be fund. 115 The directory must contain sub-directories for every supported language, 116 using the two-character language code in lower case, e.g. "en/" or "fr/". 117 Each subdirectory must then contain files with the terms of service in 118 various formats. The basename of the file of the current policy must be 119 specified under ``TERMS_ETAG``. The extension defines the mime type. 120 Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", 121 "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure 122 could be the following: 123 124 - $TERMS_DIR/en/0.pdf 125 - $TERMS_DIR/en/0.html 126 - $TERMS_DIR/en/0.txt 127 - $TERMS_DIR/fr/0.pdf 128 - $TERMS_DIR/fr/0.html 129 - $TERMS_DIR/de/0.txt 130 131 TERMS_ETAG 132 Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. 133 The value is also used for the "Etag" in the HTTP request to control 134 caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also 135 change, and old values MUST NOT be repeated. For example, the date or 136 version number of the terms of service SHOULD be used for the Etag. If 137 there are minor (e.g. spelling) fixes to the terms of service, the 138 ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must 139 approve the new terms, the ``TERMS_ETAG`` MUST change. 140 141 PRIVACY_DIR 142 Works the same as ``TERMS_DIR``, just for the privacy policy. 143 144 PRIVACY_ETAG 145 Works the same as ``TERMS_ETAG``, just for the privacy policy. 146 147 148 DONAU RSA CRYPTO HELPER OPTIONS 149 ------------------------------- 150 151 The following options must be in the section "[donau-secmod-rsa]". 152 153 LOOKAHEAD_SIGN 154 How long do we generate denomination and signing keys ahead of time? 155 156 OVERLAP_DURATION 157 Must be set to zero. 158 159 SM_PRIV_KEY 160 Where should the security module store its long-term private key? 161 162 KEY_DIR 163 Where should the security module store the private keys it manages? 164 165 UNIXPATH 166 On which path should the security module listen for signing requests? 167 168 Note that the **donau-secmod-rsa** also evaluates the ``[doco_*]`` 169 configuration sections described below. 170 171 172 DONAU CS CRYPTO HELPER OPTIONS 173 ------------------------------ 174 175 The following options must be in the section "[donau-secmod-cs]". 176 177 LOOKAHEAD_SIGN 178 How long do we generate denomination and signing keys ahead of time? 179 180 OVERLAP_DURATION 181 Must be set to zero. 182 183 SM_PRIV_KEY 184 Where should the security module store its long-term private key? 185 186 KEY_DIR 187 Where should the security module store the private keys it manages? 188 189 UNIXPATH 190 On which path should the security module listen for signing requests? 191 192 Note that the **donau-secmod-cs** also evaluates the ``[doco_*]`` 193 configuration sections described below. 194 195 196 197 DONAU EDDSA CRYPTO HELPER OPTIONS 198 --------------------------------- 199 200 The following options must be in the section "[donau-secmod-eddsa]". 201 202 LOOKAHEAD_SIGN 203 How long do we generate denomination and signing keys ahead of time? 204 205 OVERLAP_DURATION 206 How much should validity periods for coins overlap? 207 Should be long enough to avoid problems with 208 wallets picking one key and then due to network latency 209 another key being valid. The ``DURATION_WITHDRAW`` period 210 must be longer than this value. 211 212 DURATION 213 For how long should EdDSA keys be valid for signing? 214 215 SM_PRIV_KEY 216 Where should the security module store its long-term private key? 217 218 KEY_DIR 219 Where should the security module store the private keys it manages? 220 221 UNIXPATH 222 On which path should the security module listen for signing requests? 223 224 225 DONAU POSTGRES BACKEND DATABASE OPTIONS 226 --------------------------------------- 227 228 The following options must be in section “[donaudb-postgres]” if the 229 “postgres” plugin was selected for the database. 230 231 CONFIG 232 How to access the database, e.g. “postgres:///donau” to use the 233 “donau” database. Testcases use “donaucheck”. 234 235 236 .. include:: frags/exchange-coin.rst 237 238 DONAU DONATION CONFIRMATION UNIT OPTIONS 239 ---------------------------------------- 240 241 The following options must be in sections starting with ``"[doco_]"`` and are 242 largely used by **donau-httpd** to determine the meta data for the donation 243 units. Some of the options are used by the **donau-secmod-rsa** to determine 244 which RSA keys to create (and of what key length). Note that the section 245 names must match, so this part of the configuration MUST be shared between the 246 RSA helper and the Donau. Configuration values MUST NOT be changed in a 247 running setup. Instead, if parameters for a denomination type are to change, a 248 fresh *section name* should be introduced (and the existing section should be 249 deleted). 250 251 252 VALUE 253 Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per 254 donation unit receipt). 255 256 DURATION_WITHDRAW 257 How long should the same key be used for clients to withdraw coins of 258 this value? Must be set to 1 year. 259 260 DURATION_SPEND 261 How long do clients have to turn in the donation receipts. 262 Should be set to a multiple of years. 263 264 DURATION_LEGAL 265 How long does the Donau have to keep records for this denomination? 266 Should be set to a multiple of years. 267 268 CIPHER 269 What cryptosystem should be used? Must be set to either "CS" or "RSA". 270 The respective crypto-helper will then generate the keys for this 271 denomination. 272 273 RSA_KEYSIZE 274 What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA". 275 276 277 SEE ALSO 278 ======== 279 280 donau-dbinit(1), donau-httpd(1) 281 282 BUGS 283 ==== 284 285 Report bugs by using https://bugs.taler.net/ or by sending electronic 286 mail to <taler@gnu.org>.