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