summaryrefslogtreecommitdiff
path: root/libeufin
diff options
context:
space:
mode:
authorFlorian Dold <florian@dold.me>2021-01-13 23:41:34 +0100
committerFlorian Dold <florian@dold.me>2021-01-13 23:42:23 +0100
commit7ec5e10ea0ea131b1ad966e093b910acd776d435 (patch)
tree62ccb10ff7af8620c9aaa615ca286b792256a7a2 /libeufin
parent1bc751e8448b6f742c1166aa5244187feac6b8a5 (diff)
downloaddocs-7ec5e10ea0ea131b1ad966e093b910acd776d435.tar.gz
docs-7ec5e10ea0ea131b1ad966e093b910acd776d435.tar.bz2
docs-7ec5e10ea0ea131b1ad966e093b910acd776d435.zip
libeufin howto
Diffstat (limited to 'libeufin')
-rw-r--r--libeufin/nexus-tutorial.rst264
1 files changed, 222 insertions, 42 deletions
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
index fd12ad2..d20fb7a 100644
--- a/libeufin/nexus-tutorial.rst
+++ b/libeufin/nexus-tutorial.rst
@@ -1,19 +1,37 @@
-Nexus How-To
-############
+LibEuFin How-To
+###############
.. contents:: Table of Contents
-Nexus is a Web service that provides a JSON abstraction layer to
-access bank accounts. It is **not** itself a bank, but a translator
-between JSON requests and more structured banking protocols (like
-EBICS, for example), that are offered by actual banks.
+The LibEuFin Nexus is a Web service that provides a JSON abstraction layer to
+access bank accounts. It does **not** itself offer banking services, but is a
+translator between JSON requests and other banking protocols (such as EBICS),
+that are offered by banks.
This document explains how to set up Nexus to access a bank account
-via the EBICS protocol. In order to follow all the steps below, the
-reader should already have one EBICS subscriber activated at their bank.
+via the EBICS protocol.
+
+In order to follow all the steps below, the reader should either
+have access to a bank account with EBICS support or follow the
+steps in "Setting up the Sandbox".
+
+
+Installing LibEuFin
+===================
+
+Downloading prebuilt binaries
+-----------------------------
+
+Pre-built packages can be obtained from the `taler.net website
+<https://taler.net/files/libeufin>`__.
+
+Unpack the ``libeufin-$version.zip `` file to
+your desired location (typically ``/opt`` or ``~/opt``) and make sure that your ``$PATH``
+variable contains the ``bin/`` directory of the unpacked archive.
+
+Building from source
+--------------------
-Obtain Nexus
-============
Nexus belongs to the LibEuFin project, and can be downloaded via Git:
.. code-block:: console
@@ -22,8 +40,6 @@ Nexus belongs to the LibEuFin project, and can be downloaded via Git:
Note that Kotlin+Gradle should already work on the host system.
-Install Nexus
-=============
Navigate into the *libeufin* local repository, and from top-level run:
.. code-block:: console
@@ -32,6 +48,9 @@ Navigate into the *libeufin* local repository, and from top-level run:
$ ./configure --prefix=$PREFIX
$ make install
+Verifying your installation
+---------------------------
+
In case of success, the two following commands should be found:
.. code-block:: console
@@ -39,19 +58,109 @@ In case of success, the two following commands should be found:
$ which libeufin-nexus
$ which libeufin-cli
-Connect Nexus with a EBICS account
+
+(Optional) Configuring the Sandbox
==================================
-Use the following command to *(1) run the nexus service*:
+If you don't have access to a real bank account with an EBICS API, you can set
+up the sandbox. The sandbox is a simplistic and incomplete implementation of a
+core banking system with EBICS access to bank accounts.
+
+For the following commands, the sandbox service must be running.
+The sandbox service is started with the following command:
+
+.. code-block:: console
+
+ $ libeufin-sandbox serve --port 5000
+
+To reset the state of the sandbox, delete the database. By default,
+the database is a SQLite3 file in ``/tmp/libeufin-sandbox.sqlite3``.
+
+For invocations of the LibEuFin command line interface tool (``libeufin-cli``),
+the following environment variable must be set to the URL of the sandbox
+service:
+
+.. code-block:: console
+
+ export LIBEUFIN_SANDBOX_URL=http://localhost:5000/
+
+Verify that the sandbox is running:
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox check
+
+Now an EBICS host can be created:
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox ebicshost create --host-id testhost
+
+Note that most ``libeufin-cli`` subcommands will ask for input interactively if
+the respective value is not specified as a command line option.
+
+Next, create an EBICS subscriber (identified by the partner ID and user ID) for the host:
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox ebicssubscriber create \
+ --host-id testhost --partner-id partner01 --user-id user01
+
+Create a bank account for the subscriber and add a sample transaction:
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox ebicsbankaccount create \
+ --currency EUR \
+ --iban DE18500105172929531888 \
+ --bic INGDDEFFXXX \
+ --person-name "Jane Normal" \
+ --account-name "testacct01" \
+ --ebics-host-id testhost \
+ --ebics-user-id user01 \
+ --ebics-partner-id partner01
+
+The account name "testacct01" is the unique identifier of the account within
+the sandbox. The EBICS parameter identify the subscriber that should have
+access to the bank account via EBICS.
+
+To populate the account with some test transactions, run the following command
+(note that we use the bankaccount subcommand, as this command is not
+EBICS-specific!):
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox bankaccount generate-transactions testacct01
+
+Payments to a sandbox bank account can be listed as follows:
+
+.. code-block:: console
+
+ $ libeufin-cli sandbox bankaccount transactions testacct01
+
+.. note::
+
+ The sandbox is intended as a testing tool and thus not stable.
+
+ For more information on the available commands, use the built-in ``--help`` flag.
+
+ The full functionality of the sandbox is available via the API.
+
+
+Connect Nexus with an EBICS account
+===================================
+
+Use the following command to run the nexus service:
.. code-block:: console
- $ libeufin-nexus serve
+ $ libeufin-nexus serve --port 5001
-We recommend using the ``--db-conn-string=$DBCONN`` option. It
-instructs Nexus to reach the database addressed by the connection
-string. Only *SQLite* and *PostgreSQL (only via TCP)* are supported
-right now.
+By default, the SQLite3 database ``/tmp/libeufin-nexus.sqlite3`` will be used.
+
+We recommend using the ``--db-conn-string=$DBCONN`` option. It instructs Nexus
+to reach the database addressed by the JDBC connection URI. Only *SQLite* and
+*PostgreSQL (only via TCP)* are supported right now.
For example:
@@ -59,27 +168,32 @@ For example:
$ libeufin-nexus serve --db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret
-At this point a *(2) superuser account needs to be activated
-into the system*:
+At this point a superuser account needs to be created:
.. code-block:: console
$ libeufin-nexus superuser --db-conn-string=jdbc:postgresql://127.0.0.1:5433/libeufindb?user=foo&password=secret foo # Will interactively ask for password
-For simplicity, a superuser can as well act as a normal user, but a API
+For simplicity, a superuser can as well act as a normal user, but an API
to create less privileged users is offered.
-Nexus needs now to associate the user to a EBICS subscriber that was
-activated on the bank. In the Nexus terminology, this is called *(3)
-creating a EBICS connection*.
+.. note::
+
+ Privilege separation is not fully implemented yet.
+
+The command line interface needs the following three values
+to be defined in the environment: ``LIBEUFIN_NEXUS_URL``, ``LIBEUFIN_NEXUS_USERNAME``,
+and ``LIBEUFIN_NEXUS_PASSWORD``. In this example, ``LIBEUFIN_NEXUS_USERNAME`` should be
+set to ``foo``, and ``LIBEUFIN_NEXUS_PASSWORD`` to the value given for its password
+in step (2).
+
+Next, we will create an EBICS *bank connection* that that
+nexus can use to communicate with the bank.
.. note::
- The command line interface needs the following three values
- to be defined in the environment: ``NEXUS_BASE_URL``, ``NEXUS_USERNAME``,
- and ``NEXUS_PASSWORD``. In this example, ``NEXUS_USERNAME`` should be
- set to ``foo``, and ``NEXUS_PASSWORD`` to the value given for its password
- in step (2).
+ For the sandbox set up in this guide, the EBICS base URL
+ is ``http://localhost:5000/ebicsweb``.
.. code-block:: console
@@ -107,9 +221,24 @@ a backup copy* of such keys.
$CONNECTION_NAME
At this point, Nexus must communicate all the details to the bank. Therefore,
-it will *(5) synchronize the connection*. In this EBICS example, Nexus will send
+it will synchronize the connection. In this EBICS example, Nexus will send
the *INI* and *HIA* messages to the bank.
+Now that the bank has received the public keys of the subscriber electronically,
+it also needs to verify them offline. For this, the nexus can generate a key letter:
+
+.. code-block:: console
+
+ $ libeufin-cli connections keyletter $CONNECTION_NAME out.pdf
+
+.. note::
+
+ The resulting PDF should be sent to the bank, which will verify
+ that the keys printed in it match the keys sent electronically.
+
+ When using the LibEuFin sandbox, subscribers are automatically
+ activated after keys are received electronically.
+
.. code-block:: console
$ libeufin-cli \
@@ -119,7 +248,7 @@ the *INI* and *HIA* messages to the bank.
Once the connection is synchronized, Nexus needs to import locally the data
corresponding to the bank accounts offered by the bank connection just made.
-The command below *(6) downloads the list of the bank accounts offered by the*
+The command below downloads the list of the bank accounts offered by the
``$CONNECTION_NAME``.
.. code-block:: console
@@ -129,7 +258,7 @@ The command below *(6) downloads the list of the bank accounts offered by the*
download-bank-accounts \
$CONNECTION_NAME
-It is now possible to *(7) list the accounts offered by the connection*.
+It is now possible to list the accounts offered by the connection.
.. code-block:: console
@@ -138,8 +267,8 @@ It is now possible to *(7) list the accounts offered by the connection*.
list-offered-bank-accounts \
$CONNECTION_NAME
-Nexus now needs an explicit *(8) import of the accounts it needs to manage*.
-This step is needed to let the user pick a custom name for such accounts.
+Nexus now needs an explicit import of the accounts it should to manage. This
+step is needed to let the user pick a custom name for such accounts.
.. code-block:: console
@@ -159,6 +288,7 @@ Request history of transactions
===============================
..
+
FIXME: explain why requesting the history
goes through these two-phases.
@@ -174,20 +304,27 @@ This command asks Nexus to *download the latest bank statements*:
fetch-transactions \
$CUSTOM_RENAMING_FOR_ACCOUNT
+.. note::
+
+ By default, the latest available transactions are fetched. It is also
+ possible to specify a custom data range (or even all available transactions)
+ and the type of transactions to fetch ( inter-day statements or intra-day
+ reports).
+
Once Nexus stored all the information in the database, the
client can ask to actually **see** the transactions:
.. code-block:: console
- $ libeufin-cli
- accounts \
- transactions \
- $CUSTOM_RENAMING_FOR_ACCOUNT
+ $ libeufin-cli accounts \
+ transactions \
+ $CUSTOM_RENAMING_FOR_ACCOUNT
Make a payment
==============
..
+
FIXME: explain why payments go through these two-phases.
Payments pass through two phases: preparation and submission.
@@ -199,9 +336,9 @@ The following command prepares a payment:
$ libeufin-cli \
accounts \
prepare-payment \
- --credit-iban $IBAN_TO_SEND_MONEY_TO \
- --credit-bic $BIC_TO_SEND_MONEY_TO \
- --credit-name $LEGAL_ENTITY_RECEIVING_THE_PAYMENT \
+ --creditor-iban $IBAN_TO_SEND_MONEY_TO \
+ --creditor-bic $BIC_TO_SEND_MONEY_TO \
+ --creditor-name $CREDITOR_NAME \
--payment-amount $AMOUNT \
--payment-subject $SUBJECT \
$CUSTOM_RENAMING_FOR_ACCOUNT
@@ -221,6 +358,49 @@ in the next step, to **send the payment instructions to the bank**:
--payment-uuid $UUID \
$CUSTOM_RENAMING_FOR_ACCOUNT
+Automatic scheduling
+====================
+
+With an EBICS bank connection, the LibEuFin nexus needs to regularly query for
+new transactions and (re-)submit prepared payments.
+
+It is possible to schedule these tasks via an external task scheduler such as
+cron. However, the nexus also has an internal task scheduling mechanism for
+accounts.
+
+
+The following two create a schedule for submitting payments hourly,
+fetching transactions (intra-day reports) every 5 minutes and once at 11am every
+day (inter-day statements):
+
+.. code-block:: console
+
+ $ libeufin-cli accounts task-schedule myacct \
+ --task-type="submit"
+ --task-name='submit-payments-hourly'
+ --task-cronspec='0 0 *'
+
+ $ libeufin-cli accounts task-schedule myacct \
+ --task-type="fetch" \
+ --task-name='fetch-5min' \
+ --task-cronspec='0 */5 *' \
+ --task-param-level=report \
+ --task-param-range-type=latest
+
+ $ libeufin-cli accounts task-schedule myacct \
+ --task-type="fetch" \
+ --task-name='fetch-daily' \
+ --task-cronspec='0 0 23' \
+ --task-param-level=statement \
+ --task-param-range-type=latest
+
+The cronspec has the following format, which is slightly non-standard due to
+the ``SECONDS`` field
+
+.. code-block:: none
+
+ SECONDS MINUTES HOURS DAY-OF-MONTH[optional] MONTH[optional] DAY-OF-WEEK[optional]
+
Restore the backup
==================