update prebuilt docs

1 files changed, 804 insertions, 1240 deletions

diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi
index a8396143..997f2073 100644
--- a/texinfo/taler-merchant.texi
+++ b/texinfo/taler-merchant.texi
@@ -3,7 +3,7 @@
 @setfilename taler-merchant.info
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx 3.4.3.@*
+@*Generated by Sphinx 5.3.0.@*
 @end ifinfo
 @settitle Taler Merchant Manual
 @defindex ge
@@ -15,13 +15,11 @@
 * MENU ENTRY: (taler-merchant.info). DESCRIPTION
 @end direntry
 
-@definfoenclose strong,`,'
-@definfoenclose emph,`,'
 @c %**end of header
 
 @copying
 @quotation
-GNU Taler 0.9.0, Nov 03, 2022
+GNU Taler 0.9.0, Sep 24, 2023
 
 GNU Taler team
 
@@ -48,6 +46,23 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
 
 @c %**start of body
 @anchor{taler-merchant-manual doc}@anchor{0}
+@c This file is part of GNU TALER.
+@c 
+@c Copyright (C) 2014-2023 Taler Systems SA
+@c 
+@c TALER is free software; you can redistribute it and/or modify it under the
+@c terms of the GNU Affero General Public License as published by the Free Software
+@c Foundation; either version 2.1, or (at your option) any later version.
+@c 
+@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+@c 
+@c You should have received a copy of the GNU Affero General Public License along with
+@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+@c 
+@c @author Christian Grothoff
+
 @menu
 * Introduction:: 
 * Terminology:: 
@@ -57,9 +72,7 @@ Copyright @copyright{} 2014-2022 Taler Systems SA (GPLv3+ or GFDL 1.3+)
 * Secure setup:: 
 * Customization:: 
 * Upgrade procedure:: 
-* Tipping visitors:: 
 * Advanced topics:: 
-* Advanced experimental features:: 
 * Temporarily Abandoned Features:: 
 * Index:: 
 
@@ -75,27 +88,19 @@ Introduction
 Terminology
 
 * Instances:: 
-* Accounts:: 
+* Instance Bank Accounts:: 
 * Inventory:: 
 * Orders and Contracts:: 
 * Transfers:: 
-* Tipping:: 
+* Rewards:: 
 * Reserves:: 
 
 Installation
 
-* Generic instructions for installation from source:: 
+* Installing from source:: 
 * Installing the GNU Taler binary packages on Debian:: 
 * Installing the GNU Taler binary packages on Trisquel:: 
 * Installing the GNU Taler binary packages on Ubuntu:: 
-* Installing Taler on Debian GNU/Linux from source:: 
-
-Generic instructions for installation from source
-
-* Installation of dependencies:: 
-* Installing GNUnet:: 
-* Installing the GNU Taler exchange:: 
-* Installing the GNU Taler merchant backend:: 
 
 How to configure the merchant’s backend
 
@@ -111,13 +116,10 @@ Backend options
 * Currency:: 
 * Database:: 
 * Exchange:: 
-* Auditor:: 
 
 Instance setup
 
-* KUDOS Accounts:: 
-* IBAN Accounts:: 
-* Setup:: 
+* Setup without the Web interface:: 
 
 Secure setup
 
@@ -131,43 +133,37 @@ Reverse proxy configuration
 * Nginx:: 
 * Apache:: 
 
-Access control
+Status code remapping
 
 * Nginx: Nginx<2>. 
 * Apache: Apache<2>. 
 
-Status code remapping
-
-* Nginx: Nginx<3>. 
-* Apache: Apache<3>. 
-
 Customization
 
-* Templates:: 
+* Legal conditions for using the service:: 
+* Terms of Service:: 
+* Privacy Policy:: 
+* Legal policies directory layout:: 
+* Generating the Legal Terms:: 
+* Adding translations:: 
+* Updating legal documents:: 
+* Mustach HTML Templates:: 
 * Static files:: 
 * Internationalization:: 
 * Limitations:: 
 
-Tipping visitors
+Legal policies directory layout
 
-* Fund the reserve:: 
-* Authorize a tip:: 
-* Picking up of the tip:: 
+* Example:: 
 
 Advanced topics
 
 * Database Scheme:: 
-* Configuration format: Configuration format<2>. 
-
-Configuration format
-
-* Using taler-config: Using taler-config<2>. 
+* Benchmarking:: 
 
-Advanced experimental features
+Benchmarking
 
-* Benchmarking:: 
-* Benchmark setup:: 
-* Running the benchmark command:: 
+* Running taler-merchant-benchmark:: 
 
 Temporarily Abandoned Features
 
@@ -177,7 +173,7 @@ Temporarily Abandoned Features
 @end menu
 
 @node Introduction,Terminology,Top,Top
-@anchor{taler-merchant-manual ffoobar}@anchor{1}@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{2}@anchor{taler-merchant-manual introduction}@anchor{3}
+@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{1}@anchor{taler-merchant-manual introduction}@anchor{2}@anchor{taler-merchant-manual taler-merchant-backend-operator-manual}@anchor{3}
 @chapter Introduction
 
 
@@ -193,6 +189,21 @@ Temporarily Abandoned Features
 @section About GNU Taler
 
 
+@c This file is part of GNU TALER.
+@c 
+@c Copyright (C) 2014-2023 Taler Systems SA
+@c 
+@c TALER is free software; you can redistribute it and/or modify it under the
+@c terms of the GNU Affero General Public License as published by the Free Software
+@c Foundation; either version 2.1, or (at your option) any later version.
+@c 
+@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+@c 
+@c You should have received a copy of the GNU Affero General Public License along with
+@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
 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
@@ -202,19 +213,13 @@ GNU Taler is compatible with anti-money-laundering (AML) and
 know-your-customer (KYC) regulation, as well as data protection
 regulation (such as GDPR).
 
-GNU Taler is not yet production-ready: after following this manual you
-will have a backend that can process payments in “KUDOS”, but not
-regular currencies. This is not so much because of limitations in the
-backend, but because we are not aware of a Taler exchange operator
-offering regular currencies today.
-
 @node About this manual,Architecture overview,About GNU Taler,Introduction
 @anchor{taler-merchant-manual about-this-manual}@anchor{5}@anchor{taler-merchant-manual id1}@anchor{6}
 @section About this manual
 
 
 This manual targets system administrators who want to install a GNU
-Taler merchant @emph{backend}.
+Taler merchant `backend'.
 
 We expect some moderate familiarity with the compilation and
 installation of Free Software packages. An understanding of cryptography
@@ -241,11 +246,11 @@ operating a basic backend.
 @geindex KUDOS
 
 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. For testing purposes, Taler uses a
-special currency “KUDOS” and includes its own special bank.
+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.
 
 @geindex frontend
 
@@ -257,14 +262,13 @@ special currency “KUDOS” and includes its own special bank.
 
 @geindex PostgreSQL
 
-The Taler software stack for a merchant consists of four main
-components:
+The Taler software stack for a merchant consists of four main components:
 
 
 @itemize -
 
 @item 
-A @emph{frontend} which interacts with the customer’s browser. The frontend
+A `frontend' which interacts with the customer’s browser. The frontend
 enables the customer to build a shopping cart and place an order.
 Upon payment, it triggers the respective business logic to satisfy
 the order. This component is not included with Taler, but rather
@@ -273,7 +277,7 @@ The Merchant API Tutorial gives an
 introduction for how to integrate Taler with Web shop frontends.
 
 @item 
-A @emph{back-office} application that enables the shop operators to view
+A `back-office' application that enables the shop operators to view
 customer orders, match them to financial transfers, and possibly
 approve refunds if an order cannot be satisfied. This component is
 not included with Taler, but rather assumed to exist at the
@@ -282,12 +286,12 @@ the API specification that should be reviewed to integrate such a
 back-office with the Taler backend.
 
 @item 
-A Taler-specific payment @emph{backend} which makes it easy for the frontend
+A Taler-specific payment `backend' which makes it easy for the frontend
 to process financial transactions with Taler. This manual primarily
 describes how to install and configure this backend.
 
 @item 
