update merchant manual

1 files changed, 167 insertions, 140 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 5626568e..a62212ad 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -756,7 +756,7 @@ The following is an example for a complete backend configuration:
 
    [merchant-exchange-NAME]
    EXCHANGE_BASE_URL = https://exchange.demo.taler.net/
-   MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00
+   MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0
    # If currency does not match [TALER] section, the exchange
    # will be ignored!
    CURRENCY = KUDOS
@@ -773,7 +773,7 @@ Given the above configuration, the backend will use a database named
 
 The backend will deposit the coins it receives to the exchange at
 https://exchange.demo.taler.net/, which has the master key
-"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00".
+"FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0".
 
 Please note that ``doc/config.sh`` will walk you through all
 configuration steps, showing how to invoke ``taler-config`` for each of
@@ -928,16 +928,23 @@ you *should* bind the backend to a UNIX domain socket:
       $ taler-config -s MERCHANT -o SERVE -V UNIX
       $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock
 
-Alternatively, 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.
+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
 ---------------------------
 
-Assuming your domain name is /example.com/ and you have TLS configured,
-a possible reverse proxy directive for Nginx would be:
+Nginx
+^^^^^
+
+For Nginx, a possible basic reverse proxy configuration would be:
 
    ::
 
@@ -947,21 +954,39 @@ a possible reverse proxy directive for Nginx would be:
       proxy_set_header X-Forwarded-Host "example.com";
       proxy_set_header X-Forwarded-Proto "https";
 
-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.
+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:
+
+    ::
+       a2enmod proxy
+       a2enmod proxy_http
+       a2enmod headers
 
-In Apache, make sure you have "mod_proxy" enabled (a2enmod mod_proxy)
-and set:
+Then configure your Apache reverse proxy like this (you may change the
+endpoint):
 
     ::
 
        <Location "/">
-       ProxyPass "unix:/some/path/here.sock"
+       ProxyPass "unix:/some/path/here.sock|http://example.com/"
        RequestHeader add "X-Forwarded-Proto" "https"
        </Location>
-       FIXME: above is untested and incomplete
-       
+
+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
 --------------
@@ -980,6 +1005,119 @@ 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:
+
+    ::
+
+      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:
+
+    ::
+       
+      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":
+
+    ::
+       a2enmod rewrite
+       
+Then, you can restrict to an access control token using:
+
+    ::
+       <Location "/">
+       RewriteEngine On
+       RewriteCond "%{HTTP:AUTHORIZATION}" "!=SECURITYTOKEN"
+       RewriteRule "(.+)/private/" "-" [F]
+
+       ProxyPass "unix:/some/path/here.sock|http://example.com/"
+       </Location>
+
+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:
+
+    ::
+       <Location "/instances/foo/">
+       RewriteEngine On
+       RewriteCond "%{HTTP:AUTHORIZATION}" "!=FOOTOKEN"
+       RewriteRule "/instances/foo/private/" "-" [F]
+
+       ProxyPass ... # as above
+       </Location>
+       
+       <Location "/instances/bar/">
+       RewriteEngine On
+       RewriteCond "%{HTTP:AUTHORIZATION}" "!=BARTOKEN"
+       RewriteRule "/instances/bar/private/" "-" [F]
+
+       ProxyPass ... # as above
+       </Location>
+       
+       <Location "/">
+       RewriteEngine On
+       RewriteCond "%{HTTP:AUTHORIZATION}" "!=MASTERTOKEN"
+       RewriteRule "/private/" "-" [F]
+       RewriteRule "(.+)/private/" "-" [F] # reject all others
+
+       ProxyPass ... # as above
+       </Location>
+
+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
 =============
@@ -1020,7 +1158,9 @@ 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.
+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
@@ -1181,7 +1321,7 @@ Advanced topics
 Database Scheme
 ---------------
 
-The merchant database must be initialized using taler-merchant-dbinit.
+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,
@@ -1323,6 +1463,16 @@ option.
 
 
 
+
+Temporarily Abandoned Features
+==============================
+
+This documentation is outdated, or rather what it describes
+has not been properly maintained and is not expected to work
+today. However, we do hope to get it working again in the
+future (help appreciated).
+
+
 .. _MerchantBenchmarking:
 
 Benchmarking
