diff options
Diffstat (limited to 'manpages/taler.conf.5.rst')
-rw-r--r-- | manpages/taler.conf.5.rst | 364 |
1 files changed, 364 insertions, 0 deletions
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst new file mode 100644 index 00000000..853f05c6 --- /dev/null +++ b/manpages/taler.conf.5.rst @@ -0,0 +1,364 @@ +taler.conf(5) +############# + +.. only:: html + + Name + ==== + + **taler.conf** - Taler configuration file + + +Description +=========== + +The basic structure of the configuration file is the following. The file +is split into sections. Every section begins with “[SECTIONNAME]” and +contains a number of options of the form “OPTION=VALUE”. Empty lines and +lines beginning with a “#” are treated as comments. 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. + +Global Options +-------------- + +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. + +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”. + +EXCHANGE OPTIONS +---------------- + +The following options are from the “[exchange]” section and used by most +exchange tools. + +DB + Plugin to use for the database, i.e. “postgres” + +PORT + 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. + +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). + +BASE_URL + Specifies the base URL under which the exchange can be reached. Added + to wire transfers to enable tracking by merchants. + +SIGNKEY_DURATION + For how long is a signing key valid? + +LEGAL_DURATION + For how long are signatures with signing keys legally valid? + +LOOKAHEAD_SIGN + 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? + +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, i.e. “postgres:///taler” to use the + “taler” database. Testcases use “talercheck”. + +MERCHANT OPTIONS +---------------- + +The following options are from the “[merchant]” section and used by the +merchant backend. + +DB + Plugin to use for the database, i.e. “postgres” + +PORT + Port on which the HTTP server listens, i.e. 8080. + +WIRE_TRANSFER_DELAY + How quickly do we want the exchange to send us money? Note that wire + transfer fees will be higher if we ask for money to be wired often. + Given as a relative time, i.e. “5 s” + +DEFAULT_MAX_WIRE_FEE + Maximum wire fee we are willing to accept from exchanges. Given as a + Taler amount, i.e. “EUR:0.1” + +DEFAULT_MAX_DEPOSIT_FEE + Maximum deposit fee we are willing to cover. Given as a Taler amount, + i.e. “EUR:0.1” + +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, i.e. “postgres:///taler” to use the + “taler” database. Testcases use “talercheck”. + +MERCHANT INSTANCES +------------------ + +The merchant configuration must specify a set of instances, containing +at least the “default” instance. The following options must be given in +each “[instance-NAME]” section. + +KEYFILE + Name of the file where the instance´s private key is to be stored, + i.e. “${TALER_CONFIG_HOME}/merchant/instance/name.priv” + +NAME + Human-readable name of the instance, i.e. “Kudos Inc.” + +Additionally, for instances that support tipping, the following options +are required. + +TIP_EXCHANGE + Base-URL of the exchange that holds the reserve for tipping, + i.e. “https://exchange.demo.taler.net/” + +TIP_EXCHANGE_PRIV_FILENAME + Filename with the private key granting access to the reserve, + i.e. “${TALER_CONFIG_HOME}/merchant/reserve/tip.priv” + +KNOWN EXCHANGES (for merchants and wallets) +------------------------------------------- + +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 [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. + +BASE_URL + Base URL of the exchange, i.e. “https://exchange.demo.taler.net/” + +MASTER_KEY + Crockford Base32 encoded master public key, public version of the + exchange´s long-time offline signing key + +CURRENCY + Name of the currency for which this exchange is trusted, i.e. “KUDOS” + +KNOWN AUDITORS (for merchants and wallets) +------------------------------------------ + +The merchant configuration can include a list of known exchanges if the +merchant wants to specify that certain auditors are explicitly trusted. +For each trusted exchange, a section [auditor-NAME] must exist, where +NAME is a merchant-given name for the exchange. The following options +must be given in each “[auditor-NAME]” section. + +BASE_URL + Base URL of the auditor, i.e. “https://auditor.demo.taler.net/” + +AUDITOR_KEY + Crockford Base32 encoded auditor public key. + +CURRENCY + Name of the currency for which this auditor is trusted, i.e. “KUDOS” + +ACCOUNT OPTIONS (for exchanges and merchants) +--------------------------------------------- + +An exchange (or merchant) can have multiple bank accounts. The following +options are for sections named “[account-SOMETHING]”. The SOMETHING is +arbitrary and should be chosen to uniquely identify the bank account for +the operator. Additional authentication options may need to be specified +in the account section depending on the PLUGIN used. + +URL + Specifies the payto://-URL of the account. The general format is + payto://METHOD/DETAILS. This option is used for exchanges and + merchants. + +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 and the taler-merchant-httpd (to generate + the files). + +PLUGIN + Name of the plugin can be used to access the account + (i.e. “taler-bank” or “ebics”). Used by the merchant backend for back + office operations (i.e. to identify incoming wire transfers) and by + the exchange. + +ENABLE_DEBIT + Must be set to YES for the accounts that the + taler-exchange-aggregator should debit. Not used by merchants. + +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. + +HONOR_instance + Must be set to YES for the instances (where “instance” is the section + name of the instance) of the merchant backend that should allow + incoming wire transfers for this bank account. + +ACTIVE_instance + Must be set to YES for the instances (where “instance” is the section + name of the instance) of the merchant backend that should use this + bank account in new offers/contracts. Setting ACTIVE_instance to YES + requires also setting ENABLE_instance to YES. + +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. + +EBICS AUTHENTICATION OPTIONS +---------------------------- + +The following authentication options are supported by the “ebics” wire +plugin. They must be specified in the “[account-]” section that uses the +“ebics” plugin. + +NONE + Currently the “ebics” implementation is incomplete and does not + support authentication. + +EXCHANGE WIRE FEE OPTIONS +------------------------- + +For each supported wire method (i.e. “x-taler-bank” or “sepa”), sections +named “[fees-METHOD]” state the (aggregate) wire transfer fee and the +reserve closing fees charged by the exchange. Note that fees are +specified using the name of the wire method, not by the plugin name. You +need to replace “YEAR” in the option name by the calendar year for which +the fee should apply. Usually, fees should be given for serveral 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). + +CLOSING-FEE-YEAR + Reserve closing fee customers are charged in YEAR. Specified as a + Taler amount using the usual amount syntax (CURRENCY:VALUE.FRACTION). + +EXCHANGE COIN OPTIONS +--------------------- + +The following options must be in sections starting with ``"[coin_]"`` and +are used by taler-exchange-keyup to create denomination keys. + +VALUE + Value of the coin, i.e. “EUR:1.50” for 1 Euro and 50 Cents (per + coin). + +DURATION_OVERLAP + How much should validity periods for these coins overlap? + +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? + +FEE_WITHDRAW + What fee is charged for withdrawl? + +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. + +RSA_KEYSIZE + What is the RSA keysize modulos (in bits)? + +AUDITOR OPTIONS +--------------- + +The following options must be in section “[auditor]” for the Taler +auditor. + +DB + Plugin to use for the database, i.e. “postgres” + +AUDITOR_PRIV_FILE + Name of the file containing the auditor’s private key + +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, i.e. "postgres:///taler" to use the + "taler" database. Testcases use “talercheck”. + +SEE ALSO +======== + +taler-exchange-dbinit(1), taler-exchange-httpd(1), +taler-exchange-keyup(1), taler-exchange-wire(1). + +BUGS +==== + +Report bugs by using https://gnunet.org/bugs/ or by sending electronic +mail to <taler@gnu.org>. |