diff options
| -rw-r--r-- | core/api-exchange.rst | 3 | ||||
| -rw-r--r-- | frags/apt-install-taler-merchant.rst | 13 | ||||
| -rw-r--r-- | taler-merchant-manual.rst | 127 |
3 files changed, 69 insertions, 74 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst index 2ea29820..7d951a64 100644 --- a/core/api-exchange.rst +++ b/core/api-exchange.rst @@ -120,6 +120,9 @@ possibly by using HTTPS. // The format is "current:revision:age". version: string; + // The exchange's currency. + currency: string; + // EdDSA master public key of the exchange, used to sign entries in 'denoms' and 'signkeys' master_public_key: EddsaPublicKey; diff --git a/frags/apt-install-taler-merchant.rst b/frags/apt-install-taler-merchant.rst new file mode 100644 index 00000000..d9605f79 --- /dev/null +++ b/frags/apt-install-taler-merchant.rst @@ -0,0 +1,13 @@ + +To install the Taler merchant backend, you can now simply run: + +.. code-block:: console + + # apt install taler-merchant + +Note that the package does not complete the integration of the backend with +the HTTP reverse proxy (typically with TLS certificates). A configuration +fragment for Nginx or Apache will be placed in +``/etc/{apache,nginx}/conf-available/taler-merchant.conf``. You must +furthermore still configure the instances, and may need to extend the fragment +with access control restrictions for non-default instances. diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst index 8e2c7fa0..e27c6569 100644 --- a/taler-merchant-manual.rst +++ b/taler-merchant-manual.rst @@ -63,7 +63,7 @@ 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:: back-office .. index:: backend .. index:: DBMS .. index:: Postgres @@ -78,13 +78,13 @@ components: assumed to exist at the merchant. The :ref:`Merchant API Tutorial <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 +- 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 <merchant-api>` provides the API specification that should be reviewed to integrate such a - back office with the Taler backend. + 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. @@ -106,7 +106,7 @@ 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 +merchant’s signing keys and bank account information are encapsulated within the Taler backend. A typical deployment will additionally include a full-blown Web server (like @@ -380,18 +380,7 @@ Installing the GNU Taler binary packages on Debian .. include:: frags/installing-debian.rst -To install the Taler merchant backend, you can now simply run: - -.. code-block:: console - - # apt install taler-merchant - -Note that the package does not complete the integration of the backend with -the HTTP reverse proxy (typically with TLS certificates). A configuration -fragment for Nginx or Apache will be placed in -``/etc/{apache,nginx}/conf-available/taler-merchant.conf``. You must -furthermore still configure the instances, and may need to extend the fragment -with access control restrictions for non-default instances. +.. include:: frags/apt-install-taler-merchant.rst Installing the GNU Taler binary packages on Ubuntu @@ -399,18 +388,7 @@ Installing the GNU Taler binary packages on Ubuntu .. include:: frags/installing-ubuntu.rst -To install the Taler merchant backend, you can now simply run: - -.. code-block:: console - - # apt install taler-merchant - -Note that the package does not complete the integration of the backend with -the HTTP reverse proxy (typically with TLS certificates). A configuration -fragment for Nginx or Apache will be placed in -``/etc/{apache,nginx}/conf-available/taler-merchant.conf``. You must -furthermore still configure the instances, and may need to extend the fragment -with access control restrictions for non-default instances. +.. include:: frags/apt-install-taler-merchant.rst .. _Installing-Taler-on-Debian-GNU_002fLinux: @@ -585,7 +563,7 @@ The option [MERCHANT]/DB specifies which DBMS is to be used. However, currently only the value -"postgres" is supported. This is also the default. +``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. @@ -600,7 +578,7 @@ 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 +run: .. code-block:: console @@ -639,6 +617,7 @@ the Postgres documentation. Commands, like ``taler-merchant-dbinit``, that support the ``-l LOGFILE`` command-line option, send logging output to standard error by default. +See :doc:`manpages/taler-merchant-dbinit.1` for more information. .. index: MASTER_KEY @@ -650,8 +629,8 @@ 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: +- The ``EXCHANGE_BASE_URL`` option specifies the exchange’s base URL. + For example, to use the Taler demonstrator, specify: .. code-block:: console @@ -659,7 +638,7 @@ section, the following options need to be configured: -o EXCHANGE_BASE_URL \ -V https://exchange.demo.taler.net/ -- The “MASTER_KEY” option specifies the exchange’s master public key +- The ``MASTER_KEY`` option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: .. code-block:: console @@ -668,7 +647,7 @@ section, the following options need to be configured: -o MASTER_KEY \ -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 -- The “CURRENCY” option specifies the exchange’s currency. +- The ``CURRENCY`` option specifies the exchange’s currency. For the Taler demonstrator, use: .. code-block:: console @@ -680,7 +659,7 @@ section, the following options need to be configured: 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 +currency from the ``TALER`` section, the exchange is ignored. If you need to support multiple currencies, you need to configure a backend per currency. @@ -693,8 +672,8 @@ 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: +- The ``AUDITOR_BASE_URL`` option specifies the auditor’s base URL. + For example, to use the Taler demonstrator's auditor, specify: .. code-block:: console @@ -702,7 +681,7 @@ that section, the following options need to be configured: -o AUDITOR_BASE_URL \ -V https://exchange.demo.taler.net/ -- The “AUDITOR_KEY” option specifies the auditor's public key +- The ``AUDITOR_KEY`` option specifies the auditor's public key in base32 encoding. For the Taler demonstrator, use: .. code-block:: console @@ -711,7 +690,7 @@ that section, the following options need to be configured: -o AUDITOR_KEY \ -V FIXMEBADVALUENEEDTOGETTHERIGHTVALUEHEREEVENTUALLY000 -- The “CURRENCY” option specifies the auditor’s currency. +- The ``CURRENCY`` option specifies the auditor’s currency. For the Taler demonstrator, use: .. code-block:: console @@ -769,7 +748,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 -"FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0". +``FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0``. Please note that ``doc/config.sh`` will walk you through all configuration steps, showing how to invoke ``taler-config`` for each of @@ -835,8 +814,8 @@ 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/ <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" +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/ <https://bank.demo.taler.net/>`_. @@ -846,16 +825,16 @@ 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 +(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. +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 +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` @@ -874,10 +853,10 @@ create a file ``instance.json`` with an `InstanceConfigurationMessage` "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 +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 @@ -892,7 +871,7 @@ You can then create the instance using: 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". +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 @@ -958,8 +937,8 @@ process after changing the ``SERVE`` configuration. Apache ^^^^^^ -In Apache, make sure you have "mod_proxy", "mod_proxy_http" and -"mod_headers" enabled: +In Apache, make sure you have ``mod_proxy``, ``mod_proxy_http`` and +``mod_headers`` enabled: .. code-block:: console @@ -978,7 +957,7 @@ endpoint): </Location> Note that the above again assumes your domain name is ``example.com`` and that -you have TLS configured. Note that you must add the "https" header unless +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 @@ -1017,10 +996,10 @@ follows: 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 +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 @@ -1054,7 +1033,7 @@ each instance: Apache ^^^^^^ -For Apache, you should first enable "mod_rewrite": +For Apache, you should first enable ``mod_rewrite``: .. code-block:: console @@ -1072,10 +1051,10 @@ Then, you can restrict to an access control token using: 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 +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 @@ -1159,7 +1138,7 @@ 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 +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 @@ -1227,7 +1206,7 @@ Fund the 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: +10 KUDOS at instance ``default`` using the demo exchange, use: .. code-block:: console @@ -1241,7 +1220,7 @@ port 8888. The current implementation of the tool does not yet support transmission of authentication information to the backend (`see bug 6418 <https://bugs.gnunet.org/view.php?id=6418>`_). -The command will output a payto:// URI which specifies where to +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. @@ -1417,7 +1396,7 @@ 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 +Run: .. code-block:: console @@ -1425,7 +1404,7 @@ Run to list all of the configuration values in section ``$SECTION``. -Run +Run: .. code-block:: console @@ -1434,7 +1413,7 @@ Run to extract the respective configuration value for option ``$option`` in section ``$section``. -Finally, to change a setting, run +Finally, to change a setting, run: .. code-block:: console @@ -1476,7 +1455,7 @@ 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 +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). @@ -1517,7 +1496,7 @@ 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. +details are set up. For details, see the :ref:`Exchange Operator Manual <Bank-account>`. @@ -1531,7 +1510,7 @@ one of them being mandatory: 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". + ``exchange-account-exchange``. The tool comes with two operation modes: *ordinary*, and *corner*. The first just executes normal payments, meaning that it uses the @@ -1541,7 +1520,7 @@ 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. +the back-office facility. Any subcommand is also equipped with the canonical ``--help`` option, so feel free to issue the following command in order to explore all the @@ -1631,7 +1610,7 @@ 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: +request to the merchant, for example: .. code-block:: console |