@@ -1435,130 +1585,7 @@ options:
 
 
 
-Diagnostics
-===========
-
-This chapter includes various (very unpolished) sections on specific
-topics that might be helpful to understand how the exchange operates,
-which files should be backed up. The information may also be helpful for
-diagnostics.
-
-This chapter contains some legacy documentation we need to update
-before it can be considered even reasonably accurate.
-
-
-Taler payments generator
-------------------------
-
-This tool does not exist anymore right now...
-
-The tool ``taler-merchant-generate-payments`` can be used to test the
-merchant backend installation. It implements all the payment’s steps in
-a programmatically way, relying on the backend you give it as input.
-Note that this tool gets installed along all the merchant backend’s
-binaries.
-
-This tool gets configured by a config file, that must have the following
-layout:
-
-::
-
-   [PAYMENTS-GENERATOR]
-
-   # The exchange used during the test: make sure the merchant backend
-   # being tested accepts this exchange.
-   # If the sysadmin wants, she can also install a local exchange
-   # and test against it.
-   EXCHANGE = https://exchange.demo.taler.net/
-
-   # This value must indicate some URL where the backend
-   # to be tested is listening; it doesn't have to be the
-   # "official" one, though.
-   MERCHANT = http://localbackend/
-
-   # This value is used when the tool tries to withdraw coins,
-   # and must match the bank used by the exchange. If the test is
-   # done against the exchange at https://exchange.demo.taler.net/,
-   # then this value can be "https://bank.demo.taler.net/".
-   BANK = https://bank.demo.taler.net/
-
-   # The merchant instance in charge of serving the payment.
-   # Make sure this instance has a bank account at the same bank
-   # indicated by the 'bank' option above.
-   INSTANCE = default
-
-   # The currency used during the test. Must match the one used
-   # by merchant backend and exchange.
-   CURRENCY = KUDOS
-
-Run the test in the following way:
-
-::
-
-   $ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL]
-
-The argument ``config`` given to ``-c`` points to the configuration file
-and is optional – ``^/.config/taler.conf`` will be checked by default.
-By default, the tool forks two processes: one for the merchant backend,
-and one for the exchange. The option ``-e`` (``-m``) avoids any exchange
-(merchant backend) fork, and just runs the generator against the
-exchange (merchant backend) running at ``EURL`` (``MURL``).
-
-Please NOTE that the generator contains *hardcoded* values, as for
-deposit fees of the coins it uses. In order to work against the used
-exchange, those values MUST match the ones used by the exchange.
-
-The following example shows how the generator "sets" a deposit fee of
-EUR:0.01 for the 5 EURO coin.
-
-::
-
-   // from <merchant_repository>/src/sample/generate_payments.c
-   { .oc = OC_PAY,
-     .label = "deposit-simple",
-     .expected_response_code = MHD_HTTP_OK,
-     .details.pay.contract_ref = "create-proposal-1",
-     .details.pay.coin_ref = "withdraw-coin-1",
-     .details.pay.amount_with_fee = concat_amount (currency, "5"),
-     .details.pay.amount_without_fee = concat_amount (currency, "4.99") },
-
-The logic calculates the deposit fee according to the subtraction:
-``amount_with_fee - amount_without_fee``.
-
-The following example shows a 5 EURO coin configuration - needed by the
-used exchange - which is compatible with the hardcoded example above.
-
-::
-
-   [COIN_eur_5]
-   value = EUR:5
-   duration_overlap = 5 minutes
-   duration_withdraw = 7 days
-   duration_spend = 2 years
-   duration_legal = 3 years
-   fee_withdraw = EUR:0.00
-   fee_deposit = EUR:0.01 # important bit
-   fee_refresh = EUR:0.00
-   fee_refund = EUR:0.00
-   rsa_keysize = 1024
-
-If the command terminates with no errors, then the merchant backend is
-correctly installed.
-
-After this operation is done, the merchant database will have some dummy
-data in it, so it may be convenient to clean all the tables; to this
-purpose, issue the following command:
-
-::
-
-   $ taler-merchant-dbinit -r
-
-
-
-
 
-Legacy
-======
 
 Installing Taler using Docker
 -----------------------------