[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: nexus manual
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: nexus manual |
|
Date: |
Tue, 31 Oct 2023 15:28:34 +0100 |
This is an automated email from the git hooks/post-receive script.
ms pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 61043529 nexus manual
61043529 is described below
commit 61043529ef53a90e7264a5d779467daa0a6417b6
Author: MS <ms@taler.net>
AuthorDate: Tue Oct 31 15:28:23 2023 +0100
nexus manual
---
design-documents/050-libeufin-nexus.rst | 1 -
libeufin/index.rst | 2 +-
libeufin/nexus-manual.rst | 93 ++++
libeufin/nexus-tutorial.rst | 956 --------------------------------
4 files changed, 94 insertions(+), 958 deletions(-)
diff --git a/design-documents/050-libeufin-nexus.rst
b/design-documents/050-libeufin-nexus.rst
index 1d563936..272e7a7b 100644
--- a/design-documents/050-libeufin-nexus.rst
+++ b/design-documents/050-libeufin-nexus.rst
@@ -59,7 +59,6 @@ Configuration file
HOST_ID = mybank
USER_ID = myuser
PARTNER_ID = myorg
- SYSTEM_ID = banksys
IBAN = MY-IBAN
BIC = MY-BIC
NAME = MY NAME
diff --git a/libeufin/index.rst b/libeufin/index.rst
index 4ccbe1aa..2f1ef49c 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -12,7 +12,7 @@ LibEuFin is a project providing free software tooling for
European FinTech.
iso20022
banking-protocols
frontend
- nexus-tutorial
+ nexus-manual
ebics3-test-tutorial
performance
transaction-identification
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
new file mode 100644
index 00000000..1c8adf59
--- /dev/null
+++ b/libeufin/nexus-manual.rst
@@ -0,0 +1,93 @@
+.. target audience: operator, developer
+
+LibEuFin 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
+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 installation
+is described at `Installing Nexus`_.
+
+Setting up the EBICS subscriber
+===============================
+
+The following snippet shows the mandatory configuration values.
+
+.. code-block:: console
+
+ [nexus-postgres]
+ CONFIG = postgres:///libeufincheck
+
+ [nexus-ebics]
+ CURRENCY = EUR
+ HOST_BASE_URL = http://bank.example.com/
+ HOST_ID = mybank
+ USER_ID = myuser
+ PARTNER_ID = myorg
+ IBAN = myiban
+ BIC = mybic
+ NAME = myname
+ BANK_PUBLIC_KEYS_FILE = enc-auth-keys.json
+ CLIENT_PRIVATE_KEYS_FILE = private-keys-again.json
+ BANK_DIALECT = postfinance
+
+Assuming that the configuration file exists at ``$config_file``, the following
+command would start the EBICS setup process. The files
CLIENT_PRIVATE_KEYS_FILE
+and BANK_PUBLIC_KEYS_FILE would be created at the CWD. Adjust their path to
your
+setup ('$HOME' is currently not supported along paths).
+
+.. code-block:: console
+
+ libeufin-nexus ebics-setup -c $config_file
+
+If the previous command succeeded, the subscriber keys reached the bank, but
the setup
+**should** fail with an ``EBICS_AUTHENTICATION_FAILED`` error code. That
happens because
+the client tries to download the bank keys *before* having confirmed the
subscriber keys
+via the traditional post service.
+
+To that purpose, the previous run should have left a PDF document that the
subscriber can
+print, sign, and send to the bank to confirm their subscriber keys. Look for
the message
+looking like ``PDF file with keys hex encoding created at:
/tmp/libeufin-nexus-keys-$timestamp.pdf``.
+
+Once the bank received and approved such printed document, run the same
command again, in
+order to download the bank keys and let the user accept them.
+
+.. code-block:: console
+
+ libeufin-nexus ebics-setup -c $config_file
+
+The setup is considered finished once both party have accepted the counterpart
keys.
+
+Installing Nexus
+================
+
+The following section was tested on an *OpenJDK 17* environment.
+
+Building from source
+--------------------
+
+Nexus belongs to the LibEuFin project, and can be downloaded via Git:
+
+.. code-block:: console
+
+ $ git clone git://git.taler.net/libeufin
+
+Note that Kotlin and Gradle should already work on the host system.
+
+Navigate into the *libeufin* local repository, and from top-level run:
+
+.. code-block:: console
+
+ $ ./bootstrap
+ $ ./configure --prefix=$PREFIX
+ $ make install-nexus
+
+If the previous steps succeeded, the ``libeufin-nexus`` command should
+be found in the $PATH.
+
diff --git a/libeufin/nexus-tutorial.rst b/libeufin/nexus-tutorial.rst
deleted file mode 100644
index aeea4667..00000000
--- a/libeufin/nexus-tutorial.rst
+++ /dev/null
@@ -1,956 +0,0 @@
-.. target audience: operator, developer
-
-LibEuFin How-To
-###############
-
-.. contents:: Table of Contents
-
-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 either
-have access to a bank account with EBICS support or follow the
-steps in :ref:`Configuring the Sandbox <configuring-the-sandbox>`.
-
-
-Installing LibEuFin
-===================
-
-Installation on Debian
-----------------------
-
-.. include:: ../frags/installing-debian.rst
-
-To install LibEuFin, you can now simply run:
-
-.. code-block:: console
-
- # apt install libeufin-nexus libeufin-sandbox
-
-Administration via SystemD
---------------------------
-
-After the Debian installation, the installed unit files
-should be listed by the following command:
-
-.. code-block:: console
-
- # systemctl list-unit-files | egrep '(nexus|sandbox)'
-
-Both ``nexus.service`` and ``sandbox.service`` should appear.
-
-At this point, the services can be started on boot:
-
-.. code-block:: console
-
- # systemctl enable libeufin-nexus # use 'disable' to rollback
- # systemctl enable libeufin-sandbox # only if you want the sandbox
-
-Or just manually:
-
-.. code-block:: console
-
- # systemctl start libeufin-nexus # use 'stop' to terminate.
- # systemctl start libeufin-sandbox # only if you want the sandbox
-
-The following command should inform the user about the status
-of the running / terminated service:
-
-.. code-block:: console
-
- # systemctl status libeufin-nexus
-
-For more diagnostics, use:
-
-.. code-block:: console
-
- # journalctl -u libeufin-nexus
-
-Run-time dependencies
----------------------
-
-LibEuFin has the following run-time dependencies:
-
-* OpenJDK 11
-* Python 3.8
-* python3-click (can be installed via ``pip3 install click``)
-* python3-requests (can be installed via ``pip3 install requests``)
-
-These dependencies only need to be installed manually when building from source
-or using the prebuilt binaries.
-
-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``
-environment variable contains the ``bin/`` directory of the unpacked archive.
-
-
-.. _building-from-source:
-
-Building from source
---------------------
-
-Nexus belongs to the LibEuFin project, and can be downloaded via Git:
-
-.. code-block:: console
-
- $ git clone git://git.taler.net/libeufin
-
-It is recommended to run the ``v0.9.1`` version, hence
-the following command may now be given.
-
-.. code-block:: console
-
- $ git checkout v0.9.1
-
-Note that Kotlin and Gradle should already work on the host system.
-
-Navigate into the *libeufin* local repository, and from top-level run:
-
-.. code-block:: console
-
- $ ./bootstrap
- $ ./configure --prefix=$PREFIX
- $ make install # Note: This may require Java=18; Java=17 had errors,
Java>=19 is unsupported by Gradle
-
-Verifying your installation
----------------------------
-
-In case of success, the three following commands should be found:
-
-.. code-block:: console
-
- $ which libeufin-nexus
- $ which libeufin-sandbox
- $ which libeufin-cli
-
-
-.. _configuring-the-sandbox:
-
-Configuring the Sandbox (Optional)
-==================================
-
-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.
-
-The sandbox uses HTTP Basic auth, with username ``admin``.
-Choose a password and set env var ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` to it.
-
-The sandbox relies on a database, which you must specify using a Postgres
-connection URI with the ``LIBEUFIN_SANDBOX_DB_CONNECTION`` environment
-variable, before invoking any commands.
-If this variable is not set, ``libeufin-sandbox`` complains and exits:
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret
- $ libeufin-sandbox serve
- DB connection string not found in the env variable
LIBEUFIN_SANDBOX_DB_CONNECTION.
- The following two examples are valid connection strings:
- postgresql://localhost:5432/libeufindb?user=Foo&password=secret
- postgres:///libeufindb
-
-Before being usable, a Sandbox needs to be configured. This is done
-by creating the ``default`` demobank. A demobank is a set of configuration
-values associated to one name; in the example below, we'll create one
-named ``default``, that is mandatory to have.
-
-.. note::
-
- By design, many demobanks can be hosted by one running Sandbox,
- although at the time of writing only the ``default`` one is supported.
-
-A default demobank having the EUR currency is created with the following
command:
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_DB_CONNECTION=postgres:///libeufintestdb
- $ libeufin-sandbox config --currency EUR default
-
-In order to use Taler, a default exchange needs to be configured.
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_DB_CONNECTION=postgres:///libeufintestdb
- $ libeufin-sandbox default-exchange --demobank default $exchange_base_url
$exchange_payto_address
-
-The sandbox service can now be started with the following command:
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_ADMIN_PASSWORD=secret
- $ export LIBEUFIN_SANDBOX_DB_CONNECTION=postgres:///libeufintestdb
- $ libeufin-sandbox serve --port 5016
-
-The instructions below hook Nginx to the Sandbox:
-
-.. code-block:: nginx
-
- redirect / to /demobanks/default;
- rewrite ^/$ https://$host/demobanks/default;
- location / {
- proxy_set_header Host $host;
- proxy_set_header X-Forwarded-Host $host;
- proxy_set_header X-Forwarded-Proto "https";
- proxy_set_header X-Forwarded-Prefix "/";
- proxy_pass http://localhost:5016/;
- }
-
-To reset the state of the sandbox, delete the database.
-
-For invocations of the LibEuFin command-line interface tool (``libeufin-cli``),
-the following environment variables must be set to the authentication
-information, and the URL of the sandbox service:
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_USERNAME=admin
- $ export LIBEUFIN_SANDBOX_PASSWORD=secret
- $ export LIBEUFIN_SANDBOX_URL=http://localhost:5016
-
-Note that the password is the same as for ``LIBEUFIN_SANDBOX_ADMIN_PASSWORD``.
-Verify that the sandbox is running:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox check
- Hello, this is the Sandbox
-
-Now an EBICS host can be created:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox ebicshost create --host-id testhost
- $ libeufin-cli sandbox ebicshost list
- {
- "ebicsHosts" : [ "testhost" ]
- }
-
-Note that most ``libeufin-cli`` subcommands will ask for input interactively if
-the respective value is not specified on the command line.
-
-Next, register a user. For the ``libeufin-cli sandbox demobank register``
-command, the ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD``
-are assumed to be ``jrluser`` and ``easy``, respectively.
-
-.. note::
-
- All the following commands address the ``default`` demobank, see
``libeufin-cli sandbox demobank --help``.
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_USERNAME=jrluser
- $ export LIBEUFIN_SANDBOX_PASSWORD=easy
- $ libeufin-cli sandbox demobank register
-
-Check the balance of the user just created:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox \
- demobank info --bank-account jrluser
-
-With a user registered, we can now create an EBICS subscriber (identified by
-the partner ID and user ID) for the host. This command requires admin
-privileges, so ``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD``
-are reset back to ``admin`` and ``secret``, respectively.
-
-.. The plan is to replace the ‘sandbox ebicssubscriber list’ command
- below with a ‘sandbox demobank show-ebicssubscriber’ command.
- Need to implement it first!
-
-.. code-block:: console
-
- $ export LIBEUFIN_SANDBOX_USERNAME=admin
- $ export LIBEUFIN_SANDBOX_PASSWORD=secret
- $ libeufin-cli sandbox \
- demobank new-ebicssubscriber \
- --host-id testhost \
- --partner-id partner01 \
- --user-id user02 \
- --bank-account jrluser
- $ libeufin-cli sandbox ebicssubscriber list
- {
- "subscribers" : [ {
- "host_id" : "testhost",
- "partner_id" : "partner01",
- "user_id" : "user02",
- "system_id" : null,
- "demobank_account_label" : "jrluser"
- } ]
- }
-
-The ``libeufin-cli sandbox demobank new-ebicssubscriber`` command
-also creates an associated bank account. You can see it with command:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox bankaccount list
- [ {
- "label" : "bank",
- "name" : "Bank account owner's name",
- "iban" : "DE895351",
- "bic" : "SANDBOXX"
- }, {
- "label" : "jrluser",
- "name" : "Bank account owner's name",
- "iban" : "DE724881",
- "bic" : "SANDBOXX"
- } ]
-
-The account name ``jrluser`` is the unique identifier of the account within
-the sandbox. The EBICS parameters identify the subscriber that should have
-access to the bank account via EBICS.
-
-The account already has one transaction, the "Sign-up bonus" from the bank.
-Note that in the following examples we transition to using the ``bankaccount``
-subcommand, because there is no need to rely on EBICS:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox bankaccount transactions jrluser
- {
- "payments" : [ {
- "account_label" : "jrluser",
- "creditor_iban" : "DE724881",
- "creditor_bic" : "SANDBOXX",
- "creditor_name" : "Unknown",
- "debtor_iban" : "DE895351",
- "debtor_bic" : "SANDBOXX",
- "debtor_name" : "The Bank",
- "amount" : "100",
- "currency" : "EUR",
- "subject" : "Sign-up bonus",
- "date" : "Tue, 22 Feb 2022 00:04:15 GMT",
- "credit_debit_indicator" : "credit",
- "account_servicer_reference" : "2NG75I0O",
- "payment_information_id" : null
- } ]
- }
-
-To populate the account with some more transactions, run the following command:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox bankaccount generate-transactions jrluser
-
-.. code-block:: console
-
- $ libeufin-cli sandbox bankaccount simulate-incoming-transaction jrluser \
- --debtor-iban DE06500105174526623718 \
- --debtor-bic INGDDEFFXXX \
- --debtor-name "Joe Foo" \
- --subject "Hello World" \
- --amount 10.50
-
-Now the list of transactions has grown by several entries:
-
-.. code-block:: console
-
- $ libeufin-cli sandbox bankaccount transactions jrluser
- {
- "payments" : [ {
- "account_label" : "jrluser",
- "creditor_iban" : "DE724881",
- "creditor_bic" : "SANDBOXX",
- "creditor_name" : "Unknown",
- "debtor_iban" : "DE895351",
- "debtor_bic" : "SANDBOXX",
- "debtor_name" : "The Bank",
- "amount" : "100",
- "currency" : "EUR",
- "subject" : "Sign-up bonus",
- "date" : "Tue, 22 Feb 2022 00:04:15 GMT",
- "credit_debit_indicator" : "credit",
- "account_servicer_reference" : "2NG75I0O",
- "payment_information_id" : null
- }, {
- "account_label" : "jrluser",
- "creditor_iban" : "DE724881",
- "creditor_bic" : "SANDBOXX",
- "creditor_name" : "Creditor Name",
- "debtor_iban" : "DE64500105178797276788",
- "debtor_bic" : "DEUTDEBB101",
- "debtor_name" : "Max Mustermann",
- "amount" : "22",
- "currency" : "EUR",
- "subject" : "sample transaction GSF7S5LC",
- "date" : "Tue, 22 Feb 2022 01:26:18 GMT",
- "credit_debit_indicator" : "credit",
- "account_servicer_reference" : "GSF7S5LC",
- "payment_information_id" : null
- }, {
- "account_label" : "jrluser",
- "creditor_iban" : "DE64500105178797276788",
- "creditor_bic" : "DEUTDEBB101",
- "creditor_name" : "Max Mustermann",
- "debtor_iban" : "DE724881",
- "debtor_bic" : "SANDBOXX",
- "debtor_name" : "Debitor Name",
- "amount" : "10",
- "currency" : "EUR",
- "subject" : "sample transaction 1WUP303Q",
- "date" : "Tue, 22 Feb 2022 01:26:18 GMT",
- "credit_debit_indicator" : "debit",
- "account_servicer_reference" : "1WUP303Q",
- "payment_information_id" : null
- }, {
- "account_label" : "jrluser",
- "creditor_iban" : "DE724881",
- "creditor_bic" : "SANDBOXX",
- "creditor_name" : "Creditor Name",
- "debtor_iban" : "DE06500105174526623718",
- "debtor_bic" : "INGDDEFFXXX",
- "debtor_name" : "Joe Foo",
- "amount" : "10.50",
- "currency" : "EUR",
- "subject" : "Hello World",
- "date" : "Tue, 22 Feb 2022 01:26:41 GMT",
- "credit_debit_indicator" : "credit",
- "account_servicer_reference" : "sandbox-ALQP8TXKJWRVKMAH",
- "payment_information_id" : null
- } ]
- }
-
-.. note::
-
- The sandbox is intended as a testing tool and thus not stable.
-
-.. _disable-registrations:
-
-Disable registrations (experimental)
-------------------------------------
-
-Demobanks can disable/enable registrations for new users.
-The responsible options are
-``--with-registrations`` / ``--without-registrations``.
-
-For more information on the available commands, use the built-in ``--help``
flag.
-The full functionality of the sandbox is available via
-the :ref:`Core Bank API <corebank-api>`.
-
-Connect Nexus with the bank.
-============================
-
-Nexus relies on a database, which you must specify using a Postgres
-connection URI with the ``LIBEUFIN_NEXUS_DB_CONNECTION`` environment
-variable, before invoking any commands.
-(If this variable is not set, ``libeufin-nexus`` complains and exits.)
-
-Use the following command to run the Nexus service:
-
- Neuxs defaults to *not* storing the messages that it downloads
- from the bank. To revert this behaviour, export also the environment
- variable ``LIBEUFIN_NEXUS_KEEP_BANK_MESSAGES`` to ``yes`` before
- running the following command.
-
-.. code-block:: console
-
- $ export
LIBEUFIN_NEXUS_DB_CONNECTION=postgresql://localhost:5433/libeufindb?user=foo&password=secret
- $ libeufin-nexus serve --port 5017
-
-This assumes that the PostgreSQL service with a database
-called ``libeufindb`` listens on port 5433
-for requests from the Nexus service.
-The Nexus service itself listens on port 5017.
-Note that you must have the ``LIBEUFIN_NEXUS_DB_CONNECTION``
-environment variable set for most uses of the libeufin-nexus
-command.
-
-At this point a superuser account needs to be created:
-
-.. code-block:: console
-
- $ libeufin-nexus superuser foo --password secret
-
-If you omit ``--password secret``, you will interactively be asked for a
password.
-For simplicity, a superuser can as well act as a normal user, but an API
-to create less privileged users is offered.
-
-.. note::
-
- User and permissions management in LibEuFin is still under development.
- In particular, permissions for non-superusers are very limited at the moment.
-
-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 the previous step (with the ``libeufin-nexus superuser`` command). The
-``LIBEUFIN_NEXUS_URL`` could be given as ``http://localhost:5017``.
-
-Nexus speaks two protocols to reach the bank: EBICS and x-libeufin-bank.
-In Nexus speech, each protocol is also known as a *bank connection*.
-The following two sections show how to setup such bank connections. Note:
-only one is needed to operate!
-
-EBICS
------
-
-.. note::
-
- For the sandbox setup in this guide, the ``EBICS_BASE_URL``
- should be ``http://localhost:5016/ebicsweb``.
- This is the value of environment variable
- ``LIBEUFIN_SANDBOX_URL`` suffixed with ``/ebicsweb``,
- since the sandbox will be providing EBICS services.
-
- Similarly, ``EBICS_HOST_ID`` should be ``testhost``,
- and ``EBICS_PARTNER_ID`` should be ``partner01``.
- For ``EBICS_USER_ID`` we will use ``user02`` (for account ``jrluser``),
- and for ``CONNECTION_NAME``, we will use ``conn01``.
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- new-ebics-connection \
- --ebics-url $EBICS_BASE_URL \
- --host-id $EBICS_HOST_ID \
- --partner-id $EBICS_PARTNER_ID \
- --ebics-user-id $EBICS_USER_ID \
- $CONNECTION_NAME
-
-If this step executes correctly
-(use ``libeufin-cli connections list-connections``
-and ``libeufin-cli connections show-connection`` to check),
-Nexus will have created all the cryptographic
-material that is needed on the client side; in this EBICS example, it created
-the signature and identification keys. It is therefore advisable to *make
-a backup copy* of such keys.
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- export-backup \
- --passphrase $SECRET \
- --output-file $BACKUP_FILE \
- $CONNECTION_NAME
-
-At this point, Nexus needs to both communicate its keys to the bank, and
-download the bank's keys. This synchronization happens through the INI,
-HIA, and finally, HPB message types.
-
-After the electronic synchronization, the subscriber must confirm their keys
-by sending a physical mail to the bank. The following command helps generating
-such letter:
-
-.. code-block:: console
-
- $ libeufin-cli connections get-key-letter $CONNECTION_NAME out.pdf
-
-.. note::
-
- When using the LibEuFin sandbox, subscribers are automatically
- activated after keys are received electronically.
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- connect \
- $CONNECTION_NAME
-
-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 downloads the list of the bank accounts offered by
``$CONNECTION_NAME``.
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- download-bank-accounts \
- $CONNECTION_NAME
-
-It is now possible to list the accounts offered by the connection.
-
-.. _list-connections:
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- list-offered-bank-accounts \
- $CONNECTION_NAME
-
-.. note::
-
- The ``nexusBankAccountId`` field should at this step be ``null``,
- as we have not yet imported the bank account and thus the account
- does not yet have a local name.
-
-Nexus now needs an explicit import of the accounts it should manage. This
-step is needed to let the user pick a custom name for such accounts.
-
-.. code-block:: console
-
- $ libeufin-cli \
- connections \
- import-bank-account \
- --offered-account-id testacct01 \
- --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \
- $CONNECTION_NAME
-
-Once a Nexus user imported a bank account (``$LOCAL_ACCOUNT_NAME``)
-under a certain connection (``$CONNECTION_NAME``), it is possible
-to accomplish the usual operations for any bank account: asking for the
-list of transactions, and making a payment.
-
-The last step is to create background tasks that fetch and submit
-the information from and to the bank. The following command submits
-the prepared payments to the bank each second.
-
-.. _submit-task:
-
-.. code-block:: console
-
- $ libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \
- --task-type submit \
- --task-name submit-payments-each-second \
- --task-cronspec "* * *"
-
-The following step downloads from the bank all the new transactions,
-each second. The ``report`` value indicates that Nexus is interested
-in the transactions which did reach already the booked state, in order
-to provide faster times to its users.
-
-.. code-block:: console
-
- $ libeufin-cli accounts task-schedule $LOCAL_ACCOUNT_NAME \
- --task-type fetch \
- --task-name fetch-reports-each-second \
- --task-cronspec "* * *" \
- --task-param-level report \
- --task-param-range-type latest
-
-For example, the cronspec can be changed to every five seconds by the
-following value: ``"*/5 * *"`` (remember to quote, to protect from shell
-filename expansion).
-
-x-libeufin-bank
----------------
-
-This is a faster bank connection, because it relies on JSON and HTTP basic
-auth, as oppsed to EBICS XML and RSA cryptography. It is also planned to equip
-the server side with long-polling, in order to loop more slowly when asking
-for new data.
-
-The first step is to create one x-libeufin-bank connection. Make sure that
-the usual env variables LIBEUFIN_NEXUS_USERNAME, LIBEUFIN_NEXUS_PASSWORD, and
-LIBEUFIN_NEXUS_URL are set. The following command instructs Nexus about
-the bank URL and the credentials it needs
-
-.. code-block:: console
-
- libeufin-cli connections new-xlibeufinbank-connection \
- --bank-url "http://localhost:5016/demobanks/default/access-api"; \
- --username jrluser \
- --password easy \
- $CONNECTION_NAME
-
-The ``--password`` option can be omitted, and in this case the CLI will
-prompt to collect it.
-
- The credentials are exactly the same as the ones used to register a
- new bank account at Sandbox.
-
-Once the connection is created, we need -- just as in the EBICS case --
-the "connect" step. In this case, the connect step will check if the
-credentials and URL are correct and (as a side effect) download basic
-information about the bank account.
-
-.. code-block:: console
-
- libeufin-cli connections connect $CONNECTION_NAME
-
-As a proof, you can `list <list-connections_>`_ which bank account
-arrived at Nexus after the connect command succeeds. Now the bank
-account can be imported under a local name at Nexus, just as it was
-in the EBICS case.
-
-.. note::
-
- One main difference with EBICS is that now we don't need the
- ``download-bank-accounts`` step, because ``connect`` carried
- it out as a side effect of checking the credentials.
-
-
-.. code-block:: console
-
- libeufin-cli connections import-bank-account \
- --offered-account-id jrluser \
- --nexus-bank-account-id $LOCAL_ACCOUNT_NAME \
- $CONNECTION_NAME
-
-
-Now that the account is imported, the background tasks need to
-be setup, to provide always the most updated information from the
-bank.
-
-The submit task can be `the same <submit-task_>`_ as EBICS. The fetch
-task however needs one different setting, and namely it has to require
-``statement`` instead of 'report' because x-libeufin-bank has only the
-booked state for transactions. The time range is also different, because
-x-libeufin-bank does NOT offer ``latest``. Any unsupported setting should
-however generate one error and therefore not create wrong background tasks.
-
-.. code-block:: console
-
- libeufin-cli accounts task-schedule \
- --task-type fetch \
- --task-name fetch-every-second \
- --task-cronspec "* * *" \
- --task-param-level statement \
- --task-param-range-type since-last \
- $LOCAL_ACCOUNT_NAME
-
-Request history of transactions
-===============================
-
-The LibEuFin Nexus keeps a local copy of the bank account's transaction
-history. Before querying transactions locally, it is necessary
-to request transactions for the bank account via the bank connection.
-
-This command asks Nexus to download the latest transaction reports/statements
-through the bank connection:
-
-.. code-block:: console
-
- $ libeufin-cli accounts fetch-transactions $LOCAL_ACCOUNT_NAME
-
-.. note::
-
- By default, the latest available transactions are fetched. It is also
- possible to specify a custom date range (or even all available transactions)
- and the type of transactions to fetch (inter-day statements or intra-day
- reports).
-
-Once Nexus has stored all the information in the database, the
-client can ask to actually see the transactions:
-
-.. code-block:: console
-
- $ libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME
-
-Make a payment
-==============
-
-Payments pass through two phases: preparation and submission. The preparation
-phase assigns the payment initiation a unique ID, which prevents accidental
-double submissions of payments in case of network failures or other
-disruptions.
-
-
-The following command prepares a payment:
-
-.. code-block:: console
-
- $ libeufin-cli accounts prepare-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 \
- $LOCAL_ACCOUNT_NAME
-
-Note: the ``$AMOUNT`` value needs the format ``CURRENCY:X.Y``; for example
-``EUR:10``, or ``EUR:1.01``.
-
-The previous command should return a value (``$UUID``) that uniquely
-identifies the prepared payment in the Nexus system. That is needed
-in the next step, to **send the payment instructions to the bank**:
-
-.. code-block:: console
-
- $ libeufin-cli accounts submit-payments \
- --payment-uuid $UUID \
- $LOCAL_ACCOUNT_NAME
-
-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(8). However, the Nexus also has an internal task scheduling mechanism for
-accounts.
-
-
-The following three commands create a schedule for submitting payments hourly,
-fetching transactions (intra-day reports) every 5 minutes, and (inter-day
statements)
-once at 11pm every day :
-
-.. 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
-==================
-
-The following command restores all the details associated with
-one bank connection subscription. For EBICS, this means that the
-INI and HIA secret keys will be restored for the requesting user.
-
-.. code-block:: console
-
- $ libeufin-cli connections \
- restore-backup \
- --passphrase=$SECRET \
- --backup-file=$BACKUP_FILE \
- $CONNECTION_NAME
-
-..
- FIXME:
- On a bad password given, Nexus responds
- "bad backup given" instead of "authentication failed".
-
-
-Creating a Taler facade
-=======================
-
-Facades are additional abstraction layers that can serve
-specific purposes. For example, one application might need
-a filtered version of the transaction history, or it might
-want to refuse payments that do not conform to certain rules.
-
-At this moment, only the *Taler facade type* is implemented
-in the Nexus, and the command below instantiates one under a
-existing bank account / connection pair. You can freely
-assign an identifier for the ``$FACADE_NAME`` below:
-
-.. code-block:: console
-
- $ libeufin-cli facades new-taler-wire-gateway-facade \
- --currency EUR \
- --facade-name $FACADE_NAME \
- $CONNECTION_NAME \
- $LOCAL_ACCOUNT_NAME
-
-At this point, the additional *taler-wire-gateway* (FIXME: link
-here to API here) API becomes offered by the Nexus. The purpose
-is to let a Taler exchange rely on Nexus to manage its bank account.
-
-The base URL of the facade that can be used by the Taler exchange
-as the Taler Wire Gateway base URL located when listing the facades:
-
-.. code-block:: console
-
- $ libeufin-cli facades list
-
-Creating a Anastasis facade
-===========================
-
-The following command creates a Anastasis facade. At this point, *only*
-the superuser is able to create facades; please set the environment variables
-``LIBEUFIN_NEXUS_USERNAME`` and ``LIBEUFIN_NEXUS_PASSWORD`` accordingly.
-
-.. code-block:: console
-
- $ libeufin-cli facades new-anastasis-facade \
- --currency EUR \
- --facade-name $FACADE_NAME \
- $CONNECTION_NAME \
- $LOCAL_ACCOUNT_NAME
-
-If the previous command succeeded, it is possible to see the
-facade's base URL with:
-
-.. code-block:: console
-
- $ libeufin-cli facades list
-
-At this point, to allow a non superuser to use the facade, a history
-permission needs to be set:
-
-.. code-block:: console
-
- $ libeufin-cli permissions grant \
- user $USERNAME \
- facade $FACADENAME \
- facade.anastasis.history
-
-.. note::
-
- There is no need to set/unset a transfer permission on the facade
- since this one does not offer any endpoint to issue wire transfers.
-
-Managing Permissions and Users
-==============================
-
-This guide has so far assumed that a superuser is accessing the LibEuFin Nexus.
-However, it is advisable that the Nexus is accessed with users that only have a
-minimal set of permissions.
-
-The Nexus currently only has support for giving non-superusers access to Taler
-wire gateway facades.
-
-To create a new user, use the ``users`` subcommand of the CLI:
-
-.. code-block:: console
-
- $ libeufin-cli users list
- # [ ... shows available users ... ]
-
- $ libeufin-cli users create $USERNAME
- # [ ... will prompt for password ... ]
-
-Permissions are managed with the ``permissions`` subcommand.
-The following commands grant permissions to view the transaction history
-and create payment initiations with a Taler wire gateway facade:
-
-
-.. code-block:: console
-
- $ libeufin-cli permissions grant \
- user $USERNAME \
- facade $FACADENAME \
- facade.talerWireGateway.history
-
- $ libeufin-cli permissions grant \
- user $USERNAME \
- facade $FACADENAME \
- facade.talerWireGateway.transfer
-
-The list of all granted permissions can be reviewed:
-
-.. code-block:: console
-
- $ libeufin-cli permissions list
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: nexus manual,
gnunet <=