diff options
Diffstat (limited to 'manpages/libeufin-nexus.conf.5.rst')
-rw-r--r-- | manpages/libeufin-nexus.conf.5.rst | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst new file mode 100644 index 00000000..8aabe883 --- /dev/null +++ b/manpages/libeufin-nexus.conf.5.rst @@ -0,0 +1,244 @@ +libeufin-nexus.conf(5) +###################### + +.. only:: html + + Name + ==== + + **libeufin-nexus.conf** - LibEuFin Nexus configuration file + + +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. + +Durations must be expressed with a number followed by the time unit. The following +time units are supported: 's' (seconds), 'm' (minutes), 'h' (hours). For example, +the value *5m* denotes a duration of *five minutes*. + +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 +<https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_. 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_PREFIX/share/libeufin-nexus/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 +-------------- + +Setting the database belongs to the “[nexus-postgres]” section and the +following value. + +CONFIG + PostgreSQL connection string. Note: this option is NOT used by the + ebics-setup subcommand, as it stores the key files directly on the + filesystem. + +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: + +LIBEUFIN_HOME + Home directory of the user, usually “${HOME}”. Can be overwritten by + testcases by setting ${LIBEUFIN_TEST_HOME}. + +EBICS SETUP OPTIONS +------------------- + +The following options are from the “[nexus-ebics]” section and used by +the ``libeufin-nexus ebics-setup`` command. + +CURRENCY + Name of the currency, e.g. “EUR” for Euro. + +HOST_BASE_URL + URL of the EBICS server + +BANK_DIALECT + Name of the following combination: EBICS version and ISO20022 recommendations + that Nexus would honor in the communication with the bank. Currently only the + ``postfinance`` or ``gls`` value is supported. + +HOST_ID + EBICS specific: name of the EBICS host + +USER_ID + EBICS specific: user ID of the EBICS subscriber. This value must be assigned + by the bank after having activated a new EBICS subscriber. + +PARTNER_ID + EBICS specific: partner ID of the EBICS subscriber. This value must be assigned + by the bank after having activated a new EBICS subscriber. + +BANK_PUBLIC_KEYS_FILE + Filesystem location where Nexus should store the bank public keys. + +CLIENT_PRIVATE_KEYS_FILE + Filesystem location where Nexus should store the subscriber private keys. + +IBAN + IBAN of the bank account that is associated with the EBICS subscriber. + +BIC + BIC of the bank account that is associated with the EBICS subscriber. + +NAME + Legal entity that is associated with the EBICS subscriber. + + +EBICS SUBMIT OPTIONS +-------------------- + +The following configuration value(s) belong to the “[nexus-submit]” section. + +FREQUENCY + Duration value to instruct the ``ebics-submit`` subcommand how much to wait + before checking the database again to find new unsubmitted payments. + +EBICS FETCH OPTIONS +------------------- + +The following configuration value(s) belong to the “[nexus-fetch]” section. + +FREQUENCY + Duration value to instruct the ``ebics-fetch`` subcommand how often it should + download from the bank. + +IGNORE_TRANSACTIONS_BEFORE + Ignore all transactions before a certain YYYY-MM-DD date, useful when you want to use an existing account with old transactions that should not be bounced. + +HTTP SERVER OPTIONS +------------------- + +The following configuration value(s) belong to the “[nexus-httpd]” section. + +SERVE + This can either be ``tcp`` or ``unix``. + +PORT + Port on which the HTTP server listens, e.g. 9967. + Only used if ``SERVE`` is ``tcp``. + +BIND_TO + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname. + Only used if ``SERVE`` is ``tcp``. + +UNIXPATH + Which unix domain path should we bind to? + Only used if ``SERVE`` is ``unix``. + +UNIXPATH_MODE + What should be the file access permissions for ``UNIXPATH``? + Only used if ``SERVE`` is ``unix``. + +HTTP WIRE GATEWAY API OPTIONS +----------------------------- + +The following configuration value(s) belong to the “[nexus-httpd-wire-gateway-api]” section. + +ENABLED + Whether to serve the Wire Gateway API. + +AUTH_METHOD + How to authenticate this API. This can either be ``none`` or ``bearer-token``. + +AUTH_BEARER_TOKEN + The expected token. + Only used if ``AUTH_METHOD`` is ``bearer-token``. + +HTTP REVENUE API OPTIONS +------------------------ + +The following configuration value(s) belong to the “[nexus-httpd-revenue-api]” section. + +ENABLED + Whether to serve the Revenue API. + +AUTH_METHOD + How to authenticate this API. This can either be ``none`` or ``bearer-token``. + +AUTH_BEARER_TOKEN + The expected token. + Only used if ``AUTH_METHOD`` is ``bearer-token``. + +DATABASE OPTIONS +---------------- + +Setting the database belongs to the “[libeufin-nexusdb-postgres]” section and the following value. + +CONFIG + PostgreSQL connection string. + +SQL_DIR + Where are the SQL files to setup our tables? + +SEE ALSO +======== + +libeufin-nexus(1) + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. |