commit 50120e2fdc219aeeea73d132d5cb14c0bb11a2e3
parent c68e3198c38d4e106fa78c3d707cac5c77623db0
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 15 Nov 2024 16:01:18 +0100
update documentation to reflect taler-config split
Diffstat:
21 files changed, 1869 insertions(+), 1206 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -15,3 +15,4 @@ texinfo/
!/design-documents/wallet-screenshots/**/*.png
!/screenshots/*.png
+images/system.pdf
diff --git a/conf.py b/conf.py
@@ -700,9 +700,23 @@ man_pages = [
1,
),
(
- "manpages/taler-config.1",
- "taler-config",
- "Taler configuration inspection and editing",
+ "manpages/taler-auditor-config.1",
+ "taler-auditor-config",
+ "Taler auditor configuration inspection and editing",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/taler-exchange-config.1",
+ "taler-exchange-config",
+ "Taler exchange configuration inspection and editing",
+ "GNU Taler contributors",
+ 1,
+ ),
+ (
+ "manpages/taler-merchant-config.1",
+ "taler-merchant-config",
+ "Taler merchant configuration inspection and editing",
"GNU Taler contributors",
1,
),
@@ -714,9 +728,37 @@ man_pages = [
1,
),
(
- "manpages/taler.conf.5",
- "taler.conf",
- "Taler configuration file",
+ "manpages/taler-auditor.conf.5",
+ "taler-auditor.conf",
+ "Taler auditor configuration file",
+ "GNU Taler contributors",
+ 5,
+ ),
+ (
+ "manpages/taler-exchange.conf.5",
+ "taler-exchange.conf",
+ "Taler exchange configuration file",
+ "GNU Taler contributors",
+ 5,
+ ),
+ (
+ "manpages/taler-fakebank.conf.5",
+ "taler-fakebank.conf",
+ "Taler fakebank configuration file",
+ "GNU Taler contributors",
+ 5,
+ ),
+ (
+ "manpages/taler-mdb.conf.5",
+ "taler-mdb.conf",
+ "Taler-mdb configuration file",
+ "GNU Taler contributors",
+ 5,
+ ),
+ (
+ "manpages/taler-merchant.conf.5",
+ "taler-merchant.conf",
+ "Taler merchant configuration file",
"GNU Taler contributors",
5,
),
diff --git a/frags/using-taler-config.rst b/frags/using-taler-config.rst
@@ -1,9 +1,15 @@
-Using taler-config
-------------------
+Using taler-*-config
+--------------------
-The tool ``taler-config`` can be used to extract or manipulate configuration
+GNU Taler comes with various tools all called ``taler-$COMPONENT-config``,
+such as ``taler-exchange-config`` and ``taler-merchant-config``. They
+all behave the same way, but are accessing the default configurations
+of the respective ``$COMPONENT``. In this man page we will thus simply
+refer to these tools as the ``$TALER_CONFIG`` tool.
+
+The ``$TALER_CONFIG`` tool can be used to extract or manipulate configuration
values; however, the configuration use the well-known INI file format and is
-generally better edited by hand to preserve comments and structure. Thus, ``taler-config`` should primarily be used
+generally better edited by hand to preserve comments and structure. Thus, ``$TALER_CONFIG`` should primarily be used
to inspect or understand a configuration that is in place,
and not to update it!
@@ -11,7 +17,7 @@ Run
.. code-block:: console
- $ taler-config -s $SECTION
+ $ $TALER_CONFIG -s $SECTION
to list all of the configuration values in section ``$SECTION``.
@@ -19,7 +25,7 @@ Run
.. code-block:: console
- $ taler-config -s $SECTION -o $OPTION
+ $ $TALER_CONFIG -s $SECTION -o $OPTION
to extract the respective configuration value for option ``$OPTION`` in
section ``$SECTION``.
@@ -30,7 +36,7 @@ removing all comments, run
.. code-block:: console
- $ taler-config -s $SECTION -o $OPTION -V $VALUE
+ $ $TALER_CONFIG -s $SECTION -o $OPTION -V $VALUE
to set the respective configuration value to ``$VALUE``. Note that you
have to manually restart affected Taler components after you change the
@@ -38,14 +44,15 @@ configuration to make the new configuration go into effect.
Some default options will use $-variables, such as ``$DATADIR`` within
their value. To expand the ``$DATADIR`` or other $-variables in the
-configuration, pass the ``-f`` option to ``taler-config``. For example,
+configuration, pass the ``-f`` option to ``$TALER_CONFIG``. For example,
compare:
.. code-block:: console
- $ taler-config --section exchange-offline --option MASTER_PRIV_FILE
- $ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE
+ $ $TALER_CONFIG --section exchange-offline --option MASTER_PRIV_FILE
+ $ $TALER_CONFIG -f --section exchange-offline --option MASTER_PRIV_FILE
While the configuration file is typically located at
-``$HOME/.config/taler.conf``, an alternative location can be specified to any
+``$HOME/.config/taler-$COMPONENT.conf``,
+an alternative location can be specified to any
GNU Taler component using the ``-c`` option.
diff --git a/manpages/frags/currency-spec.rst b/manpages/frags/currency-spec.rst
@@ -0,0 +1,73 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Christian Grothoff
+ @author Marc Stibane
+
+
+CURRENCY SPECIFICATIONS
+-----------------------
+
+Sections with a name of the form “[currency-$NAME]” (where "$NAME" could
+be any unique string) are used to specify details about how currencies
+should be handled (and in particularly rendered) by the user interface.
+A detailed motivation for this section can be found in DD51.
+Different components can have different rules for the same currency. For
+example, a bank or merchant may decide to render Euros or Dollars with
+always exactly two fractional decimals, while an Exchange for the same
+currency may support additional decimals. The required options in each
+currency specification section are:
+
+ENABLED
+ Set to YES or NO. If set to NO, the currency specification
+ section is ignored. Can be used to disable currencies or
+ select alternative sections for the same CODE with different
+ choices.
+
+CODE
+ Code name for the currency. Can be at most 11 characters,
+ only the letters A-Z are allowed. Primary way to identify
+ the currency in the protocol.
+
+NAME
+ Long human-readable name for the currency. No restrictions,
+ but should match the official name in English.
+
+FRACTIONAL_INPUT_DIGITS
+ Number of fractional digits that users are allowed to enter
+ manually in the user interface.
+
+FRACTIONAL_NORMAL_DIGITS
+ Number of fractional digits that will be rendered normally
+ (in terms of size and placement). Digits shown beyond this
+ number will typically be rendered smaller and raised (if
+ possible).
+
+FRACTIONAL_TRAILING_ZERO_DIGITS
+ Number of fractional digits to pad rendered amounts with
+ even if these digits are all zero. For example, use 2 to
+ render 1 USD as $1.00.
+
+ALT_UNIT_NAMES
+ JSON map determining how to encode very large or very tiny
+ amounts in this currency. Maps a base10 logarithm to the
+ respective currency symbol. Must include at least an
+ entry for 0 (currency unit). For example, use
+ {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could
+ additionally use {"0":"€","3":"k€"} to render 3000 EUR
+ as 3k€. For BTC a typical map would be
+ {"0":"BTC","-3":"mBTC"}, informing the UI to render small
+ amounts in milli-Bitcoin (mBTC).
diff --git a/manpages/frags/exchange-account.rst b/manpages/frags/exchange-account.rst
@@ -0,0 +1,78 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+EXCHANGE ACCOUNT OPTIONS
+------------------------
+
+An exchange (or merchant) can have multiple bank accounts. The following
+options are for sections named “[exchange-account-SOMETHING]”. The ``SOMETHING`` is
+arbitrary and should be chosen to uniquely identify the bank account for
+the operator. These options are used by the **taler-exchange-aggregator**, **taler-exchange-closer**, **taler-exchange-transfer** and **taler-exchange-wirewatch** tools.
+
+PAYTO_URI
+ Specifies the payto://-URL of the account. The general format is
+ ``payto://$METHOD/$DETAILS``. Examples:
+ ``payto://x-taler-bank/localhost:8899/Exchange`` or
+ ``payto://iban/GENODEF1SLR/DE67830654080004822650/`` or
+ ``payto://iban/DE67830654080004822650/`` (providing the BIC is optional).
+ Note: only the wire-method is actually used from the URI.
+ Alternatively, you can also just specify the wire method.
+
+WIRE_METHOD
+ Specifies the wire method following RFC 8905. Examples:
+ ``x-taler-bank``, ``iban`` or ``wallee``. This option is
+ ignored if a PAYTO_URI is specified, and mandatory if PAYTO_URI is
+ not given.
+
+ENABLE_DEBIT
+ Must be set to ``YES`` for the accounts that the
+ **taler-exchange-aggregator** and **taler-exchange-closer** should debit.
+
+ENABLE_CREDIT
+ Must be set to ``YES`` for the accounts that the **taler-exchange-wirewatch**
+ should check for credits. It is yet uncertain if the merchant
+ implementation may check this flag as well.
+
+
+Additionally, for each enabled account there MUST be another matching section named “[exchange-accountcredentials-SOMETHING]”. This section SHOULD be in a ``secret/`` configuration file that is only readable for the **taler-exchange-wirewatch** and **taler-exchange-transfer** processes. It contains the credentials to access the bank account:
+
+WIRE_GATEWAY_URL
+ URL of the wire gateway. Typically of the form
+ ``https://$HOSTNAME[:$PORT]/taler-wire-gateway/$USERNAME/``
+ where $HOSTNAME is the hostname of the system running the bank
+ (such as the Taler Python bank or the Nexus) and ``$USERNAME`` is
+ the username of the exchange's bank account (usually matching
+ the ``USERNAME`` option used for authentication). Example:
+ ``https://bank.demo.taler.net/taler-wire-gateway/Exchange/``.
+
+WIRE_GATEWAY_AUTH_METHOD
+ This option determines how the exchange (auditor/wirewatch/aggregator)
+ authenticates with the wire gateway. Choices are ``basic``, ``bearer`` and ``none``.
+
+USERNAME
+ User name for ``basic`` authentication with the wire gateway.
+
+PASSWORD
+ Password for ``basic`` authentication with the wire gateway.
+
+TOKEN
+ Token for ``bearer`` authentication with the wire gateway.
diff --git a/manpages/frags/exchange-coin.rst b/manpages/frags/exchange-coin.rst
@@ -0,0 +1,75 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+EXCHANGE COIN OPTIONS
+---------------------
+
+The following options must be in sections starting with ``"[coin_]"`` and are
+largely used by **taler-exchange-httpd** to determine the meta data for the
+denomination keys. Some of the options are used by the
+**taler-exchange-secmod-rsa** to determine which RSA keys to create (and of
+what key length). Note that the section names must match, so this part of the
+configuration MUST be shared between the RSA helper and the exchange.
+Configuration values MUST NOT be changed in a running setup. Instead, if
+parameters for a denomination type are to change, a fresh *section name* should
+be introduced (and the existing section should be deleted).
+
+
+VALUE
+ Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per
+ coin).
+
+DURATION_WITHDRAW
+ How long should the same key be used for clients to withdraw coins of
+ this value?
+
+DURATION_SPEND
+ How long do clients have to spend these coins?
+
+DURATION_LEGAL
+ How long does the exchange have to keep records for this denomination?
+
+FEE_WITHDRAW
+ What fee is charged for withdrawal?
+
+FEE_DEPOSIT
+ What fee is charged for depositing?
+
+FEE_REFRESH
+ What fee is charged for refreshing?
+
+FEE_REFUND
+ What fee is charged for refunds? When a coin is refunded, the deposit
+ fee is returned. Instead, the refund fee is charged to the customer.
+
+CIPHER
+ What cryptosystem should be used? Must be set to either "CS" or "RSA".
+ The respective crypto-helper will then generate the keys for this
+ denomination.
+
+RSA_KEYSIZE
+ What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA".
+
+AGE_RESTRICTED
+ Setting this option to ``YES`` marks the denomination as age restricted
+ (default is ``NO``). For this option to be accepted the extension for age
+ restriction MUST be enabled.
diff --git a/manpages/frags/exchange-database.rst b/manpages/frags/exchange-database.rst
@@ -0,0 +1,51 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+EXCHANGE DATABASE OPTIONS
+-------------------------
+
+The following options must be in the section "[exchangedb]".
+
+IDLE_RESERVE_EXPIRATION_TIME
+ After which time period should reserves be closed if they are idle?
+
+LEGAL_RESERVE_EXPIRATION_TIME
+ After what time do we forget about (drained) reserves during garbage collection?
+
+AGGREGATOR_SHIFT
+ Delay between a deposit being eligible for aggregation and
+ the aggregator actually triggering.
+
+DEFAULT_PURSE_LIMIT
+ Number of concurrent purses that a reserve may have active
+ if it is paid to be opened for a year.
+
+
+EXCHANGE POSTGRES BACKEND DATABASE OPTIONS
+------------------------------------------
+
+The following options must be in section “[exchangedb-postgres]” if the
+“postgres” plugin was selected for the database.
+
+CONFIG
+ How to access the database, e.g. “postgres:///taler-exchange” to use the
+ “taler-exchange” database. Testcases use “talercheck”.
diff --git a/manpages/taler-auditor-config.1.rst b/manpages/taler-auditor-config.1.rst
@@ -0,0 +1,92 @@
+taler-auditor-config(1)
+########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-auditor-config** - manipulate GNU Taler auditor configuration files
+
+Synopsis
+========
+
+**taler-auditor-config**
+[**-c** *filename* | **--config=**\ \ *filename*]
+[**-f** | **--filename**]
+[**-F** | **--full**]
+[**-h** | **--help**]
+[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*]
+[**-l** *filename* | **--logfile=**\ \ *filename*]
+[**-o** *option* | **--option=**\ \ *option*]
+[**-r** | **--rewrite**]
+[**-S** | **--list-sections**]
+[**-s** *section* | **--section=**\ \ *section*]
+[**-V** *value* | **--value=**\ \ *value*]
+[**-v** | **--version**]
+
+
+Description
+===========
+
+**taler-auditor-config** can be used to read or modify GNU Taler auditor configuration files.
+
+**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
+ Use the configuration file *FILENAME*.
+
+**-f** \| **--filename**
+ Try to perform expansions as if the option values represent filenames (will
+ also be applied even if the option is not really a filename).
+
+**-F** \| **--full**
+ Write the full configuration file, not just the differences to the defaults.
+
+**-h** \| **--help**
+ Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL*
+ Use *LOGLEVEL* for logging.
+ Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
+ Send logging output to *FILENAME*.
+
+**-o** *OPTION* \| **--option=**\ \ *OPTION*
+ Which configuration option should be accessed or edited. Required to set a
+ value. If not given, all values of a given section will be printed in the
+ format "OPTION = VALUE".
+
+**-r** \| **--rewrite**
+ Write the configuration file even if nothing changed. Will remove all comments!
+
+**-S** \| **--list-sections**
+ List available configuration sections for use with ``--section``.
+
+**-s** *SECTION* \| **--section=**\ \ *SECTION*
+ Which configuration section should be accessed or edited.
+ Required option.
+
+**-V** *VALUE* \| **--value=**\ \ *VALUE*
+ Configuration value to store in the given section under the given option.
+ Must only be given together with ``-s`` and ``-o`` options.
+
+ Note:
+ Changing the configuration file with ``-V`` will remove comments
+ and may reorder sections and remove ``@INLINE@`` directives.
+ Using **-V** is thus dangerous! Use with extreme caution!
+
+**-v** \| **--version**
+ Print GNU Taler version number.
+
+
+
+See Also
+========
+
+taler-auditor.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-auditor.conf.5.rst b/manpages/taler-auditor.conf.5.rst
@@ -0,0 +1,121 @@
+taler-auditor.conf(5)
+#####################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-auditor.conf** - Taler auditor configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler-exchange/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+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``.
+
+Be extra careful when using ``taler-config -V VALUE`` to change configuration
+values: it will destroy all uses of ``@INLINE@`` and furthermore remove all
+comments from the configuration file!
+
+
+GLOBAL OPTIONS
+--------------
+
+The “[PATHS]” section is special in that it contains paths that can be
+referenced using “$” in other configuration values that specify
+filenames. For Taler, it commonly contains the following paths:
+
+TALER_HOME
+ Home directory of the user, usually “${HOME}”. Can be overwritten by
+ testcases by setting ${TALER_TEST_HOME}.
+
+TALER_DATA_HOME
+ Where should Taler store its long-term data.
+ Usually “${TALER_HOME}/.local/share/taler-auditor/”.
+
+TALER_CONFIG_HOME
+ Where is the Taler configuration kept.
+ Usually “${TALER_HOME}/.config/taler-auditor/”.
+
+TALER_CACHE_HOME
+ Where should Taler store cached data.
+ Usually “${TALER_HOME}/.cache/taler-auditor/”.
+
+TALER_RUNTIME_DIR
+ Where should Taler store system runtime data (like UNIX domain
+ sockets). Usually “${TMP}/taler-auditor-runtime”.
+
+
+.. include:: frags/currency-spec.rst
+.. include:: frags/exchange-database.rst
+.. include:: frags/exchange-account.rst
+.. include:: frags/exchange-coin.rst
+
+
+AUDITOR OPTIONS
+---------------
+
+The following options must be in section “[auditor]” for the Taler
+auditor.
+
+DB
+ Plugin to use for the database, e.g. “postgres”
+
+AUDITOR_PRIV_FILE
+ Name of the file containing the auditor’s private key.
+
+PUBLIC_KEY
+ Crockford Base32 encoded auditor public key. Used by (online) auditor
+ processes that do not have access to the (offline) auditor private key file.
+
+BASE_URL
+ Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
+
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
+PORT
+ Port on which the HTTP server listens, e.g. 8080.
+
+BIND_TO
+ Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
+
+
+AUDITOR POSTGRES BACKEND DATABASE OPTIONS
+-----------------------------------------
+
+The following options must be in section “[auditordb-postgres]” if the
+“postgres” plugin was selected for the database.
+
+CONFIG
+ How to access the database, e.g. "postgres:///taler" to use the
+ "taler" database. Testcases use “talercheck”.
+
+
+SEE ALSO
+========
+
+taler-auditor-dbinit(1), taler-auditor-httpd(1), taler-auditor-offline(1).
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-config.1.rst b/manpages/taler-config.1.rst
@@ -1,102 +0,0 @@
-taler-config(1)
-###############
-
-.. only:: html
-
- Name
- ====
-
- **taler-config** - manipulate GNU Taler configuration files
-
-Synopsis
-========
-
-**taler-config**
-[**-b** *backend* | **--supported-backend=**\ \ *backend*]
-[**-c** *filename* | **--config=**\ \ *filename*]
-[**-f** | **--filename**]
-[**-F** | **--full**]
-[**-h** | **--help**]
-[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*]
-[**-l** *filename* | **--logfile=**\ \ *filename*]
-[**-o** *option* | **--option=**\ \ *option*]
-[**-r** | **--rewrite**]
-[**-S** | **--list-sections**]
-[**-s** *section* | **--section=**\ \ *section*]
-[**-V** *value* | **--value=**\ \ *value*]
-[**-v** | **--version**]
-
-
-Description
-===========
-
-**taler-config** can be used to read or modify GNU Taler configuration files.
-
-**-b** *BACKEND* \| **--supported-backend=**\ \ *BACKEND*
- Tests whether the specified *BACKEND* is supported by the current installation.
- The backend must match the name of a plugin, i.e. "namestore_postgres" for
- the PostgreSQL database backend of the "NAMESTORE" service. If *BACKEND* is
- supported, taler-config will return a status code of 0 (success), otherwise
- 77 (unsupported). When this option is specified, no other options may be
- specified. Specifying this option together with other options will cause
- taler-config to return a status code of 1 (error).
-
-**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
- Use the configuration file *FILENAME*.
-
-**-f** \| **--filename**
- Try to perform expansions as if the option values represent filenames (will
- also be applied even if the option is not really a filename).
-
-**-F** \| **--full**
- Write the full configuration file, not just the differences to the defaults.
-
-**-h** \| **--help**
- Print short help on options.
-
-**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL*
- Use *LOGLEVEL* for logging.
- Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``.
-
-**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
- Send logging output to *FILENAME*.
-
-**-o** *OPTION* \| **--option=**\ \ *OPTION*
- Which configuration option should be accessed or edited. Required to set a
- value. If not given, all values of a given section will be printed in the
- format "OPTION = VALUE".
-
-**-r** \| **--rewrite**
- Write the configuration file even if nothing changed. Will remove all comments!
-
-**-S** \| **--list-sections**
- List available configuration sections for use with ``--section``.
-
-**-s** *SECTION* \| **--section=**\ \ *SECTION*
- Which configuration section should be accessed or edited.
- Required option.
-
-**-V** *VALUE* \| **--value=**\ \ *VALUE*
- Configuration value to store in the given section under the given option.
- Must only be given together with ``-s`` and ``-o`` options.
-
- Note:
- Changing the configuration file with ``-V`` will remove comments
- and may reorder sections and remove ``@INLINE@`` directives.
- Using **-V** is thus dangerous! Use with extreme caution!
-
-**-v** \| **--version**
- Print GNU Taler version number.
-
-
-
-See Also
-========
-
-taler.conf(5), taler-config-generate(1)
-
-Bugs
-====
-
-Report bugs by using https://bugs.taler.net or by sending electronic
-mail to <taler@gnu.org>.
diff --git a/manpages/taler-exchange-config.1.rst b/manpages/taler-exchange-config.1.rst
@@ -0,0 +1,92 @@
+taler-exchange-config(1)
+########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-exchange-config** - manipulate GNU Taler exchange configuration files
+
+Synopsis
+========
+
+**taler-exchange-config**
+[**-c** *filename* | **--config=**\ \ *filename*]
+[**-f** | **--filename**]
+[**-F** | **--full**]
+[**-h** | **--help**]
+[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*]
+[**-l** *filename* | **--logfile=**\ \ *filename*]
+[**-o** *option* | **--option=**\ \ *option*]
+[**-r** | **--rewrite**]
+[**-S** | **--list-sections**]
+[**-s** *section* | **--section=**\ \ *section*]
+[**-V** *value* | **--value=**\ \ *value*]
+[**-v** | **--version**]
+
+
+Description
+===========
+
+**taler-exchange-config** can be used to read or modify GNU Taler exchange configuration files.
+
+**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
+ Use the configuration file *FILENAME*.
+
+**-f** \| **--filename**
+ Try to perform expansions as if the option values represent filenames (will
+ also be applied even if the option is not really a filename).
+
+**-F** \| **--full**
+ Write the full configuration file, not just the differences to the defaults.
+
+**-h** \| **--help**
+ Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL*
+ Use *LOGLEVEL* for logging.
+ Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
+ Send logging output to *FILENAME*.
+
+**-o** *OPTION* \| **--option=**\ \ *OPTION*
+ Which configuration option should be accessed or edited. Required to set a
+ value. If not given, all values of a given section will be printed in the
+ format "OPTION = VALUE".
+
+**-r** \| **--rewrite**
+ Write the configuration file even if nothing changed. Will remove all comments!
+
+**-S** \| **--list-sections**
+ List available configuration sections for use with ``--section``.
+
+**-s** *SECTION* \| **--section=**\ \ *SECTION*
+ Which configuration section should be accessed or edited.
+ Required option.
+
+**-V** *VALUE* \| **--value=**\ \ *VALUE*
+ Configuration value to store in the given section under the given option.
+ Must only be given together with ``-s`` and ``-o`` options.
+
+ Note:
+ Changing the configuration file with ``-V`` will remove comments
+ and may reorder sections and remove ``@INLINE@`` directives.
+ Using **-V** is thus dangerous! Use with extreme caution!
+
+**-v** \| **--version**
+ Print GNU Taler version number.
+
+
+
+See Also
+========
+
+taler-exchange.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-exchange.conf.5.rst b/manpages/taler-exchange.conf.5.rst
@@ -0,0 +1,664 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+
+taler-exchange.conf(5)
+######################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-exchange.conf** - Taler exchange configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler-exchange/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+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``.
+
+Be extra careful when using ``taler-exchange-config -V VALUE`` to change configuration
+values: it will destroy all uses of ``@INLINE@`` and furthermore remove all
+comments from the configuration file!
+
+
+GLOBAL OPTIONS
+--------------
+
+The “[PATHS]” section is special in that it contains paths that can be
+referenced using “$” in other configuration values that specify
+filenames. For Taler exchange, it commonly contains the following paths:
+
+TALER_HOME
+ Home directory of the user, usually “${HOME}”. Can be overwritten by
+ testcases by setting ${TALER_TEST_HOME}.
+
+TALER_DATA_HOME
+ Where should Taler store its long-term data.
+ Usually “${TALER_HOME}/.local/share/taler-exchange/”.
+
+TALER_CONFIG_HOME
+ Where is the Taler configuration kept.
+ Usually “${TALER_HOME}/.config/taler-exchange/”.
+
+TALER_CACHE_HOME
+ Where should Taler store cached data.
+ Usually “${TALER_HOME}/.cache/taler-exchange/”.
+
+TALER_RUNTIME_DIR
+ Where should Taler store system runtime data (like UNIX domain
+ sockets). Usually “${TMP}/taler-exchange-runtime”.
+
+
+.. include:: frags/currency-spec.rst
+
+EXCHANGE OPTIONS
+----------------
+
+The following options are from the “[exchange]” section and used by most
+exchange tools.
+
+CURRENCY
+ Name of the currency, e.g. “EUR” for Euro.
+
+CURRENCY_ROUND_UNIT
+ Smallest amount in this currency that can be transferred using the
+ underlying RTGS. For example: "EUR:0.01" or "JPY:1".
+
+DB
+ Plugin to use for the database, e.g. “postgres”.
+
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
+PORT
+ Port on which the HTTP server listens, e.g. 8080.
+
+BIND_TO
+ Hostname to which the exchange HTTP server should be bound to, e.g. "localhost".
+
+MASTER_PUBLIC_KEY
+ Crockford Base32-encoded master public key, public version of the
+ exchange's long-time offline signing key. This configuration option
+ is also used by the **auditor** to determine the public key of the
+ exchange which it is auditing.
+
+TINY_AMOUNT
+ Small amount that can be transferred to the exchange for the
+ KYC authentication wire transfers. Should be given as a hint
+ for merchants what amount they need to transfer to begin the
+ KYC transfer. Note that the amount is not enforced by the
+ exchange *and* that this option is optional. However, if it is
+ not given, merchants will have to guess what amount to transfer,
+ so it really should be configured.
+
+SHOPPING_URL
+ Web URL where users can discover shops that accept digital cash
+ offered by this exchange. Optional, but highly recommended.
+
+STEFAN_ABS
+ Absolute amount to add as an offset in the STEFAN fee approximation
+ curve (see DD47). Defaults to CURRENCY:0 if not specified.
+
+STEFAN_LOG
+ Amount to multiply by the base-2 logarithm of the total amount
+ divided by the amount of the smallest denomination
+ in the STEFAN fee approximation curve (see DD47).
+ Defaults to CURRENCY:0 if not specified.
+
+STEFAN_LIN
+ Linear floating point factor to be multiplied by the total amount
+ to use in the STEFAN fee approximation curve (see DD47).
+ Defaults to 0.0 if not specified.
+
+BASE_URL
+ The base URL under which the exchange can be reached.
+ Added to wire transfers to enable tracking by merchants.
+ Used by the KYC logic when interacting with OAuth 2.0.
+
+TOPLEVEL_REDIRECT_URL
+ Where to redirect visitors that access the top-level
+ "/" endpoint of the exchange. Should point users to
+ information about the exchange operator.
+ Optional setting, defaults to "/terms".
+
+AGGREGATOR_IDLE_SLEEP_INTERVAL
+ For how long should the taler-exchange-aggregator sleep when it is idle
+ before trying to look for more work? Default is 60 seconds.
+
+CLOSER_IDLE_SLEEP_INTERVAL
+ For how long should the taler-exchange-closer sleep when it is idle
+ before trying to look for more work? Default is 60 seconds.
+
+TRANSFER_IDLE_SLEEP_INTERVAL
+ For how long should the taler-exchange-transfer sleep when it is idle
+ before trying to look for more work? Default is 60 seconds.
+
+WIREWATCH_IDLE_SLEEP_INTERVAL
+ For how long should the taler-exchange-wirewatch sleep when it is idle
+ before trying to look for more work? Default is 60 seconds.
+
+AGGREGATOR_SHARD_SIZE
+ Which share of the range from [0,..2147483648] should be processed by one of the shards of the aggregator. Useful only for Taler exchanges with ultra high-performance needs. When changing this value, you must stop all aggregators and run "taler-exchange-dbinit -s" before resuming. Default is 2147483648 (no sharding).
+
+SIGNKEY_LEGAL_DURATION
+ For how long are signatures with signing keys legally valid?
+
+MAX_KEYS_CACHING
+ For how long should clients cache ``/keys`` responses at most?
+
+MAX_REQUESTS
+ How many requests should the HTTP server process at most before committing suicide?
+
+TERMS_DIR
+ Directory where the terms of service of the exchange operator can be fund.
+ The directory must contain sub-directories for every supported language,
+ using the two-character language code in lower case, e.g. "en/" or "fr/".
+ Each subdirectory must then contain files with the terms of service in
+ various formats. The basename of the file of the current policy must be
+ specified under ``TERMS_ETAG``. The extension defines the mime type.
+ Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg",
+ "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure
+ could be the following:
+
+ - $TERMS_DIR/en/0.pdf
+ - $TERMS_DIR/en/0.html
+ - $TERMS_DIR/en/0.txt
+ - $TERMS_DIR/fr/0.pdf
+ - $TERMS_DIR/fr/0.html
+ - $TERMS_DIR/de/0.txt
+
+TERMS_ETAG
+ Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service.
+ The value is also used for the "Etag" in the HTTP request to control
+ caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also
+ change, and old values MUST NOT be repeated. For example, the date or
+ version number of the terms of service SHOULD be used for the Etag. If
+ there are minor (e.g. spelling) fixes to the terms of service, the
+ ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must
+ approve the new terms, the ``TERMS_ETAG`` MUST change.
+
+PRIVACY_DIR
+ Works the same as ``TERMS_DIR``, just for the privacy policy.
+
+PRIVACY_ETAG
+ Works the same as ``TERMS_ETAG``, just for the privacy policy.
+
+ENABLE_KYC
+ Must be set to ``YES`` to enable AML/KYC rule enforcement. Note that the administrative endpoints will always work, even if the flag is set to ``NO``.
+
+
+EXCHANGE KYC PROVIDER OPTIONS
+-----------------------------
+
+The following options must be in the section "[kyc-provider-$PROVIDER_NAME]" sections.
+
+LOGIC
+ API type of the KYC provider.
+
+Additional logic-specific options may be given in the
+section.
+
+
+EXCHANGE KYC OAUTH2 OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2".
+
+
+KYC_OAUTH2_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
+
+KYC_OAUTH2_AUTHORIZE_URL
+ URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: "http://localhost:8888/oauth/v2/authorize". To use the plugin in combination with the Challenger service's ``/setup`` step, append "#setup", thus "https://challenger.example.com/authorize#setup". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the ``/setup/$CLIENT_ID`` handler.
+
+KYC_OAUTH2_TOKEN_URL
+ URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "http://localhost:8888/oauth/v2/token" (or just "/token")
+
+KYC_OAUTH2_INFO_URL
+ URL of the OAuth2-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "http://localhost:8888/api/user/me" or "http://localhost:8888/oauth/v2/info"
+
+KYC_OAUTH2_CLIENT_ID
+ Client ID of the exchange when it talks to the KYC OAuth2 endpoint.
+
+KYC_OAUTH2_CLIENT_SECRET
+ Client secret of the exchange to use when talking to the KYC Oauth2 endpoint.
+
+KYC_OAUTH2_POST_URL
+ URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. Example: "http://example.com/thank-you"
+
+KYC_OAUTH2_CONVERTER_HELPER
+ Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider.
+
+KYC_OAUTH2_DEBUG_MODE
+ Set to YES to allow error responses to include potentially
+ sensitive private information (such as full responses
+ from the OAuth 2.0 server) that might aid in debugging
+ problems. Should be set to "NO" in production.
+
+
+EXCHANGE KYC KYCAID OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid".
+
+
+KYC_KYCAID_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
+
+KYC_KYCAID_AUTH_TOKEN
+ Authentication token to access the KYC service.
+
+KYC_KYCAID_CONVERTER_HELPER
+ Helper to convert JSON with KYC data returned by KYCAID into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-kycaid-converter.sh".
+
+KYC_KYCAID_FORM_ID
+ ID that specifies the form to use for the KYC process.
+
+KYC_KYCAID_POST_URL
+ URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
+
+
+EXCHANGE KYC PERSONA OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona".
+
+
+KYC_PERSONA_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
+
+KYC_PERSONA_AUTH_TOKEN
+ Authentication token to access the KYC service.
+
+KYC_PERSONA_SALT
+ Salt value to use for request idempotency. Optional, generated at random per process if not given.
+
+KYC_PERSONA_SUBDOMAIN
+ Subdomain to use under Persona.
+
+KYC_PERSONA_CONVERTER_HELPER
+ Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-persona-converter.sh".
+
+KYC_PERSONA_POST_URL
+ URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
+
+KYC_PERSONA_TEMPLATE_ID
+ ID of the Persona template to use.
+
+EXCHANGE KYC PERSONA GLOBAL OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following option must be in the section "[kyclogic-persona]".
+
+
+WEBHOOK_AUTH_TOKEN
+ Authentication token Persona must supply to our webhook. This is an optional setting.
+
+
+EXCHANGE KYC CHECK OPTIONS
+--------------------------
+
+The following options must be in "[kyc-check-$CHECK_NAME]" sections.
+
+TYPE
+ Which type of check is this? Also determines
+ the SPA form to show to the user for this check.
+
+ * INFO: wait for staff or contact staff out-of band
+ (only information shown, no SPA action)
+ * FORM: SPA should show an inline (HTML) form
+ * LINK: SPA may start external KYC process or upload
+
+PROVIDER_ID
+ Provider id, present only if type is LINK.
+ Refers to a ``kyc-provider-$PROVIDER_ID`` section.
+
+FORM_NAME
+ Name of the SPA form, if type is FORM
+ "INFO" and "LINK" are reserved and must not be used.
+ The exchange server and the SPA must agree on a list
+ of supported forms and the resulting attributes.
+ The SPA should include a JSON resource file
+ "forms.json" mapping form names to arrays of
+ attribute names each form provides.
+ The list of possible FORM names is fixed in the SPA
+ for a particular exchange release.
+
+DESCRIPTION
+ Descriptions to use in the SPA to display the check.
+
+DESCRIPTION_I18N
+ JSON with internationalized descriptions to use
+ in the SPA to display the check.
+
+REQUIRES
+ ';'-separated list of fields that the CONTEXT must
+ provide as inputs to this check. For example,
+ for a FORM of type CHOICE, this might state
+ ``choices: string[];``. The type after the ":"
+ is for now purely for documentation and is
+ not checked. However, it may be shown to AML staff
+ when they configure measures.
+
+OUTPUTS = "business_name street city country registration"
+ Description of the outputs provided by the check.
+ Basically, the check's output is expected to
+ provide the following fields as attribute inputs into
+ a subsequent AML program. INFO never has any outputs.
+
+FALLBACK
+ Name of an **original** measure to take if the check fails
+ (for any reason, e.g. provider or form fail to
+ satisfy constraints or provider signals user error)
+ Usually should point to a measure that requests
+ AML staff to investigate. The fallback measure
+ context always includes the reasons for the
+ failure.
+
+EXCHANGE KYC RULES
+------------------
+
+The following options must be in "[kyc-rule-$RULE_NAME]" sections.
+
+OPERATION_TYPE = WITHDRAW
+ Operation that triggers this rule.
+ Must be one of WITHDRAW, DEPOSIT, MERGE, BALANCE,
+ CLOSE, AGGREGATE, TRANSACTION or REFUND.
+
+NEXT_MEASURES
+ Space-separated list of next measures to be performed.
+ The SPA should display *all* of these measures to the user.
+ (They have a choice of either which ones, or in
+ which order they are to be performed.)
+ A special measure name "verboten" is used if the
+ specified threshold may never be crossed
+ (under this set of rules). This option is equivalent
+ to the "new_measure" string in an AmlDecisionRequest
+ (with IS_AND_COMBINATOR replacing the "+"-prefix).
+
+IS_AND_COMBINATOR
+ "YES" if all NEXT_MEASURES will eventually need
+ to be satisfied, "NO" the user has a choice between
+ them. Not actually enforced by the exchange, but
+ primarily used to inform the user whether this is
+ an "and" or "or". YES for "and".
+
+EXPOSED
+ YES if the rule (specifically, operation type,
+ threshold, timeframe) and the general nature of
+ the next measure (verboten or approval required)
+ should be exposed to the client.
+ Defaults to NO if not set.
+
+THRESHOLD
+ Threshold amount above which the rule is
+ triggered. The total must be exceeded in the given
+ timeframe.
+
+TIMEFRAME
+ Timeframe over which the amount to be compared to
+ the THRESHOLD is calculated (for example, "30 days").
+ Ignored for BALANCE. Can be 'forever'.
+
+ENABLED = NO
+ Set to YES to enable the rule (default is NO).
+
+
+EXCHANGE AML PROGRAMS
+---------------------
+
+The following options must be in "[aml-program-$PROG_NAME]" sections.
+
+COMMAND
+ Name of the program to run. Must match a binary
+ on the local machine where the exchange is running.
+
+DESCRIPTION
+ Human-readable description of what this
+ AML helper program will do. Used to show
+ to the AML staff.
+
+ENABLED
+ True if this AML program is enabled (and thus can be
+ used in measures and exposed to AML staff).
+ Optional, default is NO.
+
+FALLBACK
+ Name of an **original** measure to take if COMMAND fails
+ Usually points to a measure that asks AML staff
+ to contact the systems administrator. The fallback measure
+ context always includes the reasons for the
+ failure.
+
+EXCHANGE KYC MEASURES
+---------------------
+
+The following options must be in "[kyc-measure-$MEASURE_NAME]" sections.
+These sections define the **original** measures.
+
+CHECK_NAME
+ Name of a possible check for this measure. Optional.
+ If not given, PROGRAM should be run immediately
+ (on an empty set of attributes).
+
+CONTEXT = {"choices":["individual","business"]}
+ Context for the check. The context can be
+ just an empty JSON object if there is none.
+
+PROGRAM
+ Program to run on the context and check data to
+ determine the outcome and next measure.
+ Refers to a ``[aml-program-$PROG_NAME]`` section name.
+
+VOLUNTARY
+ Optional. Set to YES to allow this measure to be
+ done voluntarily by a client. Used to offer the
+ SPA to display measures even if they are
+ not required. Default is NO.
+
+
+
+EXCHANGE EXTENSIONS OPTIONS
+---------------------------
+
+The functionality of the exchange can be extended by extensions. Those are
+shared libraries which implement the extension-API of the exchange and are
+located under ``$LIBDIR``, starting with prefix ``libtaler_extension_``. Each
+extension can be enabled by adding a dedicated section
+"[exchange-extension-<extensionname>]" and the following option:
+
+ENABLED
+ If set to ``YES`` the extension ``<extensionsname>`` is enabled. Extension-specific
+ options might be set in the same section.
+
+
+EXCHANGE EXTENSION FOR AGE RESTRICTION
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The extension for age restriction support can be enabled by adding a section
+"[exchange-extension-age_restriction]" with the following options:
+
+ENABLE
+ Must be set to ``YES`` in order to activate the extension.
+
+AGE_GROUPS
+ A colon-seperated string of increasing non-negative integers, defining the
+ buckets of age groups supported by the exchange. Each integer marks the
+ beginning of the next age group. The zero'th age group implicitly starts
+ with 0. For example, the string "10:18" would define three age groups:
+
+ 1. Group 0: ages 0 through 9 (including)
+ 2. Group 1: ages 10 through 17 (including)
+ 3. Group 2: ages 18 and above
+
+ If not provided, the default value is "8:10:12:14:16:18:21".
+
+**Note**: Age restriction is bound to specific denominations and must be
+enabled for each selected denomination in the corresponding section by adding
+the option ``AGE_RESTRICTED = YES``, see `EXCHANGE COIN OPTIONS`_. However, the
+age groups are defined globally for all denominations.
+
+
+
+EXCHANGE OFFLINE SIGNING OPTIONS
+--------------------------------
+
+The following options must be in the section "[exchange-offline]".
+
+MASTER_PRIV_FILE
+ Location of the master private key on disk. Only used by tools that
+ can be run offline (as the master key is for offline signing).
+ Mandatory.
+
+SECM_TOFU_FILE
+ Where to store the public keys of both crypto helper modules.
+ Used to persist the keys after the first invocation of the tool,
+ so that if they ever change in the future, this is detected and
+ the tool can abort.
+ Mandatory.
+
+SECM_DENOM_PUBKEY
+ Public key of the (RSA) crypto helper module. Optional. If not given,
+ we will rely on TOFU. Note that once TOFU has been established,
+ this option will also be ignored.
+
+SECM_ESIGN_PUBKEY
+ Public key of the (EdDSA) crypto helper module. Optional. If not given,
+ we will rely on TOFU. Note that once TOFU has been established,
+ this option will also be ignored.
+
+
+EXCHANGE RSA CRYPTO HELPER OPTIONS
+----------------------------------
+
+The following options must be in the section "[taler-exchange-secmod-rsa]".
+
+LOOKAHEAD_SIGN
+ How long do we generate denomination and signing keys ahead of time?
+
+OVERLAP_DURATION
+ How much should validity periods for coins overlap?
+ Should be long enough to avoid problems with
+ wallets picking one key and then due to network latency
+ another key being valid. The ``DURATION_WITHDRAW`` period
+ must be longer than this value.
+
+SM_PRIV_KEY
+ Where should the security module store its long-term private key?
+
+KEY_DIR
+ Where should the security module store the private keys it manages?
+
+UNIXPATH
+ On which path should the security module listen for signing requests?
+
+Note that the **taler-exchange-secmod-rsa** also evaluates the ``[coin_*]``
+configuration sections described below.
+
+
+EXCHANGE CS CRYPTO HELPER OPTIONS
+---------------------------------
+
+The following options must be in the section "[taler-exchange-secmod-cs]".
+
+LOOKAHEAD_SIGN
+ How long do we generate denomination and signing keys ahead of time?
+
+OVERLAP_DURATION
+ How much should validity periods for coins overlap?
+ Should be long enough to avoid problems with
+ wallets picking one key and then due to network latency
+ another key being valid. The ``DURATION_WITHDRAW`` period
+ must be longer than this value.
+
+SM_PRIV_KEY
+ Where should the security module store its long-term private key?
+
+KEY_DIR
+ Where should the security module store the private keys it manages?
+
+UNIXPATH
+ On which path should the security module listen for signing requests?
+
+Note that the **taler-exchange-secmod-cs** also evaluates the ``[coin_*]``
+configuration sections described below.
+
+
+
+EXCHANGE EDDSA CRYPTO HELPER OPTIONS
+------------------------------------
+
+The following options must be in the section "[taler-exchange-secmod-eddsa]".
+
+LOOKAHEAD_SIGN
+ How long do we generate denomination and signing keys ahead of time?
+
+OVERLAP_DURATION
+ How much should validity periods for coins overlap?
+ Should be long enough to avoid problems with
+ wallets picking one key and then due to network latency
+ another key being valid. The ``DURATION_WITHDRAW`` period
+ must be longer than this value.
+
+DURATION
+ For how long should EdDSA keys be valid for signing?
+
+SM_PRIV_KEY
+ Where should the security module store its long-term private key?
+
+KEY_DIR
+ Where should the security module store the private keys it manages?
+
+UNIXPATH
+ On which path should the security module listen for signing requests?
+
+.. include:: frags/exchange-database.rst
+.. include:: frags/exchange-account.rst
+.. include:: frags/exchange-coin.rst
+
+SEE ALSO
+========
+
+taler-exchange-dbinit(1), taler-exchange-httpd(1), taler-exchange-offline(1)
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-fakebank.conf.5.rst b/manpages/taler-fakebank.conf.5.rst
@@ -0,0 +1,71 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+
+taler-fakebank.conf(5)
+######################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-fakebank.conf** - Taler (fake)bank configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler-bank/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+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``.
+
+Be extra careful when using ``taler-bank-config -V VALUE`` to change configuration
+values: it will destroy all uses of ``@INLINE@`` and furthermore remove all
+comments from the configuration file!
+
+
+(Fake)Bank Options
+------------------
+
+The following options must be in section "[bank]" for the taler-fakebank-run(1) command. They are not used by the exchange or LibEuFin!
+
+HTTP_PORT
+ On which TCP port should the (fake)bank offer its REST API.
+RAM_LIMIT
+ This gives the number of transactions to keep in memory. Older transactions will be overwritten and history requests for overwritten transactions will fail.
+
+SEE ALSO
+========
+
+libeufin-bank.conf(5), taler-bank-config(1), taler-fakebank-run(1).
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-mdb.conf.5.rst b/manpages/taler-mdb.conf.5.rst
@@ -0,0 +1,102 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Christian Grothoff
+
+
+taler-mdb.conf(5)
+#################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-mdb.conf** - Taler-mdb configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler-exchange/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+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``.
+
+
+Taler-mdb Options
+-----------------
+
+Taler-mdb is a component to run GNU Taler as a payment system on
+vending machines using the multi-drop bus protocol. These options
+are thus not useful for most users. Note that right now, the
+cancel button is hard-coded to be using GPIO pin 23.
+
+ADVERTISEMENT_COMMAND
+ Program to run while not vending, possibly useful to show advertisements on the screen (optional).
+ESSID
+ ESSID to advertise to wallets for use as an open WiFi to make payments (optional).
+FULFILLMENT_MSG
+ Message shown to users by their wallets upon successful payment. If "${PRODUCT_DESCRIPTION}" appears in the message, it will be replaced with the description of the product that was sold.
+BACKEND_BASE_URL
+ Base URL (possibly including instance) for the Taler merchant backend used to process payments.
+BACKEND_AUTHORIZATION
+ Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Mandatory.
+FRAMEBUFFER_BACKLIGHT
+ Name of the file used to control brightness of the display. Optional. Defaults to "/sys/class/backlight/soc:backlight/brightness" if not given.
+FRAMEBUFFER_DEVICE
+ Name of the framebuffer device to use. Defaults to "/dev/fb1" if not given.
+UART_DEVICE
+ Name of the UART device to use. Defaults to "/dev/ttyAMA0" if not given.
+FAIL_COMMAND
+ Command to run by taler-mdb to display a failure to the user. If not given, errors will not be properly shown. Should usually be set to "taler-mdb-show.sh".
+FAIL_HELPER
+ Command used by taler-mdb-network-check.sh to run to display a failure to the user. If not given, errors will not be properly shown. Should usually be set to "taler-mdb-show.sh".
+
+Each products being sold must be configured in a section where the name starts with "product-".
+In these sections, the options that must be provided are:
+
+NUMBER
+ Number identifying the slot in the vending machine that corresponds to this product.
+INSTANCE
+ Instance to use for the payment. Optional. If not given, the BACKEND_BASE_URL from "[taler-mdb]" will be used.
+BACKEND_AUTHORIZATION
+ Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Optional, will use global BACKEND_AUTHORIZATION setting from "[taler-mdb]" if missing.
+DESCRIPTION
+ Human-readable description of the product. Use "empty" if the product is known to be sold out (only effective if selling out is enabled via command-line).
+PRICE
+ Actual price of the product, as a Taler amount ("$CURRENCY:$VALUE.$FRACTION").
+KEY
+ Key used to select the product from the console during testing. Optional.
+THUMBNAIL
+ Name of a filename with a preview image of the product to be given to the wallet. Optional. Only ".png", ".jpg", ".jpeg" and ".svg" are supported at this time.
+
+
+SEE ALSO
+========
+
+taler-mdb(1), taler-mdb-qr-show(1), taler-mdb-display(1)
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant-config.1.rst b/manpages/taler-merchant-config.1.rst
@@ -0,0 +1,92 @@
+taler-merchant-config(1)
+########################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-merchant-config** - manipulate GNU Taler merchant configuration files
+
+Synopsis
+========
+
+**taler-merchant-config**
+[**-c** *filename* | **--config=**\ \ *filename*]
+[**-f** | **--filename**]
+[**-F** | **--full**]
+[**-h** | **--help**]
+[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*]
+[**-l** *filename* | **--logfile=**\ \ *filename*]
+[**-o** *option* | **--option=**\ \ *option*]
+[**-r** | **--rewrite**]
+[**-S** | **--list-sections**]
+[**-s** *section* | **--section=**\ \ *section*]
+[**-V** *value* | **--value=**\ \ *value*]
+[**-v** | **--version**]
+
+
+Description
+===========
+
+**taler-merchant-config** can be used to read or modify GNU Taler merchant configuration files.
+
+**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
+ Use the configuration file *FILENAME*.
+
+**-f** \| **--filename**
+ Try to perform expansions as if the option values represent filenames (will
+ also be applied even if the option is not really a filename).
+
+**-F** \| **--full**
+ Write the full configuration file, not just the differences to the defaults.
+
+**-h** \| **--help**
+ Print short help on options.
+
+**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL*
+ Use *LOGLEVEL* for logging.
+ Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``.
+
+**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME*
+ Send logging output to *FILENAME*.
+
+**-o** *OPTION* \| **--option=**\ \ *OPTION*
+ Which configuration option should be accessed or edited. Required to set a
+ value. If not given, all values of a given section will be printed in the
+ format "OPTION = VALUE".
+
+**-r** \| **--rewrite**
+ Write the configuration file even if nothing changed. Will remove all comments!
+
+**-S** \| **--list-sections**
+ List available configuration sections for use with ``--section``.
+
+**-s** *SECTION* \| **--section=**\ \ *SECTION*
+ Which configuration section should be accessed or edited.
+ Required option.
+
+**-V** *VALUE* \| **--value=**\ \ *VALUE*
+ Configuration value to store in the given section under the given option.
+ Must only be given together with ``-s`` and ``-o`` options.
+
+ Note:
+ Changing the configuration file with ``-V`` will remove comments
+ and may reorder sections and remove ``@INLINE@`` directives.
+ Using **-V** is thus dangerous! Use with extreme caution!
+
+**-v** \| **--version**
+ Print GNU Taler version number.
+
+
+
+See Also
+========
+
+taler-merchant.conf(5)
+
+Bugs
+====
+
+Report bugs by using https://bugs.taler.net or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler-merchant.conf.5.rst b/manpages/taler-merchant.conf.5.rst
@@ -0,0 +1,230 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2014-2024 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Florian Dold
+ @author Benedikt Muller
+ @author Sree Harsha Totakura
+ @author Marcello Stanisci
+ @author Christian Grothoff
+ @author Javier Sepulveda
+
+
+taler-merchant.conf(5)
+######################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler.conf** - Taler configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_PREFIX/share/taler-merchant/config.d/``.
+The configuration file given with **-c** to Taler binaries
+overrides these defaults.
+
+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``.
+
+Be extra careful when using ``taler-merchant-config -V VALUE`` to change configuration
+values: it will destroy all uses of ``@INLINE@`` and furthermore remove all
+comments from the configuration file!
+
+
+GLOBAL OPTIONS
+--------------
+
+The “[PATHS]” section is special in that it contains paths that can be
+referenced using “$” in other configuration values that specify
+filenames. For Taler, it commonly contains the following paths:
+
+TALER_HOME
+ Home directory of the user, usually “${HOME}”. Can be overwritten by
+ testcases by setting ${TALER_TEST_HOME}.
+
+TALER_DATA_HOME
+ Where should Taler store its long-term data.
+ Usually “${TALER_HOME}/.local/share/taler-merchant/”.
+
+TALER_CONFIG_HOME
+ Where is the Taler configuration kept.
+ Usually “${TALER_HOME}/.config/taler-merchant/”.
+
+TALER_CACHE_HOME
+ Where should Taler store cached data.
+ Usually “${TALER_HOME}/.cache/taler-merchant/”.
+
+TALER_RUNTIME_DIR
+ Where should Taler store system runtime data (like UNIX domain
+ sockets). Usually “${TMP}/taler-merchant-runtime”.
+
+.. include:: frags/currency-spec.rst
+
+
+
+
+
+CURRENCY SPECIFICATIONS
+-----------------------
+
+Sections with a name of the form “[currency-$NAME]” (where "$NAME" could
+be any unique string) are used to specify details about how currencies
+should be handled (and in particularly rendered) by the user interface.
+A detailed motivation for this section can be found in DD51.
+Different components can have different rules for the same currency. For
+example, a bank or merchant may decide to render Euros or Dollars with
+always exactly two fractional decimals, while an Exchange for the same
+currency may support additional decimals. The required options in each
+currency specification section are:
+
+ENABLED
+ Set to YES or NO. If set to NO, the currency specification
+ section is ignored. Can be used to disable currencies or
+ select alternative sections for the same CODE with different
+ choices.
+
+CODE
+ Code name for the currency. Can be at most 11 characters,
+ only the letters A-Z are allowed. Primary way to identify
+ the currency in the protocol.
+
+NAME
+ Long human-readable name for the currency. No restrictions,
+ but should match the official name in English.
+
+FRACTIONAL_INPUT_DIGITS
+ Number of fractional digits that users are allowed to enter
+ manually in the user interface.
+
+FRACTIONAL_NORMAL_DIGITS
+ Number of fractional digits that will be rendered normally
+ (in terms of size and placement). Digits shown beyond this
+ number will typically be rendered smaller and raised (if
+ possible).
+
+FRACTIONAL_TRAILING_ZERO_DIGITS
+ Number of fractional digits to pad rendered amounts with
+ even if these digits are all zero. For example, use 2 to
+ render 1 USD as $1.00.
+
+ALT_UNIT_NAMES
+ JSON map determining how to encode very large or very tiny
+ amounts in this currency. Maps a base10 logarithm to the
+ respective currency symbol. Must include at least an
+ entry for 0 (currency unit). For example, use
+ {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could
+ additionally use {"0":"€","3":"k€"} to render 3000 EUR
+ as 3k€. For BTC a typical map would be
+ {"0":"BTC","-3":"mBTC"}, informing the UI to render small
+ amounts in milli-Bitcoin (mBTC).
+
+
+MERCHANT OPTIONS
+----------------
+
+The following options are from the “[merchant]” section and used by the
+merchant backend.
+
+DB
+ Plugin to use for the database, e.g._“postgres”.
+
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+BASE_URL
+ Which base URL should the merchant backend assume for itself in the protocol. Optional. If not given, the base URL will be constructed from X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Prefix headers that a reverse-proxy should be setting.
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
+PORT
+ Port on which the HTTP server listens, e.g. 8080.
+
+BIND_TO
+ Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
+LEGAL_PRESERVATION
+ How long do we keep data in the database for tax audits after the
+ transaction has completed? Default is 10 years.
+
+FORCE_AUDIT
+ Force the merchant to report every transaction to the auditor
+ (if the exchange has an auditor)? Default is ``NO``.
+ Do not change except for testing.
+
+
+MERCHANT POSTGRES BACKEND DATABASE OPTIONS
+------------------------------------------
+
+The following options must be in section “[merchantdb-postgres]” if the
+“postgres” plugin was selected for the database.
+
+CONFIG
+ How to access the database, e.g. “postgres:///taler” to use the
+ “taler” database. Testcases use “talercheck”.
+
+
+KNOWN EXCHANGES (for merchants)
+-------------------------------
+
+The merchant configuration can include a list of known exchanges if the
+merchant wants to specify that certain exchanges are explicitly trusted.
+For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where
+$NAME is a merchant-given name for the exchange. The following options
+must be given in each “[exchange-$NAME]” section.
+
+EXCHANGE_BASE_URL
+ Base URL of the exchange, e.g. “https://exchange.demo.taler.net/”
+
+MASTER_KEY
+ Crockford Base32 encoded master public key, public version of the
+ exchange's long-time offline signing key. Can be omitted, in that
+ case the exchange will NOT be trusted unless it is audited by
+ a known auditor.
+ Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange
+ without an auditor, but should pre-load the keys of this
+ particular exchange on startup instead of waiting for it to be
+ required by a client.
+
+CURRENCY
+ Name of the currency for which this exchange is used, e.g. “KUDOS”.
+ The entire section is ignored if the currency does not match the currency
+ we use, which must be given in the ``[taler]`` section.
+
+DISABLED
+ Set to YES to disable this exchange. Optional option, defaults to NO.
+
+
+SEE ALSO
+========
+
+taler-merchant-passwd(1), taler-merchant-httpd(1)
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
@@ -1,1030 +0,0 @@
-taler.conf(5)
-#############
-
-.. only:: html
-
- Name
- ====
-
- **taler.conf** - Taler configuration file
-
-
-Description
-===========
-
-.. include:: ../frags/common-conf-syntax.rst
-
-Files containing default values for many of the options described below
-are installed under ``$TALER_PREFIX/share/taler/config.d/``.
-The configuration file given with **-c** to Taler binaries
-overrides these defaults.
-
-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``.
-
-Be extra careful when using ``taler-config -V VALUE`` to change configuration
-values: it will destroy all uses of ``@INLINE@`` and furthermore remove all
-comments from the configuration file!
-
-
-GLOBAL OPTIONS
---------------
-
-The following options are from the “[taler]” section and used by
-virtually all Taler components. Note: work is ongoing to obsolete
-these options, but for now they are in use.
-
-
-CURRENCY
- Name of the currency, e.g. “EUR” for Euro.
-
-CURRENCY_ROUND_UNIT
- Smallest amount in this currency that can be transferred using the
- underlying RTGS. For example: "EUR:0.01" or "JPY:1".
-
-
-
-The “[PATHS]” section is special in that it contains paths that can be
-referenced using “$” in other configuration values that specify
-filenames. For Taler, it commonly contains the following paths:
-
-TALER_HOME
- Home directory of the user, usually “${HOME}”. Can be overwritten by
- testcases by setting ${TALER_TEST_HOME}.
-
-TALER_DATA_HOME
- Where should Taler store its long-term data.
- Usually “${TALER_HOME}/.local/share/taler/”.
-
-TALER_CONFIG_HOME
- Where is the Taler configuration kept.
- Usually “${TALER_HOME}/.config/taler/”.
-
-TALER_CACHE_HOME
- Where should Taler store cached data.
- Usually “${TALER_HOME}/.cache/taler/”.
-
-TALER_RUNTIME_DIR
- Where should Taler store system runtime data (like UNIX domain
- sockets). Usually “${TMP}/taler-system-runtime”.
-
-
-CURRENCY SPECIFICATIONS
------------------------
-
-Sections with a name of the form “[currency-$NAME]” (where "$NAME" could
-be any unique string) are used to specify details about how currencies
-should be handled (and in particularly rendered) by the user interface.
-A detailed motivation for this section can be found in DD51.
-Different components can have different rules for the same currency. For
-example, a bank or merchant may decide to render Euros or Dollars with
-always exactly two fractional decimals, while an Exchange for the same
-currency may support additional decimals. The required options in each
-currency specification section are:
-
-ENABLED
- Set to YES or NO. If set to NO, the currency specification
- section is ignored. Can be used to disable currencies or
- select alternative sections for the same CODE with different
- choices.
-
-CODE
- Code name for the currency. Can be at most 11 characters,
- only the letters A-Z are allowed. Primary way to identify
- the currency in the protocol.
-
-NAME
- Long human-readable name for the currency. No restrictions,
- but should match the official name in English.
-
-FRACTIONAL_INPUT_DIGITS
- Number of fractional digits that users are allowed to enter
- manually in the user interface.
-
-FRACTIONAL_NORMAL_DIGITS
- Number of fractional digits that will be rendered normally
- (in terms of size and placement). Digits shown beyond this
- number will typically be rendered smaller and raised (if
- possible).
-
-FRACTIONAL_TRAILING_ZERO_DIGITS
- Number of fractional digits to pad rendered amounts with
- even if these digits are all zero. For example, use 2 to
- render 1 USD as $1.00.
-
-ALT_UNIT_NAMES
- JSON map determining how to encode very large or very tiny
- amounts in this currency. Maps a base10 logarithm to the
- respective currency symbol. Must include at least an
- entry for 0 (currency unit). For example, use
- {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could
- additionally use {"0":"€","3":"k€"} to render 3000 EUR
- as 3k€. For BTC a typical map would be
- {"0":"BTC","-3":"mBTC"}, informing the UI to render small
- amounts in milli-Bitcoin (mBTC).
-
-
-EXCHANGE OPTIONS
-----------------
-
-The following options are from the “[exchange]” section and used by most
-exchange tools.
-
-DB
- Plugin to use for the database, e.g. “postgres”.
-
-SERVE
- Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
-
-UNIXPATH
- Path to listen on if we "SERVE" is set to "unix".
-
-UNIXPATH_MODE
- Access permission mask to use for the "UNIXPATH".
-
-PORT
- Port on which the HTTP server listens, e.g. 8080.
-
-BIND_TO
- Hostname to which the exchange HTTP server should be bound to, e.g. "localhost".
-
-MASTER_PUBLIC_KEY
- Crockford Base32-encoded master public key, public version of the
- exchange's long-time offline signing key. This configuration option
- is also used by the **auditor** to determine the public key of the
- exchange which it is auditing.
-
-TINY_AMOUNT
- Small amount that can be transferred to the exchange for the
- KYC authentication wire transfers. Should be given as a hint
- for merchants what amount they need to transfer to begin the
- KYC transfer. Note that the amount is not enforced by the
- exchange *and* that this option is optional. However, if it is
- not given, merchants will have to guess what amount to transfer,
- so it really should be configured.
-
-SHOPPING_URL
- Web URL where users can discover shops that accept digital cash
- offered by this exchange. Optional, but highly recommended.
-
-STEFAN_ABS
- Absolute amount to add as an offset in the STEFAN fee approximation
- curve (see DD47). Defaults to CURRENCY:0 if not specified.
-
-STEFAN_LOG
- Amount to multiply by the base-2 logarithm of the total amount
- divided by the amount of the smallest denomination
- in the STEFAN fee approximation curve (see DD47).
- Defaults to CURRENCY:0 if not specified.
-
-STEFAN_LIN
- Linear floating point factor to be multiplied by the total amount
- to use in the STEFAN fee approximation curve (see DD47).
- Defaults to 0.0 if not specified.
-
-BASE_URL
- The base URL under which the exchange can be reached.
- Added to wire transfers to enable tracking by merchants.
- Used by the KYC logic when interacting with OAuth 2.0.
-
-TOPLEVEL_REDIRECT_URL
- Where to redirect visitors that access the top-level
- "/" endpoint of the exchange. Should point users to
- information about the exchange operator.
- Optional setting, defaults to "/terms".
-
-AGGREGATOR_IDLE_SLEEP_INTERVAL
- For how long should the taler-exchange-aggregator sleep when it is idle
- before trying to look for more work? Default is 60 seconds.
-
-CLOSER_IDLE_SLEEP_INTERVAL
- For how long should the taler-exchange-closer sleep when it is idle
- before trying to look for more work? Default is 60 seconds.
-
-TRANSFER_IDLE_SLEEP_INTERVAL
- For how long should the taler-exchange-transfer sleep when it is idle
- before trying to look for more work? Default is 60 seconds.
-
-WIREWATCH_IDLE_SLEEP_INTERVAL
- For how long should the taler-exchange-wirewatch sleep when it is idle
- before trying to look for more work? Default is 60 seconds.
-
-AGGREGATOR_SHARD_SIZE
- Which share of the range from [0,..2147483648] should be processed by one of the shards of the aggregator. Useful only for Taler exchanges with ultra high-performance needs. When changing this value, you must stop all aggregators and run "taler-exchange-dbinit -s" before resuming. Default is 2147483648 (no sharding).
-
-SIGNKEY_LEGAL_DURATION
- For how long are signatures with signing keys legally valid?
-
-MAX_KEYS_CACHING
- For how long should clients cache ``/keys`` responses at most?
-
-MAX_REQUESTS
- How many requests should the HTTP server process at most before committing suicide?
-
-TERMS_DIR
- Directory where the terms of service of the exchange operator can be fund.
- The directory must contain sub-directories for every supported language,
- using the two-character language code in lower case, e.g. "en/" or "fr/".
- Each subdirectory must then contain files with the terms of service in
- various formats. The basename of the file of the current policy must be
- specified under ``TERMS_ETAG``. The extension defines the mime type.
- Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg",
- "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure
- could be the following:
-
- - $TERMS_DIR/en/0.pdf
- - $TERMS_DIR/en/0.html
- - $TERMS_DIR/en/0.txt
- - $TERMS_DIR/fr/0.pdf
- - $TERMS_DIR/fr/0.html
- - $TERMS_DIR/de/0.txt
-
-TERMS_ETAG
- Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service.
- The value is also used for the "Etag" in the HTTP request to control
- caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also
- change, and old values MUST NOT be repeated. For example, the date or
- version number of the terms of service SHOULD be used for the Etag. If
- there are minor (e.g. spelling) fixes to the terms of service, the
- ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must
- approve the new terms, the ``TERMS_ETAG`` MUST change.
-
-PRIVACY_DIR
- Works the same as ``TERMS_DIR``, just for the privacy policy.
-
-PRIVACY_ETAG
- Works the same as ``TERMS_ETAG``, just for the privacy policy.
-
-ENABLE_KYC
- Must be set to ``YES`` to enable AML/KYC rule enforcement. Note that the administrative endpoints will always work, even if the flag is set to ``NO``.
-
-
-EXCHANGE KYC PROVIDER OPTIONS
------------------------------
-
-The following options must be in the section "[kyc-provider-$PROVIDER_NAME]" sections.
-
-LOGIC
- API type of the KYC provider.
-
-Additional logic-specific options may be given in the
-section.
-
-
-EXCHANGE KYC OAUTH2 OPTIONS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2".
-
-
-KYC_OAUTH2_VALIDITY
- Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
-
-KYC_OAUTH2_AUTHORIZE_URL
- URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: "http://localhost:8888/oauth/v2/authorize". To use the plugin in combination with the Challenger service's ``/setup`` step, append "#setup", thus "https://challenger.example.com/authorize#setup". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the ``/setup/$CLIENT_ID`` handler.
-
-KYC_OAUTH2_TOKEN_URL
- URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "http://localhost:8888/oauth/v2/token" (or just "/token")
-
-KYC_OAUTH2_INFO_URL
- URL of the OAuth2-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "http://localhost:8888/api/user/me" or "http://localhost:8888/oauth/v2/info"
-
-KYC_OAUTH2_CLIENT_ID
- Client ID of the exchange when it talks to the KYC OAuth2 endpoint.
-
-KYC_OAUTH2_CLIENT_SECRET
- Client secret of the exchange to use when talking to the KYC Oauth2 endpoint.
-
-KYC_OAUTH2_POST_URL
- URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. Example: "http://example.com/thank-you"
-
-KYC_OAUTH2_CONVERTER_HELPER
- Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider.
-
-KYC_OAUTH2_DEBUG_MODE
- Set to YES to allow error responses to include potentially
- sensitive private information (such as full responses
- from the OAuth 2.0 server) that might aid in debugging
- problems. Should be set to "NO" in production.
-
-
-EXCHANGE KYC KYCAID OPTIONS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid".
-
-
-KYC_KYCAID_VALIDITY
- Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
-
-KYC_KYCAID_AUTH_TOKEN
- Authentication token to access the KYC service.
-
-KYC_KYCAID_CONVERTER_HELPER
- Helper to convert JSON with KYC data returned by KYCAID into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-kycaid-converter.sh".
-
-KYC_KYCAID_FORM_ID
- ID that specifies the form to use for the KYC process.
-
-KYC_KYCAID_POST_URL
- URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
-
-
-EXCHANGE KYC PERSONA OPTIONS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona".
-
-
-KYC_PERSONA_VALIDITY
- Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
-
-KYC_PERSONA_AUTH_TOKEN
- Authentication token to access the KYC service.
-
-KYC_PERSONA_SALT
- Salt value to use for request idempotency. Optional, generated at random per process if not given.
-
-KYC_PERSONA_SUBDOMAIN
- Subdomain to use under Persona.
-
-KYC_PERSONA_CONVERTER_HELPER
- Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-persona-converter.sh".
-
-KYC_PERSONA_POST_URL
- URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
-
-KYC_PERSONA_TEMPLATE_ID
- ID of the Persona template to use.
-
-EXCHANGE KYC PERSONA GLOBAL OPTIONS
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The following option must be in the section "[kyclogic-persona]".
-
-
-WEBHOOK_AUTH_TOKEN
- Authentication token Persona must supply to our webhook. This is an optional setting.
-
-
-EXCHANGE KYC CHECK OPTIONS
---------------------------
-
-The following options must be in "[kyc-check-$CHECK_NAME]" sections.
-
-TYPE
- Which type of check is this? Also determines
- the SPA form to show to the user for this check.
-
- * INFO: wait for staff or contact staff out-of band
- (only information shown, no SPA action)
- * FORM: SPA should show an inline (HTML) form
- * LINK: SPA may start external KYC process or upload
-
-PROVIDER_ID
- Provider id, present only if type is LINK.
- Refers to a ``kyc-provider-$PROVIDER_ID`` section.
-
-FORM_NAME
- Name of the SPA form, if type is FORM
- "INFO" and "LINK" are reserved and must not be used.
- The exchange server and the SPA must agree on a list
- of supported forms and the resulting attributes.
- The SPA should include a JSON resource file
- "forms.json" mapping form names to arrays of
- attribute names each form provides.
- The list of possible FORM names is fixed in the SPA
- for a particular exchange release.
-
-DESCRIPTION
- Descriptions to use in the SPA to display the check.
-
-DESCRIPTION_I18N
- JSON with internationalized descriptions to use
- in the SPA to display the check.
-
-REQUIRES
- ';'-separated list of fields that the CONTEXT must
- provide as inputs to this check. For example,
- for a FORM of type CHOICE, this might state
- ``choices: string[];``. The type after the ":"
- is for now purely for documentation and is
- not checked. However, it may be shown to AML staff
- when they configure measures.
-
-OUTPUTS = "business_name street city country registration"
- Description of the outputs provided by the check.
- Basically, the check's output is expected to
- provide the following fields as attribute inputs into
- a subsequent AML program. INFO never has any outputs.
-
-FALLBACK
- Name of an **original** measure to take if the check fails
- (for any reason, e.g. provider or form fail to
- satisfy constraints or provider signals user error)
- Usually should point to a measure that requests
- AML staff to investigate. The fallback measure
- context always includes the reasons for the
- failure.
-
-EXCHANGE KYC RULES
-------------------
-
-The following options must be in "[kyc-rule-$RULE_NAME]" sections.
-
-OPERATION_TYPE = WITHDRAW
- Operation that triggers this rule.
- Must be one of WITHDRAW, DEPOSIT, MERGE, BALANCE,
- CLOSE, AGGREGATE, TRANSACTION or REFUND.
-
-NEXT_MEASURES
- Space-separated list of next measures to be performed.
- The SPA should display *all* of these measures to the user.
- (They have a choice of either which ones, or in
- which order they are to be performed.)
- A special measure name "verboten" is used if the
- specified threshold may never be crossed
- (under this set of rules). This option is equivalent
- to the "new_measure" string in an AmlDecisionRequest
- (with IS_AND_COMBINATOR replacing the "+"-prefix).
-
-IS_AND_COMBINATOR
- "YES" if all NEXT_MEASURES will eventually need
- to be satisfied, "NO" the user has a choice between
- them. Not actually enforced by the exchange, but
- primarily used to inform the user whether this is
- an "and" or "or". YES for "and".
-
-EXPOSED
- YES if the rule (specifically, operation type,
- threshold, timeframe) and the general nature of
- the next measure (verboten or approval required)
- should be exposed to the client.
- Defaults to NO if not set.
-
-THRESHOLD
- Threshold amount above which the rule is
- triggered. The total must be exceeded in the given
- timeframe.
-
-TIMEFRAME
- Timeframe over which the amount to be compared to
- the THRESHOLD is calculated (for example, "30 days").
- Ignored for BALANCE. Can be 'forever'.
-
-ENABLED = NO
- Set to YES to enable the rule (default is NO).
-
-
-EXCHANGE AML PROGRAMS
----------------------
-
-The following options must be in "[aml-program-$PROG_NAME]" sections.
-
-COMMAND
- Name of the program to run. Must match a binary
- on the local machine where the exchange is running.
-
-DESCRIPTION
- Human-readable description of what this
- AML helper program will do. Used to show
- to the AML staff.
-
-ENABLED
- True if this AML program is enabled (and thus can be
- used in measures and exposed to AML staff).
- Optional, default is NO.
-
-FALLBACK
- Name of an **original** measure to take if COMMAND fails
- Usually points to a measure that asks AML staff
- to contact the systems administrator. The fallback measure
- context always includes the reasons for the
- failure.
-
-EXCHANGE KYC MEASURES
----------------------
-
-The following options must be in "[kyc-measure-$MEASURE_NAME]" sections.
-These sections define the **original** measures.
-
-CHECK_NAME
- Name of a possible check for this measure. Optional.
- If not given, PROGRAM should be run immediately
- (on an empty set of attributes).
-
-CONTEXT = {"choices":["individual","business"]}
- Context for the check. The context can be
- just an empty JSON object if there is none.
-
-PROGRAM
- Program to run on the context and check data to
- determine the outcome and next measure.
- Refers to a ``[aml-program-$PROG_NAME]`` section name.
-
-VOLUNTARY
- Optional. Set to YES to allow this measure to be
- done voluntarily by a client. Used to offer the
- SPA to display measures even if they are
- not required. Default is NO.
-
-
-
-EXCHANGE EXTENSIONS OPTIONS
----------------------------
-
-The functionality of the exchange can be extended by extensions. Those are
-shared libraries which implement the extension-API of the exchange and are
-located under ``$LIBDIR``, starting with prefix ``libtaler_extension_``. Each
-extension can be enabled by adding a dedicated section
-"[exchange-extension-<extensionname>]" and the following option:
-
-ENABLED
- If set to ``YES`` the extension ``<extensionsname>`` is enabled. Extension-specific
- options might be set in the same section.
-
-
-EXCHANGE EXTENSION FOR AGE RESTRICTION
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The extension for age restriction support can be enabled by adding a section
-"[exchange-extension-age_restriction]" with the following options:
-
-ENABLE
- Must be set to ``YES`` in order to activate the extension.
-
-AGE_GROUPS
- A colon-seperated string of increasing non-negative integers, defining the
- buckets of age groups supported by the exchange. Each integer marks the
- beginning of the next age group. The zero'th age group implicitly starts
- with 0. For example, the string "10:18" would define three age groups:
-
- 1. Group 0: ages 0 through 9 (including)
- 2. Group 1: ages 10 through 17 (including)
- 3. Group 2: ages 18 and above
-
- If not provided, the default value is "8:10:12:14:16:18:21".
-
-**Note**: Age restriction is bound to specific denominations and must be
-enabled for each selected denomination in the corresponding section by adding
-the option ``AGE_RESTRICTED = YES``, see `EXCHANGE COIN OPTIONS`_. However, the
-age groups are defined globally for all denominations.
-
-
-
-EXCHANGE OFFLINE SIGNING OPTIONS
---------------------------------
-
-The following options must be in the section "[exchange-offline]".
-
-MASTER_PRIV_FILE
- Location of the master private key on disk. Only used by tools that
- can be run offline (as the master key is for offline signing).
- Mandatory.
-
-SECM_TOFU_FILE
- Where to store the public keys of both crypto helper modules.
- Used to persist the keys after the first invocation of the tool,
- so that if they ever change in the future, this is detected and
- the tool can abort.
- Mandatory.
-
-SECM_DENOM_PUBKEY
- Public key of the (RSA) crypto helper module. Optional. If not given,
- we will rely on TOFU. Note that once TOFU has been established,
- this option will also be ignored.
-
-SECM_ESIGN_PUBKEY
- Public key of the (EdDSA) crypto helper module. Optional. If not given,
- we will rely on TOFU. Note that once TOFU has been established,
- this option will also be ignored.
-
-
-EXCHANGE RSA CRYPTO HELPER OPTIONS
-----------------------------------
-
-The following options must be in the section "[taler-exchange-secmod-rsa]".
-
-LOOKAHEAD_SIGN
- How long do we generate denomination and signing keys ahead of time?
-
-OVERLAP_DURATION
- How much should validity periods for coins overlap?
- Should be long enough to avoid problems with
- wallets picking one key and then due to network latency
- another key being valid. The ``DURATION_WITHDRAW`` period
- must be longer than this value.
-
-SM_PRIV_KEY
- Where should the security module store its long-term private key?
-
-KEY_DIR
- Where should the security module store the private keys it manages?
-
-UNIXPATH
- On which path should the security module listen for signing requests?
-
-Note that the **taler-exchange-secmod-rsa** also evaluates the ``[coin_*]``
-configuration sections described below.
-
-
-EXCHANGE CS CRYPTO HELPER OPTIONS
----------------------------------
-
-The following options must be in the section "[taler-exchange-secmod-cs]".
-
-LOOKAHEAD_SIGN
- How long do we generate denomination and signing keys ahead of time?
-
-OVERLAP_DURATION
- How much should validity periods for coins overlap?
- Should be long enough to avoid problems with
- wallets picking one key and then due to network latency
- another key being valid. The ``DURATION_WITHDRAW`` period
- must be longer than this value.
-
-SM_PRIV_KEY
- Where should the security module store its long-term private key?
-
-KEY_DIR
- Where should the security module store the private keys it manages?
-
-UNIXPATH
- On which path should the security module listen for signing requests?
-
-Note that the **taler-exchange-secmod-cs** also evaluates the ``[coin_*]``
-configuration sections described below.
-
-
-
-EXCHANGE EDDSA CRYPTO HELPER OPTIONS
-------------------------------------
-
-The following options must be in the section "[taler-exchange-secmod-eddsa]".
-
-LOOKAHEAD_SIGN
- How long do we generate denomination and signing keys ahead of time?
-
-OVERLAP_DURATION
- How much should validity periods for coins overlap?
- Should be long enough to avoid problems with
- wallets picking one key and then due to network latency
- another key being valid. The ``DURATION_WITHDRAW`` period
- must be longer than this value.
-
-DURATION
- For how long should EdDSA keys be valid for signing?
-
-SM_PRIV_KEY
- Where should the security module store its long-term private key?
-
-KEY_DIR
- Where should the security module store the private keys it manages?
-
-UNIXPATH
- On which path should the security module listen for signing requests?
-
-
-
-EXCHANGE DATABASE OPTIONS
--------------------------
-
-The following options must be in the section "[exchangedb]".
-
-IDLE_RESERVE_EXPIRATION_TIME
- After which time period should reserves be closed if they are idle?
-
-LEGAL_RESERVE_EXPIRATION_TIME
- After what time do we forget about (drained) reserves during garbage collection?
-
-AGGREGATOR_SHIFT
- Delay between a deposit being eligible for aggregation and
- the aggregator actually triggering.
-
-DEFAULT_PURSE_LIMIT
- Number of concurrent purses that a reserve may have active
- if it is paid to be opened for a year.
-
-
-EXCHANGE POSTGRES BACKEND DATABASE OPTIONS
-------------------------------------------
-
-The following options must be in section “[exchangedb-postgres]” if the
-“postgres” plugin was selected for the database.
-
-CONFIG
- How to access the database, e.g. “postgres:///taler” to use the
- “taler” database. Testcases use “talercheck”.
-
-
-EXCHANGE ACCOUNT OPTIONS
-------------------------
-
-An exchange (or merchant) can have multiple bank accounts. The following
-options are for sections named “[exchange-account-SOMETHING]”. The ``SOMETHING`` is
-arbitrary and should be chosen to uniquely identify the bank account for
-the operator. These options are used by the **taler-exchange-aggregator**, **taler-exchange-closer**, **taler-exchange-transfer** and **taler-exchange-wirewatch** tools.
-
-PAYTO_URI
- Specifies the payto://-URL of the account. The general format is
- ``payto://$METHOD/$DETAILS``. Examples:
- ``payto://x-taler-bank/localhost:8899/Exchange`` or
- ``payto://iban/GENODEF1SLR/DE67830654080004822650/`` or
- ``payto://iban/DE67830654080004822650/`` (providing the BIC is optional).
- Note: only the wire-method is actually used from the URI.
- Alternatively, you can also just specify the wire method.
-
-WIRE_METHOD
- Specifies the wire method following RFC 8905. Examples:
- ``x-taler-bank``, ``iban`` or ``wallee``. This option is
- ignored if a PAYTO_URI is specified, and mandatory if PAYTO_URI is
- not given.
-
-ENABLE_DEBIT
- Must be set to ``YES`` for the accounts that the
- **taler-exchange-aggregator** and **taler-exchange-closer** should debit.
-
-ENABLE_CREDIT
- Must be set to ``YES`` for the accounts that the **taler-exchange-wirewatch**
- should check for credits. It is yet uncertain if the merchant
- implementation may check this flag as well.
-
-
-Additionally, for each enabled account there MUST be another matching section named “[exchange-accountcredentials-SOMETHING]”. This section SHOULD be in a ``secret/`` configuration file that is only readable for the **taler-exchange-wirewatch** and **taler-exchange-transfer** processes. It contains the credentials to access the bank account:
-
-WIRE_GATEWAY_URL
- URL of the wire gateway. Typically of the form
- ``https://$HOSTNAME[:$PORT]/taler-wire-gateway/$USERNAME/``
- where $HOSTNAME is the hostname of the system running the bank
- (such as the Taler Python bank or the Nexus) and ``$USERNAME`` is
- the username of the exchange's bank account (usually matching
- the ``USERNAME`` option used for authentication). Example:
- ``https://bank.demo.taler.net/taler-wire-gateway/Exchange/``.
-
-WIRE_GATEWAY_AUTH_METHOD
- This option determines how the exchange (auditor/wirewatch/aggregator)
- authenticates with the wire gateway. Choices are ``basic``, ``bearer`` and ``none``.
-
-USERNAME
- User name for ``basic`` authentication with the wire gateway.
-
-PASSWORD
- Password for ``basic`` authentication with the wire gateway.
-
-TOKEN
- Token for ``bearer`` authentication with the wire gateway.
-
-
-EXCHANGE COIN OPTIONS
----------------------
-
-The following options must be in sections starting with ``"[coin_]"`` and are
-largely used by **taler-exchange-httpd** to determine the meta data for the
-denomination keys. Some of the options are used by the
-**taler-exchange-secmod-rsa** to determine which RSA keys to create (and of
-what key length). Note that the section names must match, so this part of the
-configuration MUST be shared between the RSA helper and the exchange.
-Configuration values MUST NOT be changed in a running setup. Instead, if
-parameters for a denomination type are to change, a fresh *section name* should
-be introduced (and the existing section should be deleted).
-
-
-VALUE
- Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per
- coin).
-
-DURATION_WITHDRAW
- How long should the same key be used for clients to withdraw coins of
- this value?
-
-DURATION_SPEND
- How long do clients have to spend these coins?
-
-DURATION_LEGAL
- How long does the exchange have to keep records for this denomination?
-
-FEE_WITHDRAW
- What fee is charged for withdrawal?
-
-FEE_DEPOSIT
- What fee is charged for depositing?
-
-FEE_REFRESH
- What fee is charged for refreshing?
-
-FEE_REFUND
- What fee is charged for refunds? When a coin is refunded, the deposit
- fee is returned. Instead, the refund fee is charged to the customer.
-
-CIPHER
- What cryptosystem should be used? Must be set to either "CS" or "RSA".
- The respective crypto-helper will then generate the keys for this
- denomination.
-
-RSA_KEYSIZE
- What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA".
-
-AGE_RESTRICTED
- Setting this option to ``YES`` marks the denomination as age restricted
- (default is ``NO``). For this option to be accepted the extension for age
- restriction MUST be enabled (see `EXCHANGE EXTENSION FOR AGE RESTRICTION`_).
-
-
-MERCHANT OPTIONS
-----------------
-
-The following options are from the “[merchant]” section and used by the
-merchant backend.
-
-DB
- Plugin to use for the database, e.g._“postgres”.
-
-SERVE
- Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
-
-BASE_URL
- Which base URL should the merchant backend assume for itself in the protocol. Optional. If not given, the base URL will be constructed from X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Prefix headers that a reverse-proxy should be setting.
-
-UNIXPATH
- Path to listen on if we "SERVE" is set to "unix".
-
-UNIXPATH_MODE
- Access permission mask to use for the "UNIXPATH".
-
-PORT
- Port on which the HTTP server listens, e.g. 8080.
-
-BIND_TO
- Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
-
-LEGAL_PRESERVATION
- How long do we keep data in the database for tax audits after the
- transaction has completed? Default is 10 years.
-
-FORCE_AUDIT
- Force the merchant to report every transaction to the auditor
- (if the exchange has an auditor)? Default is ``NO``.
- Do not change except for testing.
-
-
-MERCHANT POSTGRES BACKEND DATABASE OPTIONS
-------------------------------------------
-
-The following options must be in section “[merchantdb-postgres]” if the
-“postgres” plugin was selected for the database.
-
-CONFIG
- How to access the database, e.g. “postgres:///taler” to use the
- “taler” database. Testcases use “talercheck”.
-
-
-KNOWN EXCHANGES (for merchants)
--------------------------------
-
-The merchant configuration can include a list of known exchanges if the
-merchant wants to specify that certain exchanges are explicitly trusted.
-For each trusted exchange, a section [merchant-exchange-$NAME] must exist, where
-$NAME is a merchant-given name for the exchange. The following options
-must be given in each “[exchange-$NAME]” section.
-
-EXCHANGE_BASE_URL
- Base URL of the exchange, e.g. “https://exchange.demo.taler.net/”
-
-MASTER_KEY
- Crockford Base32 encoded master public key, public version of the
- exchange's long-time offline signing key. Can be omitted, in that
- case the exchange will NOT be trusted unless it is audited by
- a known auditor.
- Omitting ``MASTER_KEY`` can be useful if we do not trust the exchange
- without an auditor, but should pre-load the keys of this
- particular exchange on startup instead of waiting for it to be
- required by a client.
-
-CURRENCY
- Name of the currency for which this exchange is used, e.g. “KUDOS”.
- The entire section is ignored if the currency does not match the currency
- we use, which must be given in the ``[taler]`` section.
-
-DISABLED
- Set to YES to disable this exchange. Optional option, defaults to NO.
-
-
-AUDITOR OPTIONS
----------------
-
-The following options must be in section “[auditor]” for the Taler
-auditor.
-
-DB
- Plugin to use for the database, e.g. “postgres”
-
-AUDITOR_PRIV_FILE
- Name of the file containing the auditor’s private key.
-
-PUBLIC_KEY
- Crockford Base32 encoded auditor public key. Used by (online) auditor
- processes that do not have access to the (offline) auditor private key file.
-
-BASE_URL
- Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
-
-SERVE
- Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
-
-UNIXPATH
- Path to listen on if we "SERVE" is set to "unix".
-
-UNIXPATH_MODE
- Access permission mask to use for the "UNIXPATH".
-
-PORT
- Port on which the HTTP server listens, e.g. 8080.
-
-BIND_TO
- Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
-
-
-
-
-AUDITOR POSTGRES BACKEND DATABASE OPTIONS
------------------------------------------
-
-The following options must be in section “[auditordb-postgres]” if the
-“postgres” plugin was selected for the database.
-
-CONFIG
- How to access the database, e.g. "postgres:///taler" to use the
- "taler" database. Testcases use “talercheck”.
-
-
-Bank Options
-------------
-
-The following options must be in section "[bank]" for the taler-fakebank-run(1) command. They are not used by the exchange or LibEuFin!
-
-HTTP_PORT
- On which TCP port should the (fake)bank offer its REST API.
-RAM_LIMIT
- This gives the number of transactions to keep in memory. Older transactions will be overwritten and history requests for overwritten transactions will fail.
-
-
-Taler-mdb Options
------------------
-
-Taler-mdb is a component to run GNU Taler as a payment system on
-vending machines using the multi-drop bus protocol. These options
-are thus not useful for most users. Note that right now, the
-cancel button is hard-coded to be using GPIO pin 23.
-
-ADVERTISEMENT_COMMAND
- Program to run while not vending, possibly useful to show advertisements on the screen (optional).
-ESSID
- ESSID to advertise to wallets for use as an open WiFi to make payments (optional).
-FULFILLMENT_MSG
- Message shown to users by their wallets upon successful payment. If "${PRODUCT_DESCRIPTION}" appears in the message, it will be replaced with the description of the product that was sold.
-BACKEND_BASE_URL
- Base URL (possibly including instance) for the Taler merchant backend used to process payments.
-BACKEND_AUTHORIZATION
- Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Mandatory.
-FRAMEBUFFER_BACKLIGHT
- Name of the file used to control brightness of the display. Optional. Defaults to "/sys/class/backlight/soc:backlight/brightness" if not given.
-FRAMEBUFFER_DEVICE
- Name of the framebuffer device to use. Defaults to "/dev/fb1" if not given.
-UART_DEVICE
- Name of the UART device to use. Defaults to "/dev/ttyAMA0" if not given.
-FAIL_COMMAND
- Command to run by taler-mdb to display a failure to the user. If not given, errors will not be properly shown. Should usually be set to "taler-mdb-show.sh".
-FAIL_HELPER
- Command used by taler-mdb-network-check.sh to run to display a failure to the user. If not given, errors will not be properly shown. Should usually be set to "taler-mdb-show.sh".
-
-Each products being sold must be configured in a section where the name starts with "product-".
-In these sections, the options that must be provided are:
-
-NUMBER
- Number identifying the slot in the vending machine that corresponds to this product.
-INSTANCE
- Instance to use for the payment. Optional. If not given, the BACKEND_BASE_URL from "[taler-mdb]" will be used.
-BACKEND_AUTHORIZATION
- Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Optional, will use global BACKEND_AUTHORIZATION setting from "[taler-mdb]" if missing.
-DESCRIPTION
- Human-readable description of the product. Use "empty" if the product is known to be sold out (only effective if selling out is enabled via command-line).
-PRICE
- Actual price of the product, as a Taler amount ("$CURRENCY:$VALUE.$FRACTION").
-KEY
- Key used to select the product from the console during testing. Optional.
-THUMBNAIL
- Name of a filename with a preview image of the product to be given to the wallet. Optional. Only ".png", ".jpg", ".jpeg" and ".svg" are supported at this time.
-
-
-SEE ALSO
-========
-
-taler-exchange-dbinit(1), taler-exchange-httpd(1),
-taler-exchange-offline(1), taler-auditor-offline(1).
-
-BUGS
-====
-
-Report bugs by using https://bugs.taler.net/ or by sending electronic
-mail to <taler@gnu.org>.
diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
@@ -478,7 +478,7 @@ the URL, as ``#`` is otherwise interpreted as the beginning of a comment by
the configuration file syntax:
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-oauth2.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-oauth2.conf
[kyc-provider-example-oauth2]
LOGIC = oauth2
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -481,9 +481,9 @@ The package will deploy systemd service files in
The deployment creates the following key locations in the system:
-* ``/etc/taler/``: configuration files.
-* ``/run/taler/``: contains the UNIX domain sockets for inter-process communication (IPC).
-* ``/var/lib/taler/``: serves as the $HOME for all Taler users and contains sub-directories
+* ``/etc/taler-exchange/``: configuration files.
+* ``/run/taler-exchange/``: contains the UNIX domain sockets for inter-process communication (IPC).
+* ``/var/lib/taler-exchange/``: serves as the $HOME for all Taler exchange users and contains sub-directories
with the private keys; which keys are stored here depends on the host:
* online system: exchange-secmod-eddsa, exchange-secmod-cs and exchange-secmod-rsa keys.
@@ -496,35 +496,37 @@ Configuration Fundamentals
This chapter provides fundamental details about the exchange configuration.
The configuration for all Taler components uses a single configuration file
-as entry point: ``/etc/taler/taler.conf``.
+as entry point: ``/etc/taler-exchange/taler-exchange.conf``.
System defaults are automatically loaded from files in
-``/usr/share/taler/config.d``. These default files should never be modified.
+``/usr/share/taler-exchange/config.d``.
+These default files should never be modified.
-The default configuration ``taler.conf`` configuration file also includes all
-configuration files in ``/etc/taler/conf.d``. The settings from files in
-``conf.d`` are only relevant to particular components of Taler, while
-``taler.conf`` contains settings that affect all components.
+The default configuration ``taler-exchange.conf`` configuration file
+also includes all configuration files in ``/etc/taler-exchange/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an exchange, while
+``taler-exchange.conf`` contains settings that affect all exchange components.
-The directory ``/etc/taler/secrets`` contains configuration file snippets with
+The directory ``/etc/taler-exchange/secrets`` contains configuration file snippets with
values that should only be readable to certain users. They are included with the ``@inline-secret@``
directive and should end with ``.secret.conf``.
To view the entire configuration annotated with the source of each configuration option, you
-can use the ``taler-config`` helper:
+can use the ``taler-exchange-config`` helper:
.. code-block:: shell-session
- [root@exchange-online]# taler-config --diagnostics
+ [root@exchange-online]# taler-exchange-config --diagnostics
< ... annotated, full configuration ... >
.. warning::
- While ``taler-config`` also supports rewriting configuration files, we strongly
- recommend to edit configuration files manually, as ``taler-config`` does not
- preserve comments and, by default, rewrites ``/etc/taler/taler.conf``.
+ While ``taler-exchange=config`` also supports rewriting configuration files, we strongly
+ recommend to edit configuration files manually, as ``taler-exchange-config`` does not
+ preserve comments and, by default, rewrites ``/etc/taler-exchange/taler-exchange.conf``.
.. include:: frags/configuration-format.rst
@@ -534,8 +536,8 @@ Exchange Database Setup
=======================
The access credentials for the exchange's database are configured in
-``/etc/taler/secrets/exchange-db.secret.conf``. Currently, only PostgreSQL is
-supported as a database backend.
+``/etc/taler-exchange/secrets/exchange-db.secret.conf``.
+Currently, only PostgreSQL is supported as a database backend.
The following users must have access to the exchange database:
@@ -577,7 +579,7 @@ Assuming the above database setup, the database credentials to configure
in the configuration file would simply be:
.. code-block:: ini
- :caption: /etc/taler/secrets/exchange-db.secret.conf
+ :caption: /etc/taler-exchange/secrets/exchange-db.secret.conf
[exchange]
DB = postgres
@@ -640,12 +642,12 @@ Basic Setup: Currency, Denominations and Keys
A Taler exchange only supports a single currency. The currency
and the smallest currency unit supported by the bank system
-must be specified in ``/etc/taler/taler.conf``.
+must be specified in ``/etc/taler-exchange/taler-exchange.conf``.
.. code-block:: ini
- :caption: /etc/taler/taler.conf
+ :caption: /etc/taler-exchange/taler-exchange.conf
- [taler]
+ [exchange]
CURRENCY = EUR
CURRENCY_ROUND_UNIT = EUR:0.01
@@ -653,7 +655,7 @@ must be specified in ``/etc/taler/taler.conf``.
.. warning::
- When editing ``/etc/taler/taler.conf``, take care to not accidentally remove
+ When editing ``/etc/taler-exchange/taler-exchange.conf``, take care to not accidentally remove
the ``@inline-matching@`` directive to include the configuration files in ``conf.d``.
.. _Coins-denomination-keys:
@@ -706,7 +708,7 @@ must then have the following options:
for age restrictions. See age restriction extension below for details.
This option is optional and defaults to ``NO``.
-See :doc:`manpages/taler.conf.5` for information on *duration* values
+See :doc:`manpages/taler-exchange.conf.5` for information on *duration* values
(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND`` above,
and ``OVERLAP_DURATION`` and ``DURATION`` below).
Additionally, there are two global configuration options of note:
@@ -742,7 +744,7 @@ reasonable denomination structure.
[root@exchange-online]# taler-wallet-cli deployment gen-coin-config \
--min-amount EUR:0.01 \
--max-amount EUR:100 \
- > /etc/taler/conf.d/exchange-coins.conf
+ > /etc/taler-exchange/conf.d/exchange-coins.conf
You can manually review and edit the generated configuration file. The main
change that is possibly required is updating the various fees. Note that you
@@ -820,7 +822,7 @@ The public key printed as the output of this command must be put into the
configuration of the online machine:
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-business.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-business.conf
[exchange]
MASTER_PUBLIC_KEY = YE6Q6TR1ED...
@@ -880,10 +882,10 @@ information:
Each Taler wire gateway is configured in a configuration section that follows
the pattern ``exchange-account-$id``, where ``$id`` is an internal identifier
for the bank account accessed by the exchange. The basic information for an
-account should be put in ``/etc/taler/conf.d/exchange-business.conf``. The
+account should be put in ``/etc/taler-exchange/conf.d/exchange-business.conf``. The
secret credentials to access the Taler Wire Gateway API should be put into a
corresponding ``exchange-accountcredentials-$id`` section in
-``/etc/taler/secrets/exchange-accountcredentials.conf``. The latter file
+``/etc/taler-exchange/secrets/exchange-accountcredentials.conf``. The latter file
should be only readable for the ``taler-exchange-wire`` user. Only the
``taler-exchange-wirewatch`` and ``taler-exchange-transfer`` services should
run as the ``taler-exchange-wire`` user. Other exchange processes do not need
@@ -895,7 +897,7 @@ starting with ``exchange-account-`` for the section name. You must specify
(incoming or outgoing wire transfers):
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-business.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-business.conf
[exchange-account-1]
# Account identifier in the form of an RFC-8905 payto:// URI.
@@ -920,7 +922,7 @@ starting with ``exchange-account-`` for the section name. You must specify
.. code-block:: ini
- :caption: /etc/taler/secrets/exchange-accountcredentials.secret.conf
+ :caption: /etc/taler-exchange/secrets/exchange-accountcredentials.secret.conf
[exchange-accountcredentials-1]
@@ -990,10 +992,10 @@ proxy such as nginx should be used. We strongly recommend to configure nginx
to use TLS.
The public URL that the exchange will be served under should
-be put in ``/etc/taler/conf.d/exchange-business.conf`` configuration file.
+be put in ``/etc/taler-exchange/conf.d/exchange-business.conf`` configuration file.
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-business.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-business.conf
[exchange]
BASE_URL = https://example.com/
@@ -1092,7 +1094,7 @@ base URL, run:
.. code-block:: shell-session
- [root@exchange-online]# export BASE_URL=$(taler-config -s exchange -o base_url)
+ [root@exchange-online]# export BASE_URL=$(taler-exchange-config -s exchange -o base_url)
[root@exchange-online]# wget ${BASE_URL}management/keys
The request might take some time to complete on slow machines, because
@@ -1415,10 +1417,12 @@ After enough time has passed, the money should arrive at the specified IBAN.
For more information on the taler-wallet-cli tool, see
:doc:`taler-wallet`.
-taler-config
-------------
+taler-exchange-config
+---------------------
+
+.. _Using_taler_exchange_config:
-.. _Using-taler_002dconfig-exchange:
+.. index:: taler-exchange-config
.. include:: frags/using-taler-config.rst
diff --git a/taler-kyc-manual.rst b/taler-kyc-manual.rst
@@ -198,7 +198,7 @@ section. The names of the configuration sections must being with
``kyc-proider-`` followed by an arbitrary ``$PROVIDER_ID``:
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-kyc-providers.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-kyc-providers.conf
[kyc-provider-$PROVIDER_ID]
@@ -221,7 +221,7 @@ credentials to be configured apriori to enable access to the legitimization
service. The OAuth 2.0 configuration options are:
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-oauth2.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-oauth2.conf
[kyc-provider-example-oauth2]
LOGIC = oauth2
@@ -264,7 +264,7 @@ as ``#`` is otherwise interpreted as the beginning of a comment by the
configuration file syntax.
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-challenger-oauth2.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-challenger-oauth2.conf
[kyc-provider-challenger-oauth2]
LOGIC = oauth2
@@ -296,7 +296,7 @@ configuration as shown above.
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-persona.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-persona.conf
[kyclogic-persona]
# Webhook authorization token. Global for all uses
@@ -349,7 +349,7 @@ KYCAID must be configured to use the ``/kyc-webhook/$SECTION_NAME/`` endpoint
of the exchange to notify the exchange about the completion of KYC processes.
.. code-block:: ini
- :caption: /etc/taler/conf.d/exchange-kycaid.conf
+ :caption: /etc/taler-exchange/conf.d/exchange-kycaid.conf
[kyc-provider-example-kycaid]
LOGIC = kycaid
@@ -899,7 +899,7 @@ The shipped implementation with of the exchange is installed in
.. code-block:: shell-session
- ${INSTALL_PREFIX}/share/taler/exchange/spa/forms.js
+ ${INSTALL_PREFIX}/share/taler-exchange/spa/forms.js
The variable ``form`` contains the list of all form available. For
@@ -976,7 +976,7 @@ The Exchange comes with various HTML templates that are shown to guide users
through the KYC process. The Exchange uses `C implementation of mustache
<https://gitlab.com/jobol/mustach>`__ as the templating engine. This section
describes the various templates. In general, the templates must be installed
-to the ``share/taler/exchange/templates/`` directory. The file names must be
+to the ``share/taler-exchange/templates/`` directory. The file names must be
of the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template
and ``$LANG`` is the 2-letter language code of the template. English templates
must exist and will be used as a fallback. If the browser (user-agent) has
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -410,15 +410,15 @@ libraries!
How to configure the merchant backend
=====================================
-.. index:: taler.conf
+.. index:: taler-merchant.conf
The installation already provides reasonable defaults for most of the
configuration options. However, some must be provided, in particular the
database that the backend should use. By default, the file
-``$HOME/.config/taler.conf`` is where the Web shop administrator specifies
+``$HOME/.config/taler-merchant.conf`` is where the Web shop administrator specifies
configuration values that augment or override the defaults.
Note that when using our binary packages, the systemd service files
-force the use of ``/etc/taler/taler.conf`` as the main configuration file.
+force the use of ``/etc/taler-merchant/taler-merchant.conf`` as the main configuration file.
.. include:: frags/configuration-format.rst
@@ -485,14 +485,14 @@ To run the Taler backend on TCP port 8888, use:
.. note::
If you need to change where the taler-merchant-httpd listens for requests,
- you should edit ``/etc/taler/merchant-overrides.conf``. By default, the
+ you should edit ``/etc/taler-merchant/merchant-overrides.conf``. By default, the
Taler merchant package will use a UNIX domain socket at
- ``/run/taler/merchant-httpd/merchant-http.sock``. For the best possible
+ ``/run/taler-merchant/merchant-httpd/merchant-http.sock``. For the best possible
security it is recommended to leave this in place and configure a reverse
proxy (Nginx or Apache) as described below.
When using the Debian/Ubuntu packages, the use of a UNIX domain socket
- is already pre-configured in the ``/etc/taler/conf.d/merchant.conf``
+ is already pre-configured in the ``/etc/taler-merchant/conf.d/merchant.conf``
configuration file. Suitable reverse proxy configuration
file templates (``taler-merchant``) are be installed in the
respective ``sites-available`` directories of Apache and Nginx.
@@ -522,10 +522,10 @@ value to ``KUDOS``:
.. note::
When using the Debian/Ubuntu packages, these options should be
- configured in the ``/etc/taler/taler.conf`` configuration file
- (alternatively, you can also edit ``/etc/taler/merchant-overrides.conf``).
- However, you must edit the ``taler.conf`` file manually and **must not**
- use ``taler-config`` to do this, as that would inline the include
+ configured in the ``/etc/taler-merchant/taler-merchant.conf`` configuration file
+ (alternatively, you can also edit ``/etc/taler-merchant/merchant-overrides.conf``).
+ However, you must edit the ``taler-merchant.conf`` file manually and **must not**
+ use ``taler-merchant-config`` to do this, as that would inline the include
directives and destroy the carefully setup path structure.
@@ -1115,7 +1115,7 @@ The installation process will install various HTML templates to be served to
trigger the wallet interaction. You may change those templates to your own
design. The templating language used is `C implementation of mustache
<https://gitlab.com/jobol/mustach>`__, and the templates are in the
-``share/taler/merchant/templates/`` directory.
+``share/taler-merchant/templates/`` directory.
The file names must be of the form ``$NAME.$LANG.must`` where ``$NAME`` is the
name of the template and ``$LANG`` is the 2-letter language code of the
@@ -1258,10 +1258,10 @@ processes, either via your systemd or init system, or directly.
Advanced topics
===============
-taler-config
-------------
+taler-merchant-config
+---------------------
-.. index:: taler-config
+.. index:: taler-merchant-config
.. include:: frags/using-taler-config.rst
