commit 58cf85f57a11641ae254cbf54b1246b187f9eb69
parent 2eb665f052dec70085fe48fabf683d904ea373f7
Author: Florian Dold <florian@dold.me>
Date: Wed, 4 Aug 2021 19:38:24 +0200
document new configuration layout
Diffstat:
1 file changed, 57 insertions(+), 37 deletions(-)
diff --git a/taler-exchange-setup-guide.rst b/taler-exchange-setup-guide.rst
@@ -33,8 +33,8 @@ We recommend the setup of offline signing keys to be done on a second machine th
does not have internet access.
In the guide, we mark commands that are supposed to be executed on the online
-exchange machine as `[root@exchange-online]#` / `[$user@exchange-online]$` and commands for the offline
-machine as `[root@exchange-offline]#` /`[$user@exchange-offline]$`. It is possible to do the entire setup
+exchange machine as ``[root@exchange-online]#`` / ``[$user@exchange-online]$`` and commands for the offline
+machine as ``[root@exchange-offline]#`` / ``[$user@exchange-offline]$``. It is possible to do the entire setup
on one machine, but we do not recommend this for security reasons.
@@ -145,14 +145,14 @@ Services, users, groups and file system hierarchy
The *taler-exchange-httpd* package will create several system users
to compartmentalize different parts of the system:
- * taler-exchange-httpd: runs the HTTP daemon with the core business logic
- * taler-exchange-secmod-rsa: manages the RSA private online signing keys
- * taler-exchange-secmod-eddsa: manages the EdDSA private online signing keys
- * taler-exchange-closer: closes idle reserves by triggering wire transfers that refund the originator
- * taler-exchange-aggregator: aggregates deposits into larger wire transfer requests
- * taler-exchange-wire: performs wire transfers with the bank (via libeufin/nexus)
- * postgres: runs the Postgres database (from *postgres* package)
- * www-data: runs the frontend HTTPS service with the TLS keys (from *nginx* package)
+* taler-exchange-httpd: runs the HTTP daemon with the core business logic
+* taler-exchange-secmod-rsa: manages the RSA private online signing keys
+* taler-exchange-secmod-eddsa: manages the EdDSA private online signing keys
+* taler-exchange-closer: closes idle reserves by triggering wire transfers that refund the originator
+* taler-exchange-aggregator: aggregates deposits into larger wire transfer requests
+* taler-exchange-wire: performs wire transfers with the bank (via libeufin/nexus)
+* postgres: runs the Postgres database (from *postgres* package)
+* www-data: runs the frontend HTTPS service with the TLS keys (from *nginx* package)
.. note::
@@ -162,34 +162,34 @@ to compartmentalize different parts of the system:
The exchange setup uses the following system groups:
- * taler-exchange-db: group for all Taler users with direct database access, specifically taler-exchange-httpd, taler-exchange-wire, taler-exchange-closer and taler-exchange-aggregator
- * taler-exchange-secmod: group for processes with access to online signing keys, so taler-exchange-secmod-rsa, taler-exchange-secmod-eddsa and taler-exchange-httpd
- * taler-exchange-offline: group for the access to the offline private key (only used on the offline host and not used on the online system)
+* taler-exchange-db: group for all Taler users with direct database access, specifically taler-exchange-httpd, taler-exchange-wire, taler-exchange-closer and taler-exchange-aggregator
+* taler-exchange-secmod: group for processes with access to online signing keys, so taler-exchange-secmod-rsa, taler-exchange-secmod-eddsa and taler-exchange-httpd
+* taler-exchange-offline: group for the access to the offline private key (only used on the offline host and not used on the online system)
The package will deploy systemd service files in
``/usr/lib/systemd/system/`` for the various components:
- * taler-exchange-aggregator.service: service that schedules wire transfers which combine multiple deposits to the same merchant
- * taler-exchange-closer.service: service that watches for reserves that have been abandoned and schedules wire transfers to send the money back to the originator
- * taler-exchange-httpd.service: main Taler exchange logic with the public REST API
- * taler-exchange-httpd.socket: systemd socket activation for the Taler exchange HTTP daemon
- * taler-exchange-secmod-eddsa.service: software security module for making EdDSA signatures
- * taler-exchange-secmod-rsa.service: software security module for making RSA signatures
- * taler-exchange-transfer.service: service that triggers outgoing wire transfers (pays merchants)
- * taler-exchange-wirewatch.service: service that watches for incoming wire transfers (first step of withdraw)
- * taler-exchange.target: Main target for the Taler exchange to be operational
+* taler-exchange-aggregator.service: service that schedules wire transfers which combine multiple deposits to the same merchant
+* taler-exchange-closer.service: service that watches for reserves that have been abandoned and schedules wire transfers to send the money back to the originator
+* taler-exchange-httpd.service: main Taler exchange logic with the public REST API
+* taler-exchange-httpd.socket: systemd socket activation for the Taler exchange HTTP daemon
+* taler-exchange-secmod-eddsa.service: software security module for making EdDSA signatures
+* taler-exchange-secmod-rsa.service: software security module for making RSA signatures
+* taler-exchange-transfer.service: service that triggers outgoing wire transfers (pays merchants)
+* taler-exchange-wirewatch.service: service that watches for incoming wire transfers (first step of withdraw)
+* taler-exchange.target: Main target for the Taler exchange to be operational
The deployment creates the following key locations in the system:
- * /etc/taler/: configuration files
- * /var/run/taler/: contains the UNIX domain sockets for inter-process communication (IPC)
- * /var/lib/taler/: serves as the $HOME for all Taler users and contains sub-directories
- with the private keys; which keys are stored here depends on the host:
+* /etc/taler/: configuration files
+* /var/run/taler/: contains the UNIX domain sockets for inter-process communication (IPC)
+* /var/lib/taler/: serves as the $HOME for all Taler users and contains sub-directories
+ with the private keys; which keys are stored here depends on the host:
- - online system: exchange-secmod-eddsa and exchange-secmod-rsa keys
- - offline system: exchange-offline keys
+ * online system: exchange-secmod-eddsa and exchange-secmod-rsa keys
+ * offline system: exchange-offline keys
@@ -250,20 +250,34 @@ Typically only one Wire Gateway is used.
A Taler Wire Gateway is configured in a configuration section that follows the
pattern ``exchange-account-$id``, where ``$id`` is an internal identifier for
-the bank account accessed with the Wire Gateway. The configuration file
-``/etc/taler/conf.d/exchange-system.conf`` by default loads the section
-``exchange-account-1`` from the secret file
-``/etc/taler/secrets/exchange-accounts.secret.conf``. The latter file
-should already be only readable for the taler-exchange-wire user. Other
+the bank account accessed by the exchange. The basic information for an account should
+be put in ``/etc/taler/conf.d/exchange-business.conf``.
+The secret credentials to access the Taler Wire Gateway API should
+be put into a corresponding ``exchange-accountcredentials-$id`` section
+in ``/etc/taler/secrets/exchange-accountcredentials.conf``.
+The latter file
+should already be only readable for the ``taler-exchange-wire`` user. Other
exchange processes should not have access to this information.
.. code-block:: ini
- :caption: /etc/taler/secrets/exchange-accounts.secret.conf
+ :caption: /etc/taler/secrets/exchange-business.conf
[exchange-account-1]
enable_credit = yes
enable_debit = yes
+ # Account identifier in the form of an RFC-8905 payto:// URI
+ # For SEPA, looks like payto://sepa/$IBAN
+ payto_uri =
+
+ @inline-secret@ exchange-accountcredentials-1 ../secrets/exchange-accountcredendials.secret.conf
+
+
+.. code-block:: ini
+ :caption: /etc/taler/secrets/exchange-accountcredentials.secret.conf
+
+ [exchange-accountcredentials-1]
+
# LibEuFin expects basic auth
wire_gateway_auth_method = basic
@@ -274,9 +288,6 @@ exchange processes should not have access to this information.
# base URL of the wire gateway set up with LibEuFin
wire_gateway_url = ...
- # Account identifier in the form of an RFC-8905 payto:// URI
- # For SEPA, looks like payto://sepa/$IBAN
- payto_uri =
The Wire Gateway configuration can be tested with the following command:
@@ -531,6 +542,15 @@ a merchant backend is not required, as the wallet acts as a merchant.
# After enough time has passed, the money should arrive at the specified IBAN
+Summary of Variables
+====================
+
+This section summarizes all placeholder variables used in this document.
+
+
+TBD.
+
+
FIXMEs
======
