..
This file is part of GNU Taler.
Copyright (C) 2021 Taler Systems SA
GNU Taler is free software; you can redistribute it and/or modify it under the
terms of the GNU Affero General Public License as published by the Free Software
Foundation; either version 2.1, or (at your option) any later version.
GNU Taler is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with
GNU Taler; see the file COPYING. If not, see
@author Florian Dold
GNU Taler Exchange Setup Guide
##############################
This setup guide walks a system administrator through all steps required to
install an exchange and check that it is functional. For more background,
please read the Operator Manual.
System Requirements
===================
This guide assumes that you are running Ubuntu 20.04 (Focal Fossa).
We recommend the setup of offline signing keys to be done on a second machine that
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
on one machine, but we do not recommend this for security reasons.
Before you start
================
To deploy this with a real bank, you need:
* IBAN of the bank account to use
* BIC of the bank
* EBICS host, user and partner IDs
Information to write down during the installation:
* libeufin nexus superuser password
* Taler facade base URL
* exchange nexus username and password
Installation
============
We assume that the system is a minimal installation of Ubuntu 20.04 LTS.
Ideally, you should have two hosts, ``exchange-online`` and
``exchange-offline``. It is also possible to run the HTTPS nginx server or
the Postgres database on yet another host, but in these instructions we will
assume that only two hosts are used. Alas, the instructions will also work if
you run everything on one system, but then you have the security drawback of
not keeping the high-security private keys disconnected from the Internet.
To install the exchange, first make sure that your system is up-to-date
and that the ``gnupg`` package has been installed.
.. code-block:: shell-session
[root@exchange-online]# apt-get update
[root@exchange-online]# apt-get upgrade
Next, add the ``focal-fossa`` apt repository provided by Taler Systems S.A. to
your package sources:
.. code-block:: shell-session
[root@exchange-online]# cat > /etc/apt/sources.list.d/taler.list <
.. warning::
While ``taler-config`` also supports rewriting configuration files, we strongly
recommend to edit configuration files manually, as ``taler-config`` does not
preserve comments and, by default, rewrites ``/etc/taler/taler.conf``.
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)
.. note::
The *taler-merchant-httpd* package additionally creates a taler-merchant-httpd user
to runs the HTTP daemon with the merchant business logic.
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)
..
FIXME: "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 .... what?" Seems that this sentence lacks conclusion.
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
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:
* online system: exchange-secmod-eddsa and exchange-secmod-rsa keys
* offline system: exchange-offline keys
Setup Linting
=============
The ``taler-wallet-cli`` package comes with a experimental tool that runs various
checks on the current GNU Taler exchange deployment:
.. code-block:: shell-session
[root@exchange-online]# taler-wallet-cli deployment lint-exchange
You can optionally pass the ``--debug`` option to get more verbose output, and
``--continue`` to continue with further checks even though a previous one has
failed.
Basic Setup: Currency and Denominations
=======================================
A Taler exchange only supports a single currency. The currency
and the smallest currency unit supported by the bank system
must be specified in ``/etc/taler/taler.conf``.
.. code-block:: ini
:caption: /etc/taler/taler.conf
[taler]
CURRENCY = EUR
CURRENCY_ROUND_UNIT = EUR:0.01
# ... rest of file ...
.. warning::
When editing ``/etc/taler/taler.conf``, take care to not accidentally remove
the @inline-matching@ directive to include the configuration files in ``conf.d``.
Next, the electronic cash denominations that the exchange offers must be
specified. The ``taler-wallet-cli`` has a helper command that generates a
reasonable denomination structure.
.. code-block:: shell-session
taler-wallet-cli deployment gen-coin-config --min-amount EUR:0.01 --max-amount EUR:100 > /etc/taler/conf.d/exchange-coins.conf
.. note::
FIXME: change tool to not take currency from configuration, but instead
to accept unit currency as the argument; (i.e. EUR:0.0025). Also take
another argument for how many denominations to generate (2^XX). Finally,
do use the unit currency as the default deposit fee.
You can manually review and edit the generated configuration file. The main
change that is possibly required is updating the various fees.
Wire Gateway Setup
==================
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.
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 `
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.
..
FIXME: 'dbinit' isn't a (exact) name for exchane and merchant, but this way
the reader might wrongly think it is. Also, steps that should NOT be taken
could - by not being mentioned - spare time (to the reader) and space to the
document. So the part after comma for me can be removed.
.. 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]# NEXUS_ADMIN_PW=$(tr -dc A-Za-z0-9
The public key printed as the output of this command must be put into the configuration
of the online machine:
.. code-block:: ini
:caption: /etc/taler/conf.d/exchange-business.conf
[exchange]
MASTER_PUBLIC_KEY = YE6Q6TR1ED...
# ... rest of file ...
Exchange Web service / API Setup
================================
By default, the ``taler-exchange-httpd`` service listens for HTTP connections
on a UNIX domain socket. To make the service publicly available, a reverse
proxy such as nginx should be used. We strongly recommend to configure nginx
to use TLS.
The public URL that the exchange will be served under should
be put in ``/etc/taler/conf.d/exchange-business.conf`` configuration file.
.. code-block:: ini
:caption: /etc/taler/conf.d/exchange-business.conf
[exchange]
BASE_URL = https://example.com/
# ... rest of file ...
The ``taler-exchange`` package ships with a sample configuration that can be
enabled in nginx:
.. code-block:: shell-session
[root@exchange-online]# vim /etc/nginx/sites-available/taler-exchange
< ... customize configuration ... >
[root@exchange-online]# ln -s /etc/nginx/sites-available/taler-exchange \
/etc/nginx/sites-enabled/taler-exchange
[root@exchange-online]# systemctl reload nginx
The exchange HTTP service can now be started:
.. code-block:: shell-session
[root@exchange-online]# systemctl start taler-exchange.target
.. note::
At this point, the exchange service is not yet fully operational.
To check whether the exchange is running correctly under the advertised
base URL, run:
.. code-block:: shell-session
[root@exchange-online]# export BASE_URL=$(taler-config -s exchange -o base_url)
[root@exchange-online]# wget ${BASE_URL}management/keys
Offline Signing Procedure
=========================
The exchange HTTP service should be running now, but is not yet completely
operational. To make the exchange HTTP service operational, the following
steps involving the offline signing machine must be completed:
1. The public keys of various online keys used by the exchange service are exported
via a management HTTP API
2. The offline signing system validates this request and signs it.
Additionally, the offline signing system signs policy messages
to configure the exchange's bank accounts and associated fees.
3. The messages generated by the offline signing system are uploaded
via the management API of the exchange HTTP service.
.. code-block:: shell-session
[root@exchange-online]# taler-exchange-offline \
download > sig-request.json
[root@exchange-offline]# taler-exchange-offline \
sign < sig-request.json > sig-response.json
[root@exchange-offline]# taler-exchange-offline \
enable-account payto://sepa/$IBAN > acct-response.json
[root@exchange-offline]# taler-exchange-offline \
wire-fee 2021 sepa EUR:0 EUR:0 > fee-response.json
[root@exchange-online]# taler-exchange-offline upload < sig-response.json
[root@exchange-online]# taler-exchange-offline upload < acct-response.json
[root@exchange-online]# taler-exchange-offline upload < fee-response.json
Testing and Troubleshooting
===========================
The following shell session illustrates how the wallet can be used to withdraw
electronic cash from the exchange and subsequently spend it. For these steps,
a merchant backend is not required, as the wallet acts as a merchant.
.. code-block:: shell-session
# This will now output a payto URI that money needs to be sent to in order to allow withdrawal
# of taler coins
$ taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE_URL --amount EUR:10.50
# Show the status of the manual withdrawal operation
$ taler-wallet-cli transactions
#
# At this point, a bank transfer to the exchange's bank account
# needs to be made with the correct subject / remittance information
# as instructed by the wallet after the first step.
#
# Check whether the exchange received an incoming bank transfer
[root@exchange-online]# taler-exchange-wire-gateway-client --section exchange-account-1 --credit-history
# FIXME: this one above fails, complaining that the section's name doesn't begin with `exchange-accountcredentials-`
# Blocks also the further steps from being taken. Should the include in line 33 point inside the "secrets" directory?
# https://git.taler.net/exchange.git/tree/debian/etc-taler-exchange/taler/conf.d/exchange-business.conf?id=289b816e1cd1a56a0b82582b69bff22c55e6b8a0
# Once the transfer has been made, try completing the withdrawal
$ taler-wallet-cli run-pending
# Check status of transactions and show balance
$ taler-wallet-cli transactions
$ taler-wallet-cli balance
# Now, directly deposit coins with the exchange into a target account
# (Usually, a payment is made via a merchant. The wallet provides
# this functionality for testing.)
$ taler-wallet-cli deposit create EUR:5 payto://sepa/$IBAN
# Check if transaction was successful.
# (If not, fix issue with exchange and run "run-pending" command again)
$ taler-wallet-cli transactions
# The wallet can also track if the exchange wired the money to the merchant account.
# The "deposit group id" can be found in the output of the transactions list.
$ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID
# Check whether the exchange sent an outgoing transfer
[root@exchange-online]# taler-exchangewire-gateway-client --section exchange-account-1 --debit-history
# 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
======
* We should have some summary with the inventory of services that should be
running. Systemd by default doesn't show this nicely. Maybe suggest running
"systemd list-dependencies taler-exchange.target"?
* When multiple TWGs are configured, which one will be used by the taler-exchange-transfer?
* On Ubuntu focal fossa, I get the following warning on "apt update", are we doing something wrong?
N: Skipping acquire of configured file 'main/binary-i386/Packages' as
repository 'https://deb.taler.net/apt/ubuntu focal-fossa InRelease' doesn't
support architecture 'i386'