1 files changed, 87 insertions, 0 deletions
diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst
new file mode 100644
index 00000000..76f51bfe
--- /dev/null
+++ b/frags/nexus-ebics-setup.rst
@@ -0,0 +1,87 @@
+
+When you sign up for an EBICS-enabled bank account, the bank will provide you
+with various credentials. Those must be provided in the
+``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the
+name of the *fiat* currency.
+
+.. note::
+  As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history.
+
+The following snippet shows the mandatory configuration values:
+
+.. _core-config:
+
+.. code-block:: ini
+
+  [nexus-ebics]
+  CURRENCY = CHF
+
+  # Bank
+  HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx
+  BANK_DIALECT = postfinance
+
+  # EBICS IDs
+  HOST_ID = PFEBICS
+  USER_ID = PFC00563
+  PARTNER_ID = PFC00563
+
+  # Account information
+  IBAN = CH7789144474425692816
+  BIC = POFICHBEXXX
+  NAME = John Smith S.A.
+
+.. note::
+  Refer to the manpage ``libeufin-nexus.conf(5)``
+  for the full array of configuration values.
+
+.. warning::
+  This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost.
+
+Reuse existing client keys
+--------------------------
+
+If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config).
+
+Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run:
+
+.. code-block:: console
+
+  $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json
+
+Create new client keys
+----------------------
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command should start the EBICS setup process:
+
+.. code-block:: console
+
+  $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+If the previous command failed when running EBICS INI with an error code of
+``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to
+activate your account.
+
+To that end, the previous run should have left a PDF document that you can
+print, sign and send to the bank.  Look for the message that looks like ``PDF
+file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``.
+
+Once the bank has received and processed this document you can continue.
+
+Get bank keys
+-------------
+
+Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
+command will finish the EBICS setup process:
+
+.. code-block:: console
+
+  $ libeufin-nexus ebics-setup -c "$CONFIG_FILE"
+
+The EBICS setup is finished once the bank keys have been accepted.
+
+Make sure this bank keys are accessible to the user running ``libeufin-nexus``, for the default services you should run:
+
+.. code-block:: console
+
+  $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/bank-ebics-keys.json