GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic techniques. GNU Taler allows customers to remain anonymous, while ensuring that merchants can be held accountable by governments. Hence, GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR).
This manual targets system administrators who want to install a GNU Taler merchant backend.
We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required.
This first chapter of the manual will give a brief overview of the overall Taler architecture, describing the environment in which the Taler backend operates. The second chapter then explains how to install the software, including key dependencies. The third chapter will explain how to configure the backend, including in particular the configuration of the bank account details of the merchant.
The last chapter gives some additional information about advanced topics which will be useful for system administrators but are not necessary for operating a basic backend.
Taler is a pure payment system, not a new crypto-currency. As such, it operates in a traditional banking context. In particular, this means that in order to receive funds via Taler, the merchant must have a regular bank account, and payments can be executed in ordinary currencies such as USD or EUR. Taler can also be used as a regional currency; for such scenarios, the Taler system also includes its own stand-alone bank.
The Taler software stack for a merchant consists of four main components:
The following image illustrates the various interactions of these key components:
Basically, the backend provides the cryptographic protocol support, stores Taler-specific financial information in a DBMS and communicates with the GNU Taler exchange over the Internet. The frontend accesses the backend via a RESTful API. As a result, the frontend never has to directly communicate with the exchange, and also does not deal with sensitive data. In particular, the merchant’s signing keys and bank account information are encapsulated within the Taler merchant backend.
A typical deployment will additionally include a full-blown Web server (like
Apache or Nginx). Such a Web server would be responsible for TLS termination and
access control to the /private/
and /management/
API endpoints of the
merchant backend. Please carefully review the section on secure setup before deploying a Taler merchant backend into production.
This chapter describes some of the key concepts used throughout the manual.
The backend allows a single HTTP server to support multiple independent shops
with distinct business entities sharing a single backend. An instance is
the name or identifier that allows the single HTTP server to determine which
shop a request is intended for. Each instance has its own base URL in the
REST API of the merchant backend (/instances/$INSTANCE/
). Each instance
can use its own bank accounts and keys for signing contracts. All major
accounting functionality is separate per instance. Access to each instance is
controlled via a bearer token (to be set in the HTTP “Authorization” header).
All instances share the same database, top-level HTTP(S) address and the
main Taler configuration (especially the accepted currency and exchanges).
Note
This documentation does not use the term “user” or “username” in conjunction with instances as that might create confusion between instances with paying customers using the system. We also do not use the term “account” in conjunction with instances, as that might cause confusion with bank accounts. That said, conceptually it is of course acceptable to consider instances to be the “users” or “accounts” of a merchant backend and the bearer token is equivalent to a passphrase.
To receive payments, an instance must have configured one or more bank accounts. When configuring the bank account of an instance, one should ideally also provide the address and credentials of an HTTP service implementing the Taler Bank Merchant HTTP API. Given such a service, the GNU Taler merchant backend can automatically reconcile wire transfers from the exchange to the merchant’s bank account with the orders that are being settled.
This documentation exclusively uses the term account for the bank accounts of a merchant or shop that may be associated with an instance.
The Taler backend offers inventory management as an optional function. Inventory is tracked per instance and consists of products sold in units. Inventory can be finite (physical stock) or infinite (for digital products). Products may include previews (images) to be shown to the user as well as other meta-data. Inventory management allows the frontend to lock products, reserving a number of units from stock for a particular (unpaid) order. The backend can keep track of how many units of a product remain in stock and ensure that the number of units sold does not exceed the number of units in stock.
Inventory management is optional, and it is possible for the frontend to include products in orders that are not in the inventory. The frontend can also override prices of products in the inventory or set a total price for an order that is different from the price of the sum of the products in the order.
In Taler, users pay merchants for orders. An order is first created by the merchant. To create an order, the merchant must specify the specific terms of the order. Order terms include details such as the total amount to be paid, payment fees the merchant is willing to cover, the set of products to deliver, a delivery location and many other details. The merchant API specification specifies the full set of possible order terms.
After an order is created, it is claimed by a wallet. Once an order is claimed by a specific wallet, only that wallet will be able to pay for this order, to the exclusion of other wallets even if they see the same order URL. Sharing order URLs is explicitly allowed: if a user shares an order URL with another user, that other user should be given the opportunity to purchase the same product.
To prevent unauthorized wallets from claiming an order, merchants can specify that claims require authorization in the form of a claim token. This is useful in case the order ID is predictable (say because an existing order ID scheme with predictable order IDs from the merchant frontend is used) and at the same time malicious actors claiming orders is problematic (say because of limited stocks). The use of claim tokens is optional, but if a claim token is used, it must be provided to the wallet as part of the order URI.
Additionally, when stocks are limited, you can configure Taler to set a product lock on items (say, while composing the shopping cart). These locks will ensure that the limited stock is respected when making offers to consumers.
A wallet may pay for a claimed order, at which point the order turns into a
(paid) contract. Orders have a configurable expiration date (the
pay_deadline
) after which the commercial offer expires and any stock of
products locked by the order will be automatically released, allowing the
stock to be sold in other orders. When an unpaid order expires, the customer
must request a fresh order if they still want to make a purchase.
Once a contract has been paid, the merchant should fulfill the contract. It is possible for the merchant to refund a contract order, for example if the contract cannot be fulfilled after all. Refunds are only possible after the customer paid and before the exchange has wired the payment to the merchant. Once the funds have been wired, refunds are no longer allowed by the Taler exchange. The wire deadline specifies the latest point in time by which an exchange must wire the funds, while the (earlier) refund deadline specifies the earliest point in time when an exchange may wire the funds. Thus, refunds are always possible between the time of purchase and the refund deadline, but may remain possible until the wire deadline.
Contract information is kept for legal reasons in the merchant database. The
main legal reason is typically to provide tax records in case of a tax audit.
After the legal expiration (by default: a decade), contract information is
deleted when running the garbage collector using taler-merchant-dbinit
.
The Taler backend can be used to verify that the exchange correctly wired all of the funds to the merchant. However, if no Taler Bank Merchant HTTP API was provided for the respective bank account, the backend does not have access to the incoming wire transfers of the merchant’s bank account. In this case, merchants must manually provide the backend with wire transfer data that specifies the wire transfer subject and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise.
Taler does not only allow a Website to be paid, but also to make voluntary, non-contractual payments to visitors, called tips. Such tips could be granted as a reward for filling in surveys or watching advertizements. For tips, there is no contract, tips are always voluntary actions by the Web site that do not arise from a contractual obligation. Before a Web site can create tips, it must establish a reserve. Once a reserve has been established, the merchant can grant tips, allowing wallets to pick up the tip.
..note:
Tipping is an optional feature, and exchanges may disable tipping (usually if they see compliance issues). In this case, the tipping feature will not be available.
A reserve is a pool of electronic cash at an exchange under the control of a private key. Merchants withdraw coins from a reserve when granting tips. A reserve is established by first generating the required key material in the merchant backend, and then wiring the desired amount of funds to the exchange.
An exchange will automatically close a reserve after a fixed period of time (typically about a month), wiring any remaining funds back to the merchant. While exchange APIs exists to (1) explicitly open a reserve to prevent it from being automatically closed and to (2) explicitly close a reserve at any time, the current merchant backend does not make use of these APIs.
This chapter describes how to install the GNU Taler merchant backend.
The following instructions will show how to install a GNU Taler merchant backend from source.
The package sources can be find in our download directory.
GNU Taler components version numbers follow the MAJOR.MINOR.MICRO
format.
The general rule for compatibility is that MAJOR
and MINOR
must match.
Exceptions to this general rule are documented in the release notes.
For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x
as the MAJOR version matches. A MAJOR version of 0 indicates experimental
development, and you are expected to always run all of the latest releases
together (no compatibility guarantees).
First, the following packages need to be installed before we can compile the backend:
python3-sphinx-rtd-theme
on Debian-based systems (for GNUnet documentation support, can be
omitted if GNUnet is configured with --disable-documentation
)jinja2
If you are on Debian stable or later, the following command may help you install these dependencies:
# apt-get install \
libqrencode-dev \
libsqlite3-dev \
libltdl-dev \
libunistring-dev \
libsodium-dev \
libargon2-dev \
libcurl4-gnutls-dev \
libgcrypt20-dev \
libjansson-dev \
libpq-dev \
libmicrohttpd-dev \
python3-jinja2 \
postgresql-13
Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler.
To install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows:
$ ./configure [--prefix=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
# ldconfig
If you did not specify a prefix, GNUnet will install to /usr/local
,
which requires you to run the last step as root
.
The ldconfig
command (also run as root
) makes the
shared object libraries (.so
files)
visible to the various installed programs.
Please note that unlike most packages, if you want to run the make check
command, you should run it only after having done make install
. The
latter ensures that necessary binaries are copied to the right place.
In any case, if make check
fails, please consider filing a
bug report with the Taler bug tracker.
There is no need to actually run a GNUnet peer to use the Taler merchant backend – all the merchant needs from GNUnet is a number of headers and libraries!
After installing GNUnet, unpack the GNU Taler exchange tarball, change into the resulting directory, and proceed as follows:
$ ./configure [--prefix=EXCHANGEPFX] \
[--with-gnunet=GNUNETPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
If you did not specify a prefix, the exchange will install to /usr/local
,
which requires you to run the last step as root
. You have to specify
--with-gnunet=/usr/local
if you installed GNUnet to /usr/local
in the
previous step.
There is no need to actually run a Taler exchange to use the Taler merchant backend – all the merchant needs from the Taler exchange is a few headers and libraries!
Please note that unlike most packages, if you want to run the make check
command, you should run it only after having done make install
. The
latter ensures that necessary binaries are copied to the right place.
In any case, if make check
fails, please consider filing a
bug report with the Taler bug tracker.
The following steps assume all dependencies are installed.
First, unpack the GNU Taler merchant tarball and change into the resulting directory. Then, use the following commands to build and install the merchant backend:
$ ./configure [--prefix=PFX] \
[--with-gnunet=GNUNETPFX] \
[--with-exchange=EXCHANGEPFX]
$ # Each dependency can be fetched from non standard locations via
$ # the '--with-<LIBNAME>' option. See './configure --help'.
$ make
# make install
If you did not specify a prefix, the exchange will install to
/usr/local
, which requires you to run the last step as root
.
You have to specify --with-exchange=/usr/local
and/or
--with-gnunet=/usr/local
if you installed the exchange and/or
GNUnet to /usr/local
in the previous steps.
Depending on the prefixes you specified for the installation and the
distribution you are using, you may have to edit /etc/ld.so.conf
, adding
lines for GNUNETPFX/lib/
and EXCHANGEPFX/lib/
and PFX/lib/
(replace the prefixes with the actual paths you used). Afterwards, you should
run ldconfig
. Without this step, it is possible that the linker may not
find the installed libraries and launching the Taler merchant backend would
then fail.
Please note that unlike most packages, if you want to run the make check
command, you should run it only after having done make install
. The
latter ensures that necessary binaries are copied to the right place.
In any case, if make check
fails, please consider filing a
bug report with the Taler bug tracker.
To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for Debian bookworm.
You need to add a file to import the GNU Taler packages. Typically,
this is done by adding a file /etc/apt/sources.list.d/taler.list
that
looks like this:
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian stable main
Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:
# wget -P /etc/apt/keyrings/ \
https://taler.net/taler-systems.gpg
# apt update
Note
You may want to verify the correctness of the Taler Systems SA key out-of-band.
Now your system is ready to install the official GNU Taler binary packages using apt.
To install the Taler merchant backend, you can now simply run:
# apt install dbconfig-pgsql taler-merchant
Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates). A configuration
fragment for Nginx or Apache will be placed in
/etc/{apache,nginx}/conf-available/taler-merchant.conf
. You must
furthermore still configure the instances, and may need to extend the fragment
with access control restrictions for non-default instances.
To install the GNU Taler Trisquel packages, first ensure that you have the right Trisquel distribution. Packages are currently available for Trisquel GNU/Linux 10.0. Simply follow the same instructions provided for Ubuntu.
To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for Ubuntu Kinetic.
A typical /etc/apt/sources.list.d/taler.list
file for this setup
would look like this:
deb [signed-by=/etc/apt/keysrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ stable main
The last line is crucial, as it adds the GNU Taler packages.
Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists:
# wget -P /etc/apt/keyrings/ \
https://taler.net/taler-systems.gpg
# apt update
Note
You may want to verify the correctness of the Taler Systems key out-of-band.
Now your system is ready to install the official GNU Taler binary packages using apt.
To install the Taler merchant backend, you can now simply run:
# apt install dbconfig-pgsql taler-merchant
Note that the package does not complete the integration of the backend with
the HTTP reverse proxy (typically with TLS certificates). A configuration
fragment for Nginx or Apache will be placed in
/etc/{apache,nginx}/conf-available/taler-merchant.conf
. You must
furthermore still configure the instances, and may need to extend the fragment
with access control restrictions for non-default instances.
The installation already provides reasonable defaults for most of the
configuration options. However, some must be provided, in particular the
database that the backend should use. By default, the file
$HOME/.config/taler.conf
is where the Web shop administrator specifies
configuration values that augment or override the defaults.
Note that when using our binary packages, the systemd service files
force the use of /etc/taler.conf
as the main configuration file.
All GNU Taler components are designed to possibly share the same configuration files. When installing a GNU Taler component, the installation deploys default values in configuration files located at ${prefix}/share/taler/config.d/ where ${prefix} is the installation prefix. Different components must be installed to the same prefix.
In order to override these defaults, the user can write a custom configuration
file and either pass it to the component at execution time using the -c
option, or name it taler.conf and place it under $HOME/.config/ which is where
components will look by default. Note that the systemd service files pass -c
/etc/taler.conf
, thus making /etc/taler.conf
the primary location for
the configuration.
A config file is a text file containing sections, and each section contains maps options to their values. Configuration files follow basically the INI syntax:
[section1]
value1 = string
value2 = 23
[section2]
value21 = string
value22 = /path22
Comments start with a hash (#
). Throughout the configuration, it is
possible to use $
-substitution for options relating to names of files or
directories. It is also possible to provide defaults values for those
variables that are unset, by using the following syntax:
${VAR:-default}
. There are two ways a user can set the value
of $
-prefixable variables:
- by defining them under a
[paths]
section:[paths] TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data .. [section-x] path-x = ${TALER_DEPLOYMENT_SHARED}/x
- or by setting them in the environment:
$ export VAR=/x
The configuration loader will give precedence to variables set under
[path]
over environment variables.
The utility taler-config
, which gets installed along with the exchange,
can be used get and set configuration values without directly editing the
configuration file. The option -f
is particularly useful to resolve
pathnames, when they use several levels of $
-expanded variables. See
taler-config --help
.
The repository git://git.taler.net/deployment
contains example code
for generating configuration files under deployment/netzbon/
.
The tool taler-config
can be used to extract or manipulate configuration
values; however, the configuration use the well-known INI file format and is
generally better edited by hand to preserve comments and structure.
Run
$ taler-config -s $SECTION
to list all of the configuration values in section $SECTION
.
Run
$ taler-config -s $SECTION -o $OPTION
to extract the respective configuration value for option $OPTION
in
section $SECTION
.
Finally, to change a setting, run
$ taler-config -s $SECTION -o $OPTION -V $VALUE
to set the respective configuration value to $VALUE
. Note that you
have to manually restart affected Taler components after you change the
configuration to make the new configuration go into effect.
Some default options will use $-variables, such as $DATADIR
within
their value. To expand the $DATADIR
or other $-variables in the
configuration, pass the -f
option to taler-config
. For example,
compare:
$ taler-config --section exchange-offline --option MASTER_PRIV_FILE
$ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE
While the configuration file is typically located at
$HOME/.config/taler.conf
, an alternative location can be specified to any
GNU Taler component using the -c
option.
The following table describes the options that commonly need to be
modified. Here, the notation [$SECTION]/$OPTION
denotes the option
$OPTION
under the section [$SECTION]
in the configuration file.
The following option sets the transport layer address used by the merchant backend:
[MERCHANT]/SERVE = tcp | unix
If this option is set to
tcp
then we need to set the TCP port in [MERCHANT]/PORT
;unix
then we need to set the unix domain socket path and mode
in [MERCHANT]/UNIXPATH
and [MERCHANT]/UNIXPATH_MODE
. The
latter takes the usual permission mask given as a number, e.g. 660
for user/group read-write access.The frontend can then connect to the backend over HTTP using the specified address. If frontend and backend run within the same operating system, the use of a UNIX domain socket is recommended to avoid accidentally exposing the backend to the network.
To run the Taler backend on TCP port 8888, use:
$ taler-config -s MERCHANT -o SERVE -V tcp
$ taler-config -s MERCHANT -o PORT -V 8888
Note
When using the Debian/Ubuntu packages, these options are already
configured in the /etc/taler/conf.d/merchant.conf
configuration file.
If you need to change them, you should edit
/etc/taler/merchant-overrides.conf
. By default, the Taler merchant
package will use a UNIX domain socket at
/run/taler/merchant-httpd/merchant-http.sock
. For the best possible
security it is recommended to leave this in place and configure a reverse
proxy (Nginx or Apache) as described below.
Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option
[TALER]/CURRENCY
When testing with the Taler demonstration exchange at
https://exchange.demo.taler.net/ you must set this
value to KUDOS
:
$ taler-config -s TALER -o CURRENCY -V KUDOS
Note
When using the Debian/Ubuntu packages, these options should be
configured in the /etc/taler/taler.conf
configuration file
(alternatively, you can also edit /etc/taler/merchant-overrides.conf
).
However, you must edit the taler.conf
file manually and must not
use taler-config
to do this, as that would inline the include
directives and destroy the carefully setup path structure.
In principle it is possible for the backend to support different DBMSs. The option
[MERCHANT]/DB
specifies which DBMS is to be used. However, currently only the value
postgres
is supported. This is also the default.
In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database.
Note
When using the Debian/Ubuntu packages, the database should already
be configured in the /etc/taler/secrets/merchant-db.secret.conf
configuration file. The talermerchant
database should also already
be configured, so you should be able to skip everything in this section
when using our binary packages.
For the postgres
backend, you need to specify:
[MERCHANTDB-postgres]
CONFIG = "postgres://..."
This option specifies a PostgreSQL access path, typicallly using the format
postgres:///$DBNAME
, where $DBNAME
is the name of the PostgreSQL
database you want to use. Suppose $USER
is the name of the user who will
run the backend process. Then, you need to first run:
$ sudo -u postgres createuser -d $USER
as the PostgreSQL database administrator (usually postgres
) to
grant $USER
the ability to create new databases. Next, you should
as $USER
run:
$ createdb $DBNAME
to create the backend’s database. Here, $DBNAME
must match the
database name given in the configuration file.
Now you should be able to create the tables and indices. To do this, run as
$USER
:
$ taler-merchant-dbinit
You may improve your security posture if you now REVOKE the rights to CREATE,
DROP or ALTER tables from $USER
. However, if you do so, please be aware
that you may have to temporarily GRANT those rights again when you update the
merchant backend. For details on how to REVOKE or GRANT these rights, consult
the PostgreSQL documentation.
Note
Taler may store sensitive business and customer data in the database. Any operator SHOULD thus ensure that backup operations are encrypted and secured from unauthorized access.
To add an exchange to the list of trusted payment service providers, you create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that section, the following options need to be configured:
The EXCHANGE_BASE_URL
option specifies the exchange’s base URL.
For example, to use the Taler demonstrator, specify:
[MERCHANT-EXCHANGE-demo]
EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
The MASTER_KEY
option specifies the exchange’s master public key
in base32 encoding. For the Taler demonstrator, use:
[MERCHANT-EXCHANGE-demo]
MASTER_KEY = "FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0"
The CURRENCY
option specifies the exchange’s currency.
For the Taler demonstrator, use:
[MERCHANT-EXCHANGE-demo]
CURRENCY = "KUDOS"
Note that multiple exchanges can be added to the system by using different
identifiers in place of demo
in the example above. Note that all of the
exchanges actually used will use the same currency: If the currency does not
match the main CURRENCY
option from the TALER
section, the respective
MERCHANT-EXCHANGE-
section is automatically ignored. If you need support
for multiple currencies, you need to deploy one backend per currency.
Note
Manually setting up exchanges is only recommended under special circumstances. In general, GNU Taler distributions will include trustworthy exchanges (for each currency) in the default configuration, and there is rarely a good reason for trusting an exchange that has no relationship with the GNU Taler development team.
The following is an example for a complete backend configuration:
[TALER]
CURRENCY = KUDOS
[MERCHANT]
SERVE = TCP
PORT = 8888
DATABASE = postgres
[MERCHANTDB-postgres]
CONFIG = postgres:///donations
[merchant-exchange-NAME]
EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
# If currency does not match [TALER] section, the exchange
# will be ignored!
CURRENCY = KUDOS
Given the above configuration, the backend will use a PostgreSQL database
named donations
running on the same host.
The backend will deposit the coins it receives to the exchange at
https://exchange.demo.taler.net/, which has the master key
FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
.
Assuming you have configured everything correctly, you can launch the
merchant backend as $USER
using
$ taler-merchant-httpd &
$ taler-merchant-webhook &
$ taler-merchant-wirewatch &
You only need to run taler-merchant-webhook
if one of the instances is
configured to trigger web hooks. Similarly, taler-merchant-wirewatch
is
only required if instances have accounts configured with automatic import of
wire transfers via a bank wire gateway.
To ensure these processes runs always in the background and also after rebooting, you should use systemd, cron or some other init system of your operating system to launch the process. You should also periodically re-start these services to prevent them from exhausing the memory utilization of the PostgreSQL database. Consult the documentation of your operating system for how to start and stop daemons.
Note
When using the Debian/Ubuntu packages, the systemd configuration
will already exist. You only need to enable and start the service
using systemctl enable taler-merchant-httpd
and
systemctl start taler-merchant-httpd
. Additionally, you should
review the /etc/apache2/sites-available/taler-merchant.conf
or /etc/nginx/sites-available/taler-merchant
(these files
contain additional instructions to follow), symlink it to
sites-enabled/
and restart your HTTP server. After that, you
should be able to visit the merchant backend at the respective
HTTP(S) endpoint.
If everything worked as expected, the command
$ wget -O - http://localhost:8888/config
should return some basic configuration status data about the service.
Please note that your backend might then be globally reachable without any access control. You can either:
- Use the
--auth=$TOKEN
command-line option to set an access token to be provided in anAuthorize: Bearer $TOKEN
HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified.- Set the
TALER_MERCHANT_TOKEN
environment variable to$TOKEN
for the same effect. This method has the advantage of$TOKEN
not being visible as a command-line interface to other local users on the same machine.- Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token!
Production systems should additionally be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see Secure setup.
First of all, we recommend the use of the single-page administration
application (SPA) that is served by default at the base URL of the merchant
backend. You can use it to perform all steps described in this section (and
more!), using a simple Web interface instead of the wget
commands given
below.
Regardless of which tool you use, the first step for using the backend
involves the creation of a default
instance. The default
instance can
also create / delete / configure other instances, similar to the root
account on UNIX. When no instance exists and taler-merchant-httpd
was
started without the --auth
option, then the backend is reachable without
any access control (unless you configured some in the reverse proxy).
The following documentation shows how to handle any instance. Thus, if you want to have multiple instances, you may need to perform the steps multiple times, once for each instance.
Note
A potential security concern is that normal API usage leaks instance existence. This means unauthorized users can distinguish between the case where the instance does not exist (HTTP 404) and the case where access is denied (HTTP 403). This is concern can be addressed using a properly configured reverse proxy.
Instances can be created by POSTing a request to /management/instances
without using the Web interface. This could be useful if you want to create
many instances programmatically. To create an instance without the Web
interface create a file instance.json
with an
InstanceConfigurationMessage:
{
"accounts" : [{"payto_uri":"$PAYTO_URI"}],
"id" : "default",
"name": "example.com",
"address": { "country" : "zz" },
"auth": { "method" : "external"} ,
"jurisdiction": { "country" : "zz" },
"default_max_wire_fee": "KUDOS:1",
"default_wire_fee_amortization": 100,
"default_max_deposit_fee": "KUDOS:1",
"default_wire_transfer_delay": { "d_ms" : 1209600000 },
"default_pay_delay": { "d_ms" : 1209600000 }
}
In the text above, you must replace $PAYTO_URI
with your actual
payto://
-URI. You may also leave the account array empty. The instance
owner must then configure the accounts before the instance becomes usable.
Be sure to replace KUDOS
with the fiat currency if the setup is for an
actual bank. The name
field will be shown as the name of your shop. The
address
field is expected to contain your shop’s physical address. The
various defaults specify defaults for transaction fees your shop is willing to
cover, how long offers made to the customer are valid, and how long the
exchange has before it must wire the funds to your bank account. Those
defaults can be modified for individual orders. For details, see the
contract terms specification.
You can then create the instance using:
$ wget --post-file=instance.json http://localhost:8888/management/instances
The base URL for the instance will then be
http://localhost:8888/instances/default
. You can create additional
instances by changing the id
value to identifies other than default
.
Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented in the Merchant Backend API documentation.
The Taler backend does not include even the most basic forms of access control or transport layer security. Thus, production setups must deploy the Taler backend behind an HTTP(S) server that acts as a reverse proxy, performs TLS termination and authentication and then forwards requests to the backend.
To ensure that the merchant backend is not exposed directly to the network, you should bind the backend to a UNIX domain socket:
$ taler-config -s MERCHANT -o SERVE -V unix
$ taler-config -s MERCHANT -o UNIXPATH -V "/some/path/here.sock"
Do not use a UNIX domain socket path in “/tmp”: systemd (or other init systems) may give Web servers a private “/tmp” thereby hiding UNIX domain sockets created by other users/processes in “/tmp”.
If UNIX domain sockets are for some reason not possible, you may use a host-based firewall to block access to the TCP port of the merchant backend, but this is not recommended. If you do need a TCP socket, you should instead strongly consider using the “BIND_TO” option to at least bind it only to “localhost”.
For Nginx, a possible basic reverse proxy configuration would be:
proxy_pass http://unix:/some/path/here.sock;
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host "example.com";
proxy_set_header X-Forwarded-Proto "https";
Note that the above assumes your domain name is example.com
and that you
have TLS configured. Leave out the last line if your Nginx reverse proxy does
not have HTTPS enabled. Make sure to restart the taler-merchant-httpd
process after changing the SERVE
configuration.
In Apache, make sure you have mod_proxy
, mod_proxy_http
and
mod_headers
enabled:
$ a2enmod proxy
$ a2enmod proxy_http
$ a2enmod headers
Then configure your Apache reverse proxy like this (you may change the endpoint):
<Location "/">
ProxyPass "unix:/some/path/here.sock|http://example.com/"
RequestHeader add "X-Forwarded-Proto" "https"
</Location>
Note that the above again assumes your domain name is example.com
and that
you have TLS configured. Note that you must add the https
header unless
your site is not available via TLS.
All endpoints with /private/
in the URL must be restricted to authorized
users of the respective instance. Specifically, the HTTP server must be
configured to only allow access to $BASE_URL/private/
to the authorized
users of the default instance, and to $BASE_URL/instances/$ID/private/
to
the authorized users of the instance $ID
.
By default, the GNU Taler merchant backend simply requires the respective HTTP requests to include an “Authorization” header with a “Bearer” token set to the respective shared secret which must begin with “secret-token:” (following RFC 8959).
Note that all of the other endpoints (without /private/
)
are expected to be fully exposed to the Internet, and wallets may have to
interact with those endpoints directly without client authentication.
Normal API usage leaks instance existence information. Distinguishing between 404 (Not found) and 403 (Forbidden) is useful for diagnostics.
For higher security (by leaking less information), you can add the following fragment, which remaps all 404 response codes to 403.
error_page 404 =403 /empty.gif;
cond %{STATUS} =404
set-status 403
The installation process will install various HTML templates to be served
to trigger the wallet interaction. You may change those templates to your
own design. The templating language used is Mustach, and the templates
are in the share/taler/merchant/templates/
directory.
The merchant backend also has the ability to serve small static files
under the /static/{FILENAME}
endpoint. This is used by the templating
logic to load a CSS file, but you can also put other resources such as
images or JavaScript.
Both templates and static files can be internationalized. This is done
by having the language of the resource be a part of the filename.
For templates the format is {BASENAME}.{LANGUAGE}.must
. The
language is mandatory for templates, the default language is English (en).
For static files, the format is {BASENAME}.{LANGUAGE}.{EXT}
for
internationalized files, and {BASENAME}.{EXT}
for resources that do not
support internationalization. The HTTP client will always request
/static/{BASENAME}.{EXT}
. If {BASENAME}.{EXT}
exists, that resource is
returned. Otherwise, an internationalized file based on the language
preferences indicated by the browser is returned.
All of the static files must fit into memory and it must be possible for the
process to hold open file handles for all of these files. You may want
to increase the ulimit
of the taler-merchant-httpd
process if you have
many static files. Note that Mustach templates do not increase the number of
open files.
The backend determines the MIME type based on the file’s extension. The list of supported extensions is hard-coded and includes common text and image formats.
The current backend only provides a limited set of variables for the Mustach template expansion, and does not make use of scopes and other Mustach features.
This section describes the general upgrade procedure. Please see the release notes for your specific version to check if a particular release has special upgrade requirements.
Please note that upgrades are ONLY supported for released version of the merchant. Attempting to upgrade from or to a version in Git is not supported and may result in subtle data loss.
To safely upgrade the merchant, you should first stop the existing
taler-merchant-httpd
process, backup your merchant database (see
PostgreSQL manual), and then install the latest version of the code.
If you REVOKED database permissions, ensure that the rights to CREATE,
DROP, and ALTER tables are GRANTed to $USER
again. Then, run:
$ taler-merchant-dbinit
to upgrade the database to the latest schema. After that, you may again REVOKE the database permissions. Finally, restart the merchant services processes, either via your systemd or init system, or directly.
The merchant database must be initialized using taler-merchant-dbinit
.
This tool creates the tables required by the Taler merchant to operate.
The tool also allows you to reset the Taler merchant database, which is
useful for test cases but should never be used in production. Finally,
taler-merchant-dbinit
has a function to garbage collect a database,
allowing administrators to purge records that are no longer required.
The database scheme used by the merchant looks as follows:
The merchant codebase offers the taler-merchant-benchmark
tool to
populate the database with fake payments. This tool is in charge of
starting a merchant, exchange, and bank processes, and provides them all
the input to accomplish payments. Note that each component will use its
own configuration (as they would do in production).
The main goal of the benchmarking tool is to serve as a starting point (!) for merchants that are interested in developing stress tests to see how far their infrastructure can scale.
The current tool has already a few options, but we expect that to deliver relevant results it will need to be customized to better reflect the workload of a particular merchant. This customization would at this point likely involve writing (C) code. We welcome contributions to make it easier to customize the benchmark and/or to cover more realistic workloads from the start.
The taler-merchant-benchmark
tool will automatically launch and configure the
exchange, (Python) bank and other tools required for the benchmark. However,
the configuration file must be provided and have consistent options set. The
options that require special care include the exchange’s public key (which
must match the private key in the file specified by the configuration), the
currency (which must be consistent across the file), the denomination
structure (which must enable payments in the range of 100ths of the unit
currency (often called cents)). Furthermore, the benchmark will set the
Exchange bank account password to be “x”, so the configuration must also
specify “x” for the passphrase. Finally, the bank must be configured to allow
for substantial debt least the transactions by the benchmark run out of
digital cash.
A relatively minimal configuration could look like this:
[PATHS]
# Persistent data storage for the benchmark
TALER_TEST_HOME = benchmark_home/
[taler]
# If you change the currency here, you MUST change it
# throughout the file.
CURRENCY = EUR
CURRENCY_ROUND_UNIT = EUR:0.01
[merchant]
SERVE = tcp
PORT = 8080
DB = postgres
[merchantdb-postgres]
CONFIG = postgres:///talercheck
[exchange]
DB = postgres
SERVE = tcp
PORT = 8081
BASE_URL = http://localhost:8081/
MASTER_PUBLIC_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG
[exchangedb-postgres]
CONFIG = postgres:///talercheck
[auditor]
DB = postgres
SERVE = tcp
PORT = 8083
BASE_URL = http://the.auditor/
[auditordb-postgres]
CONFIG = postgres:///talercheck
[bank]
DATABASE = postgres:///talerbank
SERVE = http
HTTP_PORT = 8082
MAX_DEBT = EUR:5000.0
MAX_DEBT_BANK = EUR:0.0
[merchant-exchange-test]
MASTER_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG
EXCHANGE_BASE_URL = http://localhost:8081/
CURRENCY = EUR
[exchange-account-exchange]
# The account name MUST be 'Exchange'
PAYTO_URI = payto://x-taler-bank/localhost/Exchange
WIRE_RESPONSE = ${TALER_CONFIG_HOME}/exchange/account.json
WIRE_GATEWAY_URL = http://localhost:8082/taler-wire-gateway/Exchange/
WIRE_GATEWAY_AUTH_METHOD = basic
USERNAME = Exchange
# The password MUST be 'x'
PASSWORD = x
ENABLE_DEBIT = YES
ENABLE_CREDIT = YES
[fees-x-taler-bank]
WIRE-FEE-2020 = EUR:0.01
WIRE-FEE-2021 = EUR:0.01
WIRE-FEE-2022 = EUR:0.01
WIRE-FEE-2023 = EUR:0.01
WIRE-FEE-2024 = EUR:0.01
WIRE-FEE-2025 = EUR:0.01
WIRE-FEE-2026 = EUR:0.01
WIRE-FEE-2027 = EUR:0.01
CLOSING-FEE-2020 = EUR:0.01
CLOSING-FEE-2021 = EUR:0.01
CLOSING-FEE-2022 = EUR:0.01
CLOSING-FEE-2023 = EUR:0.01
CLOSING-FEE-2024 = EUR:0.01
CLOSING-FEE-2025 = EUR:0.01
CLOSING-FEE-2026 = EUR:0.01
CLOSING-FEE-2027 = EUR:0.01
[coin_eur_ct_1]
value = EUR:0.01
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.00
fee_deposit = EUR:0.00
fee_refresh = EUR:0.01
fee_refund = EUR:0.01
rsa_keysize = 1024
[coin_eur_ct_10]
value = EUR:0.10
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024
[coin_eur_1]
value = EUR:1
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024
[coin_eur_5]
value = EUR:5
duration_withdraw = 7 days
duration_spend = 2 years
duration_legal = 3 years
fee_withdraw = EUR:0.01
fee_deposit = EUR:0.01
fee_refresh = EUR:0.03
fee_refund = EUR:0.01
rsa_keysize = 1024
Note that the public key must match the exchange’s private key and that the PostgreSQL database must exist before launching the benchmark. You also will need to ensure that the Exchange’s details are set up. For details, see the Exchange Operator Manual.
The tool takes all of the values it needs from the command line, with one of them being mandatory:
--exchange-account=SECTION
Specifies which configuration
section specifies the bank account for the exchange that
should be used for the benchmark. For the example
configuration above, the SECTION value provided must be
exchange-account-exchange
.The tool comes with two operation modes: ordinary, and corner. The first just executes normal payments, meaning that it uses the default instance and make sure that all payments get aggregated. The second gives the chance to leave some payments unaggregated, and also to use merchant instances other than the default (which is, actually, the one used by default by the tool).
Note: the ability of driving the aggregation policy is useful for testing the back-office facility.
Any subcommand is also equipped with the canonical --help
option, so
feel free to issue the following command in order to explore all the
possibilities. For example:
$ taler-merchant-benchmark corner --help
will show all the options offered by the corner mode. Among the most interesting, there are:
--two-coins=TC
This option instructs the tool to perform TC
many payments that use two coins, because normally only one coin is
spent per payment.--unaggregated-number=UN
This option instructs the tool to
perform UN (one coin) payments that will be left unaggregated.As for the ordinary
subcommand, it is worth explaining the following
options:
--payments-number=PN
Instructs the tool to perform PN payments.--tracks-number=TN
Instructs the tool to perform TN tracking
operations. Note that the total amount of operations will be two
times TN, since “one” tracking operation accounts for
/track/transaction
and /track/transfer
. This command should
only be used to see if the operation ends without problems, as no
actual measurement of performance is provided (despite of the
’benchmark’ word used in the tool’s name).[1] | https://docs.docker.com/ |
This section provides instructions for the merchant backend installation using ‘Docker‘.
For security reasons, we run Docker against a VirtualBox instance, so
the docker
command should connect to a docker-machine
instance
that uses the VirtualBox driver.
Therefore, the needed tools are: “docker“, “docker-machine“, and “docker-compose“. Please refer to Docker’s official [1] documentation in order to get those components installed, as that is not in this manual’s scope.
Before starting to build the merchant’s image, make sure a “docker-machine“ instance is up and running.
Because all of the Docker source file are kept in our “deployment“
repository, we start by checking out the git://git.taler.net/deployment
codebase:
$ git clone git://git.taler.net/deployment
Now we actually build the merchant’s image. From the same directory as above:
$ cd deployment/docker/merchant/
$ docker-compose build
If everything worked as expected, the merchant is ready to be launched. From the same directory as the previous step:
# Recall: the docker-machine should be up and running.
$ docker-compose up
You should see some live logging from all the involved containers. At this stage of development, you should also ignore some (harmless) error message from postresql about already existing roles and databases.
To test if everything worked as expected, it suffices to issue a simple request to the merchant, for example:
$ wget -O - http://$(docker-machine ip)/
# A greeting message should be returned by the merchant.