Contents

16.75. taler-merchant.conf(5)

16.75.1. Name

taler-merchant.conf - Taler configuration file

16.75.2. Description

The configuration file is line-oriented. Blank lines and whitespace at the beginning and end of a line are ignored. Comments start with # or % in the first column (after any beginning-of-line whitespace) and go to the end of the line.

The file is split into sections. Every section begins with [SECTIONNAME] and contains a number of options of the form OPTION=VALUE. There may be whitespace around the = (equal sign). Section names and options are case-insensitive.

The values, however, are case-sensitive. In particular, boolean values are one of YES or NO. Values can include whitespace by surrounding the entire value with " (double quote). Note, however, that there are no escape characters in such strings; all characters between the double quotes (including other double quotes) are taken verbatim.

Values that represent a time duration are represented as a series of one or more NUMBER UNIT pairs, e.g. 60 s, 4 weeks 1 day, 5 years 2 minutes.

Values that represent an amount are in the usual amount syntax: CURRENCY:VALUE.FRACTION, e.g. EUR:1.50. The FRACTION portion may extend up to 8 places.

Values that represent filenames can begin with a /bin/sh-like variable reference. This can be simple, such as $TMPDIR/foo, or complex, such as ${TMPDIR:-${TMP:-/tmp}}/foo. The variables are expanded either using key-values from the [PATHS] section (see below) or from the environment (getenv()). The values from [PATHS] take precedence over those from the environment. If the variable name is found in neither [PATHS] nor the environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if FOO=$BAR and BAR=buzz then the result is FOO=buzz. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if BAR=$FOO in the example above.

The [PATHS] section is special in that it contains paths that can be referenced using $ in other configuration values that specify filenames. Note that configuration options that are not specifically retrieved by the application as filenames will not see “$”-expressions expanded. To expand $-expressions when using taler-config, you must pass the -f command-line option.

The system automatically pre-populates the [PATHS] section with a few values at run-time (in addition to the values that are in the actual configuration file and automatically overwriting those values if they are present). These automatically generated values refer to installation properties from GNU autoconf. The values are usually dependent on an INSTALL_PREFIX which is determined by the --prefix option given to configure. The canonical values are:

  • LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/

  • DOCDIR = $INSTALL_PREFIX/share/doc/taler/

  • ICONDIR = $INSTALL_PREFIX/share/icons/

  • LOCALEDIR = $INSTALL_PREFIX/share/locale/

  • PREFIX = $INSTALL_PREFIX/

  • BINDIR = $INSTALL_PREFIX/bin/

  • LIBDIR = $INSTALL_PREFIX/lib/taler/

  • DATADIR = $INSTALL_PREFIX/share/taler/

Note that on some platforms, the given paths may differ depending on how the system was compiled or installed, the above are just the canonical locations of the various resources. These automatically generated values are never written to disk.

Files containing default values for many of the options described below are installed under $TALER_MERCHANT_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!

16.75.2.1. 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”.

16.75.2.2. 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).

16.75.2.3. 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).

16.75.2.4. 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.

16.75.2.5. 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”.

16.75.2.6. 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.

16.75.3. SEE ALSO

taler-merchant-passwd(1), taler-merchant-httpd(1)

16.75.4. BUGS

Report bugs by using https://bugs.taler.net/ or by sending electronic mail to <taler@gnu.org>.

previous

16.74. taler-merchant-wirewatch(1)

next

16.76. taler-terms-generator(1)