[taler-docs] branch master updated: improve documentation of taler.conf

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new ce15fc3  improve documentation of taler.conf
ce15fc3 is described below

commit ce15fc3472f93b3d213d220f6a144cf58a0b5706
Author: Christian Grothoff <christian@grothoff.org>
AuthorDate: Sun Jul 5 12:19:55 2020 +0200

    improve documentation of taler.conf
---
 manpages/taler.conf.5.rst | 161 ++++++++++++++++++++++------------------------
 1 file changed, 77 insertions(+), 84 deletions(-)

diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 82bff39..174587e 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -27,31 +27,31 @@ The following options are from the “[taler]” section and 
used by
 virtually all Taler components.
 
 CURRENCY
-   Name of the currency, i.e. “EUR” for Euro.
+  Name of the currency, i.e. “EUR” for Euro.
 
 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}.
+  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/”
+  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/”
+  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/”
+  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”.
+  Where should Taler store system runtime data (like UNIX domain
+  sockets). Usually “${TMP}/taler-system-runtime”.
 
 EXCHANGE OPTIONS
 ----------------
@@ -60,42 +60,42 @@ The following options are from the “[exchange]” section and 
used by most
 exchange tools.
 
 DB
-   Plugin to use for the database, i.e. “postgres”
+  Plugin to use for the database, i.e. “postgres”
 
 PORT
-   Port on which the HTTP server listens, i.e. 8080.
+  Port on which the HTTP server listens, i.e. 8080.
 
 MASTER_PUBLIC_KEY
-   Crockford Base32-encoded master public key, public version of the
-   exchange´s long-time offline signing key.
+  Crockford Base32-encoded master public key, public version of the
+  exchange´s long-time offline signing key.
 
 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).
+  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).
 
 BASE_URL
-   Specifies the base URL under which the exchange can be reached. Added
-   to wire transfers to enable tracking by merchants.
+  Specifies the base URL under which the exchange can be reached. Added
+  to wire transfers to enable tracking by merchants.
 
 AGGREGATOR_IDLE_SLEEP_INTERVAL
-   For how long should the aggregator sleep when it is idle before trying
-   to look for more work? Default is 60 seconds.
+  For how long should the aggregator sleep when it is idle before trying
+  to look for more work? Default is 60 seconds.
 
 SIGNKEY_DURATION
-   For how long is a signing key valid?
+  For how long is a signing key valid?
 
 LEGAL_DURATION
-   For how long are signatures with signing keys legally valid?
+  For how long are signatures with signing keys legally valid?
 
 LOOKAHEAD_SIGN
-   How long do we generate denomination and signing keys ahead of time?
+  How long do we generate denomination and signing keys ahead of time?
 
 LOOKAHEAD_PROVIDE
-   How long into the future do we provide signing and denomination keys
-   to clients?
+  How long into the future do we provide signing and denomination keys
+  to clients?
 
 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, i.e. "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" [...]
+  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, i.e. "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", [...]
    - $TERMS_DIR/en/0.pdf
    - $TERMS_DIR/en/0.html
    - $TERMS_DIR/en/0.txt
@@ -104,12 +104,12 @@ TERMS_DIR
    - $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 (i.e. 
spelling) fixes to the terms of service, the TERMS_ETAG probably SHOULD NOT be 
changed. However, whenever  [...]
+  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 (i.e. 
spelling) fixes to the terms of service, the TERMS_ETAG probably SHOULD NOT be 
changed. However, whenever u [...]
 
 PRIVACY_DIR
-   Works the same as TERMS_DIR, just for the privacy policy.
+  Works the same as TERMS_DIR, just for the privacy policy.
 PRIVACY_ETAG
-   Works the same as TERMS_ETAG, just for the privacy policy.
+  Works the same as TERMS_ETAG, just for the privacy policy.
 
 
 EXCHANGE DATABASE OPTIONS
@@ -118,17 +118,17 @@ EXCHANGE DATABASE OPTIONS
 The following options must be in the section "[exchangedb]".
 
 DURATION_OVERLAP
-   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.
+  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.
 
 IDLE_RESERVE_EXPIRATION_TIME
-   After which time period should reserves be closed if they are idle?
+  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?
+  After what time do we forget about (drained) reserves during garbage 
collection?
 
 
 EXCHANGE POSTGRES BACKEND DATABASE OPTIONS
@@ -138,8 +138,8 @@ The following options must be in section 
“[exchangedb-postgres]” if the
 “postgres” plugin was selected for the database.
 
 CONFIG
-   How to access the database, i.e. “postgres:///taler” to use the
-   “taler” database. Testcases use “talercheck”.
+  How to access the database, i.e. “postgres:///taler” to use the
+  “taler” database. Testcases use “talercheck”.
 
 
 EXCHANGE ACCOUNT OPTIONS