-A @emph{DBMS} which stores the transaction history for the Taler backend.
+A `DBMS' which stores the transaction history for the Taler backend.
 For now, the GNU Taler reference implementation only supports
 PostgreSQL, but the code could be easily extended to support another
 DBMS.  Please review the PostgreSQL documentation for details on
@@ -307,12 +311,12 @@ 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 backend.
+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 @code{/private/} and @code{/management/} API endpoints of the
-merchant backend. Please carefully review the section on @ref{9,,Secure setup} before deploying a Taler merchant backend to production.
+merchant backend. Please carefully review the section on @ref{9,,secure setup} before deploying a Taler merchant backend into production.
 
 @node Terminology,Installation,Introduction,Top
 @anchor{taler-merchant-manual terminology}@anchor{a}
@@ -323,41 +327,67 @@ This chapter describes some of the key concepts used throughout the manual.
 
 @menu
 * Instances:: 
-* Accounts:: 
+* Instance Bank Accounts:: 
 * Inventory:: 
 * Orders and Contracts:: 
 * Transfers:: 
-* Tipping:: 
+* Rewards:: 
 * Reserves:: 
 
 @end menu
 
-@node Instances,Accounts,,Terminology
+@node Instances,Instance Bank Accounts,,Terminology
 @anchor{taler-merchant-manual instances}@anchor{b}
 @section Instances
 
 
 @geindex instance
 
-The backend allows the user to run multiple @emph{instances} of shops with distinct
-business entities sharing a single backend. Each instance uses its own bank
-accounts and key for signing contracts. All major accounting functionality is
-separate per instance.  What is shared is the database, HTTP(S) address and
-the main Taler configuration (accepted currency, exchanges and auditors).
+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 (@code{/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').
 
-@node Accounts,Inventory,Instances,Terminology
-@anchor{taler-merchant-manual accounts}@anchor{c}
-@section Accounts
+@quotation
+
+@cartouche
+@quotation 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.
+@end quotation
+@end cartouche
+@end quotation
+
+@node Instance Bank Accounts,Inventory,Instances,Terminology
+@anchor{taler-merchant-manual instance-bank-accounts}@anchor{c}
+@section Instance Bank Accounts
 
 
-@geindex account
+@geindex instance-bank-account
 
 To receive payments, an instance must have configured one or more bank
-@emph{accounts}.  The backend does not have accounts for users, and instances are
-also not really 'accounts'. So whenever we use the term @emph{account}, it is about
-a bank account of a merchant.
+`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@footnote{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.
 
-@node Inventory,Orders and Contracts,Accounts,Terminology
+This documentation exclusively uses the term `account' for the bank
+accounts of a merchant or shop that may be associated with an instance.
+
+@node Inventory,Orders and Contracts,Instance Bank Accounts,Terminology
 @anchor{taler-merchant-manual inventory}@anchor{d}
 @section Inventory
 
@@ -373,17 +403,20 @@ a bank account of a merchant.
 @geindex order
 
 The Taler backend offers inventory management as an optional function.
-Inventory is tracked per instance and consists of @emph{products} sold in
-@emph{units}. Inventory can be finite or infinite (for digital products).
-Products may include previews (images) to be shown to the user and other
-meta-data. Inventory management allows the frontend to @emph{lock} products,
-reserving them for a particular (unpaid) @emph{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 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, or to override
-prices of products in the inventory.
+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.
 
 @node Orders and Contracts,Transfers,Inventory,Terminology
 @anchor{taler-merchant-manual orders-and-contracts}@anchor{e}
@@ -392,6 +425,8 @@ prices of products in the inventory.
 
 @geindex order
 
+@geindex terms
+
 @geindex contract
 
 @geindex claim
@@ -406,10 +441,14 @@ prices of products in the inventory.
 
 @geindex legal expiration
 
-In Taler, users pay merchants for orders. An order is first created by the
-merchant, where the merchant specifies the specific terms of 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@footnote{contract-terms} specifies the full set of possible order
+terms.
 
-After an order is created, it is @emph{claimed} by a wallet. Once an order is
+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
@@ -417,39 +456,42 @@ 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 @emph{claim token}. This is
+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 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 @emph{product lock} on items (say, while composing the shopping cart).
-These locks, as well as the @emph{order lock} (when the order is complete),
-can be configured to auto-unlock at certain times.
-
-@c FIXME: Is "can be configured" correct?  (Are there controls surfaced?)
-
-A wallet may @emph{pay} for a claimed order, at which point the order turns into
-a (paid) contract.  Orders have an expiration date after which the commercial
-offer expires and any stock of products @emph{locked} by the order is released,
-allowing the stock to be sold in other orders.
+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
+@code{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 @emph{refund} a contract order, for example if the
+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 @emph{wired} the payment to 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 @emph{wire deadline} specifies the latest time by which an
-exchange must wire the funds, while the (earlier) @emph{refund deadline} specifies
-the earliest time when an exchange may wire the funds.
-
-Contract information is kept for legal reasons, typically to provide tax
-records in case of a tax audit.  After the @emph{legal expiration} (by default a
-decade), contract information is deleted.
-
-@node Transfers,Tipping,Orders and Contracts,Terminology
+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 @code{taler-merchant-dbinit}.
+
+@node Transfers,Rewards,Orders and Contracts,Terminology
 @anchor{taler-merchant-manual transfers}@anchor{f}
 @section Transfers
 
@@ -459,33 +501,43 @@ decade), contract information is deleted.
 @geindex wire transfer
 
 The Taler backend can be used to verify that the exchange correctly wired all
-of the funds to the merchant. However, the backend does not have access to the
-incoming wire transfers of the merchant's bank account. Thus, merchants must
-manually provide the backend with wire @emph{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.
+of the funds to the merchant. However, if no Taler Bank Merchant HTTP API@footnote{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.
 
-@node Tipping,Reserves,Transfers,Terminology
-@anchor{taler-merchant-manual tipping}@anchor{10}
-@section Tipping
+@node Rewards,Reserves,Transfers,Terminology
+@anchor{taler-merchant-manual rewards}@anchor{10}
+@section Rewards
 
 
-@geindex tip
-
-@geindex grant
+@geindex reward
 
 @geindex pick up
 
 Taler does not only allow a Website to be paid, but also to make voluntary,
-non-contractual payments to visitors, called @emph{tips}.  Such tips could be
+non-contractual payments to visitors, called `rewards'.  Such rewards 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
+rewards, there is no contract, rewards 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 @emph{grant} tips, allowing wallets to @emph{pick up}
-the tip.
+can create rewards, it must establish a reserve.  Once a reserve has been
+established, the merchant can `grant' rewards, allowing wallets to `pick up'
+the reward.
+
+@quotation
+
+..note:
+
+@example
+Rewards are an optional feature, and exchanges may disable rewards (usually
+if they see compliance issues). In this case, the reward feature will
+not be available.
+@end example
+@end quotation
 
-@node Reserves,,Tipping,Terminology
+@node Reserves,,Rewards,Terminology
 @anchor{taler-merchant-manual reserves}@anchor{11}
 @section Reserves
 
@@ -494,14 +546,17 @@ the tip.
 
 @geindex close
 
-A @emph{reserve} is a pool of electronic cash at an exchange under the control of
+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
+rewards.  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 @emph{close} a reserve after a fixed period of time
+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.
 
 @node Installation,How to configure the merchant’s backend,Terminology,Top
 @anchor{taler-merchant-manual installation}@anchor{12}
@@ -511,48 +566,57 @@ An exchange will automatically @emph{close} a reserve after a fixed period of ti
 This chapter describes how to install the GNU Taler merchant backend.
 
 @menu
-* Generic instructions for installation from source:: 
+* Installing from source:: 
 * Installing the GNU Taler binary packages on Debian:: 
 * Installing the GNU Taler binary packages on Trisquel:: 
 * Installing the GNU Taler binary packages on Ubuntu:: 
-* Installing Taler on Debian GNU/Linux from source:: 
-
-@end menu
-
-@node Generic instructions for installation from source,Installing the GNU Taler binary packages on Debian,,Installation
-@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual generic-instructions-for-installation-from-source}@anchor{14}
-@section Generic instructions for installation from source
-
-
-This section provides generic instructions for the merchant backend
-installation independent of any particular operating system. Operating
-system specific instructions are provided in the following sections. You
-should follow the operating system specific instructions if those are
-available, and only consult the generic instructions if no
-system-specific instructions are provided for your specific operating
-system.
-
-@menu
-* Installation of dependencies:: 
-* Installing GNUnet:: 
-* Installing the GNU Taler exchange:: 
-* Installing the GNU Taler merchant backend:: 
 
 @end menu
 
-@node Installation of dependencies,Installing GNUnet,,Generic instructions for installation from source
-@anchor{taler-merchant-manual id3}@anchor{15}@anchor{taler-merchant-manual installation-of-dependencies}@anchor{16}
-@subsection Installation of dependencies
+@node Installing from source,Installing the GNU Taler binary packages on Debian,,Installation
+@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual installing-from-source}@anchor{14}
+@section Installing from source
+
+
+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@footnote{http://ftpmirror.gnu.org/taler/}.
+
+@c This file is part of GNU TALER.
+@c 
+@c Copyright (C) 2014-2023 Taler Systems SA
+@c 
+@c TALER is free software; you can redistribute it and/or modify it under the
+@c terms of the GNU Affero General Public License as published by the Free Software
+@c Foundation; either version 2.1, or (at your option) any later version.
+@c 
+@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+@c 
+@c You should have received a copy of the GNU Affero General Public License along with
+@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+@c 
+@c @author Christian Grothoff
 
+GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format.
+The general rule for compatibility is that @code{MAJOR} and @code{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).
 
-The following packages need to be installed before we can compile the
+First, the following packages need to be installed before we can compile the
 backend:
 
 
 @itemize -
 
 @item 
-"Sphinx RTD Theme" Python package aka @code{python3-sphinx-rtd-theme}
+“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme}
 on Debian-based systems (for GNUnet documentation support, can be
 omitted if GNUnet is configured with @code{--disable-documentation})
 
@@ -566,10 +630,10 @@ GNU libunistring >= 0.9.3
 libcurl >= 7.26 (or libgnurl >= 7.26)
 
 @item 
-libqrencode >= 4.0.0
+libqrencode >= 4.0.0 (Taler merchant only)
 
 @item 
-GNU libgcrypt >= 1.6
+GNU libgcrypt >= 1.6 (1.10 or later highly recommended)
 
 @item 
 libsodium >= 1.0
@@ -587,35 +651,31 @@ PostgreSQL >= 13, including libpq
 GNU libmicrohttpd >= 0.9.71
 
 @item 
-GNUnet >= 0.16 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/})
+GNUnet >= 0.19 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/})
 
 @item 
-GNU Taler exchange (see release announcement@footnote{https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late})
+Python3 with @code{jinja2}
 @end itemize
 
