commit ff6db32eeed6555607d12222d63bbb1caef71b4c
parent 83429780e5f459ebcc969e6eef91f62fa4e3f5c9
Author: Antoine A <>
Date: Sat, 6 Dec 2025 17:41:32 +0100
ebisync: improve manual
Diffstat:
2 files changed, 71 insertions(+), 23 deletions(-)
diff --git a/libeufin/ebisync-manual.rst b/libeufin/ebisync-manual.rst
@@ -80,13 +80,40 @@ Navigate into the *libeufin* local repository, and from top-level run:
.. code-block:: console
$ ./bootstrap
- $ ./configure --prefix=$PREFIX
- $ make install
-If the previous steps succeeded, the ``libeufin-ebisync`` command should
-be found in the $PATH.
+Install deb package
+~~~~~~~~~~~~~~~~~~~
-.. _ebisync-setup:
+To install EbiSync as a Debian/Ubuntu package with an automated secure setup and systemd services:
+
+.. code-block:: console
+
+ $ sudo apt install debhelper
+ $ make deb
+ $ sudo dpkg -i ../libeufin-ebisync*.deb
+
+If the previous steps succeeded, the ``libeufin-ebisync`` command should be found in the $PATH.
+
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *libeufin-ebisync* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``libeufin-ebisync``: runs the EBICS fetcher.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``libeufin-ebisync-fetch.service``: worker daemon that retrieves files via EBICS and upload them to a destination.
+* ``libeufin-ebisync.target``: main target for EbiSYnc to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/libeufin-ebisync/``: configuration files.
+* ``/var/lib/libeufin-ebisync/``: serves as the $HOME for libeufin-ebisync and contains the EBICS authentication keys.
Database setup
==============
@@ -96,6 +123,7 @@ tells EbiSync how it should connect to the database. The default
is:
.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/secrets/ebisync-db.secret.conf
[ebisyncdb-postgres]
config = postgres:///libeufin-ebisync
@@ -106,13 +134,10 @@ created (or updated) to the current EbiSync version using the following command:
.. code-block:: console
- $ libeufin-ebisync dbinit -c "$CONFIG_FILE"
-
-where ``$CONFIG_FILE`` is again the path to a configuration that contains at
-least the above ``[ebisyncdb-postgres]`` section.
+ $ sudo libeufin-ebisync-dbconfig
-Setting up the EBICS subscriber
-===============================
+EBICS setup
+===========
When you sign up for an EBICS-enabled bank account, the bank will provide you
with various credentials. Those must be provided in the
@@ -123,6 +148,7 @@ The following snippet shows the mandatory configuration values:
.. _core-config:
.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/libeufin-ebisync.conf
[ebisync]
# Bank
@@ -155,12 +181,11 @@ Make sure this file is accessible to the user running ``libeufin-ebisync``, for
Create new client keys
----------------------
-Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
-command should start the EBICS setup process:
+The following command should start the EBICS setup process:
.. code-block:: console
- $ libeufin-ebisync setup -c "$CONFIG_FILE"
+ $ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf
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
@@ -175,20 +200,44 @@ 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:
+The following command will finish the EBICS setup process:
.. code-block:: console
- $ libeufin-ebisync setup -c "$CONFIG_FILE"
+ $ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf
The EBICS setup is finished once the bank keys have been accepted.
-Make sure this bank keys are accessible to the user running ``libeufin-ebisync``, for the default services you should run:
+Fetch destination setup
+=======================
+
+Azure Blob Storage
+------------------
+
+The following snippet shows the mandatory configuration values:
+
+.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/conf.d/ebisync-fetch.conf
+
+ [ebisync-fetch]
+ DESTINATION = azure-blob-storage
+
+Some configuration values are sensitive and must be written to a secret configuration file that is only accessible to the ``libeufin-ebisync`` user.
+
+.. code-block:: ini
+ :caption: /etc/libeufin-ebisync/secrets/ebisync-fetch.secret.conf
+
+ [ebisync-fetch]
+ AZURE_API_URL = https://myaccount.blob.core.windows.net/
+ AZURE_ACCOUNT_NAME = myaccount
+ AZURE_ACCOUNT_KEY = Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==
+ AZURE_COUNTAINER = mycontainer
+
+The following command will finish the fetcher setup process:
.. code-block:: console
- $ chown libeufin-ebisync:libeufin-ebisync /var/lib/libeufin-ebisync/bank-ebics-keys.json
+ $ sudo -u libeufin-ebisync libeufin-ebisync setup -c /etc/libeufin-ebisync/libeufin-ebisync.conf
Fetching files
==============
@@ -234,12 +283,11 @@ The checkpoint time of day **may** be specified as
[ebisync-fetch]
CHECKPOINT_TIME_OF_DAY = 19:00
-Assuming that ``$CONFIG_FILE`` contains all required options, the following
-command would download any unseen EBICS files:
+The following command would download any unseen EBICS files:
.. code-block:: console
- $ libeufin-ebisync fetch -c "$CONFIG_FILE" --transient
+ $ sudo -u libeufin-ebisync libeufin-ebisync fetch -c /etc/libeufin-ebisync/libeufin-ebisync.conf --transient
The ``fetch`` subcommand will always cause libeufin-ebisync to download EBICS files and upload them to the configured destination.
diff --git a/manpages/libeufin-ebisync.1.rst b/manpages/libeufin-ebisync.1.rst
@@ -1,5 +1,5 @@
libeufin-ebisync(1)
-#################
+###################
.. only:: html
