inline libeufin into setup guide

1 files changed, 365 insertions, 2 deletions

diff --git a/taler-exchange-setup-guide.rst b/taler-exchange-setup-guide.rst
index 7e8a019a..3c46e5cd 100644
--- a/taler-exchange-setup-guide.rst
+++ b/taler-exchange-setup-guide.rst
@@ -270,8 +270,371 @@ The Taler Wire Gateway is an API that connects the Taler exchange to
 the underlying core banking system.
 
 LibEuFin is an implementation of the Wire Gateway API for the EBICS protocol.
-Please follow the :doc:`LibEuFin setup instructions <libeufin/nexus-tutorial>` to set up a Taler Wire Gateway with
-LibEuFin for an EBICS bank account.
+This section will walk through (1) installing and configuring LibEuFin and
+(2) connecting the Taler Exchange to LibEuFin.
+
+.. note::
+
+   If you do not have a bank account with EBICS but want to test these instructions,
+   you can use the EBICS sandbox as described in the
+   :doc:`LibEuFin Tutorial <libeufin/nexus-tutorial>`
+
+
+Installation and Basic Configuration
+------------------------------------
+
+First, install the ``libeufin`` package.  This can be done on the ``exchange-online``
+machine or a different one.
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# apt-get install -y libeufin
+
+The main component of LibEuFin is called the Nexus.  It implements a Web
+service that provides a JSON abstraction layer to access bank accounts.
+
+The Nexus currently uses an sqlite3 database as storage by default.
+We currently recommend to stick with this default.  In future
+versions, there will be a migration path to a postgresql database.
+
+The HTTP port and database connection string can be edited in the configuration:
+
+.. code-block:: ini
+  :caption: /etc/libeufin/nexus.env
+
+  LIBEUFIN_NEXUS_PORT=5017
+  LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:sqlite:/var/lib/libeufin/nexus/nexus-db.sqlite3
+
+After configuring the database, you can start the service.
+The database is initialized automatically, there is no ``dbinit`` command
+for the LibEuFin nexus.
+
+.. code-block:: shell-session
+
+   [root@exchange-online]# systemctl enable libeufin-nexus
+   [root@exchange-online]# systemctl start libeufin-nexus
+
+You can now create a superuser account.  The command to
+create the superuser needs direct database access, thus
+the configuration file is sourced first, and the relevant
+environment variable is exported.
+
+.. code-block:: console
+
+  [root@exchange-online]# source /etc/libeufin/nexus.env
+  [root@exchange-online]# export LIBEUFIN_NEXUS_DB_CONNECTION
+  [root@exchange-online]# 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.
+
+
+Connecting Nexus with an EBICS account
+--------------------------------------
+
+The command line interface of the LibEuFin nexus 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/``.
+
+Next, we create a EBICS *bank connection* that nexus can use to communicate with the bank.
+
+.. code-block:: console
+
+  [root@exchange-online]# 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, 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
+
+  [root@exchange-online]# 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 syncronization 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
+
+  [root@exchange-online]# libeufin-cli connections get-key-letter $CONNECTION_NAME out.pdf
+
+.. code-block:: console
+
+  [root@exchange-online]# 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
+
+  [root@exchange-online]# libeufin-cli \
+      connections \
+        download-bank-accounts \
+          $CONNECTION_NAME
+
+It is now possible to list the accounts offered by the connection.
+
+.. code-block:: console
+
+  [root@exchange-online]# 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
+
+  [root@exchange-online]# 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.
+
+Testing: Requesting the transaction history
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+
+  [root@exchange-online]# 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
+
+  [root@exchange-online]# libeufin-cli accounts transactions $LOCAL_ACCOUNT_NAME
+
+Testing: Making payments
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+
+  [root@exchange-online]# 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 ``X.Y:CURRENCY``; for example
+``10:EUR``, or ``1.01:EUR``.
+
+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
+
+  [root@exchange-online]# libeufin-cli accounts submit-payment \
+        --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
+
+   [root@exchange-online]# libeufin-cli accounts task-schedule myacct \
+       --task-type="submit"
+       --task-name='submit-payments-hourly'
+       --task-cronspec='0 0 *'
+
+   [root@exchange-online]# 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
+
+   [root@exchange-online]# 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]
+
+
+Restoring a 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
+
+  [root@exchange-online]# libeufin-cli connections \
+      restore-backup \
+      --passphrase=$SECRET \
+      --backup-file=$BACKUP_FILE \
+      $CONNECTION_NAME
+
+
+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
+
+  [root@exchange-online]# 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
+
+  [root@exchange-online]# libeufin-cli facades list
+
+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
+
+  [root@exchange-online]# libeufin-cli users list
+  # [ ... shows available users ... ]
+
+  [root@exchange-online]# 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
+
+  [root@exchange-online]# libeufin-cli permissions grant \
+     user $USERNAME \
+     facade $FACADENAME \
+     facade.talerWireGateway.history
+
+  [root@exchange-online]# libeufin-cli permissions grant \
+     user $USERNAME \
+     facade $FACADENAME \
+     facade.talerWireGateway.transfer
+
+The list of all granted permissions can be reviewed:
+
+.. code-block:: console
+
+  [root@exchange-online]# libeufin-cli permissions list
+
+
+Exchange Wire Configuration
+---------------------------
 
 The exchange must be configured with the right settings to
 access the Taler Wire Gateway.  An exchange can be configured