commit 65f4bc149da9c1bca3a226fb8dbf12425d15b3dd
parent b65aa4c2910dd889f07f7458c396b1870351cdf1
Author: Christian Grothoff <christian@grothoff.org>
Date: Mon, 20 Mar 2017 14:32:29 +0100
move exchange operator manual as texinfo into exchange.git
Diffstat:
7 files changed, 7 insertions(+), 542 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
@@ -64,11 +64,11 @@ source_suffix = '.rst'
#source_encoding = 'utf-8-sig'
# The master toctree document.
-master_doc = 'index'
+master_doc = 'operate-exchange'
# General information about the project.
project = u'Taler'
-copyright = u'2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)'
+copyright = u'2014, 2015, 2016, 2017 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+)'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -251,7 +251,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- ('index', 'taler', u'Taler Documentation',
+ ('index', 'taler', u'GNU Taler Exchange Operator Manual',
[u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff'],
1)
]
@@ -266,7 +266,7 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- ('index', 'taler', u'GNU Taler Documentation',
+ ('index', 'taler', u'GNU Taler Exchange Operator Manual',
u'F. Dold, B. Muller, S. H. Totakura, C. Grothoff',
'Taler', 'One-Click Cash Payments.',
'Miscellaneous'),
diff --git a/docs/deployment.rst b/docs/deployment.rst
@@ -18,7 +18,7 @@ Wallet
$ make package-stable
-The built wallet is now ready in `taler-wallet-stable-${version_name}${version}.zip`.
+The built wallet is now ready in `taler-wallet-stable-${version_name}${version}.zip`.
FIXME: here, we should do some semi-automated testing with selenium, to see
that everything works against `demo.taler.net`.
@@ -44,7 +44,7 @@ merchant.git, merchant-frontends.git, bank.git, landing.git) do:
$ cd $REPO
$ git pull origin master stable
$ git checkout stable
-
+
# option a: resolve conflicts resulting from hotfixes
$ git merge master
$ ...
@@ -66,7 +66,7 @@ The following instructions wipe out the old deployment completely.
.. code-block:: none
$ ls -l ~demo/sockets
-
+
[...] sockets -> /home/demo-green/sockets/
In this case, `demo-green` is the active deployment, and `demo-blue` should be updated.
@@ -92,140 +92,3 @@ After the update is over, the `/home/demo/sockets` symlink will be pointed to `d
# look at the logs, verify that everything is okay
Now the symlink can be updated.
-
-
-
-------------------
-Database upgrades
-------------------
-
-The exchange db can be re-initialized with
-
-.. code-block:: none
-
- $ taler-exchange-dbinit -r
-
-CAUTION: YOU WILL LOSE ALL DATA WITH THIS!
-
-
----------------------
-Standalone deployment
----------------------
-
-This tecnique aims to set a thorough Taler installation up on a
-machine whose nginx configuration is configured by config files
-from https://git.taler.net/deployment.git/tree/etc/nginx.
-
-This installation assumes that all the steps are run with ``$HOME``
-as ``$CWD``.
-
-The first step is to fetch the `deployment` repository, which hosts all
-the needed scripts.
-
-.. code-block:: none
-
- # Adapt the repository's URI to your needs.
- $ git clone /var/git/deployment.git/
-
-The next step is to fetch all the codebases from all the components.
-
-.. code-block:: none
-
- $ ./deployment/bootstrap-standalone
-
-If the previous step succeeded, a file named ``activate`` should be now
-in the ``$CWD``. It contains environmental definitions for ``$PATH`` and
-database names.
-
-.. note::
-
- Please *ignore* the output from the previous script when it succeeds,
- which is
-
- .. code-block:: none
-
- WARNING: enabling "trust" authentication for local connections
- You can change this by editing pg_hba.conf or using the option -A, or
- --auth-local and --auth-host, the next time you run initdb.
-
- Success. You can now start the database server using:
-
- /usr/lib/postgresql/9.5/bin/pg_ctl -D talerdb -l logfile start
-
- The reason is that this message is generated by Postgresql's utilities and
- you never need to start your database manually; it will be started by the
- init script that launches all the Taler processes.
-
-Now we need to compile and install all the downloaded codebases.
-
-.. code-block:: none
-
- # We first update ``$PATH``, in order to make all the compilation
- # and configuration utilities available.
- $ source activate
-
- # Double check if the previous step worked: $PATH should
- # contain $HOME/local/bin.
- $ echo $PATH
-
- # The actual compilation:
- $ taler-deployment-build
-
-The following step will generate config files for all the components.
-Please **note** that although a default currency will be picked up by the
-script, it is possible to have a custom currency by setting the environment
-variable ``TALER_CONFIG_CURRENCY`` to the wanted currency, and then running
-the config generator.
-
-.. code-block:: none
-
- $ taler-deployment-config-generate
-
-whereas the following one will place signatures inside wireformat JSON
-files.
-
-.. code-block:: none
-
- $ taler-deployment-config-sign
-
-The next step is to generate `signkeys` and `denomkeys`.
-
-.. code-block:: none
-
- $ taler-deployment-keyup
-
-..
- An error of "invalid currency name" might be related to the current
- policy of 12-chars limit for currency names; which is likely going to
- be changed.
-
-It may be necessary to define database tables for the exchange. The
-following command does that.
-
-.. code-block:: none
-
- # Erase all the data!
- $ taler-exchange-dbinit -r
-
-As of the merchant backend, it creates tables at launch time, so it is
-not required to define tables before launching it. `However`, if some
-table's definition changed over the time, and there is a need to force
-a redefinition of tables, then the following command accomplishes that
-for the merchant:
-
-.. code-block:: none
-
- # Erase all the data!
- $ taler-merchant-dbinit -r
-
-If all previous steps succeeded, it is now possible to launch all the
-processes. That is accomplished by the following command:
-
-.. code-block:: none
-
- $ taler-deployment-start
-
-.. note::
-
- Please make sure your nginx works correctly with its configuration
- at ``<DEPLOYMENT-REPO>/etc/nginx``.
diff --git a/docs/dev-exchange.rst b/docs/dev-exchange.rst
@@ -1,144 +0,0 @@
-..
- This file is part of GNU TALER.
- Copyright (C) 2014, 2015, 2016 INRIA
-
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU General Public License as published by the Free Software
- Foundation; either version 2.1, or (at your option) any later version.
-
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
- @author Christian Grothoff
- @author Marcello Stanisci
-
-========
-Exchange
-========
-
-.. _keys-duration:
-
--------------
-Keys duration
--------------
-
-`signkeys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
-is run, `taler-exchange-keyup` will generate `n` `signkeys`, where `t + (n * signkey_duration) = t +
-lookahead_sign`. In other words, we generate a number of keys which is sufficient to cover a period of
-`lookahead_sign`. As for the starting date, the first generated key will get a starting time of `t`,
-and the `j`-th key will get a starting time of `x + signkey_duration`, where `x` is the starting time
-of the `(j-1)`-th key.
-
-`denom keys`. The option `lookahead_sign` is such that, being `t` the time when `taler-exchange-keyup`
-is run, `taler-exchange-keyup` will generate `n` `denom keys` for each denomination, where
-`t + (n * duration_withdraw) = t + lookahead_sign`. In other words, for each denomination, we generate a
-number of keys which is sufficient to cover a period of `lookahead_sign`. As for the starting date, the
-first generated key will get a starting time of `t`, and the `j`-th key will get a starting time of
-`x + duration_withdraw`, where `x` is the starting time of the `(j-1)`-th key.
-
-
-
----------------
-Database Scheme
----------------
-
-The exchange database must be initialized using `taler-exchange-dbinit`. This
-tool creates the tables required by the Taler exchange to operate. The
-tool also allows you to reset the Taler exchange database, which is useful
-for test cases but should never be used in production. Finally,
-`taler-exchange-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 exchange look as follows:
-
-.. image:: exchange-db.png
-
-
--------------------
-Signing key storage
--------------------
-
-The private online signing keys of the exchange are stored in a
-subdirectory "signkeys/" of the "KEYDIR" which is an option in the
-"[exchange]" section of the configuration file. The filename is the
-starting time at which the signing key can be used in microseconds
-since the Epoch. The file format is defined by the `struct
-TALER_EXCHANGEDB_PrivateSigningKeyInformationP`:
-
-.. sourcecode:: c
-
- struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP {
- struct TALER_ExchangePrivateKeyP signkey_priv;
- struct TALER_ExchangeSigningKeyValidityPS issue;
- };
-
-------------------------
-Denomination key storage
-------------------------
-
-The private denomination keys of the exchange are store in a
-subdirectory "denomkeys/" of the "KEYDIR" which is an option in the
-"[exchange]" section of the configuration file. "denomkeys/" contains
-further subdirectories, one per denomination. The specific name of
-the subdirectory under "denomkeys/" is ignored by the exchange.
-However, the name is important for the "taler-exchange-keyup" tool
-that generates the keys. The tool combines a human-readable encoding
-of the denomination (i.e. for EUR:1.50 the prefix would be
-"EUR_1_5-", or for EUR:0.01 the name would be "EUR_0_01-") with a
-postfix that is a truncated Crockford32 encoded hash of the various
-attributes of the denomination key (relative validity periods, fee
-structure and key size). Thus, if any attributes of a coin change,
-the name of the subdirectory will also change, even if the
-denomination remains the same.
-
-Within this subdirectory, each file represents a particular
-denomination key. The filename is the starting time at which the
-signing key can be used in microseconds since the Epoch. The
-format on disk begins with a
-`struct TALER_EXCHANGEDB_DenominationKeyInformationP` giving
-the attributes of the denomination key and the associated
-signature with the exchange's long-term offline key:
-
-.. sourcecode:: c
-
- struct TALER_EXCHANGEDB_DenominationKeyInformationP {
- struct TALER_MasterSignatureP signature;
- struct TALER_DenominationKeyValidityPS properties;
- };
-
-This is then followed by the variable-size RSA private key in
-libgcrypt's S-expression format, which can be decoded using
-`GNUNET_CRYPTO_rsa_private_key_decode()`.
-
--------------------------
-Auditor signature storage
--------------------------
-
-Signatures from auditors are stored in the directory specified
-in the exchange configuration section "exchangedb" under the
-option "AUDITOR_BASE_DIR". The exchange does not care about
-the specific names of the files in this directory.
-
-Each file must contain a header with the public key information
-of the auditor, the master public key of the exchange, and
-the number of signed denomination keys:
-
-.. sourcecode:: c
-
- struct AuditorFileHeaderP {
- struct TALER_AuditorPublicKeyP apub;
- struct TALER_MasterPublicKeyP mpub;
- uint32_t dki_len;
- };
-
-This is then followed by `dki_len` signatures of the auditor of type
-`struct TALER_AuditorSignatureP`, which are then followed by another
-`dki_len` blocks of type `struct TALER_DenominationKeyValidityPS`.
-The auditor's signatures must be signatures over the information of
-the corresponding denomination key validity structures embedded in a
-`struct TALER_ExchangeKeyValidityPS` structure using the
-`TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS` purpose.
diff --git a/docs/exchange-db-generate.sh b/docs/exchange-db-generate.sh
@@ -1,3 +0,0 @@
-#!/bin/sh
-taler-exchange-dbinit -r
-java -jar schemaSpy_5.0.0.jar -t pgsql -db taler -o taler -host localhost -dp /usr/share/java/postgresql-jdbc3-9.2.jar -u grothoff -p test -s public -hq
diff --git a/docs/exchange-db.png b/docs/exchange-db.png
Binary files differ.
diff --git a/docs/index.rst b/docs/index.rst
@@ -53,7 +53,6 @@ It focuses on how to install, configure and run the required software.
global-licensing
configuration-basics
- operate-exchange
operate-merchant
versioning
@@ -86,7 +85,6 @@ core components of the Taler reference implementation.
dev-talerdotnet
dev-wallet-wx
- dev-exchange
dev-merchant
deployment
releases
diff --git a/docs/operate-exchange.rst b/docs/operate-exchange.rst
@@ -1,249 +0,0 @@
-..
- This file is part of GNU TALER.
- Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA
- TALER is free software; you can redistribute it and/or modify it under the
- terms of the GNU General Public License as published by the Free Software
- Foundation; either version 2.1, or (at your option) any later version.
- TALER is distributed in the hope that it will be useful, but WITHOUT ANY
- WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
- You should have received a copy of the GNU Lesser General Public License along with
- TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
-
- @author Christian Grothoff
-
-======================
-Operating the Exchange
-======================
-
-+++++++++++++
-Configuration
-+++++++++++++
-
-The following data and facilities have to be set up, in order to run an exchange:
-
-* Keying
-* Serving
-* Currency
-* Bank account
-* Coins
-* Database
-
-In this document, we assume that ``$HOME/.config/taler.conf`` is being customized.
-
-------
-Keying
-------
-
-The exchange works with three types of keys:
-
-* `master key`
-* `sign keys`
-* `denomination keys` (see section `Coins`)
-
-`master key`: in section `[exchange]`, edit the two following values:
-
-* `master_priv_file`: Path to the exchange's master private file.
-* `master_public_key`: Must specify the exchange's master public key.
-
-`sign keys`: the following two options under `[exchange_keys]` section control `sign keys`:
-
-* `signkey_duration`: How long should one signing key be used?
-* `lookahead_sign`: How much time we want to cover with our `signkeys`? Note that if `signkey_duration` is bigger than `lookahead_sign`, `taler-exchange-keyup` will generate a quantity of `signkeys` which is sufficient to cover all the gap. See :ref:`keys-duration`.
-
--------
-Serving
--------
-
-The exchange can serve HTTP over both TCP and UNIX domain socket. It needs this
-configuration *twice*, because it opens one connection for ordinary REST calls, and one
-for "/admin" and "/test" REST calls, because the operator may want to restrict the access to "/admin".
-
-The following values are to be configured under the section `[exchange]` and `[exchange-admin]`:
-
-* `serve`: must be set to `tcp` to serve HTTP over TCP, or `unix` to serve HTTP over a UNIX domain socket
-* `port`: Set to the TCP port to listen on if `serve` Is `tcp`.
-* `unixpath`: set to the UNIX domain socket path to listen on if `serve` Is `unix`
-* `unixpath_mode`: number giving the mode with the access permissiON MASK for the `unixpath` (i.e. 660 = rw-rw----).
-
-The exchange can be started with the `-D` option to disable the administrative
-functions entirely. It is recommended that the administrative API is only
-accessible via a properly protected UNIX domain socket.
-
---------
-Currency
---------
-
-The exchange supports only one currency. This data is set under the respective
-option `currency` in section `[taler]`.
-
-------------
-Bank account
-------------
-
-Wireformat
-^^^^^^^^^^
-
-The wireformat is the protocol to be used between the exchange and the banks.
-The option is `wireformat`, under section `[exchange]`. The exchange currently supports
-the `test` wireformat. This wireformat is used for testing the system against a fictional bank.
-
-.. note::
- The SEPA wireformat is work in progress.
-
-Incoming
-^^^^^^^^
-The bank account where the exchange gets money from customers is configured under
-the section `[exchange-wire-incoming-X]`, where `X` matches the value given to the
-option `wireformat`. This section contains only one option: `X_response_file`, which
-takes the path to a text file containing the exchange's bank account details in JSON
-format.
-
-The command line tool `taler-exchange-wire` is used to create such a file.
-For example, the utility may be invoked as follows::
-
- $ taler-exchange-wire -j '{"name": "The Exchange", "account_number": 10, "bank_uri": "https://bank.demo.taler.net", "type": "test"}' -t test -o exchange.json
-
-Note that the value given to option `-t` must match the value in the JSON's field ``"type"``.
-
-The generated file will be echoed by the exchange when serving
-`/wire <https://api.taler.net/api-exchange.html#wire-req>`_
-requests.
-
-Outgoing
-^^^^^^^^
-
-This exchange's bank account is used to give money to merchants, after successful
-`deposits <https://api.taler.net/api-exchange.html#deposit-par>`_
-operations. If `test` is the chosen wireformat, the outcoming bank account is configured by the following
-options under `[exchange-wire-outcoming-test]`:
-
- * `exchange_account_numer`: which bank account number has the exchange
- * `bank_uri`: base URL of the bank hosting the exchange bank account
-
-.. note::
- The rationale behind having two bank accounts is that the exchange operator, as a security
- measure, may want to instruct the bank that the incoming bank account is only supposed to
- *receive* money.
-
---------
-Database
---------
-
-The option `db` under section `[exchange]` gets the DB backend's name the exchange
-is going to use. So far, only `db = postgres` is supported. After choosing the backend,
-it is mandatory to supply the connection string (namely, the database name). This is
-possible in two ways:
-
-* via an environment variable: `TALER_EXCHANGEDB_POSTGRES_CONFIG`.
-* via configuration option `db_conn_str`, under section `[exchangedb-BACKEND]`. For example, the demo exchange is configured as follows:
-
-.. code-block:: text
-
- [exchange]
- ...
- db = postgres
- ...
-
- [exchangedb-postgres]
- db_conn_str = postgres:///talerdemo
-
--------------------------
-Coins (denomination keys)
--------------------------
-
-Sections specifying denomination (coin) information start with "coin\_". By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE", i.e. `[coin_eur_ct_10]` for a 10 cent piece. However, only the "coin\_" prefix is mandatory. Each "coin\_"-section must then have the following options:
-
-* `value`: How much is the coin worth, the format is CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
-* `duration_withdraw`: How long can a coin of this type be withdrawn? This limits the losses incurred by the exchange when a denomination key is compromised.
-* `duration_overlap`: What is the overlap of the withdrawal timespan for this coin type?
-* `duration_spend`: How long is a coin of the given type valid? Smaller values result in lower storage costs for the exchange.
-* `fee_withdraw`: What does it cost to withdraw this coin? Specified using the same format as `value`.
-* `fee_deposit`: What does it cost to deposit this coin? Specified using the same format as `value`.
-* `fee_refresh`: What does it cost to refresh this coin? Specified using the same format as `value`.
-* `rsa_keysize`: How many bits should the RSA modulus (product of the two primes) have for this type of coin.
-
--------------
-Keys duration
--------------
-
-Both `signkeys` and `denom keys` have a :ref:`starting date <keys-duration>`. The option `lookahead_provide`, under section `[exchange_keys]`, is such that only keys
-whose starting date is younger than `lookahead_provide` will be issued by the exchange.
-
-.. _exchange-install:
-
-++++++++++++
-Installation
-++++++++++++
-
-Please install the following packages before proceeding with the exchange compilation.
-
-* autoconf >= 2.69
-* automake >= 1.14
-* libtool >= 2.4
-* autopoint >= 0.19
-* libltdl >= 2.4
-* libunistring >= 0.9.3
-* libcurl >= 7.26 (or libgnurl >= 7.26)
-* GNU libmicrohttpd >= 0.9.39
-* GNU libgcrypt >= 1.6
-* libjansson >= 2.7
-* Postgres >= 9.4, including libpq
-* libgnunetutil (from Git)
-* GNU Taler exchange (from Git)
-
-Except for the last two, these are available in most GNU/Linux
-distributions and should just be installed using the respective
-package manager.
-
-The following instructions will show how to install libgnunetutil and
-the GNU Taler exchange.
-
-
-Before you install libgnunetutil, you must download and install the
-dependencies mentioned above, otherwise the build may succeed but fail
-to export some of the tooling required by Taler.
-
-To download and install libgnunetutil, proceed as follows::
-
- $ git clone https://gnunet.org/git/gnunet/
- $ cd gnunet/
- $ ./bootstrap
- $ ./configure [--prefix=GNUNETPFX]
- $ # Each dependency can be fetched from non standard locations via
- $ # the '--with-<LIBNAME>' option. See './configure --help'.
- $ make
- # make install
-
-
-If you did not specify a prefix, GNUnet will install to
-``/usr/local``, which requires you to run the last step as
-``root``.
-
-To download and install the GNU Taler exchange, proceeds as follows::
-
- $ git clone git://taler.net/exchange
- $ cd exchange
- $ ./bootstrap
- $ ./configure [--prefix=EXCHANGEPFX] \
- [--with-gnunet=GNUNETPFX]
- $ # Each dependency can be fetched from non standard locations via
- $ # the '--with-<LIBNAME>' 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``. Note that you have to specify ``--with-gnunet=/usr/local``
-if you installed GNUnet to ``/usr/local`` in the previous step.
-
-+++++
-Other
-+++++
-
-------------------
-Reserve management
-------------------
-
-Incoming transactions to the exchange's provider result in the creation or update of reserves, identified by their reserve key.
-The command line tool `taler-exchange-reservemod` allows create and add money to reserves in the exchange's database.
