1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
..
This file is part of GNU TALER.
Copyright (C) 2014-2024 Taler Systems SA
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.
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
TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
@author Florian Dold
@author Marcello Stanisci
@author Christian Grothoff
.. target audience: operator
Regional Currency Automated Setup Manual
########################################
This manual describes how to setup a regional currency backed by a fiat currency using a script that largely automates the process. If you want to do a custom setup you can follow the :doc:`custom setup manual<regional-custom-manual>`.
.. contents:: Table of Contents
:local:
.. include:: ../frags/regional-manual-architecture.rst
Guided Automated Setup
======================
Prerequisites
+++++++++++++
For this manual, we assume that the system is deployed on a contemporary
Debian GNU/Linux or Ubuntu LTS system using the binary packages provided.
Furthermore, you should run the process on a system with one or more globally
reachable IP address(es) *and* with various DNS names already pointing to
these IPs.
Preparing the required subdomain names
++++++++++++++++++++++++++++++++++++++
The GNU Taler program needs to have three subdomains pointing to your server IP address, in order to let NGINX to accommodate each component.
These are "bank", "exchange" and "backend", this said, you need to have a registered top level domain name,
where you can create type (A) entries, as subdomains pointing to your own server public IP address.
A very good advice when creating these subdomains, and if your domain panel lets you specify the TTL (time to live) figure, is
to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly.
Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have
propagated over the Internet correctly, and they are currently publicly available.
You can check this from your terminal very easily with the "ping" command, as this:
.. code-block:: console
$ ping -c1 bank.domainname.ltd
$ ping -c1 exchange.domainname.ltd
$ ping -c1 backend.domainname.ltd
You can also use `this tool <https://toolbox.googleapps.com/apps/dig/>`_ for the same purpose, and to check the propagation status.
Now you are ready to go with the next step.
Obtaining the Scripts
+++++++++++++++++++++
First, download the deployment scripts via Git:
.. code-block:: console
# apt update && apt install git
$ git clone git://git.taler.net/deployment
Running the Guided Configuration
++++++++++++++++++++++++++++++++
Navigate into the *regional-currency/* directory and run *main.sh* as **root**:
.. code-block:: console
$ cd deployment/regional-currency/
# ./main.sh
The script will start by installing required packages and then asking you fundamental questions about the desired setup, in particular :
#. The name of the regional currency. It must have 3 to 11 letters.
#. The ISO code of the fiat currency. Use 'CHF' or 'EUR'.
#. The name of the regional currency bank. It will be shown to business users when they interact with the system.
#. The DNS domain name of your setup (i.e: domain.tld). The installer will create by itself all the needed subdomains for your domain name, as (``bank.$DOMAIN``, ``exchange.$DOMAIN`` and ``backend.$DOMAIN``). But, these subdomain names as explained before, must have been added beforehand to your DNS domain control panel, and they must be pointing to the IP address of the server on which you are running the installation (before you execute the installer).
#. Whether to use TLS or not. You should answer ``y`` in most cases.
#. Whether to store Taler Exchange keys on this server or externally on another server. Unless you need a high-security setup and expect to run an offline key management process, say ``y``. If you say ``n``, you will need to run ``taler-exchange-offline setup`` on your offline system and provide the master public key. Furthermore, you should then study the exchange manual on offline key management to finish the exchange setup process later.
#. Whether to setup sms two-factor authentication using Telesign. You should answer ``y`` in most cases.
#. The admin password for the bank. Be absolutely sure to enter a very, very long and high-entropy password, preferably use the autogenerated one.
The information you entered as well as the generated bank admin password will
be stored in a file called ``config/user.conf``. If you run the script in
the future again (for example, to upgrade the installation), you will not be asked
these questions a second time.
After answering all of the questions, the actual installation will start. The
scripts will download and configure various packages, which may take some time.
Grab a coffee.
.. note::
At this point, the setup is NOT connected to any fiat bank account! The next
steps must always be done manually!
Running the script again from scratch
+++++++++++++++++++++++++++++++++++++
If for some reason your installation doesn't work because you have answered erroneously
some of the interactive questions, or you just want to reset the current installation and to re-deploy
the script again for having its latest changes, you will have to proceed as follows:
In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean
to remove the file itself, but only its content. Even though you can do this manually by editing the file manually
with you preferred text editor, you can also do this in one single command.
.. code-block:: console
# rm config/user.conf
.. note::
In future versions of the program when executed for the second time, the program itself will
show an option to offer wiping the content of this config/user.conf file, automatically.
Multi-factor authentication
+++++++++++++++++++++++++++
The script allows you to configure multi-factor authentication via SMS using Telesign as a provider. You can also configure multi-factor authentication via email or use providers other than Telesign for SMS. You will need to configure these channels manually as described in :ref:`multi-factor authentication <libeufin-mfa>`.
Web-based Configuration
+++++++++++++++++++++++
By default, the regional currency conversion rates are 1:1. You can change the conversion rates and the ``admin`` debt limit via the bank's web interface as the ``admin`` user.
Connecting to a Fiat Bank: the EBICS setup
++++++++++++++++++++++++++++++++++++++++++
To complete the conversion setup, you have to set up an EBICS subscriber using a fiat bank account at a bank dealing in fiat currency that offers an online banking protocol supported by LibEuFin Nexus.
.. include:: ../frags/nexus-ebics-setup.rst
Configuring the Exchange for Conversion
+++++++++++++++++++++++++++++++++++++++
This section explains how to enable currency conversion at the exchange,
which is critical for wallets to know how to wire fiat currency to an
exchange to obtain regional currency.
You will need to use the ``taler-exchange-offline`` tool to inform the
exchange about the **fiat** bank account that can be used for cash in
operations and also specify the URL for currency conversion. Additionally,
you may also configure restrictions on the bank accounts that may originate
the funds, for example, to prevent international wire transfers that may expose
you to additional compliance risks.
Given the ``$IBAN`` of the fiat currency bank account and ``$NAME`` as
the (URL-encoded) name of the exchange-account owner, the following
``taler-exchange-offline`` invocation can be used to notify wallets about
the possibility of currency conversion (cash in):
.. code-block:: console
# taler-exchange-offline \
enable-account \
payto://iban/$IBAN?receiver-name=$NAME \
conversion-url "$CONVERSION_URL" \
upload
Here, the ``$CONVERSION_URL`` must be set to the base URL of the conversion
endpoint of the bank, which should be ``https://bank.$DOMAIN/conversion-info/``
in our setup.
.. note::
The above command adds a **second** bank account to the exchange.
You (or the guided setup script) should have already enabled the
regional currency bank account (without any "conversion-url").
System ON!
++++++++++
The last step is to enable libeufin-nexus to :ref:`import incoming bank
transactions <receive-transaction-data>` (cash in) and to :ref:`trigger
outgoing bank transactions <sending-payments>` (cash out).
.. code-block:: console
# systemctl enable --now libeufin-nexus.target
.. include:: ../frags/regional-manual-use.rst
|
