commit 02e476a9c03370a4087d9f92161b97b8d0e37790
parent d25e142db980b0dffbe5ec27d3edd3be02dd4e5a
Author: Antoine A <>
Date: Mon, 22 Jul 2024 17:43:46 +0200
libeufin: update documentation
Diffstat:
6 files changed, 57 insertions(+), 141 deletions(-)
diff --git a/frags/libeufin-config-cli.rst b/frags/libeufin-config-cli.rst
@@ -17,7 +17,7 @@ It takes two arguments, the section name and the option name
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -31,7 +31,7 @@ This command dump the configuration.
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -45,7 +45,7 @@ It takes one argument, a path expression.
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst
@@ -178,7 +178,6 @@ Once this is done, you can start the libeufin-bank HTTP server:
$ libeufin-bank serve -c "$CONFIG_FILE"
-
Using the bank Web interface
============================
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -87,11 +87,6 @@ be found in the $PATH.
.. _ebics-setup:
-Setting up the EBICS subscriber
-===============================
-
-.. include:: ../frags/nexus-ebics-setup.rst
-
Database setup
==============
@@ -102,7 +97,7 @@ is:
.. code-block:: ini
[libeufin-nexusdb-postgres]
- config = postgres:///nexus
+ config = postgres:///libeufin
You must make sure that this database exists and is accessible to the user
running Nexus before continuing. Then, the Nexus database schema must be
@@ -115,6 +110,11 @@ created (or updated) to the current Nexus version using the following command:
where ``$CONFIG_FILE`` is again the path to a configuration that contains at
least the above ``[libeufin-nexusdb-postgres]`` section.
+Setting up the EBICS subscriber
+===============================
+
+.. include:: ../frags/nexus-ebics-setup.rst
+
.. _sending-payments:
Sending payments
@@ -241,19 +241,11 @@ The ``ebics-fetch`` subcommand will always cause libeufin-nexus to download
then parse EBICS files and ingest their content statements into its local
database.
-The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported:
-
-* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders.
-* ``status``: Payment status, retrieves status of pending debits.
-* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits.
-
The ``--transient`` flag makes the command download and import EBICS files only
once and return immediately afterwards. Without the flag, Nexus
will download at the frequency specified in the configuration.
-The ``--debug-ebics $SAVEDIR`` flag will cause the files to be stored in
-``$SAVEDIR/$YYYY-MM-DD/fetch`` where ``$YYYY-MM-DD`` represents the
-date when the download took place. This is mostly useful for debugging.
+The ``--debug-ebics $SAVEDIR`` flag will cause EBICS transactions steps and payloads to be stored in ``$SAVEDIR`` where ``$YYYY-MM-DD`` represents the date when the download took place. This is mostly useful for debugging.
For Testing
diff --git a/manpages/libeufin-bank.1.rst b/manpages/libeufin-bank.1.rst
@@ -56,7 +56,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -73,7 +73,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -87,7 +87,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -124,7 +124,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -152,7 +152,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
@@ -166,7 +166,7 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst
@@ -49,16 +49,18 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
**--force-keys-resubmission**
- Resubmits the client keys. If no keys were found, it creates and submits them.
+ Resubmits all the keys to the bank.
**--auto-accept-keys**
Accepts the bank keys without interactively asking the user.
**--generate-registration-pdf**
Generates the PDF with the client keys fingerprints, if the keys have the submitted state. That's useful in case the PDF went lost after the first submission and the user needs a new PDF.
+**--debug-ebics**
+ Log EBICS transactions steps and payload at log_dir.
dbinit
@@ -70,58 +72,55 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
**-r** \| **--reset**
- If present, deletes any database table (WARNING: potential data loss)
+ Reset database (DANGEROUS: All existing data is lost)
ebics-submit
------------
-This subcommand submits any initiated payment that was not already sent to the bank. In the current version, initiated payments may come from a cash-out operation or from a bounced incoming payment. ebics-submit is Taler friendly, therefore bounced payments are those that do not contain a valid subject to start a Taler withdrawal. Cash-out operations come from a tightly integrated bank that offers their customers to convert their currency to the currency whose the EBICS subscriber bank account is tied to.
+This subcommand submits EBICS files to the bank. It submits pending outgoing payments. Outgoing payment status is fetched by ebics-fetch.
+
+Submits are executed at 'FREQUENCY'.
Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
- Uploaded documents will be stored *before* being submitted to the bank. This directory would contain several directories, each named after the ``YYYY-MM-DD/submit`` format. The pain.001 file would then be named in the following schema: ``$microseconds_pain.001.xml``.
**--transient**
- This flag causes the command to check the database and submit only once, and then return.
-
+ Execute once and return, ignoring the 'FREQUENCY' configuration value.
+**--debug-ebics**
+ Log EBICS transactions steps and payload at log_dir.
ebics-fetch
-----------
-This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics-submit would as well reconcile initiated outgoing payments with any outgoing transactions that show up in the downloaded records.
+This subcommand fetches EBICS files from the bank. Incoming payments are recorded and the status of outgoing payments is updated.
-The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported:
+If ACCOUNT_TYPE is ``exchange``, incoming payments with an invalid Taler subject are bounced. Bounces are submitted by ebics-submit.
-* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders.
-* ``status``: Payment status, retrieves status of pending debits.
-* ``report``: Account intraday reports, retrieves the history of confirmed debits and credits.
-* ``statement``: Account statements, retrieves the history of confirmed debits and credits.
-* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits.
+Fetches are executed at 'FREQUENCY'.
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
-**--debug-ebics** *SAVEDIR*
- Log EBICS content at SAVEDIR.
- Downloaded documents will be stored *before* being ingested in the database. This directory would contain several directories, each named after the ``YYYY-MM-DD/fetch`` format. The stored files would then be named after the following schema: ``$microseconds_$filename``. Exception to this naming scheme are the HAC responses, since they do not get any filename assigned by the ZIP archive (they are sent unzipped). Their naming scheme is: ``$microseconds_HAC_response.pain.002.xml``.
+**--debug-ebics**
+ Log EBICS transactions steps and payload at log_dir.
**--transient**
- This flag causes the command to perform one download and return.
-**--pinned-start**
- Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents. The latest timestamp is always the current time.
+ Execute once and return, ignoring the 'FREQUENCY' configuration value.
+**--pinned-start** *YYYY-MM-DD*
+ Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents.
serve
-----
@@ -132,12 +131,12 @@ Its options are as follows:
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
**--check**
- This flag causes the command to check whether an API is in use (if it's useful to start the HTTP server) and to output 0 if at least one API is enabled, otherwise 1.
+ Check whether an API is in use (if it's useful to start the HTTP server). Exit with 0 if at least one API is enabled, otherwise 1.
initiate-payment
----------------
@@ -148,7 +147,7 @@ It takes one argument, the creditor IBAN payto URI, which must contain a 'receiv
**-h** \| **--help**
Print short help on options.
-**-c** \| **--config** *FILENAME*
+**-c** \| **--config** *config_file*
Specifies the configuration file.
**-L** \| **--log** *LOGLEVEL*
Configure logging to use LOGLEVEL.
diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst
@@ -12,63 +12,7 @@ libeufin-nexus.conf(5)
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.
+.. include:: ../frags/common-conf-syntax.rst
Files containing default values for many of the options described below
are installed under ``$TALER_PREFIX/share/libeufin-nexus/config.d/``.
@@ -83,30 +27,10 @@ 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
+EBICS OPTIONS
--------------
-Setting the database belongs to the “[libeufin-nexusdb-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.
+The following options are from the “[nexus-ebics]” section.
CURRENCY
Name of the currency, e.g. “EUR” for Euro.
@@ -114,11 +38,6 @@ CURRENCY
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
@@ -130,12 +49,6 @@ 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.
@@ -145,6 +58,19 @@ BIC
NAME
Legal entity that is associated with the 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.
+
+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.
+
+ACCOUNT_TYPE
+ Specify the account type and therefore the indexing behavior. This can either can be ``normal`` or ``exchange``. Exchange accounts bounce invalid incoming Taler transactions.
EBICS SUBMIT OPTIONS
--------------------
