summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2021-02-08 21:40:17 +0100
committerChristian Grothoff <christian@grothoff.org>2021-02-08 21:40:17 +0100
commit647c8910ae898df3d4b5da9ed44294cf51c2a3c7 (patch)
tree23dbe9c4bd620b3d5c332533acdfdea539bbd632
parent6630996e40a6873ff52e4a83e7d4250df32596bf (diff)
parentb603b7911c4c89ff4e5e78ee7c67a996331086b0 (diff)
downloaddocs-647c8910ae898df3d4b5da9ed44294cf51c2a3c7.tar.gz
docs-647c8910ae898df3d4b5da9ed44294cf51c2a3c7.tar.bz2
docs-647c8910ae898df3d4b5da9ed44294cf51c2a3c7.zip
Merge branch 'master' of git+ssh://git.taler.net/docs
-rw-r--r--core/api-exchange.rst3
-rw-r--r--frags/apt-install-taler-merchant.rst13
-rw-r--r--taler-merchant-manual.rst127
3 files changed, 69 insertions, 74 deletions
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
index 2ea2982..7d951a6 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 0000000..d9605f7
--- /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 8e2c7fa..e27c656 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