From 61043529ef53a90e7264a5d779467daa0a6417b6 Mon Sep 17 00:00:00 2001 From: MS Date: Tue, 31 Oct 2023 15:28:23 +0100 Subject: nexus manual --- libeufin/nexus-tutorial.rst | 956 -------------------------------------------- 1 file changed, 956 deletions(-) delete mode 100644 libeufin/nexus-tutorial.rst (limited to 'libeufin/nexus-tutorial.rst') 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 `. - - -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 -`__. - -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 `. - -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 `_ 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 `_ 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 -- cgit v1.2.3