-Except for the last two, these are available in most GNU/Linux distributions
-and should just be installed using the respective package manager. Be careful
-with GNU libmicrohttpd; here, some distributions only include an older version
-that will not work.
-
-While you are in the GNU Taler exchange
-download directory@footnote{http://ftpmirror.gnu.org/taler/},
-you might as well also download the tarball for GNU Taler merchant.
-
-GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format.
-The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match.
-Exceptions to this general rule are documented in the release notes.
-For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1.
+If you are on Debian stable or later, the following command may help you
+install these dependencies:
 
-The following sections will provide detailed instructions for installing
-the @code{libgnunetutil} and GNU Taler exchange dependencies.
-
-@node Installing GNUnet,Installing the GNU Taler exchange,Installation of dependencies,Generic instructions for installation from source
-@anchor{taler-merchant-manual installing-gnunet}@anchor{17}@anchor{taler-merchant-manual installing-libgnunetutil}@anchor{18}
-@subsection Installing GNUnet
-
-
-@geindex GNUnet
+@example
+# 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
+@end example
 
 Before you install GNUnet, you must download and install the dependencies
 mentioned in the previous section, otherwise the build may succeed, but could
@@ -639,16 +699,16 @@ The @code{ldconfig} command (also run as @code{root}) makes the
 shared object libraries (@code{.so} files)
 visible to the various installed programs.
 
-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!
-
-@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source
-@anchor{taler-merchant-manual id4}@anchor{19}@anchor{taler-merchant-manual installing-the-gnu-taler-exchange}@anchor{1a}
-@subsection Installing the GNU Taler exchange
+Please note that unlike most packages, if you want to run the @code{make check}
+command, you should run it only `after' having done @code{make install}.  The
+latter ensures that necessary binaries are copied to the right place.
 
+In any case, if @code{make check} fails, please consider filing a
+bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.
 
-@geindex exchange
+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:
@@ -668,24 +728,15 @@ which requires you to run the last step as @code{root}.  You have to specify
 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
+backend – all the merchant needs from the Taler exchange is a few headers and
 libraries!
 
-@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source
-@anchor{taler-merchant-manual id5}@anchor{1b}@anchor{taler-merchant-manual installing-the-gnu-taler-merchant-backend}@anchor{1c}
-@subsection Installing the GNU Taler merchant backend
-
-
-@geindex backend
-
-GNU Taler merchant has these additional dependencies:
-
-
-@itemize -
+Please note that unlike most packages, if you want to run the @code{make check}
+command, you should run it only `after' having done @code{make install}.  The
+latter ensures that necessary binaries are copied to the right place.
 
-@item 
-libqrencode >= 4.0.0
-@end itemize
+In any case, if @code{make check} fails, please consider filing a
+bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.
 
 The following steps assume all dependencies are installed.
 
@@ -719,44 +770,41 @@ 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 @code{make check}
-command, you should run it only @emph{after} having done @code{make install}.  The
+command, you should run it only `after' having done @code{make install}.  The
 latter ensures that necessary binaries are copied to the right place.
 
-Gratuitous editorial note by TTN: I think this is a quirk that we should
-fix in the long-term as such weirdness might hide other build issues.
-However, this is probably a minority viewpoint.
-
 In any case, if @code{make check} fails, please consider filing a
 bug report with the Taler bug tracker@footnote{https://bugs.taler.net}.
 
-@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Generic instructions for installation from source,Installation
-@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{1d}
+@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation
+@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{15}
 @section Installing the GNU Taler binary packages on Debian
 
 
 To install the GNU Taler Debian packages, first ensure that you have
 the right Debian distribution. At this time, the packages are built for
-Bullseye.
+Debian bookworm.
 
 You need to add a file to import the GNU Taler packages. Typically,
 this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that
 looks like this:
 
 @example
-deb https://deb.taler.net/apt/debian bullseye main
+deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian stable main
 @end example
 
 Next, you must import the Taler Systems SA public package signing key
 into your keyring and update the package lists:
 
 @example
-# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add -
+# wget -O /etc/apt/keyrings/taler-systems.gpg \
+    https://taler.net/taler-systems.gpg
 # apt update
 @end example
 
 @cartouche
 @quotation Note 
-You may want to verify the correctness of the Taler Systems key out-of-band.
+You may want to verify the correctness of the Taler Systems SA key out-of-band.
 @end quotation
 @end cartouche
 
@@ -773,33 +821,36 @@ 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
 @code{/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.
+furthermore still configure the database and the instances, and may need to
+extend the fragment with access control restrictions for non-default
+instances.
 
 @node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation
-@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{1e}
+@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{16}
 @section Installing the GNU Taler binary packages on Trisquel
 
 
 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 20.04 LTS (Focal Fossa).
+for Ubuntu.
 
-@node Installing the GNU Taler binary packages on Ubuntu,Installing Taler on Debian GNU/Linux from source,Installing the GNU Taler binary packages on Trisquel,Installation
-@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{1f}
+@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Trisquel,Installation
+@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{17}
 @section Installing the GNU Taler binary packages on 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 22.04 LTS (Jammy Jellyfish).
+Ubuntu Kinetic and Ubuntu Jammy. Make sure to have @code{universe} in your
+@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages
+from Ubuntu @code{universe}.
 
 A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup
 would look like this:
 
 @example
-deb https://deb.taler.net/apt/ubuntu/ jammy main
+deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ stable main
 @end example
 
 The last line is crucial, as it adds the GNU Taler packages.
@@ -808,8 +859,8 @@ Next, you must import the Taler Systems SA public package signing key
 into your keyring and update the package lists:
 
 @example
-# wget -O /etc/apt/trusted.gpg.d/taler-systems.asc \
-    https://taler.net/taler-systems.gpg.key
+# wget -O /etc/apt/keyrings/taler-systems.gpg \
+    https://taler.net/taler-systems.gpg
 # apt update
 @end example
 
@@ -832,91 +883,12 @@ 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
 @code{/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.
-
-@node Installing Taler on Debian GNU/Linux from source,,Installing the GNU Taler binary packages on Ubuntu,Installation
-@anchor{taler-merchant-manual installing-taler-on-debian-gnu-002flinux}@anchor{20}@anchor{taler-merchant-manual installing-taler-on-debian-gnu-linux-from-source}@anchor{21}
-@section Installing Taler on Debian GNU/Linux from source
-
-
-@geindex Wheezy
-
-@geindex Jessie
-
-@geindex Stretch
-
-@geindex Buster
-
-@geindex Bullseye
-
-@geindex Debian
-
-Debian Wheezy is too old and lacks most of the packages required.
-Debian Jessie, Stretch, and Buster are better, but still lack PostgreSQL 12.
-
-@cartouche
-@quotation Note 
-When compiling PostgreSQL 12, make sure to
-do @code{make world} to build the @code{contrib/} modules, and
-@code{cd contrib && make install} to install them, as well.
-@end quotation
-@end cartouche
-
-On Debian Stretch and Buster, only GNU libmicrohttpd needs to be compiled from
-source. To install dependencies on Debian Stretch, run the following
-commands:
-
-@example
-# apt-get install \
-  libqrencode-dev \
-  libsqlite3-dev \
-  libltdl-dev \
-  libunistring-dev \
-  libsodium-dev \
-  libargon2-0-dev \
-  libcurl4-gnutls-dev \
-  libgcrypt20-dev \
-  libjansson-dev \
-  libpq-dev \
-  postgresql-9.6
-# wget https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-latest.tar.gz
-# wget https://ftpmirror.gnu.org/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig
-# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC
-# tar xf libmicrohttpd-latest.tar.gz
-# cd libmicrohttpd-0*
-# ./configure
-# make install
-@end example
-
-For more recent versions of Debian, you should instead run:
-
-@example
-# apt-get install \
-  libqrencode-dev \
-  libsqlite3-dev \
-  libltdl-dev \
-  libunistring-dev \
-  libsodium-dev \
-  libargon2-dev \
-  libcurl4-gnutls-dev \
-  libgcrypt20-dev \
-  libjansson-dev \
-  libpq-dev \
-  postgresql-9.6 \
-  libmicrohttpd-dev
-@end example
-
-Note that Stretch requires @code{libargon2-0-dev},
-while later versions of Debian require @code{libargon2-dev}.
-
-For the rest of the installation, follow the generic installation
-instructions starting with the installation of libgnunetutil. Note that
-if you used the Debian Stretch instructions above, you need to pass
-@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations.
+furthermore still configure the database and the instances, and may need to
+extend the fragment with access control restrictions for non-default
+instances.
 
 @node How to configure the merchant’s backend,Instance setup,Installation,Top
-@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{22}
+@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{18}
 @chapter How to configure the merchant’s backend
 
 
@@ -926,12 +898,11 @@ if you used the Debian Stretch instructions above, you need to pass
 
 The installation already provides reasonable defaults for most of the
 configuration options. However, some must be provided, in particular the
-database account and bank account that the backend should use. By
-default, the file @code{$HOME/.config/taler.conf} is where the Web shop
-administrator specifies configuration values that augment or override
-the defaults. The format of the configuration file is the well-known INI
-file format. You can edit the file by hand, or use the @code{taler-config}
-commands given as examples.
+database that the backend should use. By default, the file
+@code{$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 @code{/etc/taler.conf} as the main configuration file.
 
 @menu
 * Configuration format:: 
@@ -943,20 +914,26 @@ commands given as examples.
 @end menu
 
 @node Configuration format,Using taler-config,,How to configure the merchant’s backend
-@anchor{taler-merchant-manual configuration-format}@anchor{23}
+@anchor{taler-merchant-manual configuration-format}@anchor{19}
 @section Configuration format
 
 
-In Taler realm, any component obeys to the same pattern to get
-configuration values. According to this pattern, once the component has
-been installed, the installation deploys default values in
-$@{prefix@}/share/taler/config.d/, in .conf files. In order to override
-these defaults, the user can write a custom .conf file and either pass
-it to the component at execution time, or name it taler.conf and place
-it under $HOME/.config/.
+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 @code{-c
+/etc/taler.conf}, thus making @code{/etc/taler.conf} the primary location for
+the configuration.
 
 A config file is a text file containing sections, and each section
-contains its values. The right format follows:
+contains maps options to their values.  Configuration files follow
+basically the INI syntax:
 
 @example
 [section1]
@@ -968,14 +945,23 @@ value21 = string
 value22 = /path22
 @end example
 
-Throughout any configuration file, it is possible to use @code{$}-prefixed
-variables, like @code{$VAR}, especially when they represent filesystem
-paths. It is also possible to provide defaults values for those
+Comments start with a hash (@code{#}).  Throughout the configuration, it is
+possible to use @code{$}-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:
-@code{$@{VAR:-default@}}. However, there are two ways a user can set
-@code{$}-prefixable variables:
+@code{$@{VAR:-default@}}. There are two ways a user can set the value
+of @code{$}-prefixable variables:
 
-by defining them under a @code{[paths]} section, see example below,
+@quotation
+
+
+@enumerate 
+
+@item 
+by defining them under a @code{[paths]} section:
+@end enumerate
+
+@quotation
 
 @example
 [paths]
@@ -984,47 +970,43 @@ TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
 [section-x]
 path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
 @end example
+@end quotation
 
+
+@enumerate 2
+
+@item 
 or by setting them in the environment:
+@end enumerate
+
+@quotation
 
 @example
 $ export VAR=/x
 @end example
+@end quotation
+@end quotation
 
 The configuration loader will give precedence to variables set under
-@code{[path]}, though.
+@code{[path]} over environment variables.
 
-The utility @code{taler-config}, which gets installed along with the
-exchange, serves to get and set configuration values without directly
-editing the .conf. The option @code{-f} is particularly useful to resolve
+The utility @code{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 @code{-f} is particularly useful to resolve
 pathnames, when they use several levels of @code{$}-expanded variables. See
 @code{taler-config --help}.
 
-Note that, in this stage of development, the file
-@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the
-component. For example, both an exchange and a bank can read values from
-it.
-
-The repository @code{git://taler.net/deployment} contains examples of
-configuration file used in our demos. See under @code{deployment/config}.
-
-@quotation
-
-@strong{Note}
-
-Expectably, some components will not work just by using default
-values, as their work is often interdependent. For example, a
-merchant needs to know an exchange URL, or a database name.
-@end quotation
+The repository @code{git://git.taler.net/deployment} contains example code
+for generating configuration files under @code{deployment/netzbon/}.
 
 @node Using taler-config,Backend options,Configuration format,How to configure the merchant’s backend
-@anchor{taler-merchant-manual using-taler-config}@anchor{24}
+@anchor{taler-merchant-manual using-taler-config}@anchor{1a}
 @section Using taler-config
 
 
-The tool @code{taler-config} can be used to extract or manipulate
-configuration values; however, the configuration use the well-known INI
-file format and can also be edited by hand.
+The tool @code{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
 
@@ -1037,20 +1019,20 @@ to list all of the configuration values in section @code{$SECTION}.
 Run
 
 @example
-$ taler-config -s $section -o $option
+$ taler-config -s $SECTION -o $OPTION
 @end example
 
-to extract the respective configuration value for option @code{$option} in
-section @code{$section}.
+to extract the respective configuration value for option @code{$OPTION} in
+section @code{$SECTION}.
 
 Finally, to change a setting, run
 
 @example
-$ taler-config -s $section -o $option -V $value
+$ taler-config -s $SECTION -o $OPTION -V $VALUE
 @end example
 
-to set the respective configuration value to @code{$value}. Note that you
-have to manually restart the Taler backend after you change the
+to set the respective configuration value to @code{$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 @code{$DATADIR} within
@@ -1059,19 +1041,16 @@ configuration, pass the @code{-f} option to @code{taler-config}. For example,
 compare:
 
 @example
-$ taler-config -s ACCOUNT-bank \
-               -o WIRE_RESPONSE
-$ taler-config -f -s ACCOUNT-bank \
-               -o WIRE_RESPONSE
+$ taler-config --section exchange-offline --option MASTER_PRIV_FILE
+$ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE
 @end example
 
 While the configuration file is typically located at
-@code{$HOME/.config/taler.conf}, an alternative location can be specified
-to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c}
-option.
+@code{$HOME/.config/taler.conf}, an alternative location can be specified to any
+GNU Taler component using the @code{-c} option.
 
 @node Backend options,Sample backend configuration,Using taler-config,How to configure the merchant’s backend
-@anchor{taler-merchant-manual backend-options}@anchor{25}@anchor{taler-merchant-manual id6}@anchor{26}
+@anchor{taler-merchant-manual backend-options}@anchor{1b}@anchor{taler-merchant-manual id4}@anchor{1c}
 @section Backend options
 
 
@@ -1096,20 +1075,19 @@ option.
 @geindex wire format
 
 The following table describes the options that commonly need to be
-modified. Here, the notation @code{[$section]/$option} denotes the option
-@code{$option} under the section @code{[$section]} in the configuration file.
+modified. Here, the notation @code{[$SECTION]/$OPTION} denotes the option
+@code{$OPTION} under the section @code{[$SECTION]} in the configuration file.
 
 @menu
 * Service address:: 
 * Currency:: 
 * Database:: 
 * Exchange:: 
-* Auditor:: 
 
 @end menu
 
 @node Service address,Currency,,Backend options
-@anchor{taler-merchant-manual service-address}@anchor{27}
+@anchor{taler-merchant-manual service-address}@anchor{1d}
 @subsection Service address
 
 
@@ -1117,19 +1095,19 @@ The following option sets the transport layer address used by the
 merchant backend:
 
 @example
-[MERCHANT]/SERVE = TCP | UNIX
+[MERCHANT]/SERVE = tcp | unix
 @end example
 
-If given,
+If this option is set to
 
 
 @itemize -
 
 @item 
-@code{TCP}, then we need to set the TCP port in @code{[MERCHANT]/PORT}
+@code{tcp} then we need to set the TCP port in @code{[MERCHANT]/PORT};
 
 @item 
-@code{UNIX}, then we need to set the unix domain socket path and mode
+@code{unix} then we need to set the unix domain socket path and mode
 in @code{[MERCHANT]/UNIXPATH} and @code{[MERCHANT]/UNIXPATH_MODE}. The
 latter takes the usual permission mask given as a number, e.g. 660
 for user/group read-write access.
@@ -1143,7 +1121,7 @@ the backend to the network.
 To run the Taler backend on TCP port 8888, use:
 
 @example
-$ taler-config -s MERCHANT -o SERVE -V TCP
+$ taler-config -s MERCHANT -o SERVE -V tcp
 $ taler-config -s MERCHANT -o PORT -V 8888
 @end example
 
@@ -1152,18 +1130,17 @@ $ taler-config -s MERCHANT -o PORT -V 8888
 When using the Debian/Ubuntu packages, these options are already
 configured in the @code{/etc/taler/conf.d/merchant.conf} configuration file.
 
-If you need to change them, you should edit @code{/etc/taler/merchant-overrides.conf},
-for example by passing @code{-c /etc/taler/merchant-overrides.conf} to the
-@code{taler-config} commands above.  By default, the Taler merchant
-package when installed on Debian/Ubuntu will use a UNIX domain socket
-at @code{/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.
+If you need to change them, you should edit
+@code{/etc/taler/merchant-overrides.conf}.  By default, the Taler merchant
+package will use a UNIX domain socket at
+@code{/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.
 @end quotation
 @end cartouche
 
 @node Currency,Database,Service address,Backend options
-@anchor{taler-merchant-manual currency}@anchor{28}
+@anchor{taler-merchant-manual currency}@anchor{1e}
 @subsection Currency
 
 
@@ -1174,9 +1151,9 @@ specified using the option
 [TALER]/CURRENCY
 @end example
 
-For testing purposes, the currency MUST match “KUDOS” so that tests
-will work with the Taler demonstration exchange at
-@indicateurl{https://exchange.demo.taler.net/}:
+When testing with the Taler demonstration exchange at
+@indicateurl{https://exchange.demo.taler.net/} you must set this
+value to @code{KUDOS}:
 
 @example
 $ taler-config -s TALER -o CURRENCY -V KUDOS
@@ -1187,14 +1164,14 @@ $ taler-config -s TALER -o CURRENCY -V KUDOS
 When using the Debian/Ubuntu packages, these options should be
 configured in the @code{/etc/taler/taler.conf} configuration file
 (alternatively, you can also edit @code{/etc/taler/merchant-overrides.conf}).
-However, you must edit the @code{taler.conf} file manually and @strong{must not}
+However, you must edit the @code{taler.conf} file manually and `must not'
 use @code{taler-config} to do this, as that would inline the include
 directives and destroy the carefully setup path structure.
 @end quotation
 @end cartouche
 
 @node Database,Exchange,Currency,Backend options
-@anchor{taler-merchant-manual database}@anchor{29}
+@anchor{taler-merchant-manual database}@anchor{1f}
 @subsection Database
 
 
@@ -1213,25 +1190,25 @@ DBMS-specific options to access the database.
 
 @cartouche
 @quotation Note 
-When using the Debian/Ubuntu packages, the database should already
-be configured in the @code{/etc/taler/secrets/merchant-db.secret.conf}
-configuration file.  The @code{talermerchant} database is also already
-configured (unless you answered @code{no} when asked the question during
-installation), so you can skip everything in this section.
+The `taler-merchant-dbconfig' tool can be used to automate the database
+setup. When using the Debian/Ubuntu packages, the user should already have
+been created, so you can just run the tool without any arguments and should
+have a working database configuration.
 @end quotation
 @end cartouche
 
-For the @code{postgres} backend, you need to provide:
+For the @code{postgres} backend, you need to specify:
 
 @example
-[MERCHANTDB-postgres]/CONFIG
+[MERCHANTDB-postgres]
+CONFIG = "postgres://..."
 @end example
 
-This option specifies a postgres access path using the format
-@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the
-PostgreSQL database you want to use. Suppose @code{$USER} is the name of
-the user who will run the backend process. Then, you need to first
-run:
+This option specifies a PostgreSQL access path, typicallly using the format
+@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the PostgreSQL
+database you want to use. Suppose @code{$USER} is the name of the user who will
+run the backend process (usually @code{taler-merchant-httpd}). Then, you need to
+first run:
 
 @example
 $ sudo -u postgres createuser -d $USER
@@ -1248,42 +1225,31 @@ $ createdb $DBNAME
 to create the backend’s database. Here, @code{$DBNAME} must match the
 database name given in the configuration file.
 
-To configure the Taler backend to use this database, run:
-
-@example
-$ taler-config -s MERCHANTDB-postgres -o CONFIG \
-    -V postgres:///$DBNAME
-@end example
-
-Now you should create the tables and indices. To do this, run as @code{$USER}:
+Now you should be able to create the tables and indices. To do this, run as
+@code{$USER} (usually @code{taler-merchant-httpd}):
 
 @example
 $ taler-merchant-dbinit
 @end example
 
-You can improve your security posture if you now REVOKE the rights to CREATE,
+You may improve your security posture if you now REVOKE the rights to CREATE,
 DROP or ALTER tables from @code{$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.
 
-Commands, like @code{taler-merchant-dbinit}, that support the @code{-l LOGFILE}
-command-line option, send logging output to standard error by default.
-See manpages/taler-merchant-dbinit.1 for more information.
-
 @cartouche
 @quotation Note 
-The Taler merchant backend stores private keys and other sensitive
-business and customer data in the database.  The backend operator
-SHOULD ensure that backup operations are encrypted and secured from
-unauthorized access.
+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.
 @end quotation
 @end cartouche
 
 @c index: MASTER_KEY
 
-@node Exchange,Auditor,Database,Backend options
-@anchor{taler-merchant-manual exchange}@anchor{2a}
+@node Exchange,,Database,Backend options
+@anchor{taler-merchant-manual exchange}@anchor{20}
 @subsection Exchange
 
 
@@ -1299,9 +1265,8 @@ The @code{EXCHANGE_BASE_URL} option specifies the exchange’s base URL.
 For example, to use the Taler demonstrator, specify:
 
 @example
-$ taler-config -s MERCHANT-EXCHANGE-demo \
-    -o EXCHANGE_BASE_URL \
-    -V https://exchange.demo.taler.net/
+[MERCHANT-EXCHANGE-demo]
+EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/"
 @end example
 
 @item 
@@ -1309,9 +1274,8 @@ The @code{MASTER_KEY} option specifies the exchange’s master public key
 in base32 encoding. For the Taler demonstrator, use:
 
 @example
-$ taler-config -s MERCHANT-EXCHANGE-demo \
-    -o MASTER_KEY \
-    -V FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
+[MERCHANT-EXCHANGE-demo]
+MASTER_KEY = "FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0"
 @end example
 
 @item 
@@ -1319,90 +1283,30 @@ The @code{CURRENCY} option specifies the exchange’s currency.
 For the Taler demonstrator, use:
 
 @example
-$ taler-config -s MERCHANT-EXCHANGE-demo \
-    -o CURRENCY \
-    -V KUDOS
+[MERCHANT-EXCHANGE-demo]
+CURRENCY = "KUDOS"
 @end example
 @end itemize
 
 Note that multiple exchanges can be added to the system by using different
-tokens in place of @code{demo} in the examples above. Note that all of the
-exchanges must use the same currency: If the currency does not match the main
-currency from the @code{TALER} section, the exchange is ignored. If you need to
-support multiple currencies, you need to configure a backend per currency.
+identifiers in place of @code{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 @code{CURRENCY} option from the @code{TALER} section, the respective
+@code{MERCHANT-EXCHANGE-} section is automatically ignored. If you need support
+for multiple currencies, you need to deploy one backend per currency.
 
 @cartouche
 @quotation Note 
 Manually setting up exchanges is only recommended under special
-circumstances. In general, GNU Taler will include trustworthy
-auditors (for each currency) in the default configuration, and
-there is rarely a good reason for trusting an exchange without
-an accredited auditor.
-@end quotation
-@end cartouche
-
-@node Auditor,,Exchange,Backend options
-@anchor{taler-merchant-manual auditor}@anchor{2b}
-@subsection Auditor
-
-
-To add an auditor to the list of trusted auditors (which implies
-that all exchanges audited by this auditor will be trusted!)
-you create a section with a name that starts with “MERCHANT-AUDITOR-”. In
-4that section, the following options need to be configured:
-
-
-@itemize -
-
-@item 
-The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL.
-For example, to use the Taler demonstrator's auditor, specify:
-
-@example
-$ taler-config -s MERCHANT-AUDITOR-demo \
-    -o AUDITOR_BASE_URL \
-    -V https://exchange.demo.taler.net/
-@end example
-
-@item 
-The @code{AUDITOR_KEY} option specifies the auditor's public key
-in base32 encoding. For the Taler demonstrator, use:
-
-@example
-$ taler-config -s MERCHANT-AUDITOR-demo \
-    -o AUDITOR_KEY \
-    -V DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
-@end example
-
-@item 
-The @code{CURRENCY} option specifies the auditor’s currency.
-For the Taler demonstrator, use:
-
-@example
-$ taler-config -s MERCHANT-AUDITOR-demo \
-    -o CURRENCY \
-    -V KUDOS
-@end example
-@end itemize
-
-Note that multiple auditors can be added to the system by using different
-tokens in place of @code{demo} in the examples above. Note that all of the
-auditors must use the same currency: If the currency does not match the main
-currency from the @code{TALER} section, the auditor is ignored.  If you need to
-support multiple currencies, you need to configure a backend per currency.
-
-@cartouche
-@quotation Note 
-Manually adding auditors is only recommended under special
-circumstances. In general, GNU Taler will include trustworthy
-auditors (for each currency) in the default configuration, and
-there is rarely a good reason for adding an auditor that is
-not coordinating its activities with the Taler developers.
+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.
 @end quotation
 @end cartouche
 
 @node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend
-@anchor{taler-merchant-manual id7}@anchor{2c}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{2d}
+@anchor{taler-merchant-manual id5}@anchor{21}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{22}
 @section Sample backend configuration
 
 
@@ -1428,28 +1332,17 @@ MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
 # If currency does not match [TALER] section, the exchange
 # will be ignored!
 CURRENCY = KUDOS
-
-[merchant-auditor-NAME]
-AUDITOR_BASE_URL = https://auditor.demo.taler.net/
-AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11
-# If currency does not match [TALER] section, the auditor
-# will be ignored!
-CURRENCY = KUDOS
 @end example
 
-Given the above configuration, the backend will use a database named
-@code{donations} within PostgreSQL.
+Given the above configuration, the backend will use a PostgreSQL database
+named @code{donations} running on the same host.
 
 The backend will deposit the coins it receives to the exchange at
 @indicateurl{https://exchange.demo.taler.net/}, which has the master key
 @code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}.
 
-Please note that @code{doc/config.sh} will walk you through all
-configuration steps, showing how to invoke @code{taler-config} for each of
-them.
-
 @node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend
-@anchor{taler-merchant-manual id8}@anchor{2e}@anchor{taler-merchant-manual launching-the-backend}@anchor{2f}
+@anchor{taler-merchant-manual id6}@anchor{23}@anchor{taler-merchant-manual launching-the-backend}@anchor{24}
 @section Launching the backend
 
 
@@ -1461,13 +1354,22 @@ Assuming you have configured everything correctly, you can launch the
 merchant backend as @code{$USER} using
 
 @example
-$ taler-merchant-httpd
+$ taler-merchant-httpd &
+$ taler-merchant-webhook &
+$ taler-merchant-wirewatch &
 @end example
 
-To ensure the process 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. Consult the documentation of your operating
-system for how to start and stop daemons.
+You only need to run @code{taler-merchant-webhook} if one of the instances is
+configured to trigger web hooks.  Similarly, @code{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.
 
 @cartouche
 @quotation Note 
@@ -1492,7 +1394,8 @@ $ wget -O - http://localhost:8888/config
 
 should return some basic configuration status data about the service.
 
-Please note that your backend is right now likely globally reachable.  You can either:
+Please note that your backend might then be globally reachable without
+any access control.  You can either:
 
 @quotation
 
@@ -1516,21 +1419,22 @@ and use TLS for improved network privacy, see @ref{9,,Secure setup}.
 @geindex instance
 
 @node Instance setup,Secure setup,How to configure the merchant’s backend,Top
-@anchor{taler-merchant-manual id9}@anchor{30}@anchor{taler-merchant-manual instance-setup}@anchor{31}
+@anchor{taler-merchant-manual id7}@anchor{25}@anchor{taler-merchant-manual instance-setup}@anchor{26}
 @chapter Instance setup
 
 
 First of all, we recommend the use of the single-page administration
-application 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 @code{wget} commands given below.
-
-The first step for using the backend involves the creation of a @code{default}
-instance. The @code{default} instance can also create / delete / configure other
-instances, similar to the @code{root} account on UNIX.  When no instance exists
-and @code{taler-merchant-httpd} was started without the @code{--auth} option, then
-the backend is reachable without any access control (unless you configured
-some in the reverse proxy).
+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 @code{wget} commands given
+below.
+
+Regardless of which tool you use, the first step for using the backend
+involves the creation of a @code{default} instance. The @code{default} instance can
+also create / delete / configure other instances, similar to the @code{root}
+account on UNIX.  When no instance exists and @code{taler-merchant-httpd} was
+started without the @code{--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
@@ -1538,90 +1442,57 @@ times, once for each instance.
 
 @cartouche
 @quotation Note 
-A security concern is that normal API usage leaks instance existence.
+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 all moot behind a properly configured
-@ref{32,,reverse proxy}.
+This is concern can be addressed using a properly configured
+@ref{27,,reverse proxy}.
 @end quotation
 @end cartouche
 
 @menu
-* KUDOS Accounts:: 
-* IBAN Accounts:: 
-* Setup:: 
+* Setup without the Web interface:: 
 
 @end menu
 
-@node KUDOS Accounts,IBAN Accounts,,Instance setup
-@anchor{taler-merchant-manual kudos-accounts}@anchor{33}
-@section KUDOS Accounts
-
-
-The main configuration data that must be provided for each instance
-is the bank account information.
-
-In order to receive payments, the merchant backend needs to
-communicate bank account details to the exchange.
-
-The bank account information is provided in the form of a @code{payto://}-URI.
-See RFC 8905@footnote{https://tools.ietf.org/html/rfc8905}
-for the format of @code{payto://}-URIs.
+@node Setup without the Web interface,,,Instance setup
+@anchor{taler-merchant-manual setup-without-the-web-interface}@anchor{28}
+@section Setup without the Web interface
 
-For first tests, you should sign up for a KUDOS bank
-account at @indicateurl{https://bank.demo.taler.net/}.
-In this case, the @code{payto://}-URI will be of the form
-@code{payto://x-taler-bank/bank.demo.taler.net/$USERNAME} where @code{$USERNAME}
-must be replaced with the name of the account that was established
-at @indicateurl{https://bank.demo.taler.net/}.
 
-@node IBAN Accounts,Setup,KUDOS Accounts,Instance setup
-@anchor{taler-merchant-manual iban-accounts}@anchor{34}
-@section IBAN Accounts
-
-
-When deploying Taler with the real banking system, you primarily need to
-change the currency of the configuration from KUDOS to the actual currency
-(such as EUR, USD, CHF) and provide a @code{payto://}-URI of your real bank
-account. In Europe, this will involve knowing your IBAN number. If you have an
-IBAN, the corresponding @code{payto://}-URI is simply @code{payto://iban/$IBAN} where
-@code{$IBAN} must be replaced with the actual IBAN number.
-
-@node Setup,,IBAN Accounts,Instance setup
-@anchor{taler-merchant-manual setup}@anchor{35}
-@section Setup
-
-
-With the knowledge of the @code{payto://}-URI, instances can be configured by POSTing
-a request to @code{/management/instances}.  To create a first instance,
-create a file @code{instance.json} with an InstanceConfigurationMessage
+Instances can be created by POSTing a request to @code{/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 @code{instance.json} with an
+InstanceConfigurationMessage:
 
 @example
 @{
-  "payto_uris" : [ "$PAYTO_URI" ],
+  "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",
+  "use_stefan": true,
   "default_wire_transfer_delay": @{ "d_ms" : 1209600000 @},
   "default_pay_delay": @{ "d_ms" : 1209600000 @}
 @}
 @end example
 
 In the text above, you must replace @code{$PAYTO_URI} with your actual
-@code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the
-setup is for an actual bank. The @code{name} field will be shown as the name of
-your shop. The @code{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.
+@code{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 @code{KUDOS} with the fiat currency if the setup is for an
+actual bank. The @code{name} field will be shown as the name of your shop. The
+@code{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:
 
@@ -1638,7 +1509,7 @@ or purge (deleting all associated data) instances exist as well and are document
 in the Merchant Backend API documentation.
 
 @node Secure setup,Customization,Instance setup,Top
-@anchor{taler-merchant-manual id11}@anchor{36}@anchor{taler-merchant-manual secure-setup}@anchor{9}
+@anchor{taler-merchant-manual id8}@anchor{29}@anchor{taler-merchant-manual secure-setup}@anchor{9}
 @chapter Secure setup
 
 
@@ -1646,11 +1517,11 @@ in the Merchant Backend API documentation.
 
 @geindex TLS
 
-The Taler backend does not include even the most basic forms of
-access control or transport layer security.  Thus, production
-setups @strong{must} deploy the Taler backend behind an HTTP(S) server
-that acts as a @emph{reverse proxy}, performs TLS termination and
-authentication and then forwards requests to the backend.
+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.
 
 @menu
 * Using UNIX domain sockets:: 
@@ -1661,29 +1532,30 @@ authentication and then forwards requests to the backend.
 @end menu
 
 @node Using UNIX domain sockets,Reverse proxy configuration,,Secure setup
-@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{37}
+@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{2a}
 @section Using UNIX domain sockets
 
 
 To ensure that the merchant backend is not exposed directly to the network,
-you @emph{should} bind the backend to a UNIX domain socket:
+you `should' bind the backend to a UNIX domain socket:
 
 @example
-$ taler-config -s MERCHANT -o SERVE -V UNIX
-$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
+$ taler-config -s MERCHANT -o SERVE -V unix
+$ taler-config -s MERCHANT -o UNIXPATH -V "/some/path/here.sock"
 @end example
 
-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".
+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 @emph{may} use a
+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 @emph{not recommended}.  Relying on NAT or network firewalls for access
-control is gross negligence.
+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”.
 
 @node Reverse proxy configuration,Access control,Using UNIX domain sockets,Secure setup
-@anchor{taler-merchant-manual id12}@anchor{38}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{32}
+@anchor{taler-merchant-manual id9}@anchor{2b}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{27}
 @section Reverse proxy configuration
 
 
@@ -1694,7 +1566,7 @@ control is gross negligence.
 @end menu
 
 @node Nginx,Apache,,Reverse proxy configuration
-@anchor{taler-merchant-manual nginx}@anchor{39}
+@anchor{taler-merchant-manual nginx}@anchor{2c}
 @subsection Nginx
 
 
@@ -1714,7 +1586,7 @@ not have HTTPS enabled.  Make sure to restart the @code{taler-merchant-httpd}
 process after changing the @code{SERVE} configuration.
 
 @node Apache,,Nginx,Reverse proxy configuration
-@anchor{taler-merchant-manual apache}@anchor{3a}
+@anchor{taler-merchant-manual apache}@anchor{2d}
 @subsection Apache
 
 
@@ -1741,223 +1613,324 @@ Note that the above again assumes your domain name is @code{example.com} and tha
 you have TLS configured.  Note that you must add the @code{https} header unless
 your site is not available via TLS.
 
-The above configurations are both incomplete. You must still additionally
-set up access control!
-
 @node Access control,Status code remapping,Reverse proxy configuration,Secure setup
-@anchor{taler-merchant-manual access-control}@anchor{3b}
+@anchor{taler-merchant-manual access-control}@anchor{2e}
 @section Access control
 
 
 All endpoints with @code{/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 @code{$BASE_URL/private/} and
-@code{$BASE_URL/management/} to the authorized users of the default instance, and
-to @code{$BASE_URL/instances/$ID/private/} to the authorized users of the instance
-@code{$ID}.
+configured to only allow access to @code{$BASE_URL/private/} to the authorized
+users of the default instance, and to @code{$BASE_URL/instances/$ID/private/} to
+the authorized users of the instance @code{$ID}.
 
-How access control is done (TLS client authentication, HTTP basic or digest
-authentication, etc.) is completely up to the merchant and does not matter to
-the Taler merchant backend.
+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 @code{/private/} or @code{/management/})
+Note that all of the other endpoints (without @code{/private/})
 are expected to be fully exposed to the Internet, and wallets may have to
 interact with those endpoints directly without client authentication.
 
+@node Status code remapping,,Access control,Secure setup
+@anchor{taler-merchant-manual status-code-remapping}@anchor{2f}
+@section Status code remapping
+
+
+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.
+
 @menu
 * Nginx: Nginx<2>. 
 * Apache: Apache<2>. 
 
 @end menu
 
-@node Nginx<2>,Apache<2>,,Access control
-@anchor{taler-merchant-manual id13}@anchor{3c}
+@node Nginx<2>,Apache<2>,,Status code remapping
+@anchor{taler-merchant-manual id10}@anchor{30}
 @subsection Nginx
 
 
-For Nginx, you can implement token-based merchant backend authentication as
-follows:
-
 @example
-location ~ /private/ @{
-    if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
-location /management/ @{
-    if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
+error_page 404 =403 /empty.gif;
 @end example
 
-Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret.  Note
-that the @code{~} ensures that the above matches all endpoints that include the
-string @code{/private/}.  If you only run a single instance, you could simply
-specify @code{/private/} without the @code{~} to only configure the access policy for
-the default instance.
+@node Apache<2>,,Nginx<2>,Status code remapping
+@anchor{taler-merchant-manual id11}@anchor{31}
+@subsection Apache
 
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
 
 @example
-location ~ ^/instances/foo/private/ @{
-    if ($http_authorization !~ "(?i)ApiKey FOOTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
-location ~ ^/instances/bar/private/ @{
-    if ($http_authorization !~ "(?i)ApiKey BARTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
-location /private/ @{
-    if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
-location /management/ @{
-    if ($http_authorization !~ "(?i)ApiKey MASTERTOKEN") @{
-       return 401;
-    @}
-    proxy_pass ...; # as above
-@}
-location ~ /private/ @{
-    return 401; # access to instances not explicitly configured is forbidden
-@}
+cond %@{STATUS@} =404
+set-status 403
 @end example
 
-@node Apache<2>,,Nginx<2>,Access control
-@anchor{taler-merchant-manual id14}@anchor{3d}
-@subsection Apache
+@node Customization,Upgrade procedure,Secure setup,Top
+@anchor{taler-merchant-manual customization}@anchor{32}
+@chapter Customization
 
 
-For Apache, you should first enable @code{mod_rewrite}:
+@menu
+* Legal conditions for using the service:: 
+* Terms of Service:: 
+* Privacy Policy:: 
+* Legal policies directory layout:: 
+* Generating the Legal Terms:: 
+* Adding translations:: 
+* Updating legal documents:: 
+* Mustach HTML Templates:: 
+* Static files:: 
+* Internationalization:: 
+* Limitations:: 
 
-@example
-$ a2enmod rewrite
-@end example
+@end menu
 
-Then, you can restrict to an access control token using:
+@node Legal conditions for using the service,Terms of Service,,Customization
+@anchor{taler-merchant-manual legal-conditions-for-using-the-service}@anchor{33}
+@section Legal conditions for using the service
 
-@example
-<Location "/">
-RewriteEngine On
-RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=SECURITYTOKEN"
-RewriteRule "(.+)/private/" "-" [F]
-RewriteRule "/management/" "-" [F]
 
-ProxyPass "unix:/some/path/here.sock|http://example.com/"
-</Location>
-@end example
+@c This file is part of GNU TALER.
+@c 
+@c Copyright (C) 2014-2023 Taler Systems SA
+@c 
+@c TALER is free software; you can redistribute it and/or modify it under the
+@c terms of the GNU Affero General Public License as published by the Free Software
+@c Foundation; either version 2.1, or (at your option) any later version.
+@c 
+@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+@c A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
+@c 
+@c You should have received a copy of the GNU Affero General Public License along with
+@c TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+@c 
+@c @author Christian Grothoff
 
-Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret.  Note
-that the @code{(.+)} ensures that the above matches all endpoints that include the
-string @code{/private/}.  If you only run a single instance, you could simply
-specify @code{/private/} without the @code{(.+)} to only configure the access policy for
-the default instance.
+The service has well-known API endpoints to return its legal conditions to the
+user in various languages and various formats.  This section describes how to
+setup and configure the legal conditions.
 
-If you are running different instances on the same backend, you
-likely will want to specify different access control tokens for
-each instance:
+@node Terms of Service,Privacy Policy,Legal conditions for using the service,Customization
+@anchor{taler-merchant-manual terms-of-service}@anchor{34}
+@section Terms of Service
 
-@example
-<Location "/instances/foo/">
-RewriteEngine On
-RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=FOOTOKEN"
-RewriteRule "/instances/foo/private/" "-" [F]
 
-ProxyPass ... # as above
-</Location>
+The service has an endpoint “/terms” to return the terms of service (in legal
+language) of the service operator.  Client software show these terms of
+service to the user when the user is first interacting with the service.
+Terms of service are optional for experimental deployments, if none are
+configured, the service will return a simple statement saying that there are
+no terms of service available.
 
-<Location "/instances/bar/">
-RewriteEngine On
-RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=BARTOKEN"
-RewriteRule "/instances/bar/private/" "-" [F]
+To configure the terms of service response, there are two options
+in the configuration file for the service:
 
-ProxyPass ... # as above
-</Location>
 
-<Location "/">
-RewriteEngine On
-RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=MASTERTOKEN"
-RewriteRule "/private/" "-" [F]
-RewriteRule "/management/" "-" [F]
-RewriteRule "(.+)/private/" "-" [F] # reject all others
+@itemize -
 
-ProxyPass ... # as above
-</Location>
-@end example
+@item 
+@code{TERMS_ETAG}: The current “Etag” to return for the terms of service.
+This value must be changed whenever the terms of service are
+updated. A common value to use would be a version number.
+Note that if you change the @code{TERMS_ETAG}, you MUST also provide
+the respective files in @code{TERMS_DIR} (see below).
 
-Please note that these are simply examples of how one could use Nginx or
-Apache2 for access control. Both HTTP servers support many other forms of
-authentication, including TLS client certificates, HTTP basic and digest
-authentication and others, which can all be used (possibly in combination) to
-restrict access to the internal API to authorized clients.
+@item 
+@code{TERMS_DIR}: The directory that contains the terms of service.
+The files in the directory must be readable to the service
+process.
+@end itemize
 
-System administrators are strongly advised to test their access control
-setup before going into production!
+@node Privacy Policy,Legal policies directory layout,Terms of Service,Customization
+@anchor{taler-merchant-manual privacy-policy}@anchor{35}
+@section Privacy Policy
 
-@node Status code remapping,,Access control,Secure setup
-@anchor{taler-merchant-manual status-code-remapping}@anchor{3e}
-@section Status code remapping
 
+The service has an endpoint “/pp” to return the terms privacy policy (in legal
+language) of the service operator.  Clients should show the privacy policy to
+the user when the user explicitly asks for it, but it should not be shown by
+default.  Privacy policies are optional for experimental deployments, if none
+are configured, the service will return a simple statement saying that there
+is no privacy policy available.
 
-Normal API usage leaks instance existence information.
-Distinguishing between 404 (Not found) and 403 (Forbidden)
-is useful for diagnostics.
+To configure the privacy policy response, there are two options
+in the configuration file for the service:
 
-For higher security (by leaking less information),
-you can add the following fragment,
-which remaps all 404 response codes to 403.
+
+@itemize -
+
+@item 
+@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy.
+This value must be changed whenever the privacy policy is
+updated. A common value to use would be a version number.
+Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide
+the respective files in @code{PRIVACY_DIR} (see below).
+
+@item 
+@code{PRIVACY_DIR}: The directory that contains the privacy policy.
+The files in the directory must be readable to the service
+process.
+@end itemize
+
+@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Customization
+@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{36}
+@section Legal policies directory layout
+
+
+The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a
+particular layout.  You may use the same directory for both the terms of
+service and the privacy policy, as long as you use different ETAGs.  Inside of
+the directory, there should be sub-directories using two-letter language codes
+like “en”, “de”, or “jp”.  Each of these directories would then hold
+translations of the current terms of service into the respective language.
+Empty directories are permitted in case translations are not available.
+
+Then, inside each language directory, files with the name of the value set as
+the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each
+of the files should be typical for the respective mime type.  The set of
+supported mime types is currently hard-coded in the service, and includes
+“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present,
+the service may show a warning on startup.
 
 @menu
-* Nginx: Nginx<3>. 
-* Apache: Apache<3>. 
+* Example:: 
 
 @end menu
 
-@node Nginx<3>,Apache<3>,,Status code remapping
-@anchor{taler-merchant-manual id15}@anchor{3f}
-@subsection Nginx
+@node Example,,,Legal policies directory layout
+@anchor{taler-merchant-manual example}@anchor{37}
+@subsection Example
+
+
+A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be:
+
+
+@itemize -
+
+@item 
+TERMS_DIR/en/tos-v0.txt
+
+@item 
+TERMS_DIR/en/tos-v0.html
+
+@item 
+TERMS_DIR/en/tos-v0.pdf
+
+@item 
+TERMS_DIR/en/tos-v0.epub
+
+@item 
+TERMS_DIR/en/tos-v0.md
+
+@item 
+TERMS_DIR/de/tos-v0.txt
+
+@item 
+TERMS_DIR/de/tos-v0.html
+
+@item 
+TERMS_DIR/de/tos-v0.pdf
+
+@item 
+TERMS_DIR/de/tos-v0.epub
+
+@item 
+TERMS_DIR/de/tos-v0.md
+@end itemize
+
+If the user requests an HTML format with language preferences “fr” followed by
+“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in
+French.
+
+@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Customization
+@anchor{taler-merchant-manual generating-the-legal-terms}@anchor{38}
+@section Generating the Legal Terms
 
 
+The @code{taler-terms-generator} script can be used to generate directories with
+terms of service and privacy policies in multiple languages and all required
+data formats from a single source file in @code{.rst} format and GNU gettext
+translations in @code{.po} format.
+
+To use the tool, you need to first write your legal conditions in English in
+reStructuredText (rst).  You should find a templates in
+@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you
+installed the service to. Whenever you make substantive changes to the legal
+terms, you must use a fresh filename and change the respective @code{ETAG}.  The
+resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document.
+
+Once you have written the @code{$ETAG.rst} file in English, you can
+generate the first set of outputs:
+
 @example
-error_page 404 =403 /empty.gif;
+$ taler-terms-generator -i $ETAG
 @end example
 
-@node Apache<3>,,Nginx<3>,Status code remapping
-@anchor{taler-merchant-manual id16}@anchor{40}
-@subsection Apache
+Afterwards, you should find the terms in various formats for all configured
+languages (initially only English) in @code{$PREFIX/share/terms/}.  The generator
+has a few options which are documented in its man page.
+
+@node Adding translations,Updating legal documents,Generating the Legal Terms,Customization
+@anchor{taler-merchant-manual adding-translations}@anchor{39}
+@section Adding translations
 
 
+Translations must be available in subdirectories
+@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}.
+To start translating, you first need to add a new
+language:
+
 @example
-cond %@{STATUS@} =404
-set-status 403
+$ taler-terms-generator -i $ETAG -l $LANGUAGE
 @end example
 
-@node Customization,Upgrade procedure,Secure setup,Top
-@anchor{taler-merchant-manual customization}@anchor{41}
-@chapter Customization
+Here, @code{$LANGUAGE} should be a two-letter language
+code like @code{de} or @code{fr}.  The command will generate
+a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}
+which contains each English sentence or paragraph
+in the original document and an initially empty
+translation.  Translators should update the @code{.po}
+file. Afterwards, simply re-run
 
+@example
+$ taler-terms-generator -i $ETAG
+@end example
 
-@menu
-* Templates:: 
-* Static files:: 
-* Internationalization:: 
-* Limitations:: 
+to make the current translation(s) available to the
+service.
 
-@end menu
+@cartouche
+@quotation Note 
+You must restart the service whenever adding or updating legal documents or their translations.
+@end quotation
+@end cartouche
+
+@node Updating legal documents,Mustach HTML Templates,Adding translations,Customization
+@anchor{taler-merchant-manual updating-legal-documents}@anchor{3a}
+@section Updating legal documents
+
+
+When making minor changes without legal implications, edit the @code{.rst} file,
+then re-run the step to add a new language for each existing translation to
+produce an updated @code{.po} file. Translate the sentences that have changed and
+finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to
+create the final files.
+
+When making major changes with legal implications, you should first rename (or
+copy) the existing @code{.rst} file and the associated translation files to a new
+unique name.  Afterwards, make the major changes, update the @code{.po} files,
+complete the translations and re-create the final files.  Finally, do not
+forget to update the @code{ETAG} configuration option to the new name and to
+restart the service.
 
-@node Templates,Static files,,Customization
-@anchor{taler-merchant-manual templates}@anchor{42}
-@section Templates
+@node Mustach HTML Templates,Static files,Updating legal documents,Customization
+@anchor{taler-merchant-manual mustach-html-templates}@anchor{3b}
+@section Mustach HTML Templates
 
 
 The installation process will install various HTML templates to be served
@@ -1965,8 +1938,8 @@ 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 @code{share/taler/merchant/templates/} directory.
 
-@node Static files,Internationalization,Templates,Customization
-@anchor{taler-merchant-manual static-files}@anchor{43}
+@node Static files,Internationalization,Mustach HTML Templates,Customization
+@anchor{taler-merchant-manual static-files}@anchor{3c}
 @section Static files
 
 
@@ -1976,7 +1949,7 @@ logic to load a CSS file, but you can also put other resources such as
 images or JavaScript.
 
 @node Internationalization,Limitations,Static files,Customization
-@anchor{taler-merchant-manual internationalization}@anchor{44}
+@anchor{taler-merchant-manual internationalization}@anchor{3d}
 @section Internationalization
 
 
@@ -1993,16 +1966,17 @@ returned. Otherwise, an internationalized file based on the language
 preferences indicated by the browser is returned.
 
 @node Limitations,,Internationalization,Customization
-@anchor{taler-merchant-manual limitations}@anchor{45}
+@anchor{taler-merchant-manual limitations}@anchor{3e}
 @section Limitations
 
 
 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 @code{ulimit} of the @code{taler-merchant-httpd} process if you have
-templates for many languages.
+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
+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.
 
@@ -2010,13 +1984,13 @@ 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.
 
-@node Upgrade procedure,Tipping visitors,Customization,Top
-@anchor{taler-merchant-manual upgrade-procedure}@anchor{46}
+@node Upgrade procedure,Advanced topics,Customization,Top
+@anchor{taler-merchant-manual upgrade-procedure}@anchor{3f}
 @chapter Upgrade procedure
 
 
-This is the general upgrade procedure.  Please see the release notes
-for your specific version to check if a particular release has special
+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
@@ -2035,147 +2009,22 @@ $ taler-merchant-dbinit
 @end example
 
 to upgrade the database to the latest schema.  After that, you may again
-REVOKE the database permissions. Finally, restart the HTTP service, either via
-your systemd or init system, or directly using:
-
-@example
-$ taler-merchant-httpd
-@end example
-
-@node Tipping visitors,Advanced topics,Upgrade procedure,Top
-@anchor{taler-merchant-manual id17}@anchor{47}@anchor{taler-merchant-manual tipping-visitors}@anchor{48}
-@chapter Tipping visitors
-
-
-@geindex tipping
-
-Taler can also be used to tip Web site visitors. For example, you may be
-running an online survey, and you want to reward those people that have
-dutifully completed the survey. If they have installed a Taler wallet,
-you can provide them with a tip for their deeds. This section describes
-how to setup the Taler merchant backend for tipping.
-
-There are three basic steps that must happen to tip a visitor.
-
-@menu
-* Fund the reserve:: 
-* Authorize a tip:: 
-* Picking up of the tip:: 
-
-@end menu
-
-@node Fund the reserve,Authorize a tip,,Tipping visitors
-@anchor{taler-merchant-manual fund-the-reserve}@anchor{49}@anchor{taler-merchant-manual id18}@anchor{4a}
-@section Fund the reserve
-
-
-@geindex reserve
-
-First, the reserve must be setup in the merchant backend. A reserve
-is always tied to a particular instance. To create a reserve with
-10 KUDOS at instance @code{default} using the demo exchange, use:
-
-@example
-$ taler-merchant-setup-reserve \
-    -a KUDOS:10 \
-    -e https://exchange.demo.taler.net/ \
-    -m http://localhost:8888/instances/default
-@end example
-
-The above command assumes that the merchant runs on localhost on
-port 8888.
-For more information, including how to transmit authentication information
-to the backend, see manpages/taler-merchant-setup-reserve.1.
-
-The command will output a @code{payto://} URI which specifies where to
-wire the funds and which wire transfer subject to use.
-
-FIXME: add full example output.
-
-In our example, the output for the wire transfer subject is:
-
-@example
-QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG
-@end example
-
-You now need to make a wire transfer to the exchange’s bank account
-using the given wire transfer subject.
-
-Make your wire transfer and (optionally) check at
-“@indicateurl{https://exchange/reserves/QPE24X}...” whether your transfer has arrived at the
-exchange.
-
-Once the funds have arrived, you can start to use the reserve for
-tipping.
-
-Note that an exchange will typically close a reserve after four weeks, wiring
-all remaining funds back to the sender’s account. Thus, you should plan to
-wire funds corresponding to a campaign of about two weeks to the exchange
-initially. If your campaign runs longer, you should setup another reserve
-every other week to ensure one is always ready.
-
-@node Authorize a tip,Picking up of the tip,Fund the reserve,Tipping visitors
-@anchor{taler-merchant-manual authorize-a-tip}@anchor{4b}@anchor{taler-merchant-manual id19}@anchor{4c}
-@section Authorize a tip
-
-
-When your frontend has reached the point where a client is supposed to receive
-a tip, it needs to first authorize the tip. For this, the frontend must use
-a POST to @code{/private/reserves/$RESERVE_PUB/authorize-tip}. To authorize a
-tip, the frontend has to provide the following information in the body of the
-POST request:
-
-
-@itemize -
-
-@item 
-The amount of the tip
-
-@item 
-The justification (only used internally for the back-office)
-
-@item 
-The URL where the wallet should navigate next after the tip was
-processed
+REVOKE the database permissions. Finally, restart the merchant services
+processes, either via your systemd or init system, or directly.
 
-@item 
-The tip-pickup URL (see next section)
-@end itemize
-
-In response to this request, the backend will return a tip token, an
-expiration time and the exchange URL. The expiration time will indicate
-how long the tip is valid (when the reserve expires). The tip token is
-an opaque string that contains all the information needed by the wallet
-to process the tip. The frontend must send this tip token to the browser
-in a special “402 Payment Required” response inside the @code{X-Taler-Tip}
-header.
-
-The frontend should handle errors returned by the backend, such as
-misconfigured instances or a lack of remaining funds for tipping.
-
-@node Picking up of the tip,,Authorize a tip,Tipping visitors
-@anchor{taler-merchant-manual id20}@anchor{4d}@anchor{taler-merchant-manual picking-up-of-the-tip}@anchor{4e}
-@section Picking up of the tip
-
-
-The wallet will POST a JSON object to the shop’s
-@code{/tips/$TIP_ID/pickup} handler.
-The frontend must then forward this request to the backend. The response
-generated by the backend can then be forwarded directly to the wallet.
-
-@node Advanced topics,Advanced experimental features,Tipping visitors,Top
-@anchor{taler-merchant-manual advanced-topics}@anchor{4f}
+@node Advanced topics,Temporarily Abandoned Features,Upgrade procedure,Top
+@anchor{taler-merchant-manual advanced-topics}@anchor{40}
 @chapter Advanced topics
 
 
 @menu
 * Database Scheme:: 
-* Configuration format: Configuration format<2>. 
+* Benchmarking:: 
 
 @end menu
 
-@node Database Scheme,Configuration format<2>,,Advanced topics
-@anchor{taler-merchant-manual database-scheme}@anchor{50}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{51}
+@node Database Scheme,Benchmarking,,Advanced topics
+@anchor{taler-merchant-manual database-scheme}@anchor{41}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{42}
 @section Database Scheme
 
 
@@ -2190,353 +2039,77 @@ The database scheme used by the merchant looks as follows:
 
 @image{taler-merchant-figures/merchant-db,,,,png}
 
-@node Configuration format<2>,,Database Scheme,Advanced topics
-@anchor{taler-merchant-manual id21}@anchor{52}
-@section Configuration format
-
-
-@geindex configuration
-
-In Taler realm, any component obeys to the same pattern to get
-configuration values. According to this pattern, once the component has
-been installed, the installation deploys default values in
-@code{$@{prefix@}/share/taler/config.d/}, in @code{.conf} files. In order to override
-these defaults, the user can write a custom .conf file and either pass
-it to the component at execution time, or name it @code{taler.conf} and place
-it under @code{$HOME/.config/}.
-
-A config file is a text file containing sections, and each section
-contains its values. The right format follows:
-
-@example
-[section1]
-value1 = string
-value2 = 23
-
-[section2]
-value21 = string
-value22 = /path22
-@end example
-
-Throughout any configuration file, it is possible to use @code{$}-prefixed
-variables, like @code{$VAR}, especially when they represent filesystem
-paths. It is also possible to provide defaults values for those
-variables that are unset, by using the following syntax:
-@code{$@{VAR:-default@}}. However, there are two ways a user can set
-@code{$}-prefixable variables:
-
-by defining them under a @code{[paths]} section, see example below,
-
-@example
-[paths]
-TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
-...
-[section-x]
-path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
-@end example
-
-or by setting them in the environment:
-
-@example
-$ export VAR=/x
-@end example
-
-The configuration loader will give precedence to variables set under
-@code{[path]}, though.
-
-The utility @code{taler-config}, which gets installed along with the
-exchange, serves to get and set configuration values without directly
-editing the @code{.conf}. The option @code{-f} is particularly useful to resolve
-pathnames, when they use several levels of @code{$}-expanded variables. See
-@code{taler-config --help}.
+@node Benchmarking,,Database Scheme,Advanced topics
+@anchor{taler-merchant-manual benchmarking}@anchor{43}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{44}
+@section Benchmarking
 
-Note that, in this stage of development, the file
-@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the
-components. For example, both an exchange and a bank can read values from
-it.
 
-The deployment repository@footnote{https://git.taler.net/deployment} contains examples of
-configuration file used in our demos. See under @code{deployment/config}.
+The merchant codebase offers the @code{taler-merchant-benchmark} tool to populate
+the database with fake payments.  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. As is, it
+currently is not actually good at stressing the payment system.
 
-@quotation
+The @code{taler-unified-setup.sh} script can be used to launch all required
+services and clients. However, the resulting deployment is simplistic
+(everything on the local machine, one single-threaded process per service
+type) and not optimized for performance at all. However, this can still be
+useful to assess the performance impact of changes
+to the code or configuration.
 
-@strong{Note}
+Various configuration files that can be used in the code snippets in this
+section can be found in the @code{src/merchant-tools/} directory of the
+merchant. These are generally intended as starting points.  Note that the
+configuration files ending in @code{.edited} are created by
+@code{taler-unified-setup.sh} and contain some options that are determined at
+runtime by the setup logic provided by @code{taler-unified-setup.sh}.
 
-Expectably, some components will not work just by using default
-values, as their work is often interdependent. For example, a
-merchant needs to know an exchange URL, or a database name.
-@end quotation
+See Taler Exchange Manual for how to use @code{taler-unified-setup.sh} to setup the system and in particular on how to specify the bank to be used.
 
 @menu
-* Using taler-config: Using taler-config<2>. 
+* Running taler-merchant-benchmark:: 
 
 @end menu
 
-@node Using taler-config<2>,,,Configuration format<2>
-@anchor{taler-merchant-manual id22}@anchor{53}@anchor{taler-merchant-manual using-taler-002dconfig}@anchor{54}
-@subsection Using taler-config
-
-
-@geindex taler-config
-
-The tool @code{taler-config} can be used to extract or manipulate
-configuration values; however, the configuration use the well-known INI
-file format and can also be edited by hand.
-
-Run:
-
-@example
-$ taler-config -s $SECTION
-@end example
-
-to list all of the configuration values in section @code{$SECTION}.
-
-Run:
-
-@example
-$ taler-config -s $section -o $option
-@end example
+@node Running taler-merchant-benchmark,,,Benchmarking
+@anchor{taler-merchant-manual running-taler-merchant-benchmark}@anchor{45}
+@subsection Running taler-merchant-benchmark
 
-to extract the respective configuration value for option @code{$option} in
-section @code{$section}.
 
-Finally, to change a setting, run:
+You can run the tool as follows:
 
 @example
-$ taler-config -s $section -o $option -V $value
+$ CONF=benchmark-rsa.conf
+$ taler-unified-setup.sh -emwt -c "$CONF" -f -u exchange-account-1
+$ time taler-merchant-benchmark ordinary -c "$CONF".edited -u exchange-account-1 -f -p 20
 @end example
 
-to set the respective configuration value to @code{$value}. Note that you
-have to manually restart the Taler backend after you change the
-configuration to make the new configuration go into effect.
-
-Some default options will use @code{$}-variables, such as @code{$DATADIR} within
-their value. To expand the @code{$DATADIR} or other @code{$}-variables in the
-configuration, pass the @code{-f} option to @code{taler-config}. For example,
-compare:
-
-@example
-$ taler-config -s PATHS \
-               -o TALER_DATA_HOME
-$ taler-config -f -s PATHS \
-               -o TALER_DATA_HOME
-@end example
-
-While the configuration file is typically located at
-@code{$HOME/.config/taler.conf}, an alternative location can be specified
-to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c}
-option.
-
-@node Advanced experimental features,Temporarily Abandoned Features,Advanced topics,Top
-@anchor{taler-merchant-manual advanced-experimental-features}@anchor{55}
-@chapter Advanced experimental features
-
-
-This section describes features that most merchants will not
-need, or will not need initially.
-
-@menu
-* Benchmarking:: 
-* Benchmark setup:: 
-* Running the benchmark command:: 
-
-@end menu
-
-@node Benchmarking,Benchmark setup,,Advanced experimental features
-@anchor{taler-merchant-manual benchmarking}@anchor{56}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{57}
-@section Benchmarking
-
-
-The merchant codebase offers the @code{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
-@emph{relevant} results it will need to be customized to better reflect the
+`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.
 
-@node Benchmark setup,Running the benchmark command,Benchmarking,Advanced experimental features
-@anchor{taler-merchant-manual benchmark-setup}@anchor{58}
-@section Benchmark setup
-
-
-The @code{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:
-
-@example
-[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
-
-@end example
-
-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.
-
-@node Running the benchmark command,,Benchmark setup,Advanced experimental features
-@anchor{taler-merchant-manual running-the-benchmark-command}@anchor{59}
-@section Running the benchmark command
-
-
 The tool takes all of the values it needs from the command line, with
-one of them being mandatory:
+some of them being common to all subcommands:
 
 
 @itemize -
 
 @item 
-@code{--exchange-account=SECTION} Specifies which configuration
+@code{--exchange-account-section=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
 @code{exchange-account-exchange}.
+
+@item 
+@code{--fakebank} Specifies that the benchmark should expect to interact
+with a fakebank (instead of libeufin).
 @end itemize
 
-The tool comes with two operation modes: @emph{ordinary}, and @emph{corner}.
+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
@@ -2554,43 +2127,34 @@ possibilities. For example:
 $ taler-merchant-benchmark corner --help
 @end example
 
-will show all the options offered by the @emph{corner} mode. Among the most
+will show all the options offered by the `corner' mode. Among the most
 interesting, there are:
 
 
 @itemize -
 
 @item 
-@code{--two-coins=TC} This option instructs the tool to perform @emph{TC}
+@code{--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.
 
 @item 
 @code{--unaggregated-number=UN} This option instructs the tool to
-perform @emph{UN} (one coin) payments that will be left unaggregated.
+perform `UN' (one coin) payments that will be left unaggregated.
 @end itemize
 
 As for the @code{ordinary} subcommand, it is worth explaining the following
-options:
+option:
 
 
 @itemize -
 
 @item 
-@code{--payments-number=PN} Instructs the tool to perform @emph{PN} payments.
-
-@item 
-@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking
-operations. Note that the @strong{total} amount of operations will be two
-times @emph{TN}, since "one" tracking operation accounts for
-@code{/track/transaction} and @code{/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).
+@code{--payments-number=PN} Instructs the tool to perform `PN' payments.
 @end itemize
 
-@node Temporarily Abandoned Features,Index,Advanced experimental features,Top
-@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{5a}
+@node Temporarily Abandoned Features,Index,Advanced topics,Top
+@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{46}
 @chapter Temporarily Abandoned Features
 
 
@@ -2600,7 +2164,7 @@ actual measurement of performance is provided (despite of the
 @end menu
 
 @node Installing Taler using Docker,,,Temporarily Abandoned Features
-@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{5b}
+@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{47}
 @section Installing Taler using Docker
 
 
@@ -2612,7 +2176,7 @@ the @code{docker} command should connect to a @code{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  @footnote{@w{(1)} 
+“docker-compose“. Please refer to Docker’s official  @footnote{
 @indicateurl{https://docs.docker.com/}
 } documentation
 in order to get those components installed, as that is not in this