@@ -151,11 +151,20 @@ arbitrary and should be chosen to uniquely identify the 
bank account for
 the operator.
 
 PAYTO_URI
-   Specifies the payto://-URL of the account. The general format is
-   payto://METHOD/DETAILS.
+  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).
 
 WIRE_GATEWAY_URL
-  URL of the wire gateway
+  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)
@@ -168,38 +177,22 @@ PASSWORD
   Password for ``basic`` authentication with the wire gateway.
 
 WIRE_RESPONSE
-   Specifies the name of the file in which the /wire response for this
-   account should be located. Used by the Taler exchange service and the
-   taler-exchange-wire tool.
+  Specifies the name of the file in which the /wire response for this
+  account should be located. Used by the Taler exchange service and the
+  taler-exchange-wire tool.  Example:
+  ``${TALER_DATA_HOME}/exchange/wire-sigs/SOMETHING.json``.  Note that
+  the file names must differ between all of the exchange bank accounts.
+  It is suggested to use the section name for ``SOMETHING`` to ensure
+  uniqueness.
 
 ENABLE_DEBIT
-   Must be set to YES for the accounts that the
-   taler-exchange-aggregator should debit. Not used by merchants.
+  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.
-
-
-TALER-BANK AUTHENTICATION OPTIONS (for accounts)
-------------------------------------------------
-
-The following authentication options are supported by the “taler-bank”
-wire plugin. They must be specified in the “[account-]” section that
-uses the “taler-bank” plugin.
-
-TALER_BANK_AUTH_METHOD
-   Authentication method to use. “none” or “basic” are currently
-   supported.
-
-USERNAME
-   Username to use for authentication. Used with the “basic”
-   authentication method.
-
-PASSWORD
-   Password to use for authentication. Used with the “basic”
-   authentication method.
+  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.
 
 
 EXCHANGE WIRE FEE OPTIONS
@@ -214,13 +207,13 @@ the fee should apply. Usually, fees should be given for 
several years
 in advance.
 
 WIRE-FEE-YEAR
-   Aggregate wire transfer fee merchants are charged in YEAR. Specified
-   as a Taler amount using the usual amount syntax
-   (CURRENCY:VALUE.FRACTION).
+  Aggregate wire transfer fee merchants are charged in YEAR. Specified
+  as a Taler amount using the usual amount syntax
+  (CURRENCY:VALUE.FRACTION).
 
 CLOSING-FEE-YEAR
-   Reserve closing fee customers are charged in YEAR. Specified as a
-   Taler amount using the usual amount syntax (CURRENCY:VALUE.FRACTION).
+  Reserve closing fee customers are charged in YEAR. Specified as a
+  Taler amount using the usual amount syntax (CURRENCY:VALUE.FRACTION).
 
 EXCHANGE COIN OPTIONS
 ---------------------
@@ -329,15 +322,15 @@ $NAME is a merchant-given name for the auditor. The 
following options
 must be given in each “[merchant-auditor-$NAME]” section.
 
 AUDITOR_BASE_URL
-   Base URL of the auditor, i.e. “https://auditor.demo.taler.net/”
+  Base URL of the auditor, i.e. “https://auditor.demo.taler.net/”
 
 AUDITOR_KEY
-   Crockford Base32 encoded auditor public key.
+  Crockford Base32 encoded auditor public key.
 
 CURRENCY
-   Name of the currency for which this auditor is trusted, i.e. “KUDOS”
-   The entire section is ignored if the currency does not match the currency
-   we use, which must be given in the [taler] section.
+  Name of the currency for which this auditor is trusted, i.e. “KUDOS”
+  The entire section is ignored if the currency does not match the currency
+  we use, which must be given in the [taler] section.
 
 
 AUDITOR OPTIONS
@@ -347,10 +340,10 @@ The following options must be in section “[auditor]” for 
the Taler
 auditor.
 
 DB
-   Plugin to use for the database, i.e. “postgres”
+  Plugin to use for the database, i.e. “postgres”
 
 AUDITOR_PRIV_FILE
-   Name of the file containing the auditor’s private key
+  Name of the file containing the auditor’s private key
 
 
 AUDITOR POSTGRES BACKEND DATABASE OPTIONS
@@ -360,8 +353,8 @@ The following options must be in section 
“[auditordb-postgres]” if the
 “postgres” plugin was selected for the database.
 
 CONFIG
-   How to access the database, i.e. "postgres:///taler" to use the
-   "taler" database. Testcases use “talercheck”.
+  How to access the database, i.e. "postgres:///taler" to use the
+  "taler" database. Testcases use “talercheck”.
 
 
 SEE ALSO

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.