commit b05de7c2269594fa60e9ffe20b2303581d90d52d
parent 794201a4f098e778cb9dd48ac6e3bc5d17844d0d
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 2 Feb 2024 13:13:07 +0100
work on nexus-manual
Diffstat:
3 files changed, 117 insertions(+), 106 deletions(-)
diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst
@@ -1,52 +0,0 @@
-When you sign up for an EBICS-enabled bank account, the bank will provide you
-with various credentials. Those must be provided in the
-``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the
-name of the *fiat* currency.
-
-The following snippet shows the mandatory configuration values:
-
-.. _core-config:
-
-.. code-block:: console
-
- [nexus-ebics]
- CURRENCY = CHF
-
- # Bank
- HOST_BASE_URL = http://bank.example.com/
- BANK_DIALECT = postfinance
-
- # EBICS IDs
- HOST_ID = mybank
- USER_ID = myuser
- PARTNER_ID = myorg
-
- # Account information
- IBAN = myiban
- BIC = mybic
- NAME = myname
-
-.. note::
- Refer to the manpage ``libeufin-nexus.conf(5)``
- for the full array of configuration values.
-
-.. note::
- If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the commands.
-
-Assuming that the configuration file exists at ``$config_file``, the following command would start the EBICS setup process.
-
-.. code-block:: console
-
- libeufin-nexus ebics-setup -c $config_file
-
-If the previous command failed when running EBICS INI with an error code ``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to activate your account.
-
-To that purpose, the previous run should have left a PDF document that you can print, sign and send to the bank. Look for the message that looks like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``.
-
-Once the bank has received and approved this printed documents, run the same command again to download and accept the bank keys.
-
-.. code-block:: console
-
- libeufin-nexus ebics-setup -c $config_file
-
-The setup is considered finished once the bank keys are accepted.
-\ No newline at end of file
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -1,6 +1,6 @@
..
This file is part of GNU TALER.
- Copyright (C) 2014-2023 Taler Systems SA
+ Copyright (C) 2014-2024 Taler Systems SA
TALER is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
@@ -26,13 +26,18 @@ Nexus Manual
.. contents:: Table of Contents
-LibEuFin Nexus is an EBICS facilitator. It offers a command line
-interface to setup EBICS access, download banking records, and submit payments.
-Future versions will offer a Web API to allow Taler Exchanges to talk to their
+LibEuFin Nexus is an EBICS facilitator. It offers a command line interface to
+setup EBICS access, download banking records, and submit payments. Today, the
+LibEuFin implementation supports EBICS 2.5 and 3.0 and has been tested with
+the Postfinance (CHF). Please note that banks tend to have their own dialects
+of finance messages and thus other retail banks may or may not work. Contact
+us if you need support for another bank or core banking protocol.
+
+Future versions will offer a Web API to allow Taler exchanges to talk to their
banks.
In this manual, we explain how to setup an EBICS subscriber. We assume that
-the bank had already granted EBICS access to the subscriber.
+the bank has already granted EBICS access to the subscriber.
Installing Nexus
================
@@ -66,26 +71,105 @@ be found in the $PATH.
Setting up the EBICS subscriber
===============================
-.. include:: ../frags/ebics-setup.rst
+When you sign up for an EBICS-enabled bank account, the bank will provide you
+with various credentials. Those must be provided in the
+``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the
+name of the *fiat* currency.
-Sending payments
-================
+The following snippet shows the mandatory configuration values:
+
+.. _core-config:
+
+.. code-block:: ini
+
+ [nexus-ebics]
+ CURRENCY = CHF
+
+ # Bank
+ HOST_BASE_URL = http://bank.example.com/
+ BANK_DIALECT = postfinance
+
+ # EBICS IDs
+ HOST_ID = mybank
+ USER_ID = myuser
+ PARTNER_ID = myorg
+
+ # Account information
+ IBAN = myiban
+ BIC = mybic
+ NAME = myname
+
+.. note::
+ Refer to the manpage ``libeufin-nexus.conf(5)``
+ for the full array of configuration values.
+
+.. note::
+ If you want to use existing client keys, copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` by default) before running the following commands.
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command should start the EBICS setup process:
+
+.. code-block:: console
+
+ $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+If the previous command failed when running EBICS INI with an error code of
+``EBICS_INVALID_USER_STATE``, you need to confirm your keys to your bank to
+activate your account.
+
+To that end, the previous run should have left a PDF document that you can
+print, sign and send to the bank. Look for the message that looks like ``PDF
+file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``.
+
+Once the bank has received and processed this document, run the same
+command again to download and verify the bank's keys:
-Sending payments must follow a successful `EBICS subscriber setup <ebics-setup>`_,
-where the bank obtained the subscriber keys, and the subscriber accepted the
-bank keys. The responsible subcommand for sending payments is ``ebics-submit``,
-and its configuration is a **superset** of core-config_. On top of that, it
-expects the database connection string, and *optionally* a frequency to check
-for submittable payments in the database.
+.. code-block:: console
+
+ $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+The EBICS setup is finished once the bank keys have been accepted.
-The connection string is specified as
+
+Database setup
+==============
+
+The configuration file must include a connection string that
+tells Nexus how it should connect to the database. The default
+is:
.. code-block:: ini
[nexus-postgres]
-
config = postgres:///nexus
+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
+created (or updated) to the current Nexus version using the following command:
+
+.. code-block:: console
+
+ $ libeufin-nexus-dbinit -c "$CONFIG_FILE"
+
+where ``$CONFIG_FILE`` is again the path to a configuration that contains at
+least the above ``[nexus-postgres]`` section.
+
+
+Sending payments
+================
+
+Sending payments must follow a successful `EBICS subscriber setup
+<ebics-setup>`_, where the bank obtained the subscriber keys, and the
+subscriber accepted the bank keys. Furthermore, the database has to
+be set up. Right now, some other process must queue payments to be
+submitted to the database, so this section only discusses how such
+queued payments will be executed.
+
+The responsible subcommand for sending payments is ``ebics-submit``, and its
+configuration is a **superset** of core-config_. On top of that, it expects
+the database connection string and *optionally* a frequency at which it will
+check for submittable payments in the database.
+
The frequency **may** be specified as
.. code-block:: ini
@@ -95,40 +179,31 @@ The frequency **may** be specified as
The supported time units are ``s`` (seconds), ``m`` (minutes), ``h`` (hours).
-Before delving into the following sections, the database schema must be
-created, therefore run the following command:
-
-.. code-block:: console
-
- $ libeufin-nexus dbinit -c $config_file
-
-Where ``$config_file`` is the path to a configuration path that contains at
-least the ``[nexus-postgres]`` section.
For testing
-----------
The ``ebics-submit`` subcommand is **not** suitable to send arbitrary
-payments, but rather to submit initiated payments that may be found
-in the database.
+payments, but rather to submit initiated payments that are already queued for
+submission in the Nexus database.
-Such initiated payments may be refunds of incoming payments with a subject
-that would be invalid for a Taler withdrawal, or from a Taler exchange in
-the attempt to pay a merchant.
+Such queued payments may originate from bounces of incoming payments with a
+subject that would be invalid for a Taler withdrawal, or from a Taler exchange
+that needs to send a payment to a merchant.
-For testing purposes, however, it is possible to artificially initiate
-a payment into the database with the ``contrib/payment_initiation_debug.sh``
-script, found in the libeufin repository. The script pays always one Swiss
-Franc to an IBAN and subject pair of choice.
+For testing purposes it is possible to manually initiate a payment using the
+``contrib/payment_initiation_debug.sh`` script from the libeufin repository.
+The script currently always pays one Swiss Franc to the given IBAN and
+wire transfer subject given as arguments.
The following invocation pays 1 CHF to the CH987654321 with an "Hello, Nexus!"
-subject.
+subject:
.. code-block:: console
- $ ./payment_initiation_debug.sh $config_file CH987654321 "Hello, Nexus!"
+ $ ./payment_initiation_debug.sh "$CONFIG_FILE" CH987654321 "Hello, Nexus!"
-``$config_file`` is the path to Nexus' configuration file and it does not need
+``$CONFIG_FILE`` is the path to Nexus' configuration file and it does not need
the FREQUENCY value. If the previous command worked, now the database should
contain a new row in the ``initiated_outgoing_transactions`` table, with an
``unsubmitted`` submission state.
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
@@ -161,22 +161,11 @@ Nexus to communicate with the fiat bank account that backs the regional currency
Prerequisites
+++++++++++++
-You must have a bank account at a bank dealing in fiat currency that offers an
-online banking protocol supported by LibEuFin Nexus. As legacy transactions
-in that bank account would likely confuse the system, it is highly advised to
-use a fresh bank account, with an empty transaction history.
-
-Today, the LibEuFin implementation supports EBICS 2.5 and 3.0 and has been
-tested with the Postfinance (CHF). Please note that banks tend to have their
-own dialects of finance messages and thus other retail banks may or may not work.
-Contact us if you need support for another bank or core banking protocol.
-
-.. _regional-ebics-setup:
-
-EBICS setup
-+++++++++++
-
-.. include:: ../frags/ebics-setup.rst
+Set up an EBICS subscriber as described in :ref:`ebics-setup` using a bank
+account at a bank dealing in fiat currency that offers an online banking
+protocol supported by LibEuFin Nexus. As legacy transactions in that bank
+account would likely confuse the system, it is advisable to use a fresh bank
+account with an empty transaction history.
.. note::
