commit 8640f7ce94623a4fde8d57da9e7614f3f0f818e6 parent 4dc726bbeb8611857696794171c5c4f088a48849 Author: Christian Grothoff <christian@grothoff.org> Date: Sat, 27 Sep 2025 15:36:04 +0200 add missing Donau manpages Diffstat:
| M | conf.py | | | 58 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | core/api-merchant.rst | | | 5 | +++-- |
| A | manpages/donau-config.1.rst | | | 92 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-dbconfig.1.rst | | | 61 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-dbinit.1.rst | | | 61 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-httpd.1.rst | | | 121 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-secmod-cs.1.rst | | | 76 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-secmod-eddsa.1.rst | | | 76 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau-secmod-rsa.1.rst | | | 76 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| A | manpages/donau.conf.5.rst | | | 286 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | manpages/taler-exchange-httpd.1.rst | | | 3 | +-- |
| A | manpages/taler-merchant-donaukeyupdate.1.rst | | | 73 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
12 files changed, 984 insertions(+), 4 deletions(-)
diff --git a/conf.py b/conf.py @@ -389,6 +389,64 @@ man_pages = [ "GNU Taler contributors", 5, ), + + ( + "manpages/donau-config.1", + "donau-config", + "manipulate Donau configuration files", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau-dbconfig.1", + "donau-dbconfig", + "configure Donau database", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau-dbinit.1", + "sync-dbinit", + "initialize the Donau database", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau-httpd.1", + "donau-httpd", + "provide the Donau HTTP interface", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau.conf.5", + "donau.conf", + "Donau configuration file", + "GNU Taler contributors", + 5, + ), + ( + "manpages/donau-secmod-eddsa.1", + "donau-secmod-eddsa", + "handle private EDDSA key operations for a Donau", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau-secmod-cs.1", + "donau-secmod-cs", + "handle private CS key operations for a Donau", + "GNU Taler contributors", + 1, + ), + ( + "manpages/donau-secmod-rsa.1", + "donau-secmod-rsa", + "handle private RSA key operations for a Donau", + "GNU Taler contributors", + 1, + ), + ( "manpages/taler-auditor-dbinit.1", "taler-auditor-dbinit", diff --git a/core/api-merchant.rst b/core/api-merchant.rst @@ -5325,8 +5325,9 @@ Listing charity instances // Calendar year the receipts refer to current_year: Integer; - // Exchange-style ``/keys`` response published by Donau - donau_keys_json: object; + // Exchange-style ``/keys`` response published by Donau, + // missing if not yet known to the merchant backend. + donau_keys_json?: object; } Adding a charity instance diff --git a/manpages/donau-config.1.rst b/manpages/donau-config.1.rst @@ -0,0 +1,92 @@ +donau-config(1) +############### + +.. only:: html + + Name + ==== + + **donau-config** - manipulate Donau configuration files + +Synopsis +======== + +**donau-config** +[**-c** *filename* | **--config=**\ \ *filename*] +[**-f** | **--filename**] +[**-F** | **--full**] +[**-h** | **--help**] +[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*] +[**-l** *filename* | **--logfile=**\ \ *filename*] +[**-o** *option* | **--option=**\ \ *option*] +[**-r** | **--rewrite**] +[**-S** | **--list-sections**] +[**-s** *section* | **--section=**\ \ *section*] +[**-V** *value* | **--value=**\ \ *value*] +[**-v** | **--version**] + + +Description +=========== + +**donau-config** can be used to read or modify Donau configuration files. + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration file *FILENAME*. + +**-f** \| **--filename** + Try to perform expansions as if the option values represent filenames (will + also be applied even if the option is not really a filename). + +**-F** \| **--full** + Write the full configuration file, not just the differences to the defaults. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Use *LOGLEVEL* for logging. + Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-o** *OPTION* \| **--option=**\ \ *OPTION* + Which configuration option should be accessed or edited. Required to set a + value. If not given, all values of a given section will be printed in the + format "OPTION = VALUE". + +**-r** \| **--rewrite** + Write the configuration file even if nothing changed. Will remove all comments! + +**-S** \| **--list-sections** + List available configuration sections for use with ``--section``. + +**-s** *SECTION* \| **--section=**\ \ *SECTION* + Which configuration section should be accessed or edited. + Required option. + +**-V** *VALUE* \| **--value=**\ \ *VALUE* + Configuration value to store in the given section under the given option. + Must only be given together with ``-s`` and ``-o`` options. + + Note: + Changing the configuration file with ``-V`` will remove comments + and may reorder sections and remove ``@INLINE@`` directives. + Using **-V** is thus dangerous! Use with extreme caution! + +**-v** \| **--version** + Print GNU Taler version number. + + + +See Also +======== + +donau.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-dbconfig.1.rst b/manpages/donau-dbconfig.1.rst @@ -0,0 +1,61 @@ +donau-dbconfig(1) +################# + +.. only:: html + + Name + ==== + + **donau-dbconfig** - configure Donau database + + +Synopsis +======== + +**donau-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**donau-dbconfig** is a simple shell script that configures +a Postgresql database for use by Donau. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``donau-dbinit`` manually. + +**-u** *USER* + Specifies the (main) Donau user that will access the database. + +See Also +======== + +donau-dbinit(1), donau.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-dbinit.1.rst b/manpages/donau-dbinit.1.rst @@ -0,0 +1,61 @@ +donau-dbinit(1) +############### + +.. only:: html + + Name + ==== + + **donau-dbinit** - initialize Donau database + + +Synopsis +======== + +**donau-dbinit** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-r** | **--reset**] +[**-v** | **--version**] + +Description +=========== + +**donau-dbinit** is a command-line tool to initialize the Donau database. +It creates the necessary tables and indices for the Donau to operate. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the exchange to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-r** \| **--reset** + Drop tables. Dangerous, will delete all existing data in the database + before creating the tables. + +**-v** \| **–version** + Print version information. + +See Also +======== + +donau-httpd(1), donau-dbconfig(1), donau.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-httpd.1.rst b/manpages/donau-httpd.1.rst @@ -0,0 +1,121 @@ +donau-httpd(1) +############## + +.. only:: html + + Name + ==== + + **donau-httpd** - run Donau (with RESTful API) + +Synopsis +======== + +**donau-httpd** +[**-a** | **--allow-timetravel**] +[**-C** | **--connection-close**] +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-f** *FILENAME* | **--file-input=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-n** *N* | **--num-threads=**\ \ *N*] +[**-r**|**--allow-reuse-address**] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** *SECONDS* | **--timeout=**\ \ *SECONDS*] +[**-v** | **--version**] + +Description +=========== + +**donau-httpd** is a command-line tool to run the Donau +(HTTP server). The required configuration, keys and database +must exist before running this command. + +Its options are as follows: + +**-a** \| **--allow-timetravel** + Allow clients to request /keys for arbitrary timestamps. + This should only be enabled for testing and development, + as clients could abuse this in denial of service attacks, + as it makes the /keys response generation much more expensive. + +**-C** \| **--connection-close** + Force each HTTP connection to be closed after each request (useful in + combination with **-f** to avoid having to wait for + netcat (nc) to time out). + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from FILENAME. + +**-f** *FILENAME* \| **--file-input=**\ \ *FILENAME* + This option is only available if the exchange was compiled with the + configure option --enable-developer-mode. It is used for generating + test cases against the exchange using AFL. When this option is + present, the HTTP server will + + 1. terminate after the first client’s HTTP connection is completed, + and + 2. automatically start such a client using a helper process based on + the nc(1) or ncat(1) binary using FILENAME as the standard input + to the helper process. + + As a result, the process will effectively run with *FILENAME* as the + input from an HTTP client and then immediately exit. This is useful + to test donau-httpd against many different possible inputs + in a controlled way. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-r** \| **--allow-reuse-address** + Allow the exchange to re-use the listen port even if another service + is already using it. Useful if multiple processes are used to increase + processing capacity. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** *SECONDS* \| **--timeout=**\ \ *SECONDS* + Specifies the number of SECONDS after which the HTTPD should close + (idle) HTTP connections. + +**-v** \| **--version** + Print version information. + + +Signals +======= + +**donau-httpd** responds to the following signals: + +``SIGTERM`` + Sending a SIGTERM to the process will cause it to shutdown cleanly. + +``SIGHUP`` + Sending a SIGHUP to the process will cause it to re-execute the + donau-httpd binary in the PATH, passing it the existing + listen socket. Then the old server process will automatically exit + after it is done handling existing client connections; the new server + process will accept and handle new client connections. + +See Also +======== + +donau-dbinit(1), donau.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-secmod-cs.1.rst b/manpages/donau-secmod-cs.1.rst @@ -0,0 +1,76 @@ +donau-secmod-cs(1) +################## + +.. only:: html + + Name + ==== + + **donau-secmod-cs** - handle private Clause-Schnorr key operations for a Donau + + +Synopsis +======== + +**donau-secmod-cs** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-p** *N* | ,**--parallelism=**\ \ *N*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** *TIMESTAMP* | **--time=**\ \ *TIMESTAMP*] +[**-v** | **--version**] + + +Description +=========== + +**donau-secmod-cs** is a command-line tool to +handle private Clause-Schnorr key operations for a Donau. + +FIXME: More details. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**p** *N* \| **--parallelism=**\ \ *N* + Run with *N* worker threads. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** *TIMESTAMP* \| **--time=**\ \ *TIMESTAMP* + Pretend it is *TIMESTAMP* for the update. + *TIMESTAMP* is a human-readable string (e.g., ``YYYY-MM-DD HH:MM:SS``). + +**-v** \| **--version** + Print version information. + + +See Also +======== + +donau-httpd(1). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-secmod-eddsa.1.rst b/manpages/donau-secmod-eddsa.1.rst @@ -0,0 +1,76 @@ +donau-secmod-eddsa(1) +##################### + +.. only:: html + + Name + ==== + + **donau-secmod-eddsa** - handle private EDDSA key operations for a Donau + + +Synopsis +======== + +**donau-secmod-eddsa** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-p** *N* | ,**--parallelism=**\ \ *N*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** *TIMESTAMP* | **--time=**\ \ *TIMESTAMP*] +[**-v** | **--version**] + + +Description +=========== + +**donau-secmod-eddsa** is a command-line tool to +handle private EDDSA key operations for a Donau. + +FIXME: More details. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**p** *N* \| **--parallelism=**\ \ *N* + Run with *N* worker threads. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** *TIMESTAMP* \| **--time=**\ \ *TIMESTAMP* + Pretend it is *TIMESTAMP* for the update. + *TIMESTAMP* is a human-readable string (e.g., ``YYYY-MM-DD HH:MM:SS``). + +**-v** \| **--version** + Print version information. + + +See Also +======== + +donau-httpd(1). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau-secmod-rsa.1.rst b/manpages/donau-secmod-rsa.1.rst @@ -0,0 +1,76 @@ +donau-secmod-rsa(1) +################### + +.. only:: html + + Name + ==== + + **donau-secmod-rsa** - handle private RSA key operations for a Donau + + +Synopsis +======== + +**donau-secmod-rsa** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-p** *N* | ,**--parallelism=**\ \ *N*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** *TIMESTAMP* | **--time=**\ \ *TIMESTAMP*] +[**-v** | **--version**] + + +Description +=========== + +**donau-secmod-rsa** is a command-line tool to +handle private RSA key operations for a Donau. + +FIXME: More details. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**p** *N* \| **--parallelism=**\ \ *N* + Run with *N* worker threads. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** *TIMESTAMP* \| **--time=**\ \ *TIMESTAMP* + Pretend it is *TIMESTAMP* for the update. + *TIMESTAMP* is a human-readable string (e.g., ``YYYY-MM-DD HH:MM:SS``). + +**-v** \| **--version** + Print version information. + + +See Also +======== + +donau-httpd(1). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/donau.conf.5.rst b/manpages/donau.conf.5.rst @@ -0,0 +1,286 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2025 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 3.0, 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 Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Christian Grothoff + + +donau.conf(5) +############# + +.. only:: html + + Name + ==== + + **donau.conf** - Donau configuration file + + +Description +=========== + +.. include:: ../frags/common-conf-syntax.rst + +Files containing default values for many of the options described below +are installed under ``$DONAU_PREFIX/share/donau/config.d/``. +The configuration file given with **-c** to Donau binaries +overrides these defaults. + +A configuration file may include another, by using the ``@INLINE@`` directive, +for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to +include the entirety of ``sub.conf`` at that point in ``main.conf``. + +Be extra careful when using ``donau-config -V VALUE`` to change configuration +values: it will destroy all uses of ``@INLINE@`` and furthermore remove all +comments from the configuration file! + + +GLOBAL OPTIONS +-------------- + +The “[PATHS]” section is special in that it contains paths that can be +referenced using “$” in other configuration values that specify +filenames. For Taler exchange, it commonly contains the following paths: + +DONAU_HOME + Home directory of the user, usually “${HOME}”. Can be overwritten by + testcases by setting ${DONAU_TEST_HOME}. + +DONAU_DATA_HOME + Where should Taler store its long-term data. + Usually “${DONAU_HOME}/.local/share/donau/”. + +DONAU_CONFIG_HOME + Where is the Taler configuration kept. + Usually “${DONAU_HOME}/.config/donau/”. + +DONAU_CACHE_HOME + Where should Taler store cached data. + Usually “${DONAU_HOME}/.cache/donau/”. + +DONAU_RUNTIME_DIR + Where should Taler store system runtime data (like UNIX domain + sockets). Usually “${TMP}/donau-runtime”. + + +DONAU OPTIONS +------------- + +The following options are from the “[donau]” section and used by most +Donau components. + +ADMIN_BEARER_TOKEN + Bearer access token used to access the REST API to manage charities. + Should begin with "secret-token:". + +CURRENCY + Name of the currency, e.g. “EUR” for Euro. + +DB + Plugin to use for the database, e.g. “postgres”. + +SERVE + Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd"). + +UNIXPATH + Path to listen on if we "SERVE" is set to "unix". + +UNIXPATH_MODE + Access permission mask to use for the "UNIXPATH". + +PORT + Port on which the HTTP server listens, e.g. 8080. + +BIND_TO + Hostname to which the exchange HTTP server should be bound to, e.g. "localhost". + +BASE_URL + The base URL under which the exchange can be reached. + Added to wire transfers to enable tracking by merchants. + Used by the KYC logic when interacting with OAuth 2.0. + +TERMS_DIR + Directory where the terms of service of the exchange operator can be fund. + The directory must contain sub-directories for every supported language, + using the two-character language code in lower case, e.g. "en/" or "fr/". + Each subdirectory must then contain files with the terms of service in + various formats. The basename of the file of the current policy must be + specified under ``TERMS_ETAG``. The extension defines the mime type. + Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", + "png" and "gif". For example, using a ``TERMS_ETAG`` of "0", the structure + could be the following: + + - $TERMS_DIR/en/0.pdf + - $TERMS_DIR/en/0.html + - $TERMS_DIR/en/0.txt + - $TERMS_DIR/fr/0.pdf + - $TERMS_DIR/fr/0.html + - $TERMS_DIR/de/0.txt + +TERMS_ETAG + Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service. + The value is also used for the "Etag" in the HTTP request to control + caching. Whenever the terms of service change, the ``TERMS_ETAG`` MUST also + change, and old values MUST NOT be repeated. For example, the date or + version number of the terms of service SHOULD be used for the Etag. If + there are minor (e.g. spelling) fixes to the terms of service, the + ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must + approve the new terms, the ``TERMS_ETAG`` MUST change. + +PRIVACY_DIR + Works the same as ``TERMS_DIR``, just for the privacy policy. + +PRIVACY_ETAG + Works the same as ``TERMS_ETAG``, just for the privacy policy. + + +DONAU RSA CRYPTO HELPER OPTIONS +------------------------------- + +The following options must be in the section "[donau-secmod-rsa]". + +LOOKAHEAD_SIGN + How long do we generate denomination and signing keys ahead of time? + +OVERLAP_DURATION + Must be set to zero. + +SM_PRIV_KEY + Where should the security module store its long-term private key? + +KEY_DIR + Where should the security module store the private keys it manages? + +UNIXPATH + On which path should the security module listen for signing requests? + +Note that the **donau-secmod-rsa** also evaluates the ``[doco_*]`` +configuration sections described below. + + +DONAU CS CRYPTO HELPER OPTIONS +------------------------------ + +The following options must be in the section "[donau-secmod-cs]". + +LOOKAHEAD_SIGN + How long do we generate denomination and signing keys ahead of time? + +OVERLAP_DURATION + Must be set to zero. + +SM_PRIV_KEY + Where should the security module store its long-term private key? + +KEY_DIR + Where should the security module store the private keys it manages? + +UNIXPATH + On which path should the security module listen for signing requests? + +Note that the **donau-secmod-cs** also evaluates the ``[doco_*]`` +configuration sections described below. + + + +DONAU EDDSA CRYPTO HELPER OPTIONS +--------------------------------- + +The following options must be in the section "[donau-secmod-eddsa]". + +LOOKAHEAD_SIGN + How long do we generate denomination and signing keys ahead of time? + +OVERLAP_DURATION + How much should validity periods for coins overlap? + Should be long enough to avoid problems with + wallets picking one key and then due to network latency + another key being valid. The ``DURATION_WITHDRAW`` period + must be longer than this value. + +DURATION + For how long should EdDSA keys be valid for signing? + +SM_PRIV_KEY + Where should the security module store its long-term private key? + +KEY_DIR + Where should the security module store the private keys it manages? + +UNIXPATH + On which path should the security module listen for signing requests? + + +DONAU POSTGRES BACKEND DATABASE OPTIONS +--------------------------------------- + +The following options must be in section “[donaudb-postgres]” if the +“postgres” plugin was selected for the database. + +CONFIG + How to access the database, e.g. “postgres:///donau” to use the + “donau” database. Testcases use “donaucheck”. + + +.. include:: frags/exchange-coin.rst + +DONAU DONATION CONFIRMATION UNIT OPTIONS +---------------------------------------- + +The following options must be in sections starting with ``"[doco_]"`` and are +largely used by **donau-httpd** to determine the meta data for the donation +units. Some of the options are used by the **donau-secmod-rsa** to determine +which RSA keys to create (and of what key length). Note that the section +names must match, so this part of the configuration MUST be shared between the +RSA helper and the Donau. Configuration values MUST NOT be changed in a +running setup. Instead, if parameters for a denomination type are to change, a +fresh *section name* should be introduced (and the existing section should be +deleted). + + +VALUE + Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per + donation unit receipt). + +DURATION_WITHDRAW + How long should the same key be used for clients to withdraw coins of + this value? Must be set to 1 year. + +DURATION_SPEND + How long do clients have to turn in the donation receipts. + Should be set to a multiple of years. + +DURATION_LEGAL + How long does the Donau have to keep records for this denomination? + Should be set to a multiple of years. + +CIPHER + What cryptosystem should be used? Must be set to either "CS" or "RSA". + The respective crypto-helper will then generate the keys for this + denomination. + +RSA_KEYSIZE + What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA". + + +SEE ALSO +======== + +donau-dbinit(1), donau-httpd(1) + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-httpd.1.rst b/manpages/taler-exchange-httpd.1.rst @@ -112,8 +112,7 @@ Signals See Also ======== -taler-exchange-dbinit(1), taler-exchange-offline(1), -taler-exchange-reservemod(1), taler-exchange.conf(5). +taler-exchange-dbinit(1), taler-exchange-offline(1), taler-exchange.conf(5). Bugs ==== diff --git a/manpages/taler-merchant-donaukeyupdate.1.rst b/manpages/taler-merchant-donaukeyupdate.1.rst @@ -0,0 +1,73 @@ +taler-merchant-donaukeyupdate(1) +################################ + +.. only:: html + + Name + ==== + + **taler-merchant-donaukeyupdate** - keep key material (and configuration data) of each configured Donau current + + +Synopsis +======== + +**taler-merchant-donaukeyupdate** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-merchant-donaukeyupdate** is a background job that +downloads the current key material and configuration data from +each configured Donau and keeps an up-to-date copy in our +local database. + +The tool is part of a set of processes that allow a merchant backend to ensure +that the backend can properly interact with an Donau when issuing donation +receipts. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode. Only runs until the current list of bank + transactions have all been checked. + +**-v** \| **–version** + Print version information. + +See Also +======== + +donau-httpd(1), taler-merchant.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>.