[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: Ubuntu setup guide WIP
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: Ubuntu setup guide WIP |
Date: |
Mon, 02 Aug 2021 19:06:46 +0200 |
This is an automated email from the git hooks/post-receive script.
dold pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 49f3a25 Ubuntu setup guide WIP
49f3a25 is described below
commit 49f3a2582a63ebdc4dfbcce4a0c3bd93f9307855
Author: Florian Dold <florian@dold.me>
AuthorDate: Mon Aug 2 19:06:41 2021 +0200
Ubuntu setup guide WIP
---
index.rst | 1 +
taler-exchange-setup-guide.rst | 351 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 352 insertions(+)
diff --git a/index.rst b/index.rst
index 6e18201..6f849b2 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 0000000..b439310
--- /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?
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: Ubuntu setup guide WIP,
gnunet <=