.. _ffoobar: GNU Taler Merchant Backend Operator Manual ########################################## Introduction ============ About GNU Taler --------------- GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic techniques. GNU Taler allows customers to remain anonymous, while ensuring that merchants can be held accountable by governments. Hence, GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR). 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. .. _About-this-manual: About this manual ----------------- This manual targets system administrators who want to install a GNU Taler merchant *backend*. We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required. This first chapter of the manual will give a brief overview of the overall Taler architecture, describing the environment in which the Taler backend operates. The second chapter then explains how to install the software, including key dependencies. The third chapter will explain how to configure the backend, including in particular the configuration of the bank account details of the merchant. The last chapter gives some additional information about advanced topics which will be useful for system administrators but are not necessary for operating a basic backend. .. _Architecture-overview: Architecture overview --------------------- .. index:: crypto-currency .. index:: 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. .. index:: frontend .. index:: back office .. index:: backend .. index:: DBMS .. index:: Postgres The Taler software stack for a merchant consists of four main components: - 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 assumed to exist at the merchant. The :ref:`Merchant API Tutorial ` gives an introduction for how to integrate Taler with Web shop frontends. - 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 merchant. The :ref:`Merchant Backend API ` provides the API specification that should be reviewed to integrate such a back office with the Taler backend. - 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. - A DBMS which stores the transaction history for the Taler backend. For now, the GNU Taler reference implementation only supports Postgres, but the code could be easily extended to support another DBMS. Please review the Postgres documentation for details on how to configure the database. The following image illustrates the various interactions of these key components: .. image:: arch-api.png .. index:: RESTful Basically, the backend provides the cryptographic protocol support, stores Taler-specific financial information in a DBMS and communicates with the GNU Taler exchange over the Internet. The frontend accesses the backend via a RESTful API. As a result, the frontend never has to directly communicate with the exchange, and also does not deal with sensitive data. In particular, the merchant’s signing keys and bank account information is encapsulated within the Taler backend. A typical deployment will additionally include a full-blown Web server (like Apache or Nginx). Such a Web server would be responsible for TLS termination and access control to the ``/private/`` API endpoints of the merchant backend. Please carefully review the section on :ref:`Secure setup ` before deploying a Taler merchant backend to production. Terminology =========== This chapter describes some of the key concepts used throughout the manual. Instances --------- .. index:: instance The backend allows the user to run multiple *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). Accounts -------- .. index:: account To receive payments, an instance must have configured one or more bank *accounts*. The backend does not have accounts for users, and instances are also not really 'accounts'. So whenever we use the term *account*, it is about a bank account of a merchant. Inventory --------- .. index:: inventory .. index:: product .. index:: lock .. index:: unit .. index:: order The Taler backend offers inventory management as an optional function. Inventory is tracked per instance and consists of *products* sold in *units*. Inventory can be finite 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 *lock* products, reserving them 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. Orders and Contracts -------------------- .. index:: order .. index:: contract .. index:: claim .. index:: pay .. index:: refund .. index:: wire deadline .. index:: lock .. index:: 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. 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 and order URL with another user, that other user should be given the opportunity to purchase the same product. To prevent unauthorized wallets from claiming an order, merchants can specify that claims require authorization in the form of a *claim token*. This is useful in case the order ID is predictable (say because an existing order ID scheme 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. A wallet may *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 *locked* by the order is released, allowing the stock to be sold in other orders. Once a contract has been paid, the merchant should fulfill the contract. It is possible for the merchant to *refund* a contract order, for example if the contract cannot be fulfilled after all. Refunds are only possible after the customer paid and before the exchange has *wired* the payment to the merchant. Once the funds have been wired, refunds are no longer allowed by the Taler exchange. The *wire deadline* specifies the latest time by which an exchange must wire the funds, while the (earlier) *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 *legal expiration* (by default a decade), contract information is deleted. Transfers --------- .. index:: transfer .. index:: 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 *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. Tipping ------- .. index:: tip .. index:: grant .. index:: pick up Taler does not only allow a Website to be paid, but also to make voluntary, non-contractual payments to visitors, called *tips*. Such tips could be granted as a reward for filling in surveys or watching advertisements. For tips, there is no contract, tips are always voluntary actions by the Web site that do not arise from a contractual obligation. Before a Web site can create tips, it must establish a reserve. Once a reserve has been established, the merchant can *grant* tips, allowing wallets to *pick up* the tip. Reserves -------- .. index:: reserve .. index:: close A *reserve* is a pool of electronic cash at an exchange under the control of a private key. Merchants withdraw coins from a reserve when granting tips. A reserve is established by first generating the required key material in the merchant backend, and then wiring the desired amount of funds to the exchange. An exchange will automatically *close* a reserve after a fixed period of time (typically about a month), wiring any remaining funds back to the merchant. Installation ============ This chapter describes how to install the GNU Taler merchant backend. .. _Generic-instructions: Generic instructions -------------------- 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. .. _Installation-of-dependencies: Installation of dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following packages need to be installed before we can compile the backend: - libsqlite3 >= 3.16.2 - libunistring >= 0.9.3 - libcurl >= 7.26 (or libgnurl >= 7.26) - libqrencode >= 4.0.0 - GNU libgcrypt >= 1.6 - libsodium >= 1.0 - libargon2 >= 20171227 (GNUnet 0.13 needs it to build, not actively used by GNU Taler) - libsqlite3 >= 3.0 (GNUnet 0.13 needs it to build, not actively used by GNU Taler) - libjansson >= 2.7 - Postgres >= 9.6, including libpq - GNU libmicrohttpd >= 0.9.71 - GNUnet >= 0.14.0 (from `source tarball `__) - GNU Taler exchange (see `release announcement `__) 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 `__, you might as well also download the tarball for GNU Taler merchant. GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match. Exceptions to this general rule are documented in the release notes. For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1. The following sections will provide detailed instructions for installing the ``libgnunetutil`` and GNU Taler exchange dependencies. .. _Installing-libgnunetutil: Installing GNUnet ^^^^^^^^^^^^^^^^^ .. index:: GNUnet Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. To download and install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows: .. code-block:: console $ ./configure [--prefix=GNUNETPFX] $ # Each dependency can be fetched from non standard locations via $ # the '--with-' option. See './configure --help'. $ make # make install # ldconfig If you did not specify a prefix, GNUnet will install to ``/usr/local``, which requires you to run the last step as ``root``. The ``ldconfig`` command (also run as ``root``) makes the shared object libraries (``.so`` files) visible to the various installed programs. 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! .. _Installing-the-GNU-Taler-exchange: Installing the GNU Taler exchange ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: exchange After installing GNUnet, unpack the GNU Taler exchange tarball, change into the resulting directory, and proceed as follows: .. code-block:: console $ ./configure [--prefix=EXCHANGEPFX] \ [--with-gnunet=GNUNETPFX] $ # Each dependency can be fetched from non standard locations via $ # the '--with-' option. See './configure --help'. $ make # make install If you did not specify a prefix, the exchange will install to ``/usr/local``, which requires you to run the last step as ``root``. You have to specify ``--with-gnunet=/usr/local`` if you installed GNUnet to ``/usr/local`` in the previous step. There is no need to actually run a Taler exchange to use the Taler merchant backend -- all the merchant needs from the Taler exchange is a few headers and libraries! .. _Installing-the-GNU-Taler-merchant-backend: Installing the GNU Taler merchant backend ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. index:: backend The following steps assume all dependencies are installed. First, unpack the GNU Taler merchant tarball and change into the resulting directory. Then, use the following commands to build and install the merchant backend: .. code-block:: console $ ./configure [--prefix=PFX] \ [--with-gnunet=GNUNETPFX] \ [--with-exchange=EXCHANGEPFX] $ # Each dependency can be fetched from non standard locations via $ # the '--with-' option. See './configure --help'. $ make # make install If you did not specify a prefix, the exchange will install to ``/usr/local``, which requires you to run the last step as ``root``. You have to specify ``--with-exchange=/usr/local`` and/or ``--with-gnunet=/usr/local`` if you installed the exchange and/or GNUnet to ``/usr/local`` in the previous steps. Depending on the prefixes you specified for the installation and the distribution you are using, you may have to edit ``/etc/ld.so.conf``, adding lines for ``GNUNETPFX/lib/`` and ``EXCHANGEPFX/lib/`` and ``PFX/lib/`` (replace the prefixes with the actual paths you used). Afterwards, you should run ``ldconfig``. Without this step, it is possible that the linker may not find the installed libraries and launching the Taler merchant backend would then fail. .. _Installing-Taler-on-Debian-GNU_002fLinux: Installing Taler on Debian GNU/Linux ------------------------------------ .. index:: Wheezy .. index:: Jessie .. index:: Stretch .. index:: Debian Debian wheezy is too old and lacks most of the packages required. Debian jessie is better, but still lacks PostgreSQL 9.6. On Debian stretch, only GNU libmicrohttpd needs to be compiled from source. To install dependencies on Debian stretch, run the following commands: .. code-block:: console # apt-get install \ 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://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz # wget https://ftp.gnu.org/gnu/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 For more recent versions of Debian, you should instead run: .. code-block:: console # apt-get install \ libsqlite3-dev \ libltdl-dev \ libunistring-dev \ libsodium-dev \ libargon2-dev \ libcurl4-gnutls-dev \ libgcrypt20-dev \ libjansson-dev \ libpq-dev \ postgresql-9.6 \ libmicrohttpd-dev Note that stretch requires ``libargon2-0-dev``, while later versions of Debian require ``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 ``--with-microhttpd=/usr/local/`` to all ``configure`` invocations. How to configure the merchant’s backend ======================================= .. index:: taler-config .. index:: taler.conf 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 ``$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 ``taler-config`` commands given as examples. For more information on ``taler-config``, see `Using taler-config <#Using-taler_002dconfig>`__. .. _Backend-options: Backend options --------------- .. index:: DBMS .. index:: Postgres .. index:: UNIX domain socket .. index:: TCP .. index:: port .. index:: currency .. index:: KUDOS .. index:: exchange .. index:: instance .. index:: wire format The following table describes the options that commonly need to be modified. Here, the notation ``[$section]/$option`` denotes the option ``$option`` under the section ``[$section]`` in the configuration file. Service address ^^^^^^^^^^^^^^^ The following option sets the transport layer address used by the merchant backend: .. code-block:: ini [MERCHANT]/SERVE = TCP | UNIX If given, - ``TCP``, then we need to set the TCP port in ``[MERCHANT]/PORT`` - ``UNIX``, then we need to set the unix domain socket path and mode in ``[MERCHANT]/UNIXPATH`` and ``[MERCHANT]/UNIXPATH_MODE``. The latter takes the usual permission mask given as a number, e.g. 660 for user/group read-write access. The frontend can then connect to the backend over HTTP using the specified address. If frontend and backend run within the same operating system, the use of a UNIX domain socket is recommended to avoid accidentally exposing the backend to the network. To run the Taler backend on TCP port 8888, use: .. code-block:: console $ taler-config -s MERCHANT -o SERVE -V TCP $ taler-config -s MERCHANT -o PORT -V 8888 Currency ^^^^^^^^ Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option .. code-block:: ini [TALER]/CURRENCY For testing purposes, the currency MUST match “KUDOS” so that tests will work with the Taler demonstration exchange at https://exchange.demo.taler.net/: .. code-block:: console $ taler-config -s TALER -o CURRENCY -V KUDOS Database ^^^^^^^^ In principle is possible for the backend to support different DBMSs. The option .. code-block:: ini [MERCHANT]/DB specifies which DBMS is to be used. However, currently only the value "postgres" is supported. This is also the default. In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database. For postgres, you need to provide: .. code-block:: ini [MERCHANTDB-postgres]/CONFIG This option specifies a postgres access path using the format ``postgres:///$DBNAME``, where ``$DBNAME`` is the name of the Postgres database you want to use. Suppose ``$USER`` is the name of the user who will run the backend process. Then, you need to first run .. code-block:: console $ sudo -u postgres createuser -d $USER as the Postgres database administrator (usually ``postgres``) to grant ``$USER`` the ability to create new databases. Next, you should as ``$USER`` run: .. code-block:: console $ createdb $DBNAME to create the backend’s database. Here, ``$DBNAME`` must match the database name given in the configuration file. To configure the Taler backend to use this database, run: .. code-block:: console $ taler-config -s MERCHANTDB-postgres -o CONFIG \ -V postgres:///$DBNAME Now you should create the tables and indices. To do this, run as ``$USER``: .. code-block:: console $ taler-merchant-dbinit You can improve your security posture if you now REVOKE the rights to CREATE, DROP or ALTER tables from ``$USER``. However, if you do so, please be aware that you may have to temporarily GRANT those rights again when you update the merchant backend. For details on how to REVOKE or GRANT these rights, consult the Postgres documentation. .. index: MASTER_KEY Exchange ^^^^^^^^ To add an exchange to the list of trusted payment service providers, you create a section with a name that starts with “MERCHANT-EXCHANGE-”. In that section, the following options need to be configured: - The “EXCHANGE_BASE_URL” option specifies the exchange’s base URL. For example, to use the Taler demonstrator, specify: .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ -o EXCHANGE_BASE_URL \ -V https://exchange.demo.taler.net/ - The “MASTER_KEY” option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ -o MASTER_KEY \ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 - The “CURRENCY” option specifies the exchange’s currency. For the Taler demonstrator, use: .. code-block:: console $ taler-config -s MERCHANT-EXCHANGE-demo \ -o CURRENCY \ -V KUDOS Note that multiple exchanges can be added to the system by using different tokens in place of ``demo`` in the example above. Note that all of the exchanges must use the same currency: If the currency does not match the main currency from the "TALER" section, the exchange is ignored. If you need to support multiple currencies, you need to configure a backend per currency. 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 that section, the following options need to be configured: - The “AUDITOR_BASE_URL” option specifies the auditor’s base URL. For example, to use the Taler demonstrator's auditor, specify: .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ -o AUDITOR_BASE_URL \ -V https://exchange.demo.taler.net/ - The “AUDITOR_KEY” option specifies the auditor's public key in base32 encoding. For the Taler demonstrator, use: .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ -o AUDITOR_KEY \ -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 - The “CURRENCY” option specifies the auditor’s currency. For the Taler demonstrator, use: .. code-block:: console $ taler-config -s MERCHANT-AUDITOR-demo \ -o CURRENCY \ -V KUDOS Note that multiple auditors can be added to the system by using different tokens in place of ``demo`` in the example above. Note that all of the auditors must use the same currency: If the currency does not match the main currency from the "TALER" section, the auditor is ignored. If you need to support multiple currencies, you need to configure a backend per currency. .. _Sample-backend-configuration: Sample backend configuration ---------------------------- .. index:: configuration The following is an example for a complete backend configuration: .. code-block:: ini [TALER] CURRENCY = KUDOS [MERCHANT] SERVE = TCP PORT = 8888 DATABASE = postgres [MERCHANTDB-postgres] CONFIG = postgres:///donations [merchant-exchange-NAME] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0 # If currency does not match [TALER] section, the exchange # will be ignored! CURRENCY = KUDOS [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 Given the above configuration, the backend will use a database named ``donations`` within Postgres. The backend will deposit the coins it receives to the exchange at https://exchange.demo.taler.net/, which has the master key "FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0". Please note that ``doc/config.sh`` will walk you through all configuration steps, showing how to invoke ``taler-config`` for each of them. .. _Launching-the-backend: Launching the backend --------------------- .. index:: backend .. index:: taler-merchant-httpd Assuming you have configured everything correctly, you can launch the merchant backend as ``$USER`` using .. code-block:: console $ taler-merchant-httpd 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. If everything worked as expected, the command .. code-block:: console $ curl http://localhost:8888/ should return the message .. code-block:: none Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. Please note that your backend is right now likely globally reachable. Production systems should be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see :ref:`Secure setup `. .. index:: instance .. _Instance-setup: Instance setup ============== Before using the backend, you must at least configure the "default" instance. 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 ``payto://``-URI. See RFC 8905 for the format of ``payto://``-URIs. For first tests, you should sign up for a KUDOS bank account at `https://bank.demo.taler.net/ `_. In this case, the payto://-URI will be of the form "payto://x-taler-bank/bank.demo.taler.net/$USERNAME" where "$USERNAME" must be replaced with the name of the account that was established at `https://bank.demo.taler.net/ `_. 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 payto://-URI of your real bank account. In Europe, this will involve knowing your IBAN number. If you have an IBAN, the corresponding payto://-URI is simply "payto://iban/$IBAN" where "$IBAN" must be replaced with the actual IBAN number. Setup ------ With the knowledge of the payto://-URI, instances can be configured by POSTing a request to :http:post:`/private/instances`. To create a first instance, create a file ``instance.json`` with an `InstanceConfigurationMessage` .. code-block:: json { payto_uris : [ "$PAYTO_URI" ], id : "default", name: "example.com", address: { country : "zz" }, jurisdiction: { country : "zz" }, default_max_wire_fee: "KUDOS:1", default_wire_fee_amortization: 100, default_max_deposit_fee: "KUDOS:1", default_wire_transfer_delay: { d_ms : 1209600000 }, default_pay_delay: { d_ms : 1209600000 }, } In the text above, you must replace "$PAYTO_URI" with your actual payto://-URI. Also, be sure to replace KUDOS with the fiat currency if the setup is for an actual bank. The "name" field will be shown as the name of your shop. The "address" field is expected to contain your shop's physical address. The various defaults specify defaults for transaction fees your shop is willing to cover, how long offers made to the customer are valid, and how long the exchange has before it must wire the funds to your bank account. Those defaults can be modified for individual orders. For details, see the :ref:`contract terms ` specification. You can then create the instance using: .. code-block:: console $ wget --post-file=instance.json http://localhost:8888/private/instances The base URL for the instance will then be ``http://localhost:8888/instances/default``. You can create additional instances by changing the "id" value to identifies other than "default". Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented in the :ref:`Merchant Backend API documentation `. .. _Secure-setup: Secure setup ============ .. index:: security .. index:: TLS 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. Using UNIX domain sockets ------------------------- To ensure that the merchant backend is not exposed directly to the network, you *should* bind the backend to a UNIX domain socket: .. code-block:: console $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock Do not use a UNIX domain socket path in "/tmp": systemd (or other init systems) may give Web servers a private "/tmp" thereby hiding UNIX domain sockets created by other users/processes in "/tmp". If UNIX domain sockets are for some reason not possible, you *may* use a host-based firewall to block access to the TCP port of the merchant backend, but this is *not recommended*. Relying on NAT or network firewalls for access control is gross negligence. Reverse proxy configuration --------------------------- Nginx ^^^^^ For Nginx, a possible basic reverse proxy configuration would be: .. code-block:: nginx proxy_pass http://unix:/some/path/here.sock; proxy_redirect off; proxy_set_header Host $host; proxy_set_header X-Forwarded-Host "example.com"; proxy_set_header X-Forwarded-Proto "https"; Note that the above assumes your domain name is ``example.com`` and that you have TLS configured. Leave out the last line if your Nginx reverse proxy does not have HTTPS enabled. Make sure to restart the ``taler-merchant-httpd`` process after changing the ``SERVE`` configuration. Apache ^^^^^^ In Apache, make sure you have "mod_proxy", "mod_proxy_http" and "mod_headers" enabled: .. code-block:: console $ a2enmod proxy $ a2enmod proxy_http $ a2enmod headers Then configure your Apache reverse proxy like this (you may change the endpoint): .. code-block:: apacheconf ProxyPass "unix:/some/path/here.sock|http://example.com/" RequestHeader add "X-Forwarded-Proto" "https" Note that the above again assumes your domain name is ``example.com`` and that you have TLS configured. Note that you must add the "https" header unless your site is not available via TLS. The above configuration(s) are both incomplete. You must still additionally setup access control! Access control -------------- All endpoints with ``/private/`` in the URL must be restricted to authorized users of the respective instance. Specifically, the HTTP server must be configured to only allow access to ``$BASE_URL/private/`` to the authorized users of the default instance, and to ``$BASE_URL/instances/$ID/private/`` to the authorized users of the instance ``$ID``. 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. Note that all of the other endpoints (without ``/private/``) are expected to be fully exposed to the Internet, and wallets may have to interact with those endpoints directly without client authentication. Nginx ^^^^^ For Nginx, you can implement token-based merchant backend authentication as follows: .. code-block:: nginx location ~ /private/ { if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") { return 401; } proxy_pass ...; // as above } Here, "SECURITYTOKEN" should be replaced with the actual shared secret. Note that the "~" ensures that the above matches all endpoints that include the string "/private/". If you only run a single instance, you could simply specify "/private/" without the "~" to only configure the access policy for the default instance. If you are running different instances on the same backend, you likely will want to specify different access control tokens for each instance: .. code-block:: nginx 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 ~ /private/ { return 401; // access to instances not explicitly configured is forbidden } Apache ^^^^^^ For Apache, you should first enable "mod_rewrite": .. code-block:: console $ a2enmod rewrite Then, you can restrict to an access control token using: .. code-block:: apacheconf RewriteEngine On RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN" RewriteRule "(.+)/private/" "-" [F] ProxyPass "unix:/some/path/here.sock|http://example.com/" Here, "SECURITYTOKEN" should be replaced with the actual shared secret. Note that the "(.+)" ensures that the above matches all endpoints that include the string "/private/". If you only run a single instance, you could simply specify "/private/" without the "~" to only configure the access policy for the default instance. If you are running different instances on the same backend, you likely will want to specify different access control tokens for each instance: .. code-block:: apacheconf RewriteEngine On RewriteCond "%{HTTP:AUTHORIZATION}" "!=FOOTOKEN" RewriteRule "/instances/foo/private/" "-" [F] ProxyPass ... # as above RewriteEngine On RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN" RewriteRule "/instances/bar/private/" "-" [F] ProxyPass ... # as above RewriteEngine On RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN" RewriteRule "/private/" "-" [F] RewriteRule "(.+)/private/" "-" [F] # reject all others ProxyPass ... # as above 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. System admininistrators are strongly advised to test their access control setup before going into production! Customization ============= Templates --------- The installation process will install various HTML templates to be served to trigger the wallet interaction. You may change those templates to your own design. The templating language used is Mustach, and the templates are in the ``share/taler/merchant/templates/`` directory. Static files ------------ The merchant backend also has the ability to serve small static files under the ``/static/{FILENAME}`` endpoint. This is used by the templating logic to load a CSS file, but you can also put other resources such as images or JavaScript. Internationalization -------------------- Both templates and static files can be internationalized. This is done by having the language of the resource be a part of the filename. For templates the format is ``{BASENAME}.{LANGUAGE}.must``. The language is mandatory for templates, the default language is English (en). For static files, the format is ``{BASENAME}.{LANGUAGE}.{EXT}`` for internationalized files, and ``{BASENAME}.{EXT}`` for resources that do not support internationalization. The HTTP client will always request ``/static/{BASENAME}.{EXT}``. If ``{BASENAME}.{EXT}`` exists, that resource is returned. Otherwise, an internationalized file based on the language preferences indicated by the browser is returned. 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 "ulimit" of the ``taler-merchant-httpd`` process if you have templates for many languages. The backend determines the MIME type based on the file's extension. The list of supported extensions is hard-coded and includes common text and image formats. The current backend only provides a limited set of variables for the Mustach template expansion, and does not make use of scopes and other Mustach features. 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 upgrade requirements. Please note that upgrades are ONLY supported for released version of the merchant. Attempting to upgrade from or to a version in Git is not supported and may result in subtle data loss. To safely upgrade the merchant, you should first stop the existing ``taler-merchant-httpd`` process, backup your merchant database (see Postgres manual), and then install the latest version of the code. If you REVOKED database permissions, ensure that the rights to CREATE, DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run: .. code-block:: console $ taler-merchant-dbinit 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: .. code-block:: console $ taler-merchant-httpd .. _Tipping-visitors: Tipping visitors ================ .. index:: 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. .. _Fund-the-reserve: Fund the reserve ---------------- .. index:: 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 "default" using the demo exchange, use: .. code-block:: console $ taler-merchant-setup-reserve \ -a KUDOS:10 \ -e https://exchange.demo.taler.net/ \ -m http://localhost:8888/instances/default The above command assumes that the merchant runs on localhost on port 8888. The current implementation of the tool does not yet support transmission of authentication information to the backend (`see bug 6418 `_). The command will output a 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: .. code-block:: none QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG 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 “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. .. _Authorize-a-tip: 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 the :http:post:`/private/reserves/$RESERVE_PUB/authorize-tip` API of the backend. To authorize a tip, the frontend has to provide the following information in the body of the POST request: - The amount of the tip - The justification (only used internally for the back-office) - The URL where the wallet should navigate next after the tip was processed - The tip-pickup URL (see next section) 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 ``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. .. _Picking-up-of-the-tip: Picking up of the tip --------------------- The wallet will POST a JSON object to the shop’s :http:post:`/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. Advanced topics =============== .. _MerchantDatabaseScheme: Database Scheme --------------- The merchant database must be initialized using ``taler-merchant-dbinit``. This tool creates the tables required by the Taler merchant to operate. The tool also allows you to reset the Taler merchant database, which is useful for test cases but should never be used in production. Finally, ``taler-merchant-dbinit`` has a function to garbage collect a database, allowing administrators to purge records that are no longer required. The database scheme used by the merchant looks as follows: .. image:: merchant-db.png Configuration format -------------------- .. index:: 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 ``${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/``. A config file is a text file containing sections, and each section contains its values. The right format follows: .. code-block:: ini [section1] value1 = string value2 = 23 [section2] value21 = string value22 = /path22 Throughout any configuration file, it is possible to use ``$``-prefixed variables, like ``$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: ``${VAR:-default}``. However, there are two ways a user can set ``$``-prefixable variables: by defining them under a ``[paths]`` section, see example below, .. code-block:: ini [paths] TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data ... [section-x] path-x = ${TALER_DEPLOYMENT_SHARED}/x or by setting them in the environment: .. code-block:: console $ export VAR=/x The configuration loader will give precedence to variables set under ``[path]``, though. The utility ``taler-config``, which gets installed along with the exchange, serves to get and set configuration values without directly editing the ``.conf``. The option ``-f`` is particularly useful to resolve pathnames, when they use several levels of ``$``-expanded variables. See ``taler-config --help``. Note that, in this stage of development, the file ``$HOME/.config/taler.conf`` can contain sections for *all* the components. For example, both an exchange and a bank can read values from it. The `deployment repository `_ contains examples of configuration file used in our demos. See under ``deployment/config``. **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. .. _Using-taler_002dconfig: Using taler-config ^^^^^^^^^^^^^^^^^^ .. index:: taler-config The tool ``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 .. code-block:: console $ taler-config -s $SECTION to list all of the configuration values in section ``$SECTION``. Run .. code-block:: console $ taler-config -s $section -o $option to extract the respective configuration value for option ``$option`` in section ``$section``. Finally, to change a setting, run .. code-block:: console $ taler-config -s $section -o $option -V $value to set the respective configuration value to ``$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 ``$``-variables, such as ``$DATADIR`` within their value. To expand the ``$DATADIR`` or other ``$``-variables in the configuration, pass the ``-f`` option to ``taler-config``. For example, compare: .. code-block:: console $ taler-config -s PATHS \ -o TALER_DATA_HOME $ taler-config -f -s PATHS \ -o TALER_DATA_HOME While the configuration file is typically located at ``$HOME/.config/taler.conf``, an alternative location can be specified to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c`` option. Advanced experimental features ============================== This section describes features that most merchants will not need, or will not need initially. .. _MerchantBenchmarking: Benchmarking ------------ The merchant codebase offers the ``taler-merchant-benchmark`` tool to populate the database with fake payments. This tool is in charge of starting a merchant, exchange, and bank processes, and provide them all the input to accomplish payments. Note that each component will use its own configuration (as they would do in production). The main goal of the benchmarking tool is to serve as a starting point (!) for merchants that are interested in developing stress tests to see how far their infrastructure can scale. The current tool has already a few options, but we expect that to deliver *relevant* results it will need to be customized to better reflect the workload of a particular merchant. This customization would at this point likely involve writing (C) code. We welcome contributions to make it easier to customize the benchmark and/or to cover more realistic workloads from the start. Benchmark setup --------------- The ``taler-merchant-benchmark`` tool will automatically launch and configure the exchange, (Python) bank and other tools required for the benchmark. However, the configuration file must be provided and have consistent options set. The options that require special care include the exchange's public key (which must match the private key in the file specified by the configuration), the currency (which must be consistent across the file), the denomination structure (which must enable payments in the range of 100ths of the unit currency (often called cents)). Furthermore, the benchmark will set the Exchange bank account password to be "x", so the configuration must also specify "x" for the passphrase. Finally, the bank must be configured to allow for substantial debt least the transactions by the benchmark run out of digital cash. A relatively minimal configuration could look like this: .. literalinclude:: merchant-benchmark.conf Note that the public key must match the exchange's private key and that the Postgres database must exist before launching the benchmark. You also will need to ensure that the Exchange's details are setup, usually by running .. code-block:: console $ taler-exchange-wire -c $CONFIG_FILE $ taler-exchange-keyup -c $CONFIG_FILE where "$CONFIG_FILE" should be replaced by the configuration file that is to be used. Running the benchmark command ----------------------------- The tool takes all of the values it needs from the command line, with one of them being mandatory: - ``--exchange-account=SECTION`` Specifies which configuration section specifies the bank account for the exchange that should be used for the benchmark. For the example configuration above, the SECTION value provided must be "exchange-account-exchange". The tool comes with two operation modes: *ordinary*, and *corner*. The first just executes normal payments, meaning that it uses the default instance and make sure that all payments get aggregated. The second gives the chance to leave some payments unaggregated, and also to use merchant instances other than the default (which is, actually, the one used by default by the tool). Note: the ability of driving the aggregation policy is useful for testing the backoffice facility. Any subcommand is also equipped with the canonical ``--help`` option, so feel free to issue the following command in order to explore all the possibilities. For example: .. code-block:: console $ taler-merchant-benchmark corner --help will show all the options offered by the *corner* mode. Among the most interesting, there are: - ``--two-coins=TC`` This option instructs the tool to perform *TC* many payments that use two coins, because normally only one coin is spent per payment. - ``--unaggregated-number=UN`` This option instructs the tool to perform *UN* (one coin) payments that will be left unaggregated. As for the ``ordinary`` subcommand, it is worth explaining the following options: - ``--payments-number=PN`` Instructs the tool to perform *PN* payments. - ``--tracks-number=TN`` Instructs the tool to perform *TN* tracking operations. Note that the **total** amount of operations will be two times *TN*, since "one" tracking operation accounts for ``/track/transaction`` and ``/track/transfer``. This command should only be used to see if the operation ends without problems, as no actual measurement of performance is provided (despite of the ’benchmark’ word used in the tool’s name). Temporarily Abandoned Features ============================== .. [1] https://docs.docker.com/ Installing Taler using Docker ----------------------------- This section provides instructions for the merchant backend installation using ‘Docker‘. For security reasons, we run Docker against a VirtualBox instance, so the ``docker`` command should connect to a ``docker-machine`` instance that uses the VirtualBox driver. Therefore, the needed tools are: “docker“, “docker-machine“, and “docker-compose“. Please refer to Docker’s official [1]_ documentation in order to get those components installed, as that is not in this manual’s scope. Before starting to build the merchant’s image, make sure a “docker-machine“ instance is up and running. Because all of the Docker source file are kept in our “deployment“ repository, we start by checking out the ``git://git.taler.net/deployment`` codebase: .. code-block:: console $ git clone git://git.taler.net/deployment Now we actually build the merchant’s image. From the same directory as above: .. code-block:: console $ cd deployment/docker/merchant/ $ docker-compose build If everything worked as expected, the merchant is ready to be launched. From the same directory as the previous step: .. code-block:: console # Recall: the docker-machine should be up and running. $ docker-compose up You should see some live logging from all the involved containers. At this stage of development, you should also ignore some (harmless) error message from postresql about already existing roles and databases. To test if everything worked as expected, it suffices to issue a simple request to the merchant, as: .. code-block:: console $ curl http://$(docker-machine ip)/ # A greeting message should be returned by the merchant.