Ubuntu setup guide WIP

2 files changed, 352 insertions, 0 deletions

diff --git a/index.rst b/index.rst
index 6e182011..6f849b2b 100644
--- a/index.rst
+++ b/index.rst
@@ -57,6 +57,7 @@ Documentation Overview
 
   core/index
   taler-exchange-manual
+  taler-exchange-setup-guide
   taler-merchant-manual
   taler-wallet-cli-manual
   taler-nfc-guide.rst
diff --git a/taler-exchange-setup-guide.rst b/taler-exchange-setup-guide.rst
new file mode 100644
index 00000000..b4393105
--- /dev/null
+++ b/taler-exchange-setup-guide.rst
@@ -0,0 +1,351 @@
+..
+  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 <http://www.gnu.org/licenses/>
+
+  @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.
+
+Installation
+============
+
+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
+  [root@exchange-online]# apt-get install -y gnupg
+
+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 <<EOF
+  deb https://deb.taler.net/apt/ubuntu focal-fossa main
+  EOF
+
+Before installing Taler packages, you need to add the Taler Systems S.A. package
+signing key to your list of trusted keys and update the package index:
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
+  [root@exchange-online]# apt-get update
+
+Finally, the required packages can be installed:
+
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# apt-get install nginx postgresql
+  [root@exchange-online]# apt-get install taler-exchange taler-exchange-offline
+  [root@exchange-online]# apt-get install taler-merchant taler-wallet-cli
+
+By default, all installed services will be disabled.  You need to enable
+and start them later.
+
+While ``taler-merchant`` and ``taler-wallet`` are not required to operate an
+exchange, they are useful for testing.
+
+
+Configuration Basics
+====================
+
+The configuration for all Taler components uses a single configuration file
+as entry point: ``/etc/taler/taler.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taler/config.d``.  These default files should never be modified.
+
+The default configuration ``taler.conf`` configuration file also includes all
+configuration files in ``/etc/taler/conf.d``.  The settings from files in
+``conf.d`` are only relevant to particular components of Taler, while
+``taler.conf`` contains settings that affect all components.
+
+
+The directory ``/etc/taler/secrets`` contains configuration file snippets with
+values that should only be readable to certain users.  They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taler-config`` helper:
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# taler-config --diagnostics
+  < ... annotated, full configuration ... >
+
+.. 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
+=================================================
+
+(FIXME:  Explain the Debian package users, groups and locations.)
+
+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.conf``.
+
+.. code-block:: ini
+  :caption: /etc/taler.conf
+
+   [taler]
+   CURRENCY = EUR
+   CURRENCY_ROUND_UNIT = EUR
+
+   # ... rest of file ...
+
+.. warning::
+
+   When editing ``/etc/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 --currency EUR > /etc/taler/conf.d/exchange-coins.conf
+
+You can manually review and edit the generated configuration file.
+
+
+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.
+Please follow the setup instructions in ??? to set up a Taler Wire Gateway with
+LibEuFin for an EBICS bank account.
+
+The exchange must be configured with the right settings to
+access the Taler Wire Gateway.  An exchange can be configured
+to use multiple bank accounts by using multiple Wire Gateways.
+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``.
+
+
+.. code-block:: ini
+  :caption: /etc/taler/secrets/exchange-accounts.secret.conf
+
+  [exchange-account-1]
+  enable_credit = yes
+  enable_debit = yes
+  
+  # LibEuFin expects basic auth
+  wire_gateway_auth_method = basic
+
+  # username and password set in LibEuFin
+  username = ...
+  password = ...
+  
+  # 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:
+
+.. code-block:: shell-session
+
+   [root@exchange-online]# taler-wire-gateway-client --section exchange-account-1 --debit-history
+   [root@exchange-online]# taler-wire-gateway-client --section exchange-account-1 --credit-history
+
+Exchange Database Setup
+=======================
+
+The access credentials for the exchange's database are configured in
+``/etc/taler/secrets/exchange-db.secret.conf``.  Currently, only postgres is
+supported as a database backend.
+
+The following users must have access to the exchange database:
+
+* taler-exchange-httpd
+* taler-exchange-wire
+* taler-exchange-aggregator
+* taler-exchange-closer
+
+After configuring the database credentials, the exchange database needs
+to be initialized with the following command:
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# sudo -u taler-exchange-httpd taler-exchange-dbinit
+
+
+Offline Signing Setup
+=====================
+
+The offline signing keys of the exchange should be stored on a different machine.
+The responsibilities of this offline signing machine are:
+
+* generation of the exchange's offline master signing key
+* secure storage of the exchange's offline master signing key
+* generation of certificates (signed with the offline master signing key) that will be imported by the exchange
+
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# sudo -u taler-exchange-offline taler-exchange-offline setup
+  < ... prints the exchange master public key >
+
+The public key printed as the output of this command should 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]# cp /etc/nginx/sites-available/taler-exchange /etc/nginx/sites-enabled/
+  [root@exchange-online]# vim /etc/nginx/sites-enabled/taler-exchange
+  < ... customize configuration ... >
+  [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.service
+  [root@exchange-online]# export BASE_URL=$(taler-config -s exchange -o base_url)
+  [root@exchange-online]# curl ${BASE_URL}management/keys
+
+
+.. note::
+
+   At this point, the exchange service not yet fully operational.
+
+
+To check whether the exchange is running correctly under the advertise
+base URL, run:
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# export BASE_URL=$(taler-config -s exchange -o base_url)
+  [root@exchange-online]# curl ${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
+   to 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-response.json
+  [root@exchange-offline]# taler-exchange-offline enable-account payto://sepa/$IBAN > acct-response.json
+  [root@exchange-offline]# taler-exchange-offline enable-account 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
+===========================
+
+
+FIXMEs
+======
+
+* we should have some summary with the inventory of services that should be running
+* how do we know what offline signing steps are still required?  We don't have
+  a tool for that ...
+* we need a better way to validate that the exchange is actually working correctly
+* when multiple TWGs are configured, which one will be used by the taler-exchange-transfer?