summaryrefslogtreecommitdiff
path: root/manpages/taler.conf.5.rst
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2020-07-05 12:19:55 +0200
committerChristian Grothoff <christian@grothoff.org>2020-07-05 12:19:55 +0200
commitce15fc3472f93b3d213d220f6a144cf58a0b5706 (patch)
tree1f6f75e30a6cdc887f1b9f655ab2a7745e59dbb9 /manpages/taler.conf.5.rst
parentec491ae8d7fe7444db68a8a4683c3dcafb994b3c (diff)
downloaddocs-ce15fc3472f93b3d213d220f6a144cf58a0b5706.tar.gz
docs-ce15fc3472f93b3d213d220f6a144cf58a0b5706.tar.bz2
docs-ce15fc3472f93b3d213d220f6a144cf58a0b5706.zip
improve documentation of taler.conf
Diffstat (limited to 'manpages/taler.conf.5.rst')
-rw-r--r--manpages/taler.conf.5.rst161
1 files changed, 77 insertions, 84 deletions
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index 82bff393..174587ed 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", "jpg", "jpeg", "png" and "gif". For example, using a TERMS_ETAG of "0", the structure could be the following:
+ 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", "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
@@ -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 users must approve the new terms, the TERMS_ETAG MUST change.
+ 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 users must approve the new terms, the TERMS_ETAG MUST change.
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