diff options
102 files changed, 14244 insertions, 4438 deletions
@@ -1,3 +1,7 @@ texinfo/*.html texinfo/*.info .dirstamp +*.png +_build/ +_exts/ +manpages/ diff --git a/man/challenger-admin.1 b/man/challenger-admin.1 new file mode 100644 index 00000000..22a465af --- /dev/null +++ b/man/challenger-admin.1 @@ -0,0 +1,89 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER-ADMIN" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger-admin \- manipulate list of authorized Challenger clients +.SH SYNOPSIS +.sp +\fBchallenger\-admin\fP +[\fB\-a\fP \fICLIENT_SECRET\fP\ |\ \fB–add=\fP\fICLIENT_SECRET\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-d\fP\ |\ \fB–delete\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-q\fP\ |\ \fB–quiet\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +CLIENT_URL +.SH DESCRIPTION +.sp +\fBchallenger\-admin\fP is a command\-line tool to add or delete clients from the Challenger database. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-a\fP \fISECRET\fP | \fB–add=\fP\fISECRET\fP +Add the client with the given \fICLIENT_URL setting the client secret to *SECRET\fP\&. Prints the CLIENT_ID of the added client. +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Challenger commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-d\fP | \fB–delete\fP +Delete the client with the given \fICLIENT_URL\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-q\fP | \fB–\-quiet\fP +Be less verbose in the output. Useful in shell scripts. +.TP +\fB\-v\fP | \fB–\-version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-config(1), challenger\-httpd(1), challenger.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/challenger-config.1 b/man/challenger-config.1 new file mode 100644 index 00000000..50275c66 --- /dev/null +++ b/man/challenger-config.1 @@ -0,0 +1,123 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER-CONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger-config \- manipulate Challenger configuration files +.SH SYNOPSIS +.sp +\fBchallenger\-config\fP +[\fB\-b\fP\ \fIbackend\fP\ |\ \fB–supported\-backend=\fP\fIbackend\fP] +[\fB\-c\fP\ \fIfilename\fP\ |\ \fB–config=\fP\fIfilename\fP] +[\fB\-f\fP\ |\ \fB–filename\fP] +[\fB\-F\fP\ |\ \fB–full\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fIloglevel\fP\ |\ \fB–loglevel=\fP\fIloglevel\fP] +[\fB\-l\fP\ \fIfilename\fP\ |\ \fB–logfile=\fP\fIfilename\fP] +[\fB\-o\fP\ \fIoption\fP\ |\ \fB–option=\fP\fIoption\fP] +[\fB\-r\fP\ |\ \fB–rewrite\fP] +[\fB\-S\fP\ |\ \fB–list\-sections\fP] +[\fB\-s\fP\ \fIsection\fP\ |\ \fB–section=\fP\fIsection\fP] +[\fB\-V\fP\ \fIvalue\fP\ |\ \fB–value=\fP\fIvalue\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBchallenger\-config\fP can be used to read or modify Challenger configuration files. +.INDENT 0.0 +.TP +\fB\-b\fP \fIBACKEND\fP | \fB–supported\-backend=\fP\fIBACKEND\fP +Tests whether the specified \fIBACKEND\fP is supported by the current installation. +The backend must match the name of a plugin, i.e. “namestore_postgres” for +the PostgreSQL database backend of the “NAMESTORE” service. If \fIBACKEND\fP is +supported, challenger\-config will return a status code of 0 (success), otherwise +77 (unsupported). When this option is specified, no other options may be +specified. Specifying this option together with other options will cause +challenger\-config to return a status code of 1 (error). +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration file \fIFILENAME\fP\&. +.TP +\fB\-f\fP | \fB–filename\fP +Try to perform expansions as if the option values represent filenames (will +also be applied even if the option is not really a filename). +.TP +\fB\-F\fP | \fB–full\fP +Write the full configuration file, not just the differences to the defaults. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Use \fILOGLEVEL\fP for logging. +Valid values are \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, and \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-o\fP \fIOPTION\fP | \fB–option=\fP\fIOPTION\fP +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”. +.TP +\fB\-r\fP | \fB–rewrite\fP +Write the configuration file even if nothing changed. Will remove all comments! +.TP +\fB\-S\fP | \fB–list\-sections\fP +List available configuration sections for use with \fB\-\-section\fP\&. +.TP +\fB\-s\fP \fISECTION\fP | \fB–section=\fP\fISECTION\fP +Which configuration section should be accessed or edited. +Required option. +.TP +\fB\-V\fP \fIVALUE\fP | \fB–value=\fP\fIVALUE\fP +Configuration value to store in the given section under the given option. +Must only be given together with \fB\-s\fP and \fB\-o\fP options. +.INDENT 7.0 +.TP +.B Note: +Changing the configuration file with \fB\-V\fP will remove comments +and may reorder sections and remove \fB@INLINE@\fP directives. +.UNINDENT +.TP +\fB\-v\fP | \fB–version\fP +Print GNU Taler version number. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-dbinit(1), challenger\-httpd(1), challenger.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/challenger-dbconfig.1 b/man/challenger-dbconfig.1 new file mode 100644 index 00000000..67b97611 --- /dev/null +++ b/man/challenger-dbconfig.1 @@ -0,0 +1,83 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER-DBCONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger-dbconfig \- configure challenger database +.SH SYNOPSIS +.sp +\fBchallenger\-dbconfig\fP +[\fB\-c\fP\ \fIFILENAME\fP] +[\fB\-h\fP] +[\fB\-n\fP\ \fINAME\fP] +[\fB\-r\fP] +[\fB\-s\fP] +[\fB\-u\fP\ \fIUSER\fP] +.SH DESCRIPTION +.sp +\fBchallenger\-dbconfig\fP is a simple shell script that configures +a Postgresql database for use by \fBchallenger\-httpd\fP\&. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP +Write the database configuration to FILENAME. The tool +will append the required \fBCONFIG\fP option for the +Postgresql access to the respective file. +.TP +\fB\-h\fP +Print short help on options. +.TP +\fB\-n\fP \fIDBNAME\fP +Use DBNAME for the name of the created database. +.TP +\fB\-r\fP +Reset any existing database. Looses all existing data. DANGEROUS. +.TP +\fB\-s\fP +Skip database initialization. Useful if you want to run +\fBchallenger\-dbinit\fP manually. +.TP +\fB\-u\fP \fIUSER\fP +Specifies the (main) challenger user that will access the database. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-dbinit(1), challenger.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/challenger-dbinit.1 b/man/challenger-dbinit.1 new file mode 100644 index 00000000..c87b35cd --- /dev/null +++ b/man/challenger-dbinit.1 @@ -0,0 +1,84 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER-DBINIT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger-dbinit \- initialize the Challenger database +.SH SYNOPSIS +.sp +\fBchallenger\-dbinit\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-g\fP\ |\ \fB–garbagecollect\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-r\fP\ |\ \fB–reset\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBchallenger\-dbinit\fP is a command\-line tool to initialize the Challenger database. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Challenger commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-g\fP | \fB–garbagecollect\fP +Remove state data from database. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-r\fP | \fB–reset\fP +Reset database. (\fBDANGEROUS\fP: All existing data is lost!) +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-config(1), challenger\-httpd(1), challenger.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/challenger-httpd.1 b/man/challenger-httpd.1 new file mode 100644 index 00000000..2cc1f345 --- /dev/null +++ b/man/challenger-httpd.1 @@ -0,0 +1,80 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER-HTTPD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger-httpd \- provide the Challenger HTTP interface +.SH SYNOPSIS +.sp +\fBchallenger\-httpd\fP +[\fB\-C\fP\ |\ \fB–connection\-close\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBchallenger\-httpd\fP is a command\-line tool to provide the Challenger HTTP interface. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-C\fP | \fB–connection\-close\fP +Force HTTP connections to be closed after each request. +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Challenger commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-config(1), challenger\-dbinit(1), challenger.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/challenger.conf.5 b/man/challenger.conf.5 new file mode 100644 index 00000000..f895feb1 --- /dev/null +++ b/man/challenger.conf.5 @@ -0,0 +1,179 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "CHALLENGER.CONF" "5" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +challenger.conf \- Challenger configuration file +.SH DESCRIPTION +.sp +The configuration file is line\-oriented. Blank lines and whitespace at the +beginning and end of a line are ignored. Comments start with \fB#\fP or \fB%\fP +in the first column (after any beginning\-of\-line whitespace) and go to the end +of the line. +.sp +The file is split into sections. Every section begins with \fB[SECTIONNAME]\fP +and contains a number of options of the form \fBOPTION=VALUE\fP\&. There may be +whitespace around the \fB=\fP (equal sign). Section names and options are +\fIcase\-insensitive\fP\&. +.sp +The values, however, are \fIcase\-sensitive\fP\&. In particular, boolean values are +one of \fBYES\fP or \fBNO\fP\&. Values can include whitespace by surrounding the +entire value with \fB\(dq\fP (double quote). Note, however, that there are no +escape characters in such strings; all characters between the double quotes +(including other double quotes) are taken verbatim. +.sp +Values that represent a time duration are represented as a series +of one or more \fBNUMBER UNIT\fP pairs, e.g. \fB60 s\fP, \fB4 weeks 1 day\fP, +\fB5 years 2 minutes\fP\&. +.sp +Values that represent an amount are in the usual amount syntax: +\fBCURRENCY:VALUE.FRACTION\fP, e.g. \fBEUR:1.50\fP\&. +The \fBFRACTION\fP portion may extend up to 8 places. +.sp +Values that represent filenames can begin with a \fB/bin/sh\fP\-like variable +reference. This can be simple, such as \fB$TMPDIR/foo\fP, or complex, such as +\fB${TMPDIR:\-${TMP:\-/tmp}}/foo\fP\&. The variables are expanded either using +key\-values from the \fB[PATHS]\fP section (see below) or from the environment +(\fBgetenv()\fP). The values from \fB[PATHS]\fP take precedence over those from +the environment. If the variable name is found in neither \fB[PATHS]\fP nor the +environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if \fBFOO=$BAR\fP and \fBBAR=buzz\fP then the result is \fBFOO=buzz\fP\&. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if \fBBAR=$FOO\fP in the example above. +.sp +The \fB[PATHS]\fP section is special in that it contains paths that can be +referenced using \fB$\fP in other configuration values that specify +\fIfilenames\fP\&. Note that configuration options that are not specifically +retrieved by the application as \fIfilenames\fP will not see “$”\-expressions +expanded. To expand \fB$\fP\-expressions when using \fBtaler\-config\fP, you must pass +the \fB\-f\fP command\-line option. +.sp +The system automatically pre\-populates the \fB[PATHS]\fP section with a few values +at run\-time (in addition to the values that are in the actual configuration +file and automatically overwriting those values if they are present). +These automatically generated values refer to installation properties +from \fI\%GNU autoconf\fP\&. The +values are usually dependent on an \fBINSTALL_PREFIX\fP which is determined by +the \fB\-\-prefix\fP option given to configure. The canonical values are: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ +.IP \(bu 2 +DOCDIR = $INSTALL_PREFIX/share/doc/taler/ +.IP \(bu 2 +ICONDIR = $INSTALL_PREFIX/share/icons/ +.IP \(bu 2 +LOCALEDIR = $INSTALL_PREFIX/share/locale/ +.IP \(bu 2 +PREFIX = $INSTALL_PREFIX/ +.IP \(bu 2 +BINDIR = $INSTALL_PREFIX/bin/ +.IP \(bu 2 +LIBDIR = $INSTALL_PREFIX/lib/taler/ +.IP \(bu 2 +DATADIR = $INSTALL_PREFIX/share/taler/ +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that on some platforms, the given paths may differ depending +on how the system was compiled or installed, the above are just the +canonical locations of the various resources. These +automatically generated values are never written to disk. +.sp +Files containing default values for many of the options described below +are installed under \fB$PREFIX/share/challenger/config.d/\fP\&. +The configuration file given with \fB\-c\fP to Challenger binaries +overrides these defaults. +.sp +A configuration file may include another, by using the \fB@INLINE@\fP directive, +for example, in \fBmain.conf\fP, you could write \fB@INLINE@ sub.conf\fP to +include the entirety of \fBsub.conf\fP at that point in \fBmain.conf\fP\&. +.sp +Be extra careful when using \fBchallenger\-config \-V VALUE\fP to change configuration +values: it will destroy all uses of \fB@INLINE@\fP and furthermore remove all +comments from the configuration file! +.SS GLOBAL OPTIONS +.sp +The following options are from the “[challenger]” section. +This is normally the only section in a challenger.conf file. +.INDENT 0.0 +.TP +.B SERVE +This can either be \fBtcp\fP or \fBunix\fP\&. +.TP +.B PORT +Port on which the HTTP server listens, e.g.\ 9967. +Only used if \fBSERVE\fP is \fBtcp\fP\&. +.TP +.B BIND_TO +Which IP address should we bind to? E.g. \fB127.0.0.1\fP or \fB::1\fP +for loopback. Can also be given as a hostname. We will bind to +the wildcard (dual\-stack) if left empty. +Only used if \fBSERVE\fP is \fBtcp\fP\&. +.TP +.B UNIXPATH +Which unix domain path should we bind to? +Only used if \fBSERVE\fP is \fBunix\fP\&. +.TP +.B UNIXPATH_MODE = 660 +What should be the file access permissions for \fBUNIXPATH\fP? +Only used if \fBSERVE\fP is \fBunix\fP\&. +.TP +.B DB +Plugin to use for the database, e.g.\ “postgres”. +.TP +.B VALIDATION_DURATION +How long is a validation challenge valid. After this time period, a fresh random challenge code will be generated and the retry limit counter (against guessing attacks) will be reset (to 3). +.TP +.B VALIDATION_EXPIRATION +How long is a validation allowed to take (time from +\fB/setup\fP to \fB/token\fP). After this time, the garbage collection process can delete all associated data. (Note that tokens will always allow access to 1h after they have been issued, regardless of when the validation expires). +.TP +.B AUTH_COMMAND +Which command should we execute to transmit the challenge code to the address. The address is given as the first argument, while the message to send is provided on stdin. Templates (possibly without the necessary credentials) for such commands are provided as challenger\-send\-email.sh, challenger\-send\-post.sh and challenger\-send\-sms.sh. +.TP +.B ADDRESS_TYPE +Type of the address that is being collected, returned as part of the \fBaddress_type\fP in the \fB/info\fP endpoint. Examples include \fBemail\fP or \fBphone\fP\&. +.TP +.B ADDRESS_RESTRICTIONS +JSON object with a map of keys (names of the fields of the address to be entered by the user) to objects with a “regex” (string) containing an extended Posix regular expression for allowed address field values, and a “hint”/”hint_i18n” giving a human\-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. Examples would be ‘{“email”:{“hint”:”valid e\-mail address required”,”regex”:”^[a\-zA\-Z0\-9_.+\-]+@[a\-zA\-Z0\-9\-]+.[a\-zA\-Z0\-9\-.]+$”}’ or ‘{“zip”:{“hint”:”numeric zip code required”,”regex”:”^[0\-9]+$”}’. +.UNINDENT +.SH SEE ALSO +.sp +challenger\-dbinit(1), challenger\-httpd(1), challenger\-config(1). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/libeufin-nexus.1 b/man/libeufin-nexus.1 new file mode 100644 index 00000000..93aab863 --- /dev/null +++ b/man/libeufin-nexus.1 @@ -0,0 +1,254 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "LIBEUFIN-NEXUS" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +libeufin-nexus \- service to interface to various bank access APIs +.SH SYNOPSIS +.sp +\fBlibeufin\-nexus\fP +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB–version\fP] +COMMAND [ARGS…] +.sp +Subcommands: \fBdbinit\fP, \fBebics\-setup\fP, \fBebics\-submit\fP, \fBebics\-fetch\fP, \fBconfig\fP +.SH DESCRIPTION +.sp +\fBlibeufin\-nexus\fP is a program that provides a service to interface to +various bank access APIs +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB–version\fP +Print version information. +.UNINDENT +.sp +The interaction model is as follows: +.sp +In order to operate any EBICS communication with \fBlibeufin\-nexus\fP, it is necessary to setup EBICS access via the \fBebics\-setup\fP subcommand. Setting the access means to share the client keys with the bank and downloading the bank keys. After a successful setup, the subcommands \fBebics\-submit\fP and \fBebics\-fetch\fP can be run to respectively send payments and download the bank account history. +.sp +The following sections describe each command in detail. +.SS ebics\-setup +.sp +This command creates the client keys, if they aren’t found already on the disk, and sends them to the bank if they were not sent yet. In case of sending, it ejects the PDF document that contains the keys fingerprints, so that the user can send it to the bank to confirm their keys. The process continues by checking if the bank keys exist already on disk, and proceeds with downloading them in case they are not. It checks then if the bank keys were accepted by the user; if yes, the setup terminates, otherwise it interactively asks the user to mark the keys as accepted. By accepting the bank keys, the setup terminates successfully. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.TP +\fB–force\-keys\-resubmission\fP +Resubmits the client keys. If no keys were found, it creates and submits them. +.TP +\fB–auto\-accept\-keys\fP +Accepts the bank keys without interactively asking the user. +.TP +\fB–generate\-registration\-pdf\fP +Generates the PDF with the client keys fingerprints, if the keys have the submitted state. That’s useful in case the PDF went lost after the first submission and the user needs a new PDF. +.UNINDENT +.SS dbinit +.sp +This subcommand defines the database schema for Nexus. It is mandatory to run this command before invoking the \fBebics\-submit\fP or \fBebics\-fetch\fP subcommands. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.TP +\fB\-r\fP | \fB–reset\fP +If present, deletes any database table (WARNING: potential data loss) +.UNINDENT +.SS ebics\-submit +.sp +This subcommand submits any initiated payment that was not already sent to the bank. In the current version, initiated payments may come from a cash\-out operation or from a bounced incoming payment. ebics\-submit is Taler friendly, therefore bounced payments are those that do not contain a valid subject to start a Taler withdrawal. Cash\-out operations come from a tightly integrated bank that offers their customers to convert their currency to the currency whose the EBICS subscriber bank account is tied to. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +Uploaded documents will be stored \fIbefore\fP being submitted to the bank. This directory would contain several directories, each named after the \fBYYYY\-MM\-DD/submit\fP format. The pain.001 file would then be named in the following schema: \fB$microseconds_pain.001.xml\fP\&. +.TP +\fB–transient\fP +This flag, enabled by default, causes the command to check the database and submit only once, and then return. +.UNINDENT +.SS ebics\-fetch +.sp +This subcommand downloads and parse EBICS files and ingest them into the database. Along the download, ebics\-fetch would bounce incoming payments that do not have a valid Taler subject, or as well those with an already existing valid subject. Valid incoming payments are then stored in the database so that they can trigger Taler withdrawals. Along this process, ebics\-submit would as well reconcile initiated outgoing payments with any outgoing transactions that show up in the downloaded records. +.sp +The files type can be given as an argument to select what will be fetched. If no argument is given, all supported files are fetched. The following files are supported: +.INDENT 0.0 +.IP \(bu 2 +\fBacknowledgement\fP: EBICS acknowledgement, retrieves the status of EBICS orders. +.IP \(bu 2 +\fBstatus\fP: Payment status, retrieves status of pending debits. +.IP \(bu 2 +\fBnotification\fP: Debit & credit notifications, retrieves the history of confirmed debits and credits. +.UNINDENT +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.TP +\fB–debug\-ebics\fP \fISAVEDIR\fP +Log EBICS content at SAVEDIR. +Downloaded documents will be stored \fIbefore\fP being ingested in the database. This directory would contain several directories, each named after the \fBYYYY\-MM\-DD/fetch\fP format. The stored files would then be named after the following schema: \fB$microseconds_$filename\fP\&. Exception to this naming scheme are the HAC responses, since they do not get any filename assigned by the ZIP archive (they are sent unzipped). Their naming scheme is: \fB$microseconds_HAC_response.pain.002.xml\fP\&. +.TP +\fB–transient\fP +This flag, enabled by default, causes the command to perform one download and return. +.TP +\fB–pinned\-start\fP +Only supported in –transient mode, this option lets specify the earliest timestamp of the downloaded documents. The latest timestamp is always the current time. +.UNINDENT +.SS initiate\-payment +.sp +This subcommand initiates an outgoing payment. The pending payment is stored in the database and will be performed the next time \fBebics\-submit\fP run. +.sp +It takes one argument, the creditor IBAN payto URI, which must contain a ‘receiver\-name’ and may contain an ‘amount’ and a ‘message’ if they have not been defined using CLI options. +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.TP +\fB–amount\fP \fIAMOUNT\fP +The amount to transfer, payto ‘amount’ parameter takes the precedence +.TP +\fB–subject\fP \fITEXT\fP +The payment subject, payto ‘message’ parameter takes the precedence +.TP +\fB–request\-uid\fP \fITEXT\fP +The payment request UID, will be randomly generated if missing. +.UNINDENT +.SS config +.sp +This command inspect or change the configuration. +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.UNINDENT +.sp +Subcommands: \fBget\fP, \fBdump\fP, \fBpathsub\fP +.SS config get +.sp +This command lookup config value. +.sp +It takes two arguments, the section name and the option name +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.TP +\fB\-f\fP | \fB–filename\fP +Interpret value as path with dollar\-expansion. +.UNINDENT +.SS config dump +.sp +This command dump the configuration. +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.UNINDENT +.SS config pathsub +.sp +This command substitute variables in a path. +.sp +It takes one argument, a path expression. +.INDENT 0.0 +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-c\fP | \fB–config\fP \fIFILENAME\fP +Specifies the configuration file. +.TP +\fB\-L\fP | \fB–log\fP \fILOGLEVEL\fP +Configure logging to use LOGLEVEL. +.UNINDENT +.SH SEE ALSO +.sp +libeufin\-nexus.conf(5) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/libeufin-nexus.conf.5 b/man/libeufin-nexus.conf.5 new file mode 100644 index 00000000..a93b8524 --- /dev/null +++ b/man/libeufin-nexus.conf.5 @@ -0,0 +1,225 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "LIBEUFIN-NEXUS.CONF" "5" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +libeufin-nexus.conf \- LibEuFin Nexus configuration file +.SH DESCRIPTION +.sp +The configuration file is line\-oriented. Blank lines and whitespace at the +beginning and end of a line are ignored. Comments start with \fB#\fP or \fB%\fP +in the first column (after any beginning\-of\-line whitespace) and go to the end +of the line. +.sp +The file is split into sections. Every section begins with \fB[SECTIONNAME]\fP +and contains a number of options of the form \fBOPTION=VALUE\fP\&. There may be +whitespace around the \fB=\fP (equal sign). Section names and options are +\fIcase\-insensitive\fP\&. +.sp +The values, however, are \fIcase\-sensitive\fP\&. In particular, boolean values are +one of \fBYES\fP or \fBNO\fP\&. Values can include whitespace by surrounding the +entire value with \fB\(dq\fP (double quote). Note, however, that there are no +escape characters in such strings; all characters between the double quotes +(including other double quotes) are taken verbatim. +.sp +Durations must be expressed with a number followed by the time unit. The following +time units are supported: ‘s’ (seconds), ‘m’ (minutes), ‘h’ (hours). For example, +the value \fI5m\fP denotes a duration of \fIfive minutes\fP\&. +.sp +Values that represent filenames can begin with a \fB/bin/sh\fP\-like variable +reference. This can be simple, such as \fB$TMPDIR/foo\fP, or complex, such as +\fB${TMPDIR:\-${TMP:\-/tmp}}/foo\fP\&. The variables are expanded either using +key\-values from the \fB[PATHS]\fP section (see below) or from the environment +(\fBgetenv()\fP). The values from \fB[PATHS]\fP take precedence over those from +the environment. If the variable name is found in neither \fB[PATHS]\fP nor the +environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if \fBFOO=$BAR\fP and \fBBAR=buzz\fP then the result is \fBFOO=buzz\fP\&. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if \fBBAR=$FOO\fP in the example above. +.sp +The \fB[PATHS]\fP section is special in that it contains paths that can be +referenced using \fB$\fP in other configuration values that specify +\fIfilenames\fP\&. Note that configuration options that are not specifically +retrieved by the application as \fIfilenames\fP will not see “$”\-expressions +expanded. To expand \fB$\fP\-expressions when using \fBtaler\-config\fP, you must pass +the \fB\-f\fP command\-line option. +.sp +The system automatically pre\-populates the \fB[PATHS]\fP section with a few values +at run\-time (in addition to the values that are in the actual configuration +file and automatically overwriting those values if they are present). +These automatically generated values refer to installation properties +from \fI\%GNU autoconf\fP\&. The +values are usually dependent on an \fBINSTALL_PREFIX\fP which is determined by +the \fB\-\-prefix\fP option given to configure. The canonical values are: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ +.IP \(bu 2 +DOCDIR = $INSTALL_PREFIX/share/doc/taler/ +.IP \(bu 2 +ICONDIR = $INSTALL_PREFIX/share/icons/ +.IP \(bu 2 +LOCALEDIR = $INSTALL_PREFIX/share/locale/ +.IP \(bu 2 +PREFIX = $INSTALL_PREFIX/ +.IP \(bu 2 +BINDIR = $INSTALL_PREFIX/bin/ +.IP \(bu 2 +LIBDIR = $INSTALL_PREFIX/lib/taler/ +.IP \(bu 2 +DATADIR = $INSTALL_PREFIX/share/taler/ +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that on some platforms, the given paths may differ depending +on how the system was compiled or installed, the above are just the +canonical locations of the various resources. These +automatically generated values are never written to disk. +.sp +Files containing default values for many of the options described below +are installed under \fB$TALER_PREFIX/share/libeufin\-nexus/config.d/\fP\&. +The configuration file given with \fB\-c\fP to Taler binaries +overrides these defaults. +.sp +A configuration file may include another, by using the \fB@INLINE@\fP directive, +for example, in \fBmain.conf\fP, you could write \fB@INLINE@ sub.conf\fP to +include the entirety of \fBsub.conf\fP at that point in \fBmain.conf\fP\&. +.sp +Be extra careful when using \fBtaler\-config \-V VALUE\fP to change configuration +values: it will destroy all uses of \fB@INLINE@\fP and furthermore remove all +comments from the configuration file! +.SS GLOBAL OPTIONS +.sp +Setting the database belongs to the “[nexus\-postgres]” section and the +following value. +.INDENT 0.0 +.TP +.B CONFIG +PostgreSQL connection string. Note: this option is NOT used by the +ebics\-setup subcommand, as it stores the key files directly on the +filesystem. +.UNINDENT +.sp +The “[paths]” section is special in that it contains paths that can be +referenced using “$” in other configuration values that specify +filenames. For Taler, it commonly contains the following paths: +.INDENT 0.0 +.TP +.B LIBEUFIN_HOME +Home directory of the user, usually “${HOME}”. Can be overwritten by +testcases by setting ${LIBEUFIN_TEST_HOME}. +.UNINDENT +.SS EBICS SETUP OPTIONS +.sp +The following options are from the “[nexus\-ebics]” section and used by +the \fBlibeufin\-nexus ebics\-setup\fP command. +.INDENT 0.0 +.TP +.B CURRENCY +Name of the currency, e.g.\ “EUR” for Euro. +.TP +.B HOST_BASE_URL +URL of the EBICS server +.TP +.B BANK_DIALECT +Name of the following combination: EBICS version and ISO20022 recommendations +that Nexus would honor in the communication with the bank. Currently only the +‘postfinance’ value is supported. +.TP +.B HOST_ID +EBICS specific: name of the EBICS host +.TP +.B USER_ID +EBICS specific: user ID of the EBICS subscriber. This value must be assigned +by the bank after having activated a new EBICS subscriber. +.TP +.B PARTNER_ID +EBICS specific: partner ID of the EBICS subscriber. This value must be assigned +by the bank after having activated a new EBICS subscriber. +.TP +.B BANK_PUBLIC_KEYS_FILE +Filesystem location where Nexus should store the bank public keys. +.TP +.B CLIENT_PRIVATE_KEYS_FILE +Filesystem location where Nexus should store the subscriber private keys. +.TP +.B IBAN +IBAN of the bank account that is associated with the EBICS subscriber. +.TP +.B BIC +BIC of the bank account that is associated with the EBICS subscriber. +.TP +.B NAME +Legal entity that is associated with the EBICS subscriber. +.UNINDENT +.SS EBICS SUBMIT OPTIONS +.sp +The following configuration value(s) belong to the “[nexus\-submit]” section. +.INDENT 0.0 +.TP +.B FREQUENCY +Duration value to instruct the \fBebics\-submit\fP subcommand how much to wait +before checking the database again to find new unsubmitted payments. +.UNINDENT +.SS EBICS FETCH OPTIONS +.sp +The following configuration value(s) belong to the “[nexus\-fetch]” section. +.INDENT 0.0 +.TP +.B FREQUENCY +Duration value to instruct the \fBebics\-fetch\fP subcommand how often it should +download from the bank. +.TP +.B IGNORE_TRANSACTIONS_BEFORE +Ignore all transactions before a certain YYYY\-MM\-DD date, useful when you want to use an existing account with old transactions that should not be bounced. +.UNINDENT +.SS DATABASE OPTIONS +.sp +Setting the database belongs to the “[libeufin\-nexusdb\-postgres]” section and the following value. +.INDENT 0.0 +.TP +.B CONFIG +PostgreSQL connection string. +.TP +.B SQL_DIR +Where are the SQL files to setup our tables? +.UNINDENT +.SH SEE ALSO +.sp +libeufin\-nexus(1) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/sync-config.1 b/man/sync-config.1 new file mode 100644 index 00000000..dd99d519 --- /dev/null +++ b/man/sync-config.1 @@ -0,0 +1,123 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SYNC-CONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +sync-config \- manipulate Sync configuration files +.SH SYNOPSIS +.sp +\fBsync\-config\fP +[\fB\-b\fP\ \fIbackend\fP\ |\ \fB–supported\-backend=\fP\fIbackend\fP] +[\fB\-c\fP\ \fIfilename\fP\ |\ \fB–config=\fP\fIfilename\fP] +[\fB\-f\fP\ |\ \fB–filename\fP] +[\fB\-F\fP\ |\ \fB–full\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fIloglevel\fP\ |\ \fB–loglevel=\fP\fIloglevel\fP] +[\fB\-l\fP\ \fIfilename\fP\ |\ \fB–logfile=\fP\fIfilename\fP] +[\fB\-o\fP\ \fIoption\fP\ |\ \fB–option=\fP\fIoption\fP] +[\fB\-r\fP\ |\ \fB–rewrite\fP] +[\fB\-S\fP\ |\ \fB–list\-sections\fP] +[\fB\-s\fP\ \fIsection\fP\ |\ \fB–section=\fP\fIsection\fP] +[\fB\-V\fP\ \fIvalue\fP\ |\ \fB–value=\fP\fIvalue\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBsync\-config\fP can be used to read or modify Sync configuration files. +.INDENT 0.0 +.TP +\fB\-b\fP \fIBACKEND\fP | \fB–supported\-backend=\fP\fIBACKEND\fP +Tests whether the specified \fIBACKEND\fP is supported by the current installation. +The backend must match the name of a plugin, i.e. “namestore_postgres” for +the PostgreSQL database backend of the “NAMESTORE” service. If \fIBACKEND\fP is +supported, sync\-config will return a status code of 0 (success), otherwise +77 (unsupported). When this option is specified, no other options may be +specified. Specifying this option together with other options will cause +sync\-config to return a status code of 1 (error). +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration file \fIFILENAME\fP\&. +.TP +\fB\-f\fP | \fB–filename\fP +Try to perform expansions as if the option values represent filenames (will +also be applied even if the option is not really a filename). +.TP +\fB\-F\fP | \fB–full\fP +Write the full configuration file, not just the differences to the defaults. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Use \fILOGLEVEL\fP for logging. +Valid values are \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, and \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-o\fP \fIOPTION\fP | \fB–option=\fP\fIOPTION\fP +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”. +.TP +\fB\-r\fP | \fB–rewrite\fP +Write the configuration file even if nothing changed. Will remove all comments! +.TP +\fB\-S\fP | \fB–list\-sections\fP +List available configuration sections for use with \fB\-\-section\fP\&. +.TP +\fB\-s\fP \fISECTION\fP | \fB–section=\fP\fISECTION\fP +Which configuration section should be accessed or edited. +Required option. +.TP +\fB\-V\fP \fIVALUE\fP | \fB–value=\fP\fIVALUE\fP +Configuration value to store in the given section under the given option. +Must only be given together with \fB\-s\fP and \fB\-o\fP options. +.INDENT 7.0 +.TP +.B Note: +Changing the configuration file with \fB\-V\fP will remove comments +and may reorder sections and remove \fB@INLINE@\fP directives. +.UNINDENT +.TP +\fB\-v\fP | \fB–version\fP +Print GNU Taler version number. +.UNINDENT +.SH SEE ALSO +.sp +sync\-dbinit(1), sync\-httpd(1), sync.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/sync-dbconfig.1 b/man/sync-dbconfig.1 new file mode 100644 index 00000000..6d06034f --- /dev/null +++ b/man/sync-dbconfig.1 @@ -0,0 +1,83 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SYNC-DBCONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +sync-dbconfig \- configure sync database +.SH SYNOPSIS +.sp +\fBsync\-dbconfig\fP +[\fB\-c\fP\ \fIFILENAME\fP] +[\fB\-h\fP] +[\fB\-n\fP\ \fINAME\fP] +[\fB\-r\fP] +[\fB\-s\fP] +[\fB\-u\fP\ \fIUSER\fP] +.SH DESCRIPTION +.sp +\fBsync\-dbconfig\fP is a simple shell script that configures +a Postgresql database for use by \fBsync\-httpd\fP\&. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP +Write the database configuration to FILENAME. The tool +will append the required \fBCONFIG\fP option for the +Postgresql access to the respective file. +.TP +\fB\-h\fP +Print short help on options. +.TP +\fB\-n\fP \fIDBNAME\fP +Use DBNAME for the name of the created database. +.TP +\fB\-r\fP +Reset any existing database. Looses all existing data. DANGEROUS. +.TP +\fB\-s\fP +Skip database initialization. Useful if you want to run +\fBsync\-dbinit\fP manually. +.TP +\fB\-u\fP \fIUSER\fP +Specifies the (main) sync user that will access the database. +.UNINDENT +.SH SEE ALSO +.sp +sync\-dbinit(1), sync.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/sync-dbinit.1 b/man/sync-dbinit.1 new file mode 100644 index 00000000..7db7d856 --- /dev/null +++ b/man/sync-dbinit.1 @@ -0,0 +1,84 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SYNC-DBINIT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +sync-dbinit \- initialize the Sync database +.SH SYNOPSIS +.sp +\fBsync\-dbinit\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-g\fP\ |\ \fB–garbagecollect\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-r\fP\ |\ \fB–reset\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBsync\-dbinit\fP is a command\-line tool to initialize the Sync database. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Sync commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-g\fP | \fB–garbagecollect\fP +Remove state data from database. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-r\fP | \fB–reset\fP +Reset database. (\fBDANGEROUS\fP: All existing data is lost!) +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +sync\-config(1), sync\-httpd(1), sync.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/sync-httpd.1 b/man/sync-httpd.1 new file mode 100644 index 00000000..ea47b170 --- /dev/null +++ b/man/sync-httpd.1 @@ -0,0 +1,97 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SYNC-HTTPD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +sync-httpd \- provide the Sync HTTP interface +.SH SYNOPSIS +.sp +\fBsync\-httpd\fP +[\fB\-A\fP\ \fIUSERNAME:PASSWORD\fP\ |\ \fB–auth=\fP\fIUSERNAME:PASSWORD\fP] +[\fB\-C\fP\ |\ \fB–connection\-close\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-k\fP\ \fIKEYFILE\fP\ |\ \fB–key=\fP\fIKEYFILE\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ \fIKEYFILEPASSPHRASE\fP\ |\ \fB–pass=\fP\fIKEYFILEPASSPHRASE\fP] +[\fB\-t\fP\ \fICERTTYPE\fP\ |\ \fB–type=\fP\fICERTTYPE\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBsync\-httpd\fP is a command\-line tool to provide the Sync HTTP interface. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-A\fP \fIUSERNAME:PASSWORD\fP | \fB–auth=\fP\fIUSERNAME:PASSWORD\fP +Use the given \fIUSERNAME\fP and \fIPASSWORD\fP for client authentication. +.TP +\fB\-C\fP | \fB–connection\-close\fP +Force HTTP connections to be closed after each request. +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Sync commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-k\fP \fIKEYFILE\fP | \fB–key=\fP\fIKEYFILE\fP +Consult \fIKEYFILE\fP for the private TLS key for TLS client authentication. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-p\fP \fIKEYFILEPASSPHRASE\fP | \fB–pass=\fP\fIKEYFILEPASSPHRASE\fP +Use \fIKEYFILEPASSPHRASE\fP to decrypt the TLS client private key file. +.TP +\fB\-t\fP \fICERTTYPE\fP | \fB–type=\fP\fICERTTYPE\fP +Use \fICERTTYPE\fP as the type of the TLS client certificate. +If unspecified, defaults to PEM. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +sync\-config(1), sync\-dbinit(1), sync.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/sync.conf.5 b/man/sync.conf.5 new file mode 100644 index 00000000..c1d3e318 --- /dev/null +++ b/man/sync.conf.5 @@ -0,0 +1,183 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "SYNC.CONF" "5" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +sync.conf \- Sync configuration file +.SH DESCRIPTION +.sp +The configuration file is line\-oriented. Blank lines and whitespace at the +beginning and end of a line are ignored. Comments start with \fB#\fP or \fB%\fP +in the first column (after any beginning\-of\-line whitespace) and go to the end +of the line. +.sp +The file is split into sections. Every section begins with \fB[SECTIONNAME]\fP +and contains a number of options of the form \fBOPTION=VALUE\fP\&. There may be +whitespace around the \fB=\fP (equal sign). Section names and options are +\fIcase\-insensitive\fP\&. +.sp +The values, however, are \fIcase\-sensitive\fP\&. In particular, boolean values are +one of \fBYES\fP or \fBNO\fP\&. Values can include whitespace by surrounding the +entire value with \fB\(dq\fP (double quote). Note, however, that there are no +escape characters in such strings; all characters between the double quotes +(including other double quotes) are taken verbatim. +.sp +Values that represent a time duration are represented as a series +of one or more \fBNUMBER UNIT\fP pairs, e.g. \fB60 s\fP, \fB4 weeks 1 day\fP, +\fB5 years 2 minutes\fP\&. +.sp +Values that represent an amount are in the usual amount syntax: +\fBCURRENCY:VALUE.FRACTION\fP, e.g. \fBEUR:1.50\fP\&. +The \fBFRACTION\fP portion may extend up to 8 places. +.sp +Values that represent filenames can begin with a \fB/bin/sh\fP\-like variable +reference. This can be simple, such as \fB$TMPDIR/foo\fP, or complex, such as +\fB${TMPDIR:\-${TMP:\-/tmp}}/foo\fP\&. The variables are expanded either using +key\-values from the \fB[PATHS]\fP section (see below) or from the environment +(\fBgetenv()\fP). The values from \fB[PATHS]\fP take precedence over those from +the environment. If the variable name is found in neither \fB[PATHS]\fP nor the +environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if \fBFOO=$BAR\fP and \fBBAR=buzz\fP then the result is \fBFOO=buzz\fP\&. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if \fBBAR=$FOO\fP in the example above. +.sp +The \fB[PATHS]\fP section is special in that it contains paths that can be +referenced using \fB$\fP in other configuration values that specify +\fIfilenames\fP\&. Note that configuration options that are not specifically +retrieved by the application as \fIfilenames\fP will not see “$”\-expressions +expanded. To expand \fB$\fP\-expressions when using \fBtaler\-config\fP, you must pass +the \fB\-f\fP command\-line option. +.sp +The system automatically pre\-populates the \fB[PATHS]\fP section with a few values +at run\-time (in addition to the values that are in the actual configuration +file and automatically overwriting those values if they are present). +These automatically generated values refer to installation properties +from \fI\%GNU autoconf\fP\&. The +values are usually dependent on an \fBINSTALL_PREFIX\fP which is determined by +the \fB\-\-prefix\fP option given to configure. The canonical values are: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ +.IP \(bu 2 +DOCDIR = $INSTALL_PREFIX/share/doc/taler/ +.IP \(bu 2 +ICONDIR = $INSTALL_PREFIX/share/icons/ +.IP \(bu 2 +LOCALEDIR = $INSTALL_PREFIX/share/locale/ +.IP \(bu 2 +PREFIX = $INSTALL_PREFIX/ +.IP \(bu 2 +BINDIR = $INSTALL_PREFIX/bin/ +.IP \(bu 2 +LIBDIR = $INSTALL_PREFIX/lib/taler/ +.IP \(bu 2 +DATADIR = $INSTALL_PREFIX/share/taler/ +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that on some platforms, the given paths may differ depending +on how the system was compiled or installed, the above are just the +canonical locations of the various resources. These +automatically generated values are never written to disk. +.sp +Files containing default values for many of the options described below +are installed under \fB$PREFIX/share/sync/config.d/\fP\&. +The configuration file given with \fB\-c\fP to Sync binaries +overrides these defaults. +.sp +A configuration file may include another, by using the \fB@INLINE@\fP directive, +for example, in \fBmain.conf\fP, you could write \fB@INLINE@ sub.conf\fP to +include the entirety of \fBsub.conf\fP at that point in \fBmain.conf\fP\&. +.sp +Be extra careful when using \fBsync\-config \-V VALUE\fP to change configuration +values: it will destroy all uses of \fB@INLINE@\fP and furthermore remove all +comments from the configuration file! +.SS GLOBAL OPTIONS +.sp +The following options are from the “[sync]” section. +This is normally the only section in a sync.conf file. +.INDENT 0.0 +.TP +.B SERVE +This can either be \fBtcp\fP or \fBunix\fP\&. +.TP +.B PORT +Port on which the HTTP server listens, e.g.\ 9967. +Only used if \fBSERVE\fP is \fBtcp\fP\&. +.TP +.B BIND_TO +Which IP address should we bind to? E.g. \fB127.0.0.1\fP or \fB::1\fP +for loopback. Can also be given as a hostname. We will bind to +the wildcard (dual\-stack) if left empty. +Only used if \fBSERVE\fP is \fBtcp\fP\&. +.TP +.B UNIXPATH +Which unix domain path should we bind to? +Only used if \fBSERVE\fP is \fBunix\fP\&. +.TP +.B UNIXPATH_MODE = 660 +What should be the file access permissions for \fBUNIXPATH\fP? +Only used if \fBSERVE\fP is \fBunix\fP\&. +.TP +.B DB +Plugin to use for the database, e.g.\ “postgres”. +.TP +.B ANNUAL_FEE +Annual fee for an account. +This is in the usual amount syntax, e.g. \fBTESTKUDOS:0.1\fP\&. +.TP +.B INSURANCE +Insurance provided against loss, e.g. \fBTESTKUDOS:0.0\fP\&. +.TP +.B UPLOAD_LIMIT_MB +Upload limit per backup, in megabytes, e.g. \fB16\fP\&. +.TP +.B FULFILLMENT_URL +Fulfillment URL of the SYNC service itself. +.TP +.B PAYMENT_BACKEND_URL +Base URL of our payment backend. +.TP +.B API_KEY +API key to pass when accessing the merchant backend. +This is a secret value. +.UNINDENT +.SH SEE ALSO +.sp +sync\-dbinit(1), sync\-httpd(1), sync\-config(1). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-aggregator-benchmark.1 b/man/taler-aggregator-benchmark.1 new file mode 100644 index 00000000..ee744c30 --- /dev/null +++ b/man/taler-aggregator-benchmark.1 @@ -0,0 +1,93 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-AGGREGATOR-BENCHMARK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-aggregator-benchmark \- generate database to measure aggregator performance +.SH SYNOPSIS +.sp +\fBtaler\-aggregator\-benchmark\fP +[\fB\-c\fP\ \fICONFIG_FILENAME\fP\ |\ \fB–config=\fP\fICONFIG_FILENAME\fP] +[\fB\-d\fP\ \fIDN\fP\ |\ \fB–deposits=\fP\fIDN\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log\-level=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIDM\fP\ |\ \fB–merchants=\fP\fIDM\fP] +[\fB\-r\fP\ \fIRATE\fP\ |\ \fB–refunds=\fP\fIRATE\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-aggregator\-benchmark\fP is a command\-line tool to fill an exchange +database with records suitable for benchmarking the +\fBtaler\-exchange\-aggregator\fP\&. The \fBtaler\-aggregator\-benchmark\fP tool does +not run the actual workload for the benchmark (which usually consists of +starting multiple \fBtaler\-exchange\-aggregator\fP processes) and instead only +prepares the database with synthetic work. +.INDENT 0.0 +.TP +\fB\-c\fP \fICONFIG_FILENAME\fP | \fB–config=\fP\fICONFIG_FILENAME\fP +(Mandatory) Use CONFIG_FILENAME as the name for the configuration file. +.TP +\fB\-d\fP \fIDN\fP | \fB–deposits=\fP\fIDN\fP +How many deposits should be instantiated \fIper merchant\fP\&. +Defaults to 1. +.TP +\fB\-h\fP | \fB–help\fP +Prints a compiled\-in help text. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log\-level=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-m\fP \fIDM\fP | \fB–merchants=\fP\fIDM\fP +How many different merchants should we create. Defaults to 1. +.TP +\fB\-r\fP \fIRATE\fP | \fB–refunds=\fP\fIRATE\fP +Probability of a deposit having a refund (as an integer between 0\-100). +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-dbinit(1), taler\-merchant\-benchmark(1), +taler\-exchange\-aggregator(1), taler\-unified\-setup(1), taler.conf(5) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-auditor-dbconfig.1 b/man/taler-auditor-dbconfig.1 new file mode 100644 index 00000000..2918932d --- /dev/null +++ b/man/taler-auditor-dbconfig.1 @@ -0,0 +1,83 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-AUDITOR-DBCONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-dbconfig \- configure Taler auditor database +.SH SYNOPSIS +.sp +\fBtaler\-auditor\-dbconfig\fP +[\fB\-c\fP\ \fIFILENAME\fP] +[\fB\-h\fP] +[\fB\-n\fP\ \fINAME\fP] +[\fB\-r\fP] +[\fB\-s\fP] +[\fB\-u\fP\ \fIUSER\fP] +.SH DESCRIPTION +.sp +\fBtaler\-auditor\-dbconfig\fP is a simple shell script that configures +a Postgresql database for use by the GNU Taler auditor. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP +Write the database configuration to FILENAME. The tool +will append the required \fBCONFIG\fP option for the +Postgresql access to the respective file. +.TP +\fB\-h\fP +Print short help on options. +.TP +\fB\-n\fP \fIDBNAME\fP +Use DBNAME for the name of the created database. +.TP +\fB\-r\fP +Reset any existing database. Looses all existing data. DANGEROUS. +.TP +\fB\-s\fP +Skip database initialization. Useful if you want to run +\fBtaler\-auditor\-dbinit\fP manually. +.TP +\fB\-u\fP \fIUSER\fP +Specifies the (main) auditor user that will access the database. +.UNINDENT +.SH SEE ALSO +.sp +taler\-auditor\-dbinit(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-auditor-dbinit.1 b/man/taler-auditor-dbinit.1 index a5754dc4..f2193ff0 100644 --- a/man/taler-auditor-dbinit.1 +++ b/man/taler-auditor-dbinit.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-AUDITOR-DBINIT" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-dbinit \- setup auditor database . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-AUDITOR-DBINIT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-dbinit \- setup auditor database .SH SYNOPSIS .sp \fBtaler\-auditor\-dbinit\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-g\fP\ |\ \fB––gc\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-R\fP\ |\ \fB––reset\fP] -[\fB\-r\fP\ |\ \fB––restart\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-g\fP\ |\ \fB–gc\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-R\fP\ |\ \fB–reset\fP] +[\fB\-r\fP\ |\ \fB–restart\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-dbinit\fP is a command\-line tool to initialize the Taler @@ -50,32 +50,32 @@ Taler exchange to operate. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-g\fP | \fB––gc\fP +\fB\-g\fP | \fB–gc\fP Garbage collect database. Deletes all unnecessary data in the database. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-R\fP | \fB––reset\fP +\fB\-R\fP | \fB–reset\fP Drop tables. Dangerous, will delete all existing data in the database. .TP -\fB\-r\fP | \fB––restart\fP +\fB\-r\fP | \fB–restart\fP Restart all auditors from the beginning. Useful for testing. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -88,6 +88,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-auditor-exchange.1 b/man/taler-auditor-exchange.1 index b41ad692..f1fd1c66 100644 --- a/man/taler-auditor-exchange.1 +++ b/man/taler-auditor-exchange.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-AUDITOR-EXCHANGE" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-exchange \- add or remove exchange from auditor’s list . .nr rst2man-indent-level 0 . @@ -30,15 +27,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-AUDITOR-EXCHANGE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-exchange \- add or remove exchange from auditor’s list .SH SYNOPSIS .sp \fBtaler\-auditor\-exchange\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-m\fP\ \fIMASTERKEY\fP\ |\ \fB––exchange\-key=\fP\fIMASTERKEY\fP] -[\fB\-r\fP\ |\ \fB––remove\fP] -[\fB\-u\fP\ \fIEXCHANGE_URL\fP\ |\ \fB––auditor\-url=\fP\fIEXCHANGE_URL\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-m\fP\ \fIMASTERKEY\fP\ |\ \fB–exchange\-key=\fP\fIMASTERKEY\fP] +[\fB\-r\fP\ |\ \fB–remove\fP] +[\fB\-u\fP\ \fIEXCHANGE_URL\fP\ |\ \fB–auditor\-url=\fP\fIEXCHANGE_URL\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-auditor\-exchange\fP is a command\-line tool to be used by an @@ -49,27 +49,27 @@ taler\-auditor or taler\-wire\-auditor. Afterwards the exchange will be visible via the /exchanges API of the taler\-auditor\-httpd. .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-m\fP \fIMASTERKEY\fP | \fB––exchange\-key=\fP\fIMASTERKEY\fP +\fB\-m\fP \fIMASTERKEY\fP | \fB–exchange\-key=\fP\fIMASTERKEY\fP Public key of the exchange in Crockford base32 encoding, for example as generated by \fBtaler\-auditor\-offline setup\fP\&. .TP -\fB\-r\fP | \fB––remove\fP +\fB\-r\fP | \fB–remove\fP Instead of adding the exchange, remove it. Note that this will drop ALL data associated with that exchange, including existing auditing information. So use with extreme care! .TP -\fB\-u\fP \fIEXCHANGE_URL\fP | \fB––auditor\-url=\fP\fIEXCHANGE_URL\fP +\fB\-u\fP \fIEXCHANGE_URL\fP | \fB–auditor\-url=\fP\fIEXCHANGE_URL\fP URL of the exchange. The exchange’s HTTP API must be available at this address. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH DIAGNOSTICS @@ -92,6 +92,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-auditor-httpd.1 b/man/taler-auditor-httpd.1 index ed1c3eb2..68b96f58 100644 --- a/man/taler-auditor-httpd.1 +++ b/man/taler-auditor-httpd.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-AUDITOR-HTTPD" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-httpd \- HTTP server providing a RESTful API to access a Taler auditor . .nr rst2man-indent-level 0 . @@ -30,16 +27,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-AUDITOR-HTTPD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-httpd \- HTTP server providing a RESTful API to access a Taler auditor .SH SYNOPSIS .sp \fBtaler\-auditor\-httpd\fP -[\fB\-C\fP\ |\ \fB––connection\-close\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-t\fP\ \fISECONDS\fP\ |\ \fB––timeout\fP\fISECONDS\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-C\fP\ |\ \fB–connection\-close\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-t\fP\ \fISECONDS\fP\ |\ \fB–timeout\fP\fISECONDS\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-auditor\-httpd\fP is a command\-line tool to run the Taler auditor @@ -48,30 +48,30 @@ before running this command. .SH OPTIONS .INDENT 0.0 .TP -\fB\-C\fP | \fB––connection\-close\fP +\fB\-C\fP | \fB–connection\-close\fP Force each HTTP connection to be closed after each request (useful in combination with \-f to avoid having to wait for nc to time out). .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from FILENAME. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-t\fP \fISECONDS\fP | \fB––timeout=\fP\fISECONDS\fP +\fB\-t\fP \fISECONDS\fP | \fB–timeout=\fP\fISECONDS\fP Specifies the number of \fISECONDS\fP after which the HTTPD should close (idle) HTTP connections. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SIGNALS @@ -91,6 +91,6 @@ electronic mail to <\fI\%taler@gnu.org\fP> .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-auditor-offline.1 b/man/taler-auditor-offline.1 index 79ed11cf..d73d2a32 100644 --- a/man/taler-auditor-offline.1 +++ b/man/taler-auditor-offline.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-AUDITOR-OFFLINE" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-offline \- Taler auditor certifies that it audits a Taler exchange . .nr rst2man-indent-level 0 . @@ -30,24 +27,27 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-AUDITOR-OFFLINE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-offline \- Taler auditor certifies that it audits a Taler exchange .SH SYNOPSIS .sp \fBtaler\-auditor\-offline\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-v\fP\ |\ \fB––version\fP] -[subcommand ...] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[subcommand …] .SH DESCRIPTION .sp \fBtaler\-auditor\-offline\fP is a command\-line tool to be used by an auditor to -sign that he is aware of certain keys being used by a exchange. Using this +sign that he is aware of certain keys being used by an exchange. Using this signature, the auditor affirms that he will verify that the exchange is properly accounting for coins of those denominations. The tool takes a list of subcommands as arguments which are then processed sequentially. .sp -The tool includes two subcommands to interact \fIonline\fP with the exchange\(aqs +The tool includes two subcommands to interact \fIonline\fP with the exchange’s REST APIs. The \fBdownload\fP subcommand downloads current public keys from the running exchange. Note that this only includes keys that the exchange operator has previously validated using the \fBtaler\-exchange\-offline\fP tool. @@ -55,10 +55,10 @@ The resulting data serves as input to the \fBsign\fP and \fBshow\fP subcommands. .sp The \fBupload\fP subcommand uploads the signatures created with the private key to the exchange. It handles the output of all subcommands (except \fBdownload\fP). -The \fBdownload\fP and \fBupload\fP subcommands must naturally be run "online" and do not -require access to the auditor\(aqs private key, which should be kept offline. +The \fBdownload\fP and \fBupload\fP subcommands must naturally be run “online” and do not +require access to the auditor’s private key, which should be kept offline. .sp -All other subcommands are intended to be run "offline". However, especially +All other subcommands are intended to be run “offline”. However, especially when testing, it is of course possible to run the subcommands online as well. Generally, subcommands read inputs (beyond command\-line arguments) from \fBstdin\fP\&. However, they may also consume outputs of previous @@ -68,28 +68,28 @@ and if not consumed the final output is printed to \fBstdout\fP\&. The general options for \fBtaler\-auditor\-offline\fP are: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH CONFIGURATION .sp The exchange and the \fBtaler\-auditor\-httpd\fP must both be provided with -the auditor\(aqs public key, such that they can validate messages signed -by the auditor. To obtain the auditor\(aqs public key, use: +the auditor’s public key, such that they can validate messages signed +by the auditor. To obtain the auditor’s public key, use: .INDENT 0.0 .INDENT 3.5 .sp @@ -102,13 +102,13 @@ $ taler\-auditor\-offline setup .UNINDENT .sp Note that if the private key file already exists, the above will simply output -the existing key. Passing additional arguments after setup (including "\-") +the existing key. Passing additional arguments after setup (including “\-“) will cause the output to be encapsulated in JSON. .sp Relevant configuration options for \fBtaler\-auditor\-offline\fP are: .INDENT 0.0 .IP \(bu 2 -\fB[auditor/AUDITOR_PRIV_FILE]\fP \-\-\- where to store the private key +\fB[auditor/AUDITOR_PRIV_FILE]\fP — where to store the private key .UNINDENT .SH SUBCOMMANDS .SS setup @@ -233,6 +233,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-auditor-sync.1 b/man/taler-auditor-sync.1 new file mode 100644 index 00000000..55a33fb2 --- /dev/null +++ b/man/taler-auditor-sync.1 @@ -0,0 +1,95 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-AUDITOR-SYNC" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor-sync \- tool to safely synchronize auditor database +.SH SYNOPSIS +.sp +\fBtaler\-auditor\-sync\fP +[\fB\-s\fP\ \fIFILENAME\fP\ |\ \fB–source\-configuration=\fP\fIFILENAME\fP] +[\fB\-d\fP\ \fIFILENAME\fP\ |\ \fB–destination\-configuration=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-b\fP\ \fISIZE\fP\ |\ \fB–batch=\fP\fISIZE\fP] +[\fB\-t\fP\ |\ \fB–terminate\-when\-synchronized\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +.SH DESCRIPTION +.sp +\fBtaler\-auditor\-sync\fP is a command\-line tool to synchronize the +Taler auditor’s database in a safe way from a Taler exchange +database. If the exchange database violates the assumed database +invariants (as expressed by database constraints) or attempts to +DELETE or UPDATE tables (at least those that the auditor relies +upon), \fBtaler\-auditor\-sync\fP will not replicate those changes +and instead halt with an error. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-s\fP \fIFILENAME\fP | \fB–source\-configuration=\fP\fIFILENAME\fP +Use the configuration in \fIFILENAME\fP to access the original (source) exchange +database to copy records from. +.TP +\fB\-d\fP \fIFILENAME\fP | \fB–destination\-configuration=\fP\fIFILENAME\fP +Use the configuration in \fIFILENAME\fP to access the target (destination) exchange +database to copy records to. +.TP +\fB\-t\fP | \fB–terminate\-when\-synchronized\fP +The program should exit once the two databases are in sync, instead of continuously +copying more records when the source database is updated. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-b\fP \fISIZE\fP | \fB–batch=\fP\fISIZE\fP +Target number of records to copy in one transaction. Once the databases are +in sync, the batch size is used to determine how long the process sleeps before +trying to again synchronize the two databases. Not useful if \fB\-t\fP is used. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-auditor(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-auditor.1 b/man/taler-auditor.1 index 3c7b9ce7..89903a2e 100644 --- a/man/taler-auditor.1 +++ b/man/taler-auditor.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-AUDITOR" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor \- audit exchange . .nr rst2man-indent-level 0 . @@ -30,17 +27,21 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-AUDITOR" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-auditor \- audit exchange .SH SYNOPSIS .sp \fBtaler\-auditor\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-i**_|_\fP––internal**] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIMASTER_KEY\fP\ |\ \fB––exchange\-key=\fP\fIMASTER_KEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-i**_|_\fP–internal**] +[\fB\-I**_|_\fP–ignore\-not\-found**] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIMASTER_KEY\fP\ |\ \fB–exchange\-key=\fP\fIMASTER_KEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-auditor\fP is a command\-line tool to be used by an auditor to @@ -54,36 +55,40 @@ incoming and outgoing wire transfers that the bank claims to have matches the exchange’s database. Its options are as follows. .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Run additional checks that can only performed on the exchange\-internal -database and not the "safe" replicated database at the auditor. +database and not the “safe” replicated database at the auditor. +.TP +\fB\-I\fP | \fB–ignore\-not\-found\fP +Do not fail if the bank says that the exchange bank account does not (yet) exist. +Keep trying. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Public master key of the exchange in Crockford base32 encoding, for example as generated by \fBtaler\-auditor\-offline setup\fP\&. If this option is missing, taler\-auditor will use the MASTER_PUBLIC_KEY value from the “exchange” section of the configuration. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -96,6 +101,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-bank-benchmark.1 b/man/taler-bank-benchmark.1 new file mode 100644 index 00000000..9bf26087 --- /dev/null +++ b/man/taler-bank-benchmark.1 @@ -0,0 +1,106 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-BANK-BENCHMARK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-bank-benchmark \- measure bank performance +.SH SYNOPSIS +.sp +\fBtaler\-bank\-benchmark\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-f\fP\ |\ \fB–fakebank\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ \fINPROCS\fP\ |\ \fB–worker\-parallelism=\fP\fINPROCS\fP] +[\fB\-r\fP\ \fINRESERVES\fP\ |\ \fB–reserves=\fP\fINRESERVES\fP] +[\fB\-u\fP\ \fISECTION\fP\ |\ \fB–exchange\-account\-section=\fP\fISECTION\fP] +[\fB\-V\fP\ |\ \fB–verbose\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[\fB\-w**_*NPROC*\ |\ **–wirewatch=\fP\fINPROC\fP] +.SH DESCRIPTION +.sp +\fBtaler\-bank\-benchmark\fP is a command\-line tool to benchmark only the “bank” +and the \fBtaler\-exchange\-wirewatch\fP tool. +.sp +The options for \fBtaler\-bank\-benchmark\fP are: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-f\fP | \fB–fakebank\fP +Expect to be run against a fakebank (instead of against libeufin) +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-m\fP \fIMODE\fP | \fB–mode=\fP\fIMODE\fP +Run as \fBbank\fP, \fBclient\fP or \fBboth\fP\&. +If unspecified, \fIMODE\fP defaults to \fBboth\fP\&. +.TP +\fB\-p\fP \fINPROCS\fP | \fB–worker\-parallelism=\fP\fINPROCS\fP +Run with \fINPROCS\fP client processes. +.TP +\fB\-r\fP \fINRESERVES\fP | \fB–reserves=\fP\fINRESERVES\fP +Create \fINRESERVES\fP reserves per client. +.TP +\fB\-u\fP \fISECTION\fP | \fB–exchange\-account\-section=\fP\fISECTION\fP +Use \fISECTION\fP as the name of the configuration section which specifies the exchange bank account. +.TP +\fB\-V\fP | \fB–verbose\fP +Display more output than usual. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.TP +\fB\-w\fP \fINPROC\fP | \fB–wirewatch=\fP\fINPROC\fP +Run \fINPROC\fP processes of the \fBtaler\-exchange\-wirewatch\fP tool. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-bank-transfer.1 b/man/taler-bank-transfer.1 deleted file mode 100644 index dac66037..00000000 --- a/man/taler-bank-transfer.1 +++ /dev/null @@ -1,137 +0,0 @@ -.\" Man page generated from reStructuredText. -. -.TH "TALER-BANK-TRANSFER" "1" "Mar 22, 2020" "0.6pre1" "GNU Taler" -.SH NAME -taler-bank-transfer \- trigger a transfer at the bank -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.SH SYNOPSIS -.sp -\fBtaler\-bank\-transfer\fP -[\fB\-a\fP\ \fIVALUE\fP\ |\ \fB\-\-amount=\fP\fIVALUE\fP] -[\fB\-b\fP\ \fIURL\fP\ |\ \fB\-\-bank=\fP\fIURL\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB\-\-config=\fP\fIFILENAME\fP] -[\fB\-C\fP\ \fIACCOUNT\fP\ |\ \fB\-\-credit=\fP\fIACCOUNT\fP] -[\fB\-D\fP\ \fIACCOUNT\fP\ |\ \fB\-\-debit=\fP\fIACCOUNT\fP] -[\fB\-h\fP\ |\ \fB\-\-help\fP] -[\fB\-i\fP\ |\ \fB\-\-credit\-history\fP] -[\fB\-o\fP\ |\ \fB\-\-debit\-history\fP] -[\fB\-p\fP\ \fIPASSPHRASE\fP\ |\ \fB\-\-pass=\fP\fIPASSPHRASE\fP] -[\fB\-s\fP\ \fIACCOUNT\-SECTION\fP\ |\ \fB\-\-section=\fP\fIACCOUNT\-SECTION\fP] -[\fB\-S\fP\ \fISTRING\fP\ |\ \fB\-\-subject=\fP\fISTRING\fP] -[\fB\-u\fP\ \fIUSERNAME\fP\ |\ \fB\-\-user=\fP\fIUSERNAME\fP] -[\fB\-v\fP\ |\ \fB\-\-version\fP] -[\fB\-w\fP\ \fIROW\fP\ |\ \fB\-\-since\-when=\fP\fIROW\fP] -.SH DESCRIPTION -.sp -\fBtaler\-bank\-transfer\fP is a command line tool to trigger bank transfers or -inspect wire transfers for exchange accounts using the wire API. The tool is -expected to be used during testing or for diagnostics. -.sp -You can do one of the following four operations during one invocation. -.INDENT 0.0 -.INDENT 3.5 -.INDENT 0.0 -.IP 1. 3 -Execute wire transfer from the exchange to consumer account (\fB\-C\fP). -.IP 2. 3 -Execute wire transfer from consumer account to the exchange (\fB\-D\fP). -.IP 3. 3 -Inspect credit history of the exchange (\fB\-i\fP). -.IP 4. 3 -Inspect debit history of the exchange (\fB\-o\fP). -.UNINDENT -.UNINDENT -.UNINDENT -.sp -Doing more than one of these at a time will result in an error. Note, -however, that the \fB\-C\fP and \fB\-D\fP options also can be used to act as filters -on transaction history operations. -.SH OPTIONS -.INDENT 0.0 -.TP -\fB\-a\fP \fIVALUE\fP | \fB\-\-amount=\fP\fIVALUE\fP -Amount to transfer. Given in the Taler\-typical format of -CURRENCY:VALUE.FRACTION. -.TP -\fB\-b\fP \fIURL\fP | \fB\-\-bank=\fP\fIURL\fP -URL at which the bank is operation. Conflicts with \fB\-s\fP\&. -.TP -\fB\-c\fP \fIFILENAME\fP | \fB\-\-config=\fP\fIFILENAME\fP -Use the given configuration file. -.TP -\fB\-C\fP \fIACCOUNT\fP | \fB\-\-credit=\fP\fIACCOUNT\fP -When doing a wire transfer from the exchange, the money should be credited to \fIACCOUNT\fP\&. -Specifies the payto:// URI of the account. Can also be used as a filter by credit -account when looking at transaction histories. -.TP -\fB\-D\fP \fIACCOUNT\fP | \fB\-\-debit=\fP\fIACCOUNT\fP -When doing a wire transfer to the exchange, the \fIACCOUNT\fP is to be debited. -Specifies the payto:// URI of the account. Can also be used as a filter by debit -account when looking at transaction histories. -.TP -\fB\-h\fP | \fB\-\-help\fP -Print short help on options. -.TP -\fB\-i\fP | \fB\-\-credit\-history\fP -Obtain credit history of the exchange. Conflicts with \fB\-o\fP\&. -.TP -\fB\-o\fP | \fB\-\-debit\-history\fP -Obtain debit history of the exchange. Conflicts with \fB\-i\fP\&. -.TP -\fB\-S\fP \fISUBJECT\fP | \fB\-\-subject=\fP\fISUBJECT\fP -Use \fISUBJECT\fP for the wire transfer subject. Must be a reserve public key for credit operations and a wire transfer identifier for debit operations. If not specified, a random value will be generated instead. -.TP -\fB\-s\fP \fIACCOUNT_SECTION\fP | \fB\-\-section=\fP\fIACCOUNT\-SECTION\fP -Obtain exchange account information from the \fIACCOUNT\-SECTION\fP of the configuration. Conflicts with \fB\-u\fP, \fB\-p\fP and \fB\-b\fP\&. Note that either \fB\-b\fP or \fB\-s\fP must be specified. -.TP -\fB\-u\fP \fIUSERNAME\fP | \fB\-\-user=\fP\fIUSERNAME\fP -Specifies the username for authentication. Optional and conflicts with \fB\-s\fP\&. If neither \fB\-u\fP nor \fB\-s\fP are used, we will attempt to talk to the bank without authentication. -.TP -\fB\-p\fP \fIPASSPHRASE\fP | \fB\-\-pass=\fP\fIPASSPHRASE\fP -Specifies the pass phrase for authentication. Conflicts with \fB\-s\fP\&. -.TP -\fB\-v\fP | \fB\-\-version\fP -Print version information. -.TP -\fB\-w\fP \fIROW\fP | \fB\-\-since\-when=\fP\fIROW\fP -Specifies a \fIROW\fP from which the history should be obtained. If not given, the 10 youngest transactions are returned. -.UNINDENT -.SH SEE ALSO -.sp -taler\-bank\-manage(1), taler.conf(5), \fI\%https://docs.taler.net/core/api\-wire.html#wire\-transfer\-test\-apis\fP -.SH BUGS -.sp -Report bugs by using \fI\%https://gnunet.org/bugs/\fP or by sending electronic -mail to <\fI\%taler@gnu.org\fP> -.SH AUTHOR -GNU Taler contributors -.SH COPYRIGHT -2014, 2015, 2016 Florian Dold, Benedikt Muller, Sree Harsha Totakura, Christian Grothoff, Marcello Stanisci (GPLv3+ or GFDL 1.3+) -.\" Generated by docutils manpage writer. -. diff --git a/man/taler-config.1 b/man/taler-config.1 new file mode 100644 index 00000000..37ee9fd8 --- /dev/null +++ b/man/taler-config.1 @@ -0,0 +1,124 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-CONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-config \- Taler configuration inspection and editing +.SH SYNOPSIS +.sp +\fBtaler\-config\fP +[\fB\-b\fP\ \fIbackend\fP\ |\ \fB–supported\-backend=\fP\fIbackend\fP] +[\fB\-c\fP\ \fIfilename\fP\ |\ \fB–config=\fP\fIfilename\fP] +[\fB\-f\fP\ |\ \fB–filename\fP] +[\fB\-F\fP\ |\ \fB–full\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fIloglevel\fP\ |\ \fB–loglevel=\fP\fIloglevel\fP] +[\fB\-l\fP\ \fIfilename\fP\ |\ \fB–logfile=\fP\fIfilename\fP] +[\fB\-o\fP\ \fIoption\fP\ |\ \fB–option=\fP\fIoption\fP] +[\fB\-r\fP\ |\ \fB–rewrite\fP] +[\fB\-S\fP\ |\ \fB–list\-sections\fP] +[\fB\-s\fP\ \fIsection\fP\ |\ \fB–section=\fP\fIsection\fP] +[\fB\-V\fP\ \fIvalue\fP\ |\ \fB–value=\fP\fIvalue\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-config\fP can be used to read or modify GNU Taler configuration files. +.INDENT 0.0 +.TP +\fB\-b\fP \fIBACKEND\fP | \fB–supported\-backend=\fP\fIBACKEND\fP +Tests whether the specified \fIBACKEND\fP is supported by the current installation. +The backend must match the name of a plugin, i.e. “namestore_postgres” for +the PostgreSQL database backend of the “NAMESTORE” service. If \fIBACKEND\fP is +supported, taler\-config will return a status code of 0 (success), otherwise +77 (unsupported). When this option is specified, no other options may be +specified. Specifying this option together with other options will cause +taler\-config to return a status code of 1 (error). +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration file \fIFILENAME\fP\&. +.TP +\fB\-f\fP | \fB–filename\fP +Try to perform expansions as if the option values represent filenames (will +also be applied even if the option is not really a filename). +.TP +\fB\-F\fP | \fB–full\fP +Write the full configuration file, not just the differences to the defaults. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Use \fILOGLEVEL\fP for logging. +Valid values are \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, and \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-o\fP \fIOPTION\fP | \fB–option=\fP\fIOPTION\fP +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”. +.TP +\fB\-r\fP | \fB–rewrite\fP +Write the configuration file even if nothing changed. Will remove all comments! +.TP +\fB\-S\fP | \fB–list\-sections\fP +List available configuration sections for use with \fB\-\-section\fP\&. +.TP +\fB\-s\fP \fISECTION\fP | \fB–section=\fP\fISECTION\fP +Which configuration section should be accessed or edited. +Required option. +.TP +\fB\-V\fP \fIVALUE\fP | \fB–value=\fP\fIVALUE\fP +Configuration value to store in the given section under the given option. +Must only be given together with \fB\-s\fP and \fB\-o\fP options. +.INDENT 7.0 +.TP +.B Note: +Changing the configuration file with \fB\-V\fP will remove comments +and may reorder sections and remove \fB@INLINE@\fP directives. +Using \fB\-V\fP is thus dangerous! Use with extreme caution! +.UNINDENT +.TP +\fB\-v\fP | \fB–version\fP +Print GNU Taler version number. +.UNINDENT +.SH SEE ALSO +.sp +taler.conf(5), taler\-config\-generate(1) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-aggregator.1 b/man/taler-exchange-aggregator.1 index f1ac00a6..c9a226e2 100644 --- a/man/taler-exchange-aggregator.1 +++ b/man/taler-exchange-aggregator.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-AGGREGATOR" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-aggregator \- aggregate deposits into wire transfers . .nr rst2man-indent-level 0 . @@ -30,47 +27,58 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-AGGREGATOR" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-aggregator \- aggregate deposits into wire transfers .SH SYNOPSIS .sp \fBtaler\-exchange\-aggregator\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel\fP\fIUSEC\fP] -[\fB\-t\fP\ |\ \fB––test\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[\fB\-y**_|_\fP–kyc\-off**] .SH DESCRIPTION .sp \fBtaler\-exchange\-aggregator\fP is a command\-line tool to run aggregate deposits to the same merchant into larger wire transfers. The actual transfers are then done by \fBtaler\-exchange\-transfer\fP\&. +.sp +The AGGREGATOR_SHARD_SIZE option can be used to allow multiple aggregator processes to run in parallel and share the load. This is only recommended if a single aggregator is insufficient for the workload. +.sp +The aggregator uses a special table to lock shards it is working on. If an aggregator process dies (say due to a power failure), these shard locks may prevent the aggregator from resuming normally. In this case, you must run “taler\-exchange\-dbinit \-s” to release the shard locks before restarting the aggregator. .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP | \fB––test\fP +\fB\-t\fP | \fB–test\fP Run in test mode and exit when idle. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. +.TP +\fB\-y\fP | \fB–kyc\-off\fP +Run without KYC checks. Talk with your regulator before using this option. .UNINDENT .SH SEE ALSO .sp @@ -83,6 +91,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-benchmark.1 b/man/taler-exchange-benchmark.1 index 3fd342ed..18e966c0 100644 --- a/man/taler-exchange-benchmark.1 +++ b/man/taler-exchange-benchmark.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-BENCHMARK" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-benchmark \- measure exchange performance . .nr rst2man-indent-level 0 . @@ -30,82 +27,75 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-BENCHMARK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-benchmark \- measure exchange performance .SH SYNOPSIS .sp \fBtaler\-exchange\-benchmark\fP -[\fB\-c\fP\ \fICONFIG_FILENAME\fP\ |\ \fB––config=\fP\fICONFIG_FILENAME\fP] -[\fB\-F\fP\ |\ \fB––reserves\-first\fP] -[\fB\-f\fP\ |\ \fB––fakebank\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-K\fP\ |\ \fB––linger\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––log\-level=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIMODE\fP\ |\ \fB––mode=\fP\fIMODE\fP] -[\fB\-n\fP\ \fIHOWMANY_COINS\fP\ |\ \fB––coins\-number=\fP\fIHOWMANY_COINS\fP] -[\fB\-p\fP\ \fINPROCS\fP\ |\ \fB––parallelism=\fP\fINPROCS\fP] -[\fB\-R\fP\ \fIRATE\fP\ |\ \fB––refresh\-rate=\fP\fIRATE\fP] -[\fB\-r\fP\ \fIN\fP\ |\ \fB––reserves=\fP\fIN\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fICONFIG_FILENAME\fP\ |\ \fB–config=\fP\fICONFIG_FILENAME\fP] +[\fB\-F\fP\ |\ \fB–reserves\-first\fP] +[\fB\-f\fP\ |\ \fB–fakebank\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–log\-level=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-n\fP\ \fIHOWMANY_COINS\fP\ |\ \fB–coins\-number=\fP\fIHOWMANY_COINS\fP] +[\fB\-p\fP\ \fINPROCS\fP\ |\ \fB–parallelism=\fP\fINPROCS\fP] +[\fB\-R\fP\ \fIRATE\fP\ |\ \fB–refresh\-rate=\fP\fIRATE\fP] +[\fB\-r\fP\ \fIN\fP\ |\ \fB–reserves=\fP\fIN\fP] +[\fB\-u\fP\ \fISECTION\fP\ |\ \fB–exchange\-account\-section=\fP\fISECTION\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-benchmark\fP is a command\-line tool to measure the time -spent to serve withdrawals/deposits/refreshes. It usually needs a -dedicate configuration file where all the services \- the exchange and -the (fake)bank \- listen to URLs not subject to any reverse proxy, as say -Nginx. Moreover, the benchmark runs on a “volatile” database, that means -that table are always erased during a single benchmark run. +spent to serve withdrawals/deposits/refreshes. Before running the benchmark, +the GNU Taler services must already be running at the configured addresses. .INDENT 0.0 .TP -\fB\-c\fP \fICONFIG_FILENAME\fP | \fB––config=\fP\fICONFIG_FILENAME\fP +\fB\-c\fP \fICONFIG_FILENAME\fP | \fB–config=\fP\fICONFIG_FILENAME\fP (Mandatory) Use CONFIG_FILENAME. .TP -\fB\-F\fP | \fB––reserves\-first\fP +\fB\-F\fP | \fB–reserves\-first\fP Create all reserves first, before starting normal operations. .TP -\fB\-f\fP | \fB––fakebank\fP -Launch a fakebank instead of the Python bank. Only meaningful if the -mode is to launch more than just a client. Note that using the -fakebank will cause the benchmark application to reset all databases -as the fakebank is stateless and thus previous database state would -inherently cause trouble. +\fB\-f\fP | \fB–fakebank\fP +Expect to interact with a fakebank instead of libeufin. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Prints a compiled\-in help text. .TP -\fB\-K\fP | \fB––linger\fP -Linger around until keypress after the benchmark is done. -.TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––log\-level=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log\-level=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIMODE\fP | \fB––mode=\fP\fIMODE\fP -Mode of operation. Accepted values are: \fBexchange\fP, \fBclients\fP, \fBboth\fP\&. -.TP -\fB\-n\fP \fIHOWMANY_COINS\fP | \fB––coins\-number=\fP\fIHOWMANY_COINS\fP +\fB\-n\fP \fIHOWMANY_COINS\fP | \fB–coins\-number=\fP\fIHOWMANY_COINS\fP Defaults to 1. Specifies how many coins this benchmark should withdraw and spend. After being spent, each coin will be refreshed with a probability RATE (see option \fB\-\-refresh\-rate\fP). .TP -\fB\-p\fP \fINPROCS\fP | \fB––parallelism=\fP\fINPROCS\fP +\fB\-p\fP \fINPROCS\fP | \fB–parallelism=\fP\fINPROCS\fP Run with \fINPROCS\fP client processes. .TP -\fB\-R\fP \fIRATE\fP | \fB––refresh\-rate=\fP\fIRATE\fP +\fB\-R\fP \fIRATE\fP | \fB–refresh\-rate=\fP\fIRATE\fP Defaults to 10. Probability of refresh per coin (0\-100). .TP -\fB\-r\fP \fIN\fP | \fB––reserves=\fP\fIN\fP +\fB\-r\fP \fIN\fP | \fB–reserves=\fP\fIN\fP Create \fIN\fP reserves per client. .TP -\fB\-v\fP | \fB––version\fP +\fB\-u\fP \fISECTION\fP | \fB–exchange\-account\-section=\fP\fISECTION\fP +Which configuration section should be used for the bank account +of the exchange. +.TP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO .sp taler\-exchange\-dbinit(1), taler\-exchange\-offline(1), taler\-merchant\-benchmark(1), -taler\-exchange\-httpd(1), taler.conf(5) +taler\-exchange\-httpd(1), taler\-unified\-setup(1), taler.conf(5) .SH BUGS .sp Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic @@ -113,6 +103,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-closer.1 b/man/taler-exchange-closer.1 index dbc268d9..8ddc6550 100644 --- a/man/taler-exchange-closer.1 +++ b/man/taler-exchange-closer.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-CLOSER" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-closer \- close idle reserves . .nr rst2man-indent-level 0 . @@ -30,16 +27,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-CLOSER" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-closer \- close idle reserves .SH SYNOPSIS .sp \fBtaler\-exchange\-closer\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-t\fP\ |\ \fB––test\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-closer\fP is a command\-line tool to run close @@ -47,29 +47,29 @@ reserves that have been idle for too long, causing transfers to the originating bank account to be scheduled. .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP | \fB––test\fP +\fB\-t\fP | \fB–test\fP Run in test mode and exit when idle. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -82,6 +82,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-dbconfig.1 b/man/taler-exchange-dbconfig.1 new file mode 100644 index 00000000..6e3846f6 --- /dev/null +++ b/man/taler-exchange-dbconfig.1 @@ -0,0 +1,83 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-DBCONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-dbconfig \- configure Taler exchange database +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-dbconfig\fP +[\fB\-c\fP\ \fIFILENAME\fP] +[\fB\-h\fP] +[\fB\-n\fP\ \fINAME\fP] +[\fB\-r\fP] +[\fB\-s\fP] +[\fB\-u\fP\ \fIUSER\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-dbconfig\fP is a simple shell script that configures +a Postgresql database for use by the GNU Taler exchange. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP +Write the database configuration to FILENAME. The tool +will append the required \fBCONFIG\fP option for the +Postgresql access to the respective file. +.TP +\fB\-h\fP +Print short help on options. +.TP +\fB\-n\fP \fIDBNAME\fP +Use DBNAME for the name of the created database. +.TP +\fB\-r\fP +Reset any existing database. Looses all existing data. DANGEROUS. +.TP +\fB\-s\fP +Skip database initialization. Useful if you want to run +\fBtaler\-exchange\-dbinit\fP manually. +.TP +\fB\-u\fP \fIUSER\fP +Specifies the (main) exchange user that will access the database. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-dbinit(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-dbinit.1 b/man/taler-exchange-dbinit.1 index 2220abca..2fe53de3 100644 --- a/man/taler-exchange-dbinit.1 +++ b/man/taler-exchange-dbinit.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-DBINIT" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-dbinit \- initialize Taler exchange database . .nr rst2man-indent-level 0 . @@ -30,16 +27,21 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-DBINIT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-dbinit \- initialize Taler exchange database .SH SYNOPSIS .sp \fBtaler\-exchange\-dbinit\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-g\fP\ |\ \fB––gc\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-r\fP\ |\ \fB––reset\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-a\fP\ |\ \fB–inject\-auditor\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-g\fP\ |\ \fB–gc\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-r\fP\ |\ \fB–reset\fP] +[\fB\-s\fP\ |\ \fB–shardunlock\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-dbinit\fP is a command\-line tool to initialize the Taler @@ -49,28 +51,34 @@ Taler exchange to operate. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-a\fP | \fB–inject\-auditor\fP +Installs triggers to notify real\-time auditors of relevant changes to the database state. +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-g\fP | \fB––gc\fP +\fB\-g\fP | \fB–gc\fP Garbage collect database. Deletes all unnecessary data in the database. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-r\fP | \fB––reset\fP +\fB\-r\fP | \fB–reset\fP Drop tables. Dangerous, will delete all existing data in the database before creating the tables. .TP +\fB\-s\fP | \fB–shardunlock\fP +Clears the (revolving) shards table. Needed to clear locks that may be held after a crash (of taler\-exchange\-aggregator or the operating system, say due to power outage) or if the AGGREGATOR_SHARD_SIZE option is changed in the configuration file. +.TP \fB\-v\fP | \fB–version\fP Print version information. .UNINDENT @@ -85,6 +93,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-drain.1 b/man/taler-exchange-drain.1 new file mode 100644 index 00000000..48a7db8a --- /dev/null +++ b/man/taler-exchange-drain.1 @@ -0,0 +1,78 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-DRAIN" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-drain \- drain profits from exchange +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-drain\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-drain\fP is used to trigger a wire transfer from the exchange’s escrow account to a normal (non\-escrowed) bank account of the exchange. The entire drain process is necessary to ensure that the auditor is aware of the +balance changes arising from an exchange making profits from fees. +.sp +To use it, you must first create an upload a ‘drain’ command using \fBtaler\-exchange\-offline\fP\&. Afterwards this command should be run to actually queue the drain. The actual drain will then be executed by \fBtaler\-exchange\-transfer\fP\&. +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the exchange to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-transfer(1), taler\-exchange\-offline(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-expire.1 b/man/taler-exchange-expire.1 new file mode 100644 index 00000000..27eb47af --- /dev/null +++ b/man/taler-exchange-expire.1 @@ -0,0 +1,88 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-EXPIRE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-expire \- refund expired purses +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-expire\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-expire\fP is a command\-line tool to run refund +money in purses that were not merged before their expiration time. +This allows the wallet to recover the funds deposited into the +purse using a refresh operation. +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the exchange to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode and exit when idle. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-router(1), taler\-exchange\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-httpd.1 b/man/taler-exchange-httpd.1 index 1936b3b3..395e0f95 100644 --- a/man/taler-exchange-httpd.1 +++ b/man/taler-exchange-httpd.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-HTTPD" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-httpd \- run Taler exchange (with RESTful API) . .nr rst2man-indent-level 0 . @@ -30,20 +27,24 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-HTTPD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-httpd \- run Taler exchange (with RESTful API) .SH SYNOPSIS .sp \fBtaler\-exchange\-httpd\fP -[\fB\-a\fP\ |\ \fB––allow\-timetravel\fP] -[\fB\-C\fP\ |\ \fB––connection\-close\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-f\fP\ \fIFILENAME\fP\ |\ \fB––file\-input=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-n\fP\ \fIN\fP\ |\ \fB––num\-threads=\fP\fIN\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-t\fP\ \fISECONDS\fP\ |\ \fB––timeout=\fP\fISECONDS\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-a\fP\ |\ \fB–allow\-timetravel\fP] +[\fB\-C\fP\ |\ \fB–connection\-close\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-f\fP\ \fIFILENAME\fP\ |\ \fB–file\-input=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-n\fP\ \fIN\fP\ |\ \fB–num\-threads=\fP\fIN\fP] +[\fB\-r**|\fP–allow\-reuse\-address**] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ \fISECONDS\fP\ |\ \fB–timeout=\fP\fISECONDS\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-httpd\fP is a command\-line tool to run the Taler @@ -53,23 +54,24 @@ must exist before running this command. Its options are as follows: .INDENT 0.0 .TP -\fB\-a\fP | \fB––allow\-timetravel\fP +\fB\-a\fP | \fB–allow\-timetravel\fP 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. .TP -\fB\-C\fP | \fB––connection\-close\fP +\fB\-C\fP | \fB–connection\-close\fP Force each HTTP connection to be closed after each request (useful in -combination with \fB\-f\fP to avoid having to wait for nc to time out). +combination with \fB\-f\fP to avoid having to wait for +netcat (nc) to time out). .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from FILENAME. .TP -\fB\-f\fP \fIFILENAME\fP | \fB––file\-input=\fP\fIFILENAME\fP +\fB\-f\fP \fIFILENAME\fP | \fB–file\-input=\fP\fIFILENAME\fP This option is only available if the exchange was compiled with the -configure option ––enable\-developer\-mode. It is used for generating +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 .INDENT 7.0 @@ -87,29 +89,31 @@ input from an HTTP client and then immediately exit. This is useful to test taler\-exchange\-httpd against many different possible inputs in a controlled way. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-n\fP \fIN\fP | \fB––num\-threads=\fP\fIN\fP -Use \fIN\fP threads in the thread pool. +\fB\-r\fP | \fB–allow\-reuse\-address\fP +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. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP \fISECONDS\fP | \fB––timeout=\fP\fISECONDS\fP +\fB\-t\fP \fISECONDS\fP | \fB–timeout=\fP\fISECONDS\fP Specifies the number of SECONDS after which the HTTPD should close (idle) HTTP connections. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SIGNALS @@ -117,10 +121,6 @@ Print version information. \fBtaler\-exchange\-httpd\fP responds to the following signals: .INDENT 0.0 .TP -.B \fBSIGUSR1\fP -Sending a SIGUSR1 to the process will cause it to reload denomination -and signing keys. -.TP .B \fBSIGTERM\fP Sending a SIGTERM to the process will cause it to shutdown cleanly. .TP @@ -142,6 +142,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-kyc-aml-pep-trigger.1 b/man/taler-exchange-kyc-aml-pep-trigger.1 new file mode 100644 index 00000000..e6a0fb7f --- /dev/null +++ b/man/taler-exchange-kyc-aml-pep-trigger.1 @@ -0,0 +1,55 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-KYC-AML-PEP-TRIGGER" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-kyc-aml-pep-trigger \- Taler KYC_AML_TRIGGER example +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-kyc\-aml\-pep\-trigger\fP +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-kyc\-aml\-pep\-trigger\fP is a trivial shell script to illustrate how to trigger an AML process when the KYC process sets the “PEP” flag in the attribute data. +.sp +The script is mostly an example (or starting point) for +writing programs for the KYC_AML_TRIGGER option of the +exchange. +.SH SEE ALSO +.sp +taler.conf(5) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-kyc-tester.1 b/man/taler-exchange-kyc-tester.1 new file mode 100644 index 00000000..ff80a8df --- /dev/null +++ b/man/taler-exchange-kyc-tester.1 @@ -0,0 +1,112 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-KYC-TESTER" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-kyc-tester \- test KYC service integration +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-kyc\-tester\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-i\fP\ \fISECTION_NAME\fP\ |\ \fB–initiate=\fP\fISECTION_NAME\fP] +[\fB\-u\fP\ \fIID\fP\ |\ \fB–user=\fP\fIID\fP] +[\fB\-U\fP\ \fIID\fP\ |\ \fB–legitimization=\fP\fIID\fP] +[\fB\-P\fP\ |\ \fB–print\-payto\-hash\fP] +[\fB\-p\fP\ \fIHASH\fP\ |\ \fB–payto\-hash=\fP\fIHASH\fP] +[\fB\-r\fP\ \fINUMBER\fP\ |\ \fB–rowid=\fP\fINUMBER\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[\fB\-w\fP\ |\ \fB–run\-webservice\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-kyc\-tester\fP is used to test the interaction between a Taler exchange and a KYC service. The tool can be used to manually trigger the various steps of a KYC process and to observe the interaction with the respective KYC service. It is supposted to help test the configuration of the integration, and \fInot\fP required at all during production. +.sp +To use it, you must first provide a configuration file with at least one KYC service configured. Some other exchange\-specific options, like the PORT for the HTTP service and the BASE_URL under which the Taler exchange will run are also required. You should be able to use exactly the same configuration file that one would usually give to a Taler exchange. Starting with this, the tool allows the simulation of a KYC process. Note that it will not write any information to the database. +.sp +Begin with a first invocation of taler\-exchange\-kyc\-tester using the options \fB\-i\fP for an individual or business and use \fB\-R\fP to specify a list of checks required from the process. The output will be an URL to visit with the browser, as well as \fB\-p\fP, \fB\-u\fP, \fB\-U\fP options to use in future invocations of the tool. +.sp +Next, run taler\-exchange\-kyc\-tester again, but this time using \fB\-w\fP (to run the Webserver) and using the \fB\-u\fP and \fB\-U\fP options output by the previous call, as well as the \fB\-p\fP option with the payto hash. Then visit the Web site from the link output by the previous invocation and “pass” (or “fail”) the KYC check. +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the exchange to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-i\fP \fIUSERTYPE\fP | \fB–initiate=\fP\fIUSERTYPE\fP +Specifies the type of user for which we are starting a fresh KYC process. USERTYPE must be either “individual” or “business”. +.TP +\fB\-u\fP \fIID\fP | \fB–user=\fP\fIID\fP +Run the process with ID for the user identifier at the KYC provider. Not useful in conjunction with \fB\-i\fP and \fB\-R\fP as that option will override whatever value is provided here. +.TP +\fB\-U\fP \fIID\fP | \fB–legitimization=\fP\fIID\fP +Run the process with ID for the legitimization process identifier at the KYC provider. Not useful in conjunction with \fB\-R\fP / \fB\-i\fP as that option will override whatever value is provided here. +.TP +\fB\-p\fP \fIHASH\fP | \fB–payto\-hash=\fP\fIHASH\fP +Run the process with HASH as the hash of the payto://\-URI that identifies the account or wallet triggering the KYC requirement. If not given, a fresh random value is used. Rarely useful. +.TP +\fB\-P\fP | \fB–print\-payto\-hash\fP +Print the HASH of the payto://\-URI used for the KYC simulation this time. Useful if the hash is needed for a subsequent use in conjunction with \fB\-p\fP\&. +.TP +\fB\-r\fP \fINUMBER\fP | \fB–rowid=\fP\fINUMBER\fP +Run the process with NUMBER as the database row for the legitimization operation. Rarely useful, except maybe for debugging. Defaults to 42. +.TP +\fB\-R\fP \fICHECKS\fP | \fB–requirements=\fP\fICHECKS\fP +Start a fresh KYC process for the given list of CHECKS. CHECKS must be a space\-separated list of checks that must be in the configuration under \fIPROVIDED_CHECKS\fP for some of the providers. The exchange will determine which provider to use for KYC based on the CHECKS given. The tool will output the HTTP URL where the user has to begin the KYC process to the command\-line. This is usually the first thing to do when using this tool. Outputs the KYC\-logic specific user and legitimization IDs, or NULL if not used by the KYC\-logic at the initiation stage. You may want to use the \fB\-P\fP option to also obtain the Payto\-Hash for use with \fBp\fP later. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.TP +\fB\-w\fP | \fB–run\-webservice\fP +Run a simulated Taler exchange HTTP service on the configured port with the \fB/kyc\-proof/\fP and \fB/kyc\-webhook/\fP endpoints. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-offline.1 b/man/taler-exchange-offline.1 index 63d4a074..687d86c0 100644 --- a/man/taler-exchange-offline.1 +++ b/man/taler-exchange-offline.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-OFFLINE" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-offline \- operations using the offline key of a Taler exchange . .nr rst2man-indent-level 0 . @@ -30,32 +27,38 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-OFFLINE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-offline \- operations using the offline key of a Taler exchange .SH SYNOPSIS .sp \fBtaler\-exchange\-offline\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-v\fP\ |\ \fB––version\fP] -[subcommand ...] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[subcommand …] .SH DESCRIPTION .sp \fBtaler\-exchange\-offline\fP is a command\-line tool to interact with the Taler -exchange\(aqs master private key. Most operations of this tool require access to +exchange’s master private key. Most operations of this tool require access to the exchange’s long\-term offline signing key and should be run in a secure (offline) environment under strict controls. The tool takes a list of subcommands as arguments which are then processed sequentially. .sp -The tool includes two subcommands to interact \fIonline\fP with the exchange\(aqs -REST APIs. The \fBdownload\fP subcommand downloads the future public keys from the -running exchange. The resulting data serves as input to the \fBsign\fP and \fBshow\fP -subcommands. The \fBupload\fP subcommand uploads the signatures created with the -private master key to the exchange. It handles the output of all subcommands -(except \fBdownload\fP). The \fBdownload\fP and \fBupload\fP subcommands must naturally be -run "online" and do not require access to the offline key. -.sp -All other subcommands are intended to be run "offline". However, especially +The tool includes two subcommands to interact \fIonline\fP with the exchange’s +REST APIs. To determine how to talk to the exchange, these two subcommands +rely on the \fBBASE_URL\fP configuration option from the \fB[exchange]\fP section +of the configuration file. The \fBdownload\fP subcommand downloads the future +public keys from the running exchange. The resulting data serves as input to +the \fBsign\fP and \fBshow\fP subcommands. The \fBupload\fP subcommand uploads the +signatures created with the private master key to the exchange. It handles +the output of all subcommands (except \fBdownload\fP). The \fBdownload\fP and +\fBupload\fP subcommands must naturally be run “online” and do not require +access to the offline key. +.sp +All other subcommands are intended to be run “offline”. However, especially when testing, it is of course possible to run the subcommands online as well. Generally, subcommands read inputs (beyond command\-line arguments) from \fBstdin\fP\&. However, they may also consume outputs of previous @@ -65,21 +68,21 @@ and if not consumed the final output is printed to \fBstdout\fP\&. The general options for \fBtaler\-exchange\-offline\fP are: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH CONFIGURATION @@ -99,17 +102,17 @@ $ taler\-exchange\-offline setup .UNINDENT .sp Note that if the private key file already exists, the above will simply output -the existing key. Passing additional arguments after setup (including "\-") +the existing key. Passing additional arguments after setup (including “\-“) will cause the output to be encapsulated in JSON. .sp Relevant configuration options for \fBtaler\-exchange\-offline\fP are: .INDENT 0.0 .IP \(bu 2 -\fB[exchange/BASE_URL]\fP \-\-\- how to reach the exchange (for download/upload) +\fB[exchange/BASE_URL]\fP — how to reach the exchange (for download/upload) .IP \(bu 2 -\fB[exchange\-offline/MASTER_PRIV_FILE]\fP \-\-\- where to store the private keys +\fB[exchange\-offline/MASTER_PRIV_FILE]\fP — where to store the private keys .IP \(bu 2 -\fB[exchange\-offline/SECM_TOFU_FILE]\fP \-\-\- where to store TOFU data +\fB[exchange\-offline/SECM_TOFU_FILE]\fP — where to store TOFU data .UNINDENT .SH SUBCOMMANDS .SS setup @@ -147,6 +150,42 @@ directly. .sp It outputs the signatures over \fIall\fP denomination and signing keys present in the input, in a format suitable for the \fBupload\fP subcommand. +.SS extensions +.sp +This subcommand is responsible for the management of available extensions in +the exchange. +.sp +It consumes the output of the \fBdownload\fP subcommand, either from \fBstdin\fP or +directly. +.sp +It provides the sub\-subcommand \fBextensions show\fP to show the configuration +for extensions and the \fBextensions sign\fP command to sign the current +configuration of extensions, in a format suitable for the \fBupload\fP +subcommand. +.sp +Note that an extension on the exchange will only become activated at runtime +\fIafter\fP the extension’s configurations has been signed by the offline tool with +the signing key and the signed configuration been uploaded to the exchange. +.SS drain +.sp +This subcommand allows an exchange operator to transfer the +profits made from transaction fees to a regular (non\-escrowed) bank +account. Using this command, draining profits from the +escrow account can be done in such a way that the auditor +is aware of the special transaction and does not flag the +resulting balance as fundamentally problematic. Note that +the drained amounts must still total up to less than the fees +earned by the exchange. +.sp +Arguments to the \fBdrain\fP command are the amount to be drained (in the usual +Taler amount format), the section of the exchange configuration specifying the +account to be debited (this argument is currently ignored, and the account is +purely derived from the wire method and the account being set for debiting), +and finally the payto://\-URI to wire the funds to. +.sp +Note that to actually wire the funds, the exchange administrator must run +\fBtaler\-exchange\-drain\fP manually and confirm the operation after the +\fBupload\fP was completed. .SS revoke\-denomination .sp This subcommand signs a revocation message for a denomination key. @@ -169,23 +208,23 @@ in a format suitable for the \fBupload\fP subcommand. .sp This subcommand informs an exchange that an auditor is to be activated. Afterwards, the -exchange will accept inputs from that auditor\(aqs \fBtaler\-auditor\-offline\fP +exchange will accept inputs from that auditor’s \fBtaler\-auditor\-offline\fP tool. Note that the auditor also must add the exchange to the list of exchanges that it audits via \fBtaler\-auditor\-exchange\fP\&. Furthermore, the -exchange\(aqs database will need to be provided to the auditor. This subcommand +exchange’s database will need to be provided to the auditor. This subcommand only informs the exchange about the auditor, but does not perform those additional mandatory steps for a working auditor. .sp -The auditor\(aqs public key must be given in the usual base32\-encoding as the +The auditor’s public key must be given in the usual base32\-encoding as the first argument. .sp -The auditor\(aqs REST API base URL must be given as the second argument. The tool -performs a minimal sanity check, namely that the URL begins with "http" -(this also allows "https"), but as it runs offline does not perform any further +The auditor’s REST API base URL must be given as the second argument. The tool +performs a minimal sanity check, namely that the URL begins with “http” +(this also allows “https”), but as it runs offline does not perform any further validation! .sp The third argument must be a human\-readable name for the auditor. This may -be shown to users and should identify the auditor\(aqs business entity. If +be shown to users and should identify the auditor’s business entity. If the name includes spaces, the argument should be quoted. .sp The subcommand takes no inputs from \fBstdin\fP or other subcommands. @@ -196,10 +235,10 @@ in a format suitable for the \fBupload\fP subcommand. .sp This subcommand informs an exchange that an auditor is to be deactivated. Afterwards, the -exchange will refuse inputs from that auditor\(aqs \fBtaler\-auditor\-offline\fP +exchange will refuse inputs from that auditor’s \fBtaler\-auditor\-offline\fP tool. .sp -The auditor\(aqs public key must be given in the usual base32\-encoding as the +The auditor’s public key must be given in the usual base32\-encoding as the first argument. .sp The subcommand takes no inputs from \fBstdin\fP or other subcommands. @@ -208,19 +247,74 @@ It outputs the signature affirming the removal of the auditor, in a format suitable for the \fBupload\fP subcommand. .SS enable\-account .sp -This subcommand -informs an exchange that it should advertise a bank account as belonging to -the exchange on its \fB/wire\fP endpoint. Note that this does \fInot\fP ensure that -the exchange will use this bank account for incoming or outgoing wire -transfers! For this, the \fBtaler\-exchange\-transfer\fP and +This subcommand informs an exchange that it should advertise a bank account as +belonging to the exchange on its \fB/keys\fP endpoint. Note that this does +\fInot\fP ensure that the exchange will use this bank account for incoming or +outgoing wire transfers! For this, the \fBtaler\-exchange\-transfer\fP and \fBtaler\-exchange\-wirewatch\fP tools must be configured. Furthermore, the bank account information advertised could theoretically differ from that which these tool actually use, for example if the public bank account is only a front for the actual internal business accounts. .sp -The \fBpayto://\fP URI (RFC 8905) of the exchange\(aqs bank account must be given +The \fBpayto://\fP URI (RFC 8905) of the exchange’s bank account must be given as the first argument to the subcommand. .sp +Afterwards, optional arguments can be given: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBconversion\-url\fP $URL: specifies that using this bank account is subject +to currency conversion. $URL must be the address of a currency conversion +REST API that allows merchants and wallets to determine the current +conversion rate. +.IP \(bu 2 +\fBdisplay\-hint\fP $PRIORITY $LABEL: specifies that this bank account should +be shown to the user with the given numeric $PRIORITY (higher is earlier) +and with the given $LABEL. This is useful to ensure that if an exchange +has multiple bank accounts, we can show the user those that are most likely +useful first, and give them appropriately labeled hints for selecting other +accounts as well. A display hint is optional, if missing the priority is 0 +and the wallet must pick some appropriate label itself somehow. +.IP \(bu 2 +\fBcredit\-restriction\fP $TYPE [$ARGS]: Specifies that there are +restrictions in place when crediting this bank account. Details depend on +the restriction $TYPE. This argument may be given multiple times, in which +case debitor accounts must satisfy all restrictions. Restriction types are +discussed below. +.IP \(bu 2 +\fBdebit\-restriction\fP $TYPE [$ARGS]: Specifies that there are restrictions +in place when receiving money from the exchange. Wallets and merchants +must check that their target bank account satisfies these restrictions +before sending deposit requests to the exchange. Details depend on the +restriction $TYPE. This argument may be given multiple times, in which +case debitor accounts must satisfy all restrictions. Restriction types are +discussed below. +.UNINDENT +.UNINDENT +.UNINDENT +.sp +The following types of credit\- and debit\-restrictions are supported: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +\fBdeny\fP: A $TYPE of \fBdeny\fP means that this bank account cannot be used +for the given operation. \fBdeny\fP takes no further arguments. +.IP \(bu 2 +\fBregex\fP $EXPR $HINT $JSON: A $TYPE of \fBregex\fP means that the partner’s +bank account \fBpayto\fP\-URI representation must follow a certain regular +expression given in $EXPR where the syntax follows posix\-egrep, but +without support for character classes, GNU extensions, back\-references or +intervals. See +\fI\%Findutils Manual\fP +for a description of the posix\-egrep syntax. The $HINT must be a +human\-readable description of the $EXPR. $JSON should be a JSON array +mapping IETF BCP 47 language tags to localized versions of $HINT. +.UNINDENT +.UNINDENT +.UNINDENT +.sp The subcommand takes no inputs from \fBstdin\fP or other subcommands. .sp It outputs the signature affirming the addition of the wire account, @@ -229,9 +323,9 @@ in a format suitable for the \fBupload\fP subcommand. .sp This subcommand informs an exchange that it should stop advertising a bank account as -belonging to the exchange on its \fB/wire\fP endpoint. +belonging to the exchange on its \fB/keys\fP endpoint. .sp -The \fBpayto://\fP URI (RFC 8905) of the exchange\(aqs (former) bank account must be +The \fBpayto://\fP URI (RFC 8905) of the exchange’s (former) bank account must be given as the first argument to the subcommand. .sp The subcommand takes no inputs from \fBstdin\fP or other subcommands. @@ -240,13 +334,13 @@ It outputs the signature affirming the deletion of the wire account, in a format suitable for the \fBupload\fP subcommand. .SS wire\-fee .sp -This subcommand informs an exchange about the desired wire fee (and closing fee) -structure for particular wire method and a calendar year (!). The tool does not +This subcommand informs an exchange about the desired wire fee structure (that is, wire, and closing fees) +for particular wire method and a calendar year (!). The tool does not permit changing wire fees during a calendar year. Also, once the wire fee has been set for a calendar year, it cannot be changed. .sp The subcommand takes the year, wire\-method (see RFC 8905, examples include -\fBx\-taler\-bank\fP or \fBiban\fP), wire fee and closing fee as arguments. +\fBx\-taler\-bank\fP or \fBiban\fP), wire fee, and closing fee as arguments. Instead of a year, the string \fBnow\fP can be given for the current year (this is mostly useful for test cases). The wire\-method should follow the GANA registry as given in RFC 8905. The fees must be given in the usual @@ -256,6 +350,127 @@ The subcommand takes no inputs from \fBstdin\fP or other subcommands. .sp It outputs the signature affirming the wire fees, in a format suitable for the \fBupload\fP subcommand. +.SS global\-fee +.sp +This subcommand informs an exchange about the desired global fee structure and +related global configuration options for a calendar year (!). The tool does +not permit changing global fees during a calendar year. Also, once the global +fee structure has been set for a calendar year, it cannot be changed. +.sp +The subcommand takes the year, history fee, account fee, purse fee, +purse timeout, history expiration and the (free) purse (per) +account limit as arguments. Instead of a year, the string \fBnow\fP can be +given for the current year (this is mostly useful for test cases). The fees +must be given in the usual Taler format of \fBCURRENCY:NUMBER.FRACTION\fP\&. +.sp +The subcommand takes no inputs from \fBstdin\fP or other subcommands. +.sp +It outputs the signature affirming the global fees, in a format suitable for +the \fBupload\fP subcommand. +.SS enable\-partner +.sp +This subcommand informs an exchange about the wad fee and frequency to apply +to a partner exchange. The arguments provided must include: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Partner exchange base URL. +.IP 2. 3 +Partner exchange master public key. +.IP 3. 3 +Calendar year for which the fee applies, ‘now’ for the current year. +.IP 4. 3 +Wad frequency, in minutes (for example, ‘30’). +.IP 5. 3 +Wad fee (for example, ‘KUDOS:0.1’). +.UNINDENT +.UNINDENT +.UNINDENT +.SS p2p\-fees +.sp +This subcommand configures fees related to wallet\-to\-wallet payments. If this configuration is not provided, wallet\-to\-wallet payments will be disabled by the exchange. +.sp +The arguments provided must include: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Calendar year for which the fee applies, ‘now’ for the current year. +.IP 2. 3 +KYC timeout. How long does the exchange keep a reserve open that is waiting for the KYC. +.IP 3. 3 +KYC fee. How much will the exchange charge for performing KYC. +.IP 4. 3 +Purse timeout. How long does the exchange keep information about a purse around after it expired or was successfully merged? +.IP 5. 3 +Purse fee. How much will the exchange charge for an abandoned purse. Also the minimum amount that can be in a purse that is not associated with an account. +.IP 6. 3 +Number of free purses per account. +.IP 7. 3 +Annual fee charged to an open account. +.IP 8. 3 +How long will the exchange preserve an account history. +.IP 9. 3 +History fee charged when inquiring about non\-recent account history. +.UNINDENT +.UNINDENT +.UNINDENT +.SS aml\-enable +.sp +Enable AML officer’s account, granting them access to AML data and, +if ‘rw’ is given, the power to make AML decisions. +.sp +The arguments provided must include: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +AML staff member public key (in base32 encoding) +.IP 2. 3 +AML staff member legal name +.IP 3. 3 +‘ro’ or ‘rw’ to set access to read\-only or read\-write +.UNINDENT +.UNINDENT +.UNINDENT +.SS aml\-disable +.sp +Disable AML officer’s account. Also updates the legal name. +.sp +The arguments provided must include: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +AML staff member public key (in base32 encoding) +.IP 2. 3 +AML staff member legal name +.UNINDENT +.UNINDENT +.UNINDENT +.SS add\-partner +.sp +Add partner exchange for wad transfers. Enables P2P payments +between users of these exchanges. +.sp +The arguments provided must include: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Master public key of the partner exchange. +.IP 2. 3 +Base URL of the partner exchange API. +.IP 3. 3 +Wad fee to charge. +.IP 4. 3 +Wad transfer frequency. +.IP 5. 3 +Year for which the above options are to be configured, ‘now’ for the current year. +.UNINDENT +.UNINDENT +.UNINDENT .SS upload .sp This subcommand uploads outputs from other subcommands (except \fBdownload\fP and \fBshow\fP) @@ -314,13 +529,18 @@ $ taler\-exchange\-offline upload < sigs.json .UNINDENT .SS Download, sign and upload, all in one (online) .sp -Note that doing this is only recommended in non\-production deployments. +Note that doing this is only recommended in non\-production deployments, +as this requires putting the “offline” key onto a system that is actually +online! .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -$ taler\-exchange\-offline download sign upload +$ taler\-exchange\-offline \e + download \e + sign \e + upload .ft P .fi .UNINDENT @@ -333,18 +553,50 @@ so that \fBsign\fP can see it as input, as in the variant without \fBshow\fP\&. .sp .nf .ft C -$ taler\-exchange\-offline download show \- sign upload +$ taler\-exchange\-offline \e + download \e + show \- \e + sign \e + upload .ft P .fi .UNINDENT .UNINDENT .SS Create signature to enable bank account (offline) +.sp +The following command sets up an unrestricted simple exchange bank account +without conversion: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ taler\-exchange\-offline \e + enable\-account payto://iban/DE24242?receiver\-name=operator > account.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following command would set up an exchange bank account with conversion +and restrict it to only receive money from Switzerland and deny its use for +debit operations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -$ taler\-exchange\-offline enable\-account payto://iban/DE24242 > account.json +$ taler\-exchange\-offline \e + enable\-account payto://x\-taler\-bank/example.com/?receiver\-name=name \e + conversion\-url http://conversion.exchange.com/ \e + debit\-restriction \e + deny \e + credit\-restriction \e + regex \e + \(aqpayto://iban/.*/CH.*?receiver\-name=.*\(aq \e + \(aqSwiss only\(aq \e + \(aq{ \(dqde\(dq : \(dqnur Schweiz\(dq, \e + \(dqfr\(dq : \(dqSuisse uniquement\(dq }\(aq .ft P .fi .UNINDENT @@ -361,16 +613,25 @@ $ taler\-exchange\-offline upload < account.json .UNINDENT .UNINDENT .SS Combine signing keys and enabling bank account (offline) +.sp +You can chain multiple commands into one invocation: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -$ taler\-exchange\-offline sign enable\-account payto://iban/DE24242 < keys.json > combo.json +$ taler\-exchange\-offline \e + sign \e + enable\-account \e + payto://iban/DE24242 < keys.json > combo.json .ft P .fi .UNINDENT .UNINDENT +.sp +Note that \fBsign\fP must be first as it consumes the \fBkeys.json\fP +input. The resulting output combines the outputs of the \fBsign\fP +and \fBenable\-account\fP subcommands. .SS Upload various signatures (online) .INDENT 0.0 .INDENT 3.5 @@ -383,20 +644,29 @@ $ taler\-exchange\-offline upload < combo.json .UNINDENT .UNINDENT .SS Create multiple revocation messages in one pass (offline) +.sp +You can freely combine almost all commands, including those for +key revocation: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -$ taler\-exchange\-offline revoke\-denomination $DKH1 revoke\-denomination $DKH2 > revoke.json -$ taler\-exchange\-offline revoke\-signkey $SK1 revoke\-signkey $SK2 > revoke.json -$ taler\-exchange\-offline revoke\-signkey $SK revoke\-denomkey $DKH > mix.json +$ taler\-exchange\-offline \e + revoke\-denomination $DKH1 \e + revoke\-denomination $DKH2 > revoke.json +$ taler\-exchange\-offline \e + revoke\-signkey $SK1 \e + revoke\-signkey $SK2 > revoke.json +$ taler\-exchange\-offline \e + revoke\-signkey $SK \e + revoke\-denomkey $DKH > mix.json .ft P .fi .UNINDENT .UNINDENT .sp -The outputs ("revoke.json", "mix.json") must be uploaded using the \fBupload\fP +The outputs (“revoke.json”, “mix.json”) must be uploaded using the \fBupload\fP subcommand to the exchange to actually revoke the keys. .SH SECURITY CONSIDERATIONS .sp @@ -405,8 +675,8 @@ system with \fImonotonic time\fP\&. The time does not have to precisely match th of the exchange, but it must be monotonic across tool invocations. The clock of the offline system is used in the enable/disable signatures to communicate an order of the events to the exchange. This prevents someone from replaying -an older "enable" (or "disable") message after a more recent "disable" (or -"enable") message has been provided to the exchange. Thus, there is no need +an older “enable” (or “disable”) message after a more recent “disable” (or +“enable”) message has been provided to the exchange. Thus, there is no need to keep the actual files exchanged with the offline tool secret. .sp The \fBtaler\-exchange\-offline\fP tool tries to make sure that the online signing @@ -416,7 +686,7 @@ but \fInot\fP the security modules from providing attacker\-controlled keys to t offline signing process. .sp For this, the \fBtaler\-exchange\-offline\fP signing subcommand always -automatically learns the security module\(aqs public signing key and \fItrusts it +automatically learns the security module’s public signing key and \fItrusts it on first use\fP (TOFU), but stores it to disk (see the \fBSECM_TOFU_FILE\fP option in the \fB[exchange\-offline]\fP section of the configuration). If the keys change subsequently, the tool will refuse to sign. @@ -430,6 +700,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-router.1 b/man/taler-exchange-router.1 new file mode 100644 index 00000000..3b4c095b --- /dev/null +++ b/man/taler-exchange-router.1 @@ -0,0 +1,89 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-ROUTER" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-router \- route payments to partner exchanges +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-router\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-router\fP is a NOT YET IMPLEMENTED command\-line +tool to route P2P payments to partner exchanges via wad transfers. +This will be needed if wallet\-to\-wallet payments are made between +wallets where the recipient has performed the KYC at a different +exchange than the sender. This is currently not supported. +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the exchange to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode and exit when idle. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-expire(1), taler\-exchange\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-secmod-cs.1 b/man/taler-exchange-secmod-cs.1 new file mode 100644 index 00000000..cd8001b5 --- /dev/null +++ b/man/taler-exchange-secmod-cs.1 @@ -0,0 +1,95 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-EXCHANGE-SECMOD-CS" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-secmod-cs \- handle private CS key operations for a Taler exchange +.SH SYNOPSIS +.sp +\fBtaler\-exchange\-secmod\-cs\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ \fIN\fP\ |\ ,**–parallelism=**\fIN\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ \fITIMESTAMP\fP\ |\ \fB–time=\fP\fITIMESTAMP\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-exchange\-secmod\-cs\fP is a command\-line tool to +handle private Clause\-Schnorr key operations for a Taler exchange. +.sp +FIXME: More details. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fBp\fP \fIN\fP | \fB–parallelism=\fP\fIN\fP +Run with \fIN\fP worker threads. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP \fITIMESTAMP\fP | \fB–time=\fP\fITIMESTAMP\fP +Pretend it is \fITIMESTAMP\fP for the update. +\fITIMESTAMP\fP is a human\-readable string (e.g., \fBYYYY\-MM\-DD HH:MM:SS\fP). +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-httpd(1). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-exchange-secmod-eddsa.1 b/man/taler-exchange-secmod-eddsa.1 index c8c7cde5..4e4a890b 100644 --- a/man/taler-exchange-secmod-eddsa.1 +++ b/man/taler-exchange-secmod-eddsa.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-SECMOD-EDDSA" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-secmod-eddsa \- handle private EDDSA key operations for a Taler exchange . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-SECMOD-EDDSA" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-secmod-eddsa \- handle private EDDSA key operations for a Taler exchange .SH SYNOPSIS .sp \fBtaler\-exchange\-secmod\-eddsa\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-p\fP\ \fIN\fP\ |\ ,**––parallelism=**\fIN\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-t\fP\ \fITIMESTAMP\fP\ |\ \fB––time=\fP\fITIMESTAMP\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ \fIN\fP\ |\ ,**–parallelism=**\fIN\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ \fITIMESTAMP\fP\ |\ \fB–time=\fP\fITIMESTAMP\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-secmod\-eddsa\fP is a command\-line tool to @@ -51,33 +51,33 @@ FIXME: More details. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fBp\fP \fIN\fP | \fB––parallelism=\fP\fIN\fP +\fBp\fP \fIN\fP | \fB–parallelism=\fP\fIN\fP Run with \fIN\fP worker threads. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP \fITIMESTAMP\fP | \fB––time=\fP\fITIMESTAMP\fP +\fB\-t\fP \fITIMESTAMP\fP | \fB–time=\fP\fITIMESTAMP\fP Pretend it is \fITIMESTAMP\fP for the update. \fITIMESTAMP\fP is a human\-readable string (e.g., \fBYYYY\-MM\-DD HH:MM:SS\fP). .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -90,6 +90,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-secmod-rsa.1 b/man/taler-exchange-secmod-rsa.1 index c1720b11..ee998ad6 100644 --- a/man/taler-exchange-secmod-rsa.1 +++ b/man/taler-exchange-secmod-rsa.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-SECMOD-RSA" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-secmod-rsa \- handle private RSA key operations for a Taler exchange . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-SECMOD-RSA" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-secmod-rsa \- handle private RSA key operations for a Taler exchange .SH SYNOPSIS .sp \fBtaler\-exchange\-secmod\-rsa\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-p\fP\ \fIN\fP\ |\ ,**––parallelism=**\fIN\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-t\fP\ \fITIMESTAMP\fP\ |\ \fB––time=\fP\fITIMESTAMP\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ \fIN\fP\ |\ ,**–parallelism=**\fIN\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-t\fP\ \fITIMESTAMP\fP\ |\ \fB–time=\fP\fITIMESTAMP\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-secmod\-rsa\fP is a command\-line tool to @@ -51,33 +51,33 @@ FIXME: More details. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fBp\fP \fIN\fP | \fB––parallelism=\fP\fIN\fP +\fBp\fP \fIN\fP | \fB–parallelism=\fP\fIN\fP Run with \fIN\fP worker threads. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP \fITIMESTAMP\fP | \fB––time=\fP\fITIMESTAMP\fP +\fB\-t\fP \fITIMESTAMP\fP | \fB–time=\fP\fITIMESTAMP\fP Pretend it is \fITIMESTAMP\fP for the update. \fITIMESTAMP\fP is a human\-readable string (e.g., \fBYYYY\-MM\-DD HH:MM:SS\fP). .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -90,6 +90,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-transfer.1 b/man/taler-exchange-transfer.1 index 6291ec89..d8b3426f 100644 --- a/man/taler-exchange-transfer.1 +++ b/man/taler-exchange-transfer.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-TRANSFER" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-transfer \- execute wire transfers . .nr rst2man-indent-level 0 . @@ -30,45 +27,48 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-TRANSFER" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-transfer \- execute wire transfers .SH SYNOPSIS .sp \fBtaler\-exchange\-transfer\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel\fP\fIUSEC\fP] -[\fB\-t\fP\ |\ \fB––test\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-transfer\fP is a command\-line tool to actually execute scheduled wire transfers (using the bank/wire gateway). The transfers are prepared by the \fBtaler\-exchange\-aggregator\fP and \fBtaler\-exchange\-closer\fP tools. .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP | \fB––test\fP +\fB\-t\fP | \fB–test\fP Run in test mode and exit when idle. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -82,6 +82,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-wire-gateway-client.1 b/man/taler-exchange-wire-gateway-client.1 index 9fec8eda..25d09723 100644 --- a/man/taler-wire-gateway-client.1 +++ b/man/taler-exchange-wire-gateway-client.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-WIRE-GATEWAY-CLIENT" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-wire-gateway-client \- trigger a transfer at the bank . .nr rst2man-indent-level 0 . @@ -30,28 +27,31 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-WIRE-GATEWAY-CLIENT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-wire-gateway-client \- trigger a transfer at the bank .SH SYNOPSIS .sp -\fBtaler\-wire\-gateway\-client\fP -[\fB\-a\fP\ \fIVALUE\fP\ |\ \fB––amount=\fP\fIVALUE\fP] -[\fB\-b\fP\ \fIURL\fP\ |\ \fB––bank=\fP\fIURL\fP] -[\fB\-C\fP\ \fIACCOUNT\fP\ |\ \fB––credit=\fP\fIACCOUNT\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-D\fP\ \fIACCOUNT\fP\ |\ \fB––debit=\fP\fIACCOUNT\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-i\fP\ |\ \fB––credit\-history\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-o\fP\ |\ \fB––debit\-history\fP] -[\fB\-p\fP\ \fIPASSPHRASE\fP\ |\ \fB––pass=\fP\fIPASSPHRASE\fP] -[\fB\-S\fP\ \fISTRING\fP\ |\ \fB––subject=\fP\fISTRING\fP] -[\fB\-s\fP\ \fIACCOUNT\-SECTION\fP\ |\ \fB––section=\fP\fIACCOUNT\-SECTION\fP] -[\fB\-u\fP\ \fIUSERNAME\fP\ |\ \fB––user=\fP\fIUSERNAME\fP] -[\fB\-v\fP\ |\ \fB––version\fP] -[\fB\-w\fP\ \fIROW\fP\ |\ \fB––since\-when=\fP\fIROW\fP] +\fBtaler\-exchange\-wire\-gateway\-client\fP +[\fB\-a\fP\ \fIVALUE\fP\ |\ \fB–amount=\fP\fIVALUE\fP] +[\fB\-b\fP\ \fIURL\fP\ |\ \fB–bank=\fP\fIURL\fP] +[\fB\-C\fP\ \fIACCOUNT\fP\ |\ \fB–credit=\fP\fIACCOUNT\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-D\fP\ \fIACCOUNT\fP\ |\ \fB–debit=\fP\fIACCOUNT\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-i\fP\ |\ \fB–credit\-history\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-o\fP\ |\ \fB–debit\-history\fP] +[\fB\-p\fP\ \fIPASSPHRASE\fP\ |\ \fB–pass=\fP\fIPASSPHRASE\fP] +[\fB\-S\fP\ \fISTRING\fP\ |\ \fB–subject=\fP\fISTRING\fP] +[\fB\-s\fP\ \fIACCOUNT\-SECTION\fP\ |\ \fB–section=\fP\fIACCOUNT\-SECTION\fP] +[\fB\-u\fP\ \fIUSERNAME\fP\ |\ \fB–user=\fP\fIUSERNAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[\fB\-w\fP\ \fIROW\fP\ |\ \fB–since\-when=\fP\fIROW\fP] .SH DESCRIPTION .sp -\fBtaler\-wire\-gateway\-client\fP is a command\-line tool to trigger bank transfers or +\fBtaler\-exchange\-wire\-gateway\-client\fP is a command\-line tool to trigger bank transfers or inspect wire transfers for exchange accounts using the wire API. The tool is expected to be used during testing or for diagnostics. .sp @@ -77,63 +77,63 @@ on transaction history operations. .SH OPTIONS .INDENT 0.0 .TP -\fB\-a\fP \fIVALUE\fP | \fB––amount=\fP\fIVALUE\fP +\fB\-a\fP \fIVALUE\fP | \fB–amount=\fP\fIVALUE\fP Amount to transfer. Given in the Taler\-typical format of CURRENCY:VALUE.FRACTION. .TP -\fB\-b\fP \fIURL\fP | \fB––bank=\fP\fIURL\fP +\fB\-b\fP \fIURL\fP | \fB–bank=\fP\fIURL\fP URL at which the bank is operation. Conflicts with \fB\-s\fP\&. .TP -\fB\-C\fP \fIACCOUNT\fP | \fB––credit=\fP\fIACCOUNT\fP +\fB\-C\fP \fIACCOUNT\fP | \fB–credit=\fP\fIACCOUNT\fP When doing a wire transfer from the exchange, the money should be credited to \fIACCOUNT\fP\&. Specifies the payto:// URI of the account. Can also be used as a filter by credit account when looking at transaction histories. .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the given configuration file. .TP -\fB\-D\fP \fIACCOUNT\fP | \fB––debit=\fP\fIACCOUNT\fP +\fB\-D\fP \fIACCOUNT\fP | \fB–debit=\fP\fIACCOUNT\fP When doing a wire transfer to the exchange, the \fIACCOUNT\fP is to be debited. Specifies the payto:// URI of the account. Can also be used as a filter by debit account when looking at transaction histories. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––credit\-history\fP +\fB\-i\fP | \fB–credit\-history\fP Obtain credit history of the exchange. Conflicts with \fB\-o\fP\&. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-o\fP | \fB––debit\-history\fP +\fB\-o\fP | \fB–debit\-history\fP Obtain debit history of the exchange. Conflicts with \fB\-i\fP\&. .TP -\fB\-p\fP \fIPASSPHRASE\fP | \fB––pass=\fP\fIPASSPHRASE\fP +\fB\-p\fP \fIPASSPHRASE\fP | \fB–pass=\fP\fIPASSPHRASE\fP Specifies the pass phrase for authentication. Conflicts with \fB\-s\fP\&. .TP -\fB\-S\fP \fISUBJECT\fP | \fB––subject=\fP\fISUBJECT\fP +\fB\-S\fP \fISUBJECT\fP | \fB–subject=\fP\fISUBJECT\fP Use \fISUBJECT\fP for the wire transfer subject. Must be a reserve public key for credit operations and a wire transfer identifier for debit operations. If not specified, a random value will be generated instead. .TP -\fB\-s\fP \fIACCOUNT_SECTION\fP | \fB––section=\fP\fIACCOUNT\-SECTION\fP -Obtain exchange account information from the \fIACCOUNT\-SECTION\fP of the configuration. Conflicts with \fB\-u\fP, \fB\-p\fP and \fB\-b\fP\&. Note that either \fB\-b\fP or \fB\-s\fP must be specified. +\fB\-s\fP \fIACCOUNT_SECTION\fP | \fB–section=\fP\fIACCOUNT\-SECTION\fP +Obtain exchange account information from the \fIACCOUNT\-SECTION\fP of the configuration. The argument must be a \fB[exchange\-accountcredentials\-$NAME]\fP section name and thus start with the \fBexchange\-accountcredentials\-\fP prefix. Conflicts with \fB\-u\fP, \fB\-p\fP and \fB\-b\fP\&. Note that either \fB\-b\fP or \fB\-s\fP must be specified. .TP -\fB\-u\fP \fIUSERNAME\fP | \fB––user=\fP\fIUSERNAME\fP +\fB\-u\fP \fIUSERNAME\fP | \fB–user=\fP\fIUSERNAME\fP Specifies the username for authentication. Optional and conflicts with \fB\-s\fP\&. If neither \fB\-u\fP nor \fB\-s\fP are used, we will attempt to talk to the bank without authentication. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .TP -\fB\-w\fP \fIROW\fP | \fB––since\-when=\fP\fIROW\fP +\fB\-w\fP \fIROW\fP | \fB–since\-when=\fP\fIROW\fP Specifies a \fIROW\fP from which the history should be obtained. If not given, the 10 youngest transactions are returned. .UNINDENT .SH SEE ALSO .sp -taler\-bank\-manage(1), taler.conf(5), \fI\%https://docs.taler.net/core/api\-wire.html#wire\-transfer\-test\-apis\fP +taler.conf(5), \fI\%https://docs.taler.net/core/api\-wire.html#wire\-transfer\-test\-apis\fP .SH BUGS .sp Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic @@ -141,6 +141,6 @@ mail to <\fI\%taler@gnu.org\fP> .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-exchange-wirewatch.1 b/man/taler-exchange-wirewatch.1 index 281dd348..414cfb86 100644 --- a/man/taler-exchange-wirewatch.1 +++ b/man/taler-exchange-wirewatch.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-WIREWATCH" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-wirewatch \- watch for incoming wire transfers . .nr rst2man-indent-level 0 . @@ -30,17 +27,21 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-EXCHANGE-WIREWATCH" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-exchange-wirewatch \- watch for incoming wire transfers .SH SYNOPSIS .sp \fBtaler\-exchange\-wirewatch\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-r\fP\ |\ \fB––reset\fP] -[\fB\-T\fP\ |\ \fB––test\fP] -[\fB\-t\fP\ \fIPLUGINNAME\fP\ |\ \fB––type=\fP\fIPLUGINNAME\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-I**_|_\fP–ignore\-not\-found**] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-r\fP\ |\ \fB–reset\fP] +[\fB\-T\fP\ |\ \fB–test\fP] +[\fB\-t\fP\ \fIPLUGINNAME\fP\ |\ \fB–type=\fP\fIPLUGINNAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-exchange\-wirewatch\fP is a command\-line tool to import wire @@ -49,33 +50,40 @@ transactions into the Taler exchange database. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-f\fP \fIDELAY\fP| \fB–longpoll\-timeout=\fP\fIDELAY\fP +How long do we wait for a response for bank transactions from the bank. This is both the timeout for the long polling as well as the maximum frequency at which we would query the bank. Specified with unit (e.g. 30s, 1d, 2w), if no unit is given the number is interpreted in microseconds. Default is 60s. +.TP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-I\fP | \fB–ignore\-not\-found\fP +Do not fail if the bank says that the exchange bank account does not (yet) exist. +Keep trying. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-r\fP | \fB––reset\fP +\fB\-r\fP | \fB–reset\fP Ignore our own database and start with transactions from the beginning of time. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-t\fP | \fB––test\fP +\fB\-t\fP | \fB–test\fP Run in test mode and exit when idle. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -88,6 +96,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-fakebank-run.1 b/man/taler-fakebank-run.1 new file mode 100644 index 00000000..d10e2245 --- /dev/null +++ b/man/taler-fakebank-run.1 @@ -0,0 +1,91 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-FAKEBANK-RUN" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-fakebank-run \- run in-memory bank service for testing and benchmarking +.SH SYNOPSIS +.sp +\fBtaler\-fakebank\-run\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-n\fP\ \fIN\fP\ |\ \fB–num\-threads=\fP\fIN\fP] +[\fB\-s\fP\ \fIAMOUNT\fP\ |\ \fB–signup\-bonus=\fP\fIAMOUNT\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-fakebank\-run\fP is a command\-line tool to run a Taler “bank” API (HTTP REST service). The program is useful to provide the bank functionality for benchmarking or testing when LibEuFin is unavailable or otherwise unsuitable. +.sp +It should be noted that the fakebank will keep a configured number of transactions in memory. If the number of transactions exceeds the configured memory limit, the fakebank will simply discard and overwrite the old entries. At that point, any requests involving such overwritten transactions will fail. Users of the fakebank are responsible for ensuring that the transaction history kept in memory is long enough for the purpose the bank is used for. The default limit is 128k entries. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-C\fP | \fB–connection\-close\fP +Force each HTTP connection to be closed after each request (useful in +combination with \fB\-f\fP to avoid having to wait for nc to time out). +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from FILENAME. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-n\fP \fIN\fP | \fB–num\-threads=\fP\fIN\fP +Use \fIN\fP threads in the thread pool. +.TP +\fB\-s\fP \fIAMOUNT\fP | \fB–signup\-bonus=\fP\fIAMOUNT\fP +Credit newly registered accounts with a balance of \fIAMOUNT\fP\&. Unlike other banks, this initial balance will be created out of thin air and not via a wire transfer from some bank\-internal account. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-helper-auditor-aggregation.1 b/man/taler-helper-auditor-aggregation.1 index 960d1294..f27b2c2a 100644 --- a/man/taler-helper-auditor-aggregation.1 +++ b/man/taler-helper-auditor-aggregation.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-HELPER-AUDITOR-AGGREGATION" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-aggregation \- audit Taler exchange aggregation activity . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-HELPER-AUDITOR-AGGREGATION" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-aggregation \- audit Taler exchange aggregation activity .SH SYNOPSIS .sp \fBtaler\-helper\-auditor\-aggregation\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fBi\fP\ |\ \fB––internal\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIKEY\fP\ |\ \fB––exchange\-key=\fP\fIKEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-helper\-auditor\-aggregation\fP is a command\-line tool to @@ -51,32 +51,32 @@ FIXME: More detail. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Perform checks only applicable for exchange\-internal audits. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -89,6 +89,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-helper-auditor-coins.1 b/man/taler-helper-auditor-coins.1 index 7fd7b74b..1257b69d 100644 --- a/man/taler-helper-auditor-coins.1 +++ b/man/taler-helper-auditor-coins.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-HELPER-AUDITOR-COINS" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-coins \- audit Taler coin processing . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-HELPER-AUDITOR-COINS" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-coins \- audit Taler coin processing .SH SYNOPSIS .sp \fBtaler\-helper\-auditor\-coins\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fBi\fP\ |\ \fB––internal\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIKEY\fP\ |\ \fB––exchange\-key=\fP\fIKEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-helper\-auditor\-coins\fP is a command\-line tool to @@ -51,32 +51,32 @@ FIXME: More detail. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Perform checks only applicable for exchange\-internal audits. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -89,6 +89,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-helper-auditor-deposits.1 b/man/taler-helper-auditor-deposits.1 index ecf31a72..4922077f 100644 --- a/man/taler-helper-auditor-deposits.1 +++ b/man/taler-helper-auditor-deposits.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-HELPER-AUDITOR-DEPOSITS" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-deposits \- audit Taler exchange database for deposit confirmation consistency . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-HELPER-AUDITOR-DEPOSITS" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-deposits \- audit Taler exchange database for deposit confirmation consistency .SH SYNOPSIS .sp \fBtaler\-helper\-auditor\-deposits\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fBi\fP\ |\ \fB––internal\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIKEY\fP\ |\ \fB––exchange\-key=\fP\fIKEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-helper\-auditor\-deposits\fP is a command\-line tool to @@ -51,32 +51,32 @@ FIXME: More detail. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Perform checks only applicable for exchange\-internal audits. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -89,6 +89,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-helper-auditor-purses.1 b/man/taler-helper-auditor-purses.1 new file mode 100644 index 00000000..d97ec893 --- /dev/null +++ b/man/taler-helper-auditor-purses.1 @@ -0,0 +1,94 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-HELPER-AUDITOR-PURSES" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-purses \- audit Taler exchange purse handling +.SH SYNOPSIS +.sp +\fBtaler\-helper\-auditor\-purses\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-helper\-auditor\-purses\fP is a command\-line tool to +audit Taler exchange purse handling. +.sp +FIXME: More detail. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the auditor to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-i\fP | \fB–internal\fP +Perform checks only applicable for exchange\-internal audits. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP +Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-auditor(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-helper-auditor-reserves.1 b/man/taler-helper-auditor-reserves.1 index a2261792..98c94584 100644 --- a/man/taler-helper-auditor-reserves.1 +++ b/man/taler-helper-auditor-reserves.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-HELPER-AUDITOR-RESERVES" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-reserves \- audit Taler exchange reserve handling . .nr rst2man-indent-level 0 . @@ -30,17 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-HELPER-AUDITOR-RESERVES" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-reserves \- audit Taler exchange reserve handling .SH SYNOPSIS .sp \fBtaler\-helper\-auditor\-reserves\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fBi\fP\ |\ \fB––internal\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIKEY\fP\ |\ \fB––exchange\-key=\fP\fIKEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-helper\-auditor\-reserves\fP is a command\-line tool to @@ -51,32 +51,32 @@ FIXME: More detail. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Perform checks only applicable for exchange\-internal audits. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -89,6 +89,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-helper-auditor-wire.1 b/man/taler-helper-auditor-wire.1 index f3c71569..d90d3279 100644 --- a/man/taler-helper-auditor-wire.1 +++ b/man/taler-helper-auditor-wire.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-HELPER-AUDITOR-WIRE" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-wire \- audit exchange database for consistency with the bank's wire transfers . .nr rst2man-indent-level 0 . @@ -30,53 +27,56 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-HELPER-AUDITOR-WIRE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-helper-auditor-wire \- audit exchange database for consistency with the bank's wire transfers .SH SYNOPSIS .sp \fBtaler\-helper\-auditor\-wire\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fBi\fP\ |\ \fB––internal\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIKEY\fP\ |\ \fB––exchange\-key=\fP\fIKEY\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel=\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fBi\fP\ |\ \fB–internal\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-m\fP\ \fIKEY\fP\ |\ \fB–exchange\-key=\fP\fIKEY\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel=\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-helper\-auditor\-wire\fP is a command\-line tool to -audit exchange database for consistency with the bank\(aqs wire transfers. +audit exchange database for consistency with the bank’s wire transfers. .sp FIXME: More detail. .sp Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the auditor to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-i\fP | \fB––internal\fP +\fB\-i\fP | \fB–internal\fP Perform checks only applicable for exchange\-internal audits. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-m\fP \fIKEY\fP | \fB––exchange\-key=\fP\fIKEY\fP +\fB\-m\fP \fIKEY\fP | \fB–exchange\-key=\fP\fIKEY\fP Use \fIKEY\fP (Crockford base32 encoded) as the public key of the exchange. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO @@ -89,6 +89,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-mdb.1 b/man/taler-mdb.1 new file mode 100644 index 00000000..91b7cb4c --- /dev/null +++ b/man/taler-mdb.1 @@ -0,0 +1,92 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MDB" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-mdb \- operate multi drop bus (MDB) based vending machines with Taler payments +.SH SYNOPSIS +.sp +\fBtaler\-mdb\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-d\fP\ |\ \fB–disable\-mdb\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-i\fP\ |\ \fB–backlight\-invert\fP] +[\fB\-L\fP _*LOGLEVEL*\ |\ \fB–log=\fP\fILOGLEVEL\fP] +[\fB\-l\fP _*FILENAME*\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-s\fP\ |\ \fB–enable\-soldout\fP] +[\fB\-t\fP\ |\ \fB–disable\-tty\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-mdb\fP is a command\-line tool to operate a vending machine using GNU Taler for payments. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the Sync commands +to operate from \fIFILENAME\fP\&. +.TP +\fB\-d\fP | \fB–disable\-mdb\fP +Disable interaction with the MDB bus (for testing). +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-i\fP | \fB–backlight\-invert\fP +Invert the bit for turning on/off the backlight. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–log=\fP\fILOGLEVEL\fP +Configure logging to use \fILOGLEVEL\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Configure logging to write logs to \fIFILENAME\fP\&. +.TP +\fB\-s\fP | \fB–enable\-soldout\fP +When the machine fails to dispense a product, internally set the product to “sold out” and refuse future orders until restarted. +.TP +\fB\-t\fP | \fB–disable\-tty\fP +Disable interactive command\-line use. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-benchmark.1 b/man/taler-merchant-benchmark.1 index 70f4f8bb..a43632f8 100644 --- a/man/taler-merchant-benchmark.1 +++ b/man/taler-merchant-benchmark.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-MERCHANT-BENCHMARK" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-benchmark \- generate Taler-style benchmarking payments . .nr rst2man-indent-level 0 . @@ -30,6 +27,9 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-MERCHANT-BENCHMARK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-benchmark \- generate Taler-style benchmarking payments .SH SYNOPSIS .sp \fBtaler\-merchant\-benchmark\fP [\fIsubcommand\fP] [\fIoptions\fP] @@ -43,27 +43,24 @@ merchant database with payments for benchmarking. .B ordinary Generate normal payments: all the payments are performed (by the default instance) and aggregated by the exchange. Takes the following -options. +option: .INDENT 7.0 .TP -\fB\-p\fP \fIPN\fP | \fB––payments\-number=\fP\fIPN\fP +\fB\-p\fP \fIPN\fP | \fB–payments\-number=\fP\fIPN\fP Perform PN many payments, defaults to 1. -.TP -\fB\-t\fP \fITN\fP | \fB––tracks\-number=\fP\fITN\fP -Perform TN many tracking operations, defaults to 1. .UNINDENT .TP .B corner Drive the generator to create unusual situations, like for example leaving payments unaggregated, or using a non\-default merchant -instance. Takes the following options. +instance. Takes the following options: .INDENT 7.0 .TP -\fB\-t\fP \fITC\fP | \fB––two\-coins=\fP\fITC\fP +\fB\-t\fP \fITC\fP | \fB–two\-coins=\fP\fITC\fP Perform TC many payments that use two coins (normally, all the payments use only one coin). TC defaults to 1. .TP -\fB\-u\fP \fIUN\fP | \fB––unaggregated\-number=\fP\fIUN\fP +\fB\-u\fP \fIUN\fP | \fB–unaggregated\-number=\fP\fIUN\fP Generate UN payments that will be left unaggregated. Note that subsequent invocations of the generator may pick those unaggregated payments and actually aggregated them. @@ -72,33 +69,32 @@ unaggregated payments and actually aggregated them. .SH COMMON OPTIONS .INDENT 0.0 .TP -\fB\-a\fP \fIAPIKEY\fP | \fB\-\-apikey=\fP\fIAPIKEY\fP -HTTP \(aqAuthorization\(aq header to send to the merchant. +\fB\-a\fP \fIAPIKEY\fP | \fB–apikey=\fP\fIAPIKEY\fP +HTTP ‘Authorization’ header to send to the merchant. .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from FILENAME. .TP -\fB\-e\fP \fISECTION\fP | \fB\-\-exchange\-account=\fP\fISECTION\fP -Mandatory. +\fB\-u\fP \fISECTION\fP | \fB–exchange\-account\-section=\fP\fISECTION\fP Configuration \fISECTION\fP specifying the exchange account to use. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SEE ALSO .sp -taler\-merchant\-dbinit(1), taler\-merchant\-tip\-enable(1), taler.conf(5) +taler\-merchant\-dbinit(1), taler.conf(5) .SH BUGS .sp Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic @@ -106,6 +102,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-merchant-dbconfig.1 b/man/taler-merchant-dbconfig.1 new file mode 100644 index 00000000..82d7dc2c --- /dev/null +++ b/man/taler-merchant-dbconfig.1 @@ -0,0 +1,83 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-DBCONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-dbconfig \- configure Taler merchant database +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-dbconfig\fP +[\fB\-c\fP\ \fIFILENAME\fP] +[\fB\-h\fP] +[\fB\-n\fP\ \fINAME\fP] +[\fB\-r\fP] +[\fB\-s\fP] +[\fB\-u\fP\ \fIUSER\fP] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-dbconfig\fP is a simple shell script that configures +a Postgresql database for use by the GNU Taler merchant. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP +Write the database configuration to FILENAME. The tool +will append the required \fBCONFIG\fP option for the +Postgresql access to the respective file. +.TP +\fB\-h\fP +Print short help on options. +.TP +\fB\-n\fP \fIDBNAME\fP +Use DBNAME for the name of the created database. +.TP +\fB\-r\fP +Reset any existing database. Looses all existing data. DANGEROUS. +.TP +\fB\-s\fP +Skip database initialization. Useful if you want to run +\fBtaler\-merchant\-dbinit\fP manually. +.TP +\fB\-u\fP \fIUSER\fP +Specifies the (main) merchant user that will access the database. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-dbinit(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-dbinit.1 b/man/taler-merchant-dbinit.1 index b0bd2761..c2897053 100644 --- a/man/taler-merchant-dbinit.1 +++ b/man/taler-merchant-dbinit.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-MERCHANT-DBINIT" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-dbinit \- initialize Taler merchant database . .nr rst2man-indent-level 0 . @@ -30,15 +27,18 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-MERCHANT-DBINIT" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-dbinit \- initialize Taler merchant database .SH SYNOPSIS .sp \fBtaler\-merchant\-dbinit\fP -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-r\fP\ |\ \fB––reset\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-r\fP\ |\ \fB–reset\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-merchant\-dbinit\fP is a command\-line tool to initialize the Taler @@ -48,21 +48,21 @@ Taler merchant to operate. Its options are as follows: .INDENT 0.0 .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from \fIFILENAME\fP\&. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-r\fP | \fB––reset\fP +\fB\-r\fP | \fB–reset\fP Drop tables. Dangerous, will delete all existing data in the database before creating the tables. .TP @@ -79,6 +79,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-merchant-depositcheck.1 b/man/taler-merchant-depositcheck.1 new file mode 100644 index 00000000..46d2ae10 --- /dev/null +++ b/man/taler-merchant-depositcheck.1 @@ -0,0 +1,100 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-DEPOSITCHECK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-depositcheck \- check status of deposits with exchange +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-depositcheck\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-e\fP \fIBASE_URL\fP\ |\ \fB–exchange=\fP\fIBASE_URL\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-depositcheck\fP is a command\-line tool to inquire with exchanges about whether they completed +bank transfers in response to deposits made by the +merchant backend. This will allow the merchant backend to detect deposit issues, for example if a KYC is blocking +a wire transfer. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-e\fP \fIBASE_URL\fP | \fB–exchange=\fP\fIBASE_URL\fP +Base URL of the exchange to monitor. If not given, a worker process will be spawned for each exchange in the configuration (“merchant\-exchange\-” sections). +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-s\fP \fISECTION\fP | \fB–section=\fP\fISECTION\fP +Configuration section to use. Default is taler\-merchant\-depositcheck. Needed +if different processes are used to watch multiple bank accounts (for the +same instance or different instances). +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode. Only runs until the current list of bank +transactions are all imported. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-exchange.1 b/man/taler-merchant-exchange.1 new file mode 100644 index 00000000..ab138da0 --- /dev/null +++ b/man/taler-merchant-exchange.1 @@ -0,0 +1,95 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-EXCHANGE" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-exchange \- ask exchange which deposits were aggregated for a particular wire transfer that credited a merchant account +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-exchange\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-exchange\fP is a background job that reconciles +wire transfers that credit the merchant’s bank account with +the respective contracts that have been paid by asking the +exchange to provide a list of all deposits that were aggregated +into a wire transfer. +.sp +The tool is part of a set of processes that allow a merchant backend to +validate that the exchange paid the merchant correctly. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode. Only runs until the current list of bank +transactions have all been checked. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-depositcheck(1), taler\-merchant\-wirewatch(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-httpd.1 b/man/taler-merchant-httpd.1 index d0cf9cce..34865889 100644 --- a/man/taler-merchant-httpd.1 +++ b/man/taler-merchant-httpd.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-MERCHANT-HTTPD" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-httpd \- run Taler merchant backend (with RESTful API) . .nr rst2man-indent-level 0 . @@ -30,16 +27,20 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER-MERCHANT-HTTPD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-httpd \- run Taler merchant backend (with RESTful API) .SH SYNOPSIS .sp \fBtaler\-merchant\-httpd\fP -[\fB\-C\fP\ |\ \fB––connection\-close\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB––timetravel\fP\fIUSEC\fP] -[\fB\-v\fP\ |\ \fB––version\fP] +[\fB\-a**_|_\fP–auth**] +[\fB\-C\fP\ |\ \fB–connection\-close\fP] +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-v\fP\ |\ \fB–version\fP] .SH DESCRIPTION .sp \fBtaler\-merchant\-httpd\fP is a command\-line tool to run the Taler merchant @@ -48,44 +49,44 @@ before running this command. .SH OPTIONS .INDENT 0.0 .TP -\fB\-a\fP \fITOKEN\fP | \fB––auth=\fP\fITOKEN\fP -Use TOKEN for initial access control to the merchant backend. The value +\fB\-a\fP \fITOKEN\fP | \fB–auth=\fP\fITOKEN\fP +Use TOKEN for initial access control to the merchant backend. TOKEN must start with the “secret\-token:” prefix, as per RFC 8959. The value given in TOKEN must appear in backoffice requests to the default instance -of the merchant, i.e. "Authorization: secret\-token:TOKEN" to obtain +of the merchant, i.e. “Authorization: Bearer TOKEN” to obtain access to the merchant backend. Note that setting a passphrase for the default instance by any means will block future access via TOKEN. This is basically a way to reset the passphrase protecting access. TOKEN -should be a "pchar" as per RFC 8959, but this is NOT checked. Note that -TOKEN will only grant access to the \(aqdefault\(aq instance, not other instances. +should be a “pchar” as per RFC 8959, but this is NOT checked. Note that +TOKEN will only grant access to the ‘default’ instance, not other instances. Instead of using the command\-line, which exposes TOKEN to users on the system, you may want to consider setting the TALER_MERCHANT_TOKEN environment variable instead. .TP -\fB\-C\fP | \fB––connection\-close\fP +\fB\-C\fP | \fB–connection\-close\fP Force each HTTP connection to be closed after each request (useful in combination with \-f to avoid having to wait for nc to time out). .TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP Use the configuration and other resources for the merchant to operate from FILENAME. .TP -\fB\-h\fP | \fB––help\fP +\fB\-h\fP | \fB–help\fP Print short help on options. .TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. .TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP Send logging output to \fIFILENAME\fP\&. .TP -\fB\-T\fP \fIUSEC\fP | \fB––timetravel=\fP\fIUSEC\fP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP Modify the system time by \fIUSEC\fP microseconds. \fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). This option is intended for debugging/testing only. .TP -\fB\-v\fP | \fB––version\fP +\fB\-v\fP | \fB–version\fP Print version information. .UNINDENT .SH SIGNALS @@ -99,12 +100,12 @@ cleanly. .INDENT 0.0 .TP .B TALER_MERCHANT_TOKEN -Like the "\-a" option, resets the access token for the default +Like the “\-a” option, resets the access token for the default instance to the given value. .UNINDENT .SH SEE ALSO .sp -taler\-merchant\-dbinit(1), taler\-merchant\-tip\-enable(1), taler.conf(5) +taler\-merchant\-dbinit(1), taler\-merchant\-setup\-reserve(1), taler.conf(5) .SH BUGS .sp Report bugs by using Mantis \fI\%https://bugs.taler.net/\fP or by sending @@ -112,6 +113,6 @@ electronic mail to <\fI\%taler@gnu.org\fP> .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/man/taler-merchant-passwd.1 b/man/taler-merchant-passwd.1 new file mode 100644 index 00000000..7772cf9e --- /dev/null +++ b/man/taler-merchant-passwd.1 @@ -0,0 +1,86 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-PASSWD" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-passwd \- change Taler merchant instance password +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-passwd\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-i**_*NAME*\ |\ **–instance\fP\fINAME\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +[PASSWORD] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-passwd\fP is a command\-line tool to reset passwords +of existing Taler instances. The password must either be specified +as the last command\-line argument or in the TALER_MERCHANT_PASSWORD +environment variable. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-i\fP \fINAME\fP | \fB–instance\fP\fINAME\fP +Specifies the name of the instance for which the password should be +updated. If not given, the “default” instance is modified. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-setup-reserve.1 b/man/taler-merchant-setup-reserve.1 deleted file mode 100644 index 5f4892c1..00000000 --- a/man/taler-merchant-setup-reserve.1 +++ /dev/null @@ -1,134 +0,0 @@ -.\" Man page generated from reStructuredText. -. -.TH "TALER-MERCHANT-SETUP-RESERVE" "1" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-setup-reserve \- setup reserve for tipping at a Taler merchant backend -. -.nr rst2man-indent-level 0 -. -.de1 rstReportMargin -\\$1 \\n[an-margin] -level \\n[rst2man-indent-level] -level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] -- -\\n[rst2man-indent0] -\\n[rst2man-indent1] -\\n[rst2man-indent2] -.. -.de1 INDENT -.\" .rstReportMargin pre: -. RS \\$1 -. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] -. nr rst2man-indent-level +1 -.\" .rstReportMargin post: -.. -.de UNINDENT -. RE -.\" indent \\n[an-margin] -.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] -.nr rst2man-indent-level -1 -.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] -.in \\n[rst2man-indent\\n[rst2man-indent-level]]u -.. -.SH SYNOPSIS -.sp -\fBtaler\-merchant\-setup\-reserve\fP -[\fB\-A\fP\ \fIUSERNAME:PASSWORD\fP\ |\ \fB––auth=\fP\fIUSERNAME:PASSWORD\fP] -[\fB\-a\fP\ \fIVALUE\fP\ |\ \fB––amount=\fP\fIVALUE\fP] -[\fB\-C\fP\ \fICERTFILE\fP\ |\ \fB––cert=\fP\fICERTFILE\fP] -[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB––config=\fP\fIFILENAME\fP] -[\fB\-e\fP\ \fIURL\fP\ |\ \fB––exchange\-url=\fP\fIURL\fP] -[\fB\-h\fP\ |\ \fB––help\fP] -[\fB\-k\fP\ \fIKEYFILE\fP\ |\ \fB––key=\fP\fIKEYFILE\fP] -[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB––loglevel=\fP\fILOGLEVEL\fP] -[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB––logfile=\fP\fIFILENAME\fP] -[\fB\-m\fP\ \fIURL\fP\ |\ \fB––merchant\-url=\fP\fIURL\fP] -[\fB\-p\fP\ \fIKEYFILEPASSPHRASE\fP\ |\ \fB––pass=\fP\fIKEYFILEPASSPHRASE\fP] -[\fB\-t\fP\ \fICERTTYPE\fP\ |\ \fB––type=\fP\fICERTTYPE\fP] -[\fB\-w\fP\ \fIMETHOD\fP\ |\ \fB––wire\-method=\fP\fIMETHOD\fP] -[\fB\-v\fP\ |\ \fB––version\fP] -.SH DESCRIPTION -.sp -\fBtaler\-merchant\-setup\-reserve\fP is a command\-line tool to setup a reserve -(creating the private reserve key) and obtaining the wire transfer information -from the exchange needed to fill the reserve. -.SH OPTIONS -.INDENT 0.0 -.TP -\fB\-A\fP \fIUSERNAME:PASSWORD\fP | \fB––auth=\fP\fIUSERNAME:PASSWORD\fP -Use \fBUSERNAME\fP and \fBPASSWORD\fP for HTTP client authentication. -The ":" must be present as a separator. -Note that this form of authentication has nothing to do with the TLS client -certificate authentication supported with the \fB\-C\fP, \fB\-k\fP and \fB\-p\fP options. -The \fBPASSWORD\fP given to this option is given to the server! -.TP -\fB\-a\fP \fIVALUE\fP | \fB––amount=\fP\fIVALUE\fP -Mandatory. -Amount to be transferred to the reserve. -.TP -\fB\-C\fP \fICERTFILE\fP | \fB––cert=\fP\fICERTFILE\fP -The specified \fBCERTFILE\fP contains a TLS client certificate to be used to -authenticate the client. See also \fB\-t\fP\&. -.TP -\fB\-c\fP \fIFILENAME\fP | \fB––config=\fP\fIFILENAME\fP -Use the configuration and other resources for the merchant to -operate from \fBFILENAME\fP\&. -.TP -\fB\-e\fP \fIURL\fP | \fB––exchange\-url=\fP\fIURL\fP -Mandatory. -Use \fBURL\fP for the exchange base URL. -This is the exchange where the reserve will be created. -The currency used in the amount specification must be offered by this exchange. -.TP -\fB\-h\fP | \fB––help\fP -Print short help on options. -.TP -\fB\-k\fP \fIKEYFILE\fP | \fB––key=\fP\fIKEYFILE\fP -The specified \fBKEYFILE\fP contains a TLS client private key to be used to -authenticate the client. See also \fB\-p\fP and \fB\-C\fP\&. -.TP -\fB\-L\fP \fILOGLEVEL\fP | \fB––loglevel=\fP\fILOGLEVEL\fP -Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, -\fBWARNING\fP, \fBERROR\fP\&. -.TP -\fB\-l\fP \fIFILENAME\fP | \fB––logfile=\fP\fIFILENAME\fP -Send logging output to \fIFILENAME\fP\&. -.TP -\fB\-m\fP \fIURL\fP | \fB––merchant\-url=\fP\fIURL\fP -Mandatory. -Use \fBURL\fP as the merchant base URL. -Should include the path to the instance if the reserve is to be -created for a non\-default instance. -.TP -\fB\-p\fP \fIKEYFILEPASSPHRASE\fP | \fB––pass=\fP\fIKEYFILEPASSPHRASE\fP -The specified \fBKEYFILEPASSPHRASE\fP is to be used to decrypt the KEYFILE. -See also \fB\-k\fP\&. Not to be confused with \fB\-A\fP\&. -The \fBKEYFILEPASSPHRASE\fP given here is only used locally to decrypt the KEYFILE. -.TP -\fB\-t\fP \fICERTTYPE\fP | \fB––type=\fP\fICERTTYPE\fP -The specified CERTFILE contains a TLS client certificate of \fBCERTTYPE\fP\&. -Default is \fBPEM\fP\&. See also \fB\-C\fP\&. -.TP -\fB\-w\fP \fIMETHOD\fP | \fB––wire\-method=\fP\fIMETHOD\fP -Mandatory. -Which wire method should be used. -Needed to select the wire transfer method of the exchange. -The method must be supported by the exchange. -Typical values would be \fBiban\fP or \fBx\-taler\-bank\fP\&. -.TP -\fB\-v\fP | \fB––version\fP -Print version information. -.UNINDENT -.SH SEE ALSO -.sp -taler\-merchant\-dbinit(1), taler.conf(5) -.SH BUGS -.sp -Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic -mail to <\fI\%taler@gnu.org\fP>. -.SH AUTHOR -GNU Taler contributors -.SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) -.\" Generated by docutils manpage writer. -. diff --git a/man/taler-merchant-webhook.1 b/man/taler-merchant-webhook.1 new file mode 100644 index 00000000..4fe1ba92 --- /dev/null +++ b/man/taler-merchant-webhook.1 @@ -0,0 +1,90 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-WEBHOOK" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-webhook \- execute webhooks of the Taler merchant backend (optional service) +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-webhook\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-webhook\fP is a command\-line tool to trigger webhooks +scheduled by a Taler merchant backend. It makes the necessary HTTP +requests and updates the Taler merchant database accordingly. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode. Only runs until there are no more webhooks +to be executed. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-merchant-wirewatch.1 b/man/taler-merchant-wirewatch.1 new file mode 100644 index 00000000..434061ba --- /dev/null +++ b/man/taler-merchant-wirewatch.1 @@ -0,0 +1,100 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-MERCHANT-WIREWATCH" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-merchant-wirewatch \- import credit transactions from a merchant bank account into merchant backend (optional) +.SH SYNOPSIS +.sp +\fBtaler\-merchant\-wirewatch\fP +[\fB\-c\fP\ \fIFILENAME\fP\ |\ \fB–config=\fP\fIFILENAME\fP] +[\fB\-h\fP\ |\ \fB–help\fP] +[\fB\-L\fP\ \fILOGLEVEL\fP\ |\ \fB–loglevel=\fP\fILOGLEVEL\fP] +[\fB\-l\fP\ \fIFILENAME\fP\ |\ \fB–logfile=\fP\fIFILENAME\fP] +[\fB\-p\fP\ |\ \fB–persist\fP] +[\fB\-T\fP\ \fIUSEC\fP\ |\ \fB–timetravel\fP\fIUSEC\fP] +[\fB\-t\fP\ |\ \fB–test\fP] +[\fB\-v\fP\ |\ \fB–version\fP] +.SH DESCRIPTION +.sp +\fBtaler\-merchant\-wirewatch\fP is a command\-line tool to import +information about incoming bank transfers into a Taler merchant +backend. This will allow the merchant backend to validate that +the exchange paid the merchant correctly. +.sp +Its options are as follows: +.INDENT 0.0 +.TP +\fB\-c\fP \fIFILENAME\fP | \fB–config=\fP\fIFILENAME\fP +Use the configuration and other resources for the merchant to operate +from \fIFILENAME\fP\&. +.TP +\fB\-h\fP | \fB–help\fP +Print short help on options. +.TP +\fB\-L\fP \fILOGLEVEL\fP | \fB–loglevel=\fP\fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-l\fP \fIFILENAME\fP | \fB–logfile=\fP\fIFILENAME\fP +Send logging output to \fIFILENAME\fP\&. +.TP +\fB\-p\fP | \fB–persist\fP +Run in persist mode. Does not exit when the account configuration changes. Useful when not running under systemd. +.TP +\fB\-s\fP \fISECTION\fP | \fB–section=\fP\fISECTION\fP +Configuration section to use. Default is taler\-merchant\-wirewatch. Needed +if different processes are used to watch multiple bank accounts (for the +same instance or different instances). +.TP +\fB\-T\fP \fIUSEC\fP | \fB–timetravel=\fP\fIUSEC\fP +Modify the system time by \fIUSEC\fP microseconds. +\fIUSEC\fP may be prefixed with \fB+\fP or \fB\-\fP (e.g. \fB\-T +300\fP). +This option is intended for debugging/testing only. +.TP +\fB\-t\fP | \fB–test\fP +Run in test mode. Only runs until the current list of bank +transactions are all imported. +.TP +\fB\-v\fP | \fB–version\fP +Print version information. +.UNINDENT +.SH SEE ALSO +.sp +taler\-merchant\-httpd(1), taler.conf(5). +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-terms-generator.1 b/man/taler-terms-generator.1 new file mode 100644 index 00000000..1fa588b1 --- /dev/null +++ b/man/taler-terms-generator.1 @@ -0,0 +1,91 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-TERMS-GENERATOR" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-terms-generator \- create legal policy documents for services +.SH SYNOPSIS +.sp +\fBtaler\-terms\-generator\fP +[\fB\-a\fP\ \fIAUTHOR\fP] +[\fB\-C\fP\ \fICOPYRIGHT\fP] +[\fB\-h\fP] +[\fB\-i\fP\ \fIINPUT\fP] +[\fB\-l\fP\ \fILANGUAGE\fP] +[\fB\-o\fP\ \fIOUTPUT\fP] +[\fB\-p\fP\ \fIPAPER\fP] +[\fB\-t\fP\ \fITITLE\fP] +.SH DESCRIPTION +.INDENT 0.0 +.TP +\fBtaler\-terms\-generator\fP is a command\-line tool to create terms of service +and privacy policy files in various file formats and languages from a +reStructuredText (“.rst”) input. It can be used to generate the responses +various GNU Taler services serve under the \fB/terms\fP and \fB/pp\fP endpoints. +.TP +\fB\-a\fP \fIAUTHOR\fP +set the author information to the given AUTHOR in the meta\-data of various generated outputs. +.TP +\fB\-C\fP \fICOPYRIGHT\fP +set the copyright information to the given COPYRIGHT in the meta\-data of various generated outputs. +.TP +\fB\-h\fP | \fB–help\fP +Prints a compiled\-in help text. +.TP +\fB\-i\fP \fIINPUT\fP +Name of the input (.rst) file with the terms of service or privacy policy to convert. +.TP +\fB\-l\fP \fILANGUAGE\fP +Add the given \fILANGUAGE\fP to the list of translations for the current \fIINPUT\fP\&. \fILANGUAGE\fP must be a two\-letter language code (like “de” or “it”). This will generate or update the respective “.po” files to translate the \fIINPUT\fP terms to this \fILANGUAGE\fP\&. +.TP +\fB\-L\fP \fILOCALE_DIR\fP +Specify locale/ directory where GNU gettext resources for translating the input are located. If “\-l” is given, this directory is where fresh or updated “.po” files will be placed, and otherwise this directory will be scanned for translations of the “.rst” input file. +.TP +\fB\-o\fP \fIOUTPUT\fP +Specifies where to write the output. This should be the directory where the service expects to find the generated resources. Unless you changed the default configuration, you probably do not have to specify this value. +.TP +\fB\-p\fP \fIPAPER\fP +Specifies the paper format for generated PDF documents. Can be “a4” or “letter”. +.TP +\fB\-t\fP \fITITLE\fP +Overrides the document title. By default, the title will be set to the contents of the first line of the \fIINPUT\fP “.rst” file. +.UNINDENT +.SH SEE ALSO +.sp +taler\-config(1), taler.conf(5) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler-unified-setup.1 b/man/taler-unified-setup.1 new file mode 100644 index 00000000..ff6f7d77 --- /dev/null +++ b/man/taler-unified-setup.1 @@ -0,0 +1,129 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TALER-UNIFIED-SETUP" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-unified-setup \- conveniently start and stop various GNU Taler services +.SH SYNOPSIS +.sp +\fBtaler\-unified\-setup\fP +[\fB\-a\fP] +[\fB\-b\fP] +[\fB\-c\fP\ \fICONFIG_FILENAME\fP] +[\fB\-d\fP\ \fIMETHOD\fP] +[\fB\-e\fP] +[\fB\-f\fP] +[\fB\-h\fP] +[\fB\-k\fP] +[\fB\-l\fP\ \fIFILENAME\fP] +[\fB\-m\fP] +[\fB\-n\fP] +[\fB\-r\fP\ \fIMEX\fP] +[\fB\-s\fP] +[\fB\-t\fP] +[\fB\-u\fP\ \fISECTION\fP] +[\fB\-v\fP] +[\fB\-w\fP] +.SH DESCRIPTION +.sp +\fBtaler\-unified\-setup\fP is a command\-line tool to launch and stop +GNU Taler services in bulk. It is usually used in test cases or +for development. For production, services should be launched via +systemd and not via this tool. +.INDENT 0.0 +.TP +\fB\-a\fP +Start auditor +.TP +\fB\-b\fP +Start backup/sync service +.TP +\fB\-c\fP \fICONFIG_FILENAME\fP +(Mandatory) Use CONFIG_FILENAME. +.TP +\fB\-d\fP \fIMETHOD\fP +use the given wire method. Default is ‘x\-taler\-bank’. +.TP +\fB\-e\fP +Start exchange +.TP +\fB\-f\fP +Start fakebank +.TP +\fB\-g\fP +Start aggregator +.TP +\fB\-h\fP | \fB–help\fP +Prints a compiled\-in help text. +.TP +\fB\-k\fP +Start challenger (KYC service) +.TP +\fB\-L\fP \fILOGLEVEL\fP +Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, +\fBWARNING\fP, \fBERROR\fP\&. +.TP +\fB\-m\fP +Start merchant +.TP +\fB\-n\fP +Start libeufin nexus +.TP +\fB\-r\fP \fIMEX\fP +Which exchange to use at the merchant +.TP +\fB\-s\fP +Start libeufin sandbox +.TP +\fB\-t\fP +Start taler\-exchange\-transfer +.TP +\fB\-u\fP \fISECTION\fP +Specifies configuration section with the exchange account to use +.TP +\fB\-v\fP +Use valgrind +.TP +\fB\-w\fP +Start taler\-exchange\-wirewatch +.UNINDENT +.SH SEE ALSO +.sp +taler\-exchange\-dbinit(1), taler\-exchange\-offline(1), taler\-merchant\-benchmark(1), +taler\-exchange\-httpd(1), taler.conf(5) +.SH BUGS +.sp +Report bugs by using \fI\%https://bugs.taler.net/\fP or by sending electronic +mail to <\fI\%taler@gnu.org\fP>. +.SH AUTHOR +GNU Taler contributors +.SH COPYRIGHT +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +.\" Generated by docutils manpage writer. +. diff --git a/man/taler.conf.5 b/man/taler.conf.5 index b7dfca03..85856dd4 100644 --- a/man/taler.conf.5 +++ b/man/taler.conf.5 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER.CONF" "5" "Apr 28, 2021" "0.8" "GNU Taler" -.SH NAME -taler.conf \- Taler configuration file . .nr rst2man-indent-level 0 . @@ -30,40 +27,85 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. +.TH "TALER.CONF" "5" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler.conf \- Taler configuration file .SH DESCRIPTION .sp -The configuration file is line\-oriented. -Blank lines and whitespace at the beginning and end of a line are ignored. -Comments start with \fB#\fP or \fB%\fP in the first column -(after any beginning\-of\-line whitespace) and go to the end of the line. -.sp -The file is split into sections. -Every section begins with “[SECTIONNAME]” and -contains a number of options of the form “OPTION=VALUE”. -There may be whitespace around the \fB=\fP (equal sign). -Section names and options are \fIcase\-insensitive\fP\&. -.sp -The values, however, are \fIcase\-sensitive\fP\&. -In particular, boolean values are one of \fBYES\fP or \fBNO\fP\&. -Values can include whitespace by surrounding -the entire value with \fB"\fP (double quote). -Note, however, that there are no escape characters in such strings; -all characters between the double quotes (including other double quotes) -are taken verbatim. -.sp -Values that represent filenames can begin with a \fB/bin/sh\fP\-like -variable reference. -This can be simple, such as \fB$TMPDIR/foo\fP, or complex, -such as \fB${TMPDIR:\-${TMP:\-/tmp}}/foo\fP\&. -See \fB[PATHS]\fP (below). -.sp -Values that represent a time duration are represented as a series of one or -more \fBNUMBER UNIT\fP pairs, e.g. \fB60 s\fP, \fB4 weeks 1 day\fP, \fB5 years 2 minutes\fP\&. +The configuration file is line\-oriented. Blank lines and whitespace at the +beginning and end of a line are ignored. Comments start with \fB#\fP or \fB%\fP +in the first column (after any beginning\-of\-line whitespace) and go to the end +of the line. +.sp +The file is split into sections. Every section begins with \fB[SECTIONNAME]\fP +and contains a number of options of the form \fBOPTION=VALUE\fP\&. There may be +whitespace around the \fB=\fP (equal sign). Section names and options are +\fIcase\-insensitive\fP\&. +.sp +The values, however, are \fIcase\-sensitive\fP\&. In particular, boolean values are +one of \fBYES\fP or \fBNO\fP\&. Values can include whitespace by surrounding the +entire value with \fB\(dq\fP (double quote). Note, however, that there are no +escape characters in such strings; all characters between the double quotes +(including other double quotes) are taken verbatim. +.sp +Values that represent a time duration are represented as a series +of one or more \fBNUMBER UNIT\fP pairs, e.g. \fB60 s\fP, \fB4 weeks 1 day\fP, +\fB5 years 2 minutes\fP\&. .sp Values that represent an amount are in the usual amount syntax: \fBCURRENCY:VALUE.FRACTION\fP, e.g. \fBEUR:1.50\fP\&. The \fBFRACTION\fP portion may extend up to 8 places. .sp +Values that represent filenames can begin with a \fB/bin/sh\fP\-like variable +reference. This can be simple, such as \fB$TMPDIR/foo\fP, or complex, such as +\fB${TMPDIR:\-${TMP:\-/tmp}}/foo\fP\&. The variables are expanded either using +key\-values from the \fB[PATHS]\fP section (see below) or from the environment +(\fBgetenv()\fP). The values from \fB[PATHS]\fP take precedence over those from +the environment. If the variable name is found in neither \fB[PATHS]\fP nor the +environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if \fBFOO=$BAR\fP and \fBBAR=buzz\fP then the result is \fBFOO=buzz\fP\&. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if \fBBAR=$FOO\fP in the example above. +.sp +The \fB[PATHS]\fP section is special in that it contains paths that can be +referenced using \fB$\fP in other configuration values that specify +\fIfilenames\fP\&. Note that configuration options that are not specifically +retrieved by the application as \fIfilenames\fP will not see “$”\-expressions +expanded. To expand \fB$\fP\-expressions when using \fBtaler\-config\fP, you must pass +the \fB\-f\fP command\-line option. +.sp +The system automatically pre\-populates the \fB[PATHS]\fP section with a few values +at run\-time (in addition to the values that are in the actual configuration +file and automatically overwriting those values if they are present). +These automatically generated values refer to installation properties +from \fI\%GNU autoconf\fP\&. The +values are usually dependent on an \fBINSTALL_PREFIX\fP which is determined by +the \fB\-\-prefix\fP option given to configure. The canonical values are: +.INDENT 0.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ +.IP \(bu 2 +DOCDIR = $INSTALL_PREFIX/share/doc/taler/ +.IP \(bu 2 +ICONDIR = $INSTALL_PREFIX/share/icons/ +.IP \(bu 2 +LOCALEDIR = $INSTALL_PREFIX/share/locale/ +.IP \(bu 2 +PREFIX = $INSTALL_PREFIX/ +.IP \(bu 2 +BINDIR = $INSTALL_PREFIX/bin/ +.IP \(bu 2 +LIBDIR = $INSTALL_PREFIX/lib/taler/ +.IP \(bu 2 +DATADIR = $INSTALL_PREFIX/share/taler/ +.UNINDENT +.UNINDENT +.UNINDENT +.sp +Note that on some platforms, the given paths may differ depending +on how the system was compiled or installed, the above are just the +canonical locations of the various resources. These +automatically generated values are never written to disk. +.sp Files containing default values for many of the options described below are installed under \fB$TALER_PREFIX/share/taler/config.d/\fP\&. The configuration file given with \fB\-c\fP to Taler binaries @@ -72,15 +114,23 @@ overrides these defaults. A configuration file may include another, by using the \fB@INLINE@\fP directive, for example, in \fBmain.conf\fP, you could write \fB@INLINE@ sub.conf\fP to include the entirety of \fBsub.conf\fP at that point in \fBmain.conf\fP\&. -.. TODO: Document ‘taler\-config \-V’ in light of ‘@INLINE@’ in taler\-config(1). +.sp +Be extra careful when using \fBtaler\-config \-V VALUE\fP to change configuration +values: it will destroy all uses of \fB@INLINE@\fP and furthermore remove all +comments from the configuration file! .SS GLOBAL OPTIONS .sp The following options are from the “[taler]” section and used by -virtually all Taler components. +virtually all Taler components. Note: work is ongoing to obsolete +these options, but for now they are in use. .INDENT 0.0 .TP .B CURRENCY Name of the currency, e.g.\ “EUR” for Euro. +.TP +.B CURRENCY_ROUND_UNIT +Smallest amount in this currency that can be transferred using the +underlying RTGS. For example: “EUR:0.01” or “JPY:1”. .UNINDENT .sp The “[PATHS]” section is special in that it contains paths that can be @@ -108,6 +158,60 @@ Usually “${TALER_HOME}/.cache/taler/”. Where should Taler store system runtime data (like UNIX domain sockets). Usually “${TMP}/taler\-system\-runtime”. .UNINDENT +.SS CURRENCY SPECIFICATIONS +.sp +Sections with a name of the form “[currency\-$NAME]” (where “$NAME” could +be any unique string) are used to specify details about how currencies +should be handled (and in particularly rendered) by the user interface. +A detailed motivation for this section can be found in DD51. +Different components can have different rules for the same currency. For +example, a bank or merchant may decide to render Euros or Dollars with +always exactly two fractional decimals, while an Exchange for the same +currency may support additional decimals. The required options in each +currency specification section are: +.INDENT 0.0 +.TP +.B ENABLED +Set to YES or NO. If set to NO, the currency specification +section is ignored. Can be used to disable currencies or +select alternative sections for the same CODE with different +choices. +.TP +.B CODE +Code name for the currency. Can be at most 11 characters, +only the letters A\-Z are allowed. Primary way to identify +the currency in the protocol. +.TP +.B NAME +Long human\-readable name for the currency. No restrictions, +but should match the official name in English. +.TP +.B FRACTIONAL_INPUT_DIGITS +Number of fractional digits that users are allowed to enter +manually in the user interface. +.TP +.B FRACTIONAL_NORMAL_DIGITS +Number of fractional digits that will be rendered normally +(in terms of size and placement). Digits shown beyond this +number will typically be rendered smaller and raised (if +possible). +.TP +.B FRACTIONAL_TRAILING_ZERO_DIGITS +Number of fractional digits to pad rendered amounts with +even if these digits are all zero. For example, use 2 to +render 1 USD as $1.00. +.TP +.B ALT_UNIT_NAMES +JSON map determining how to encode very large or very tiny +amounts in this currency. Maps a base10 logarithm to the +respective currency symbol. Must include at least an +entry for 0 (currency unit). For example, use +{“0”:”€”} for Euros or “{“0”:”$”} for Dollars. You could +additionally use {“0”:”€”,”3”:”k€”} to render 3000 EUR +as 3k€. For BTC a typical map would be +{“0”:”BTC”,”\-3”:”mBTC”}, informing the UI to render small +amounts in milli\-Bitcoin (mBTC). +.UNINDENT .SS EXCHANGE OPTIONS .sp The following options are from the “[exchange]” section and used by most @@ -117,40 +221,97 @@ exchange tools. .B DB Plugin to use for the database, e.g.\ “postgres”. .TP +.B SERVE +Should the HTTP server listen on a UNIX domain socket (set option to “unix”) or on a TCP socket (set option to “tcp”)? +.TP +.B UNIXPATH +Path to listen on if we “SERVE” is set to “unix”. +.TP +.B UNIXPATH_MODE +Access permission mask to use for the “UNIXPATH”. +.TP .B PORT Port on which the HTTP server listens, e.g.\ 8080. .TP +.B BIND_TO +Hostname to which the exchange HTTP server should be bound to, e.g. “localhost”. +.TP .B MASTER_PUBLIC_KEY Crockford Base32\-encoded master public key, public version of the -exchange\(aqs long\-time offline signing key. +exchange’s long\-time offline signing key. This configuration option +is also used by the \fBauditor\fP to determine the public key of the +exchange which it is auditing. .TP -.B MASTER_PRIV_FILE -Location of the master private key on disk. Only used by tools that -can be run offline (as the master key is for offline signing). +.B AML_THRESHOLD +Largest amount in this currency that can be transferred per month without +an AML staff member doing a (manual) AML check. For example: “USD:1000000”. +.TP +.B KYC_AML_TRIGGER +Program to run on KYC attribute data to decide whether we should immediately flag an account for AML review. Program must return 0 if a manual AML review is not needed, and non\-zero to trigger an AML review. The KYC attribute data of the new user will be passed on standard\-input. +.TP +.B STEFAN_ABS +Absolute amount to add as an offset in the STEFAN fee approximation +curve (see DD47). Defaults to CURRENCY:0 if not specified. +.TP +.B STEFAN_LOG +Amount to multiply by the base\-2 logarithm of the total amount +divided by the amount of the smallest denomination +in the STEFAN fee approximation curve (see DD47). +Defaults to CURRENCY:0 if not specified. +.TP +.B STEFAN_LIN +Linear floating point factor to be multiplied by the total amount +to use in the STEFAN fee approximation curve (see DD47). +Defaults to 0.0 if not specified. .TP .B 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. +.TP +.B TOPLEVEL_REDIRECT_URL +Where to redirect visitors that access the top\-level +“/” endpoint of the exchange. Should point users to +information about the exchange operator. +Optional setting, defaults to “/terms”. .TP .B AGGREGATOR_IDLE_SLEEP_INTERVAL -For how long should the aggregator sleep when it is idle +For how long should the taler\-exchange\-aggregator sleep when it is idle +before trying to look for more work? Default is 60 seconds. +.TP +.B CLOSER_IDLE_SLEEP_INTERVAL +For how long should the taler\-exchange\-closer sleep when it is idle +before trying to look for more work? Default is 60 seconds. +.TP +.B TRANSFER_IDLE_SLEEP_INTERVAL +For how long should the taler\-exchange\-transfer sleep when it is idle before trying to look for more work? Default is 60 seconds. .TP +.B WIREWATCH_IDLE_SLEEP_INTERVAL +For how long should the taler\-exchange\-wirewatch sleep when it is idle +before trying to look for more work? Default is 60 seconds. +.TP +.B AGGREGATOR_SHARD_SIZE +Which share of the range from [0,..2147483648] should be processed by one of the shards of the aggregator. Useful only for Taler exchanges with ultra high\-performance needs. When changing this value, you must stop all aggregators and run “taler\-exchange\-dbinit \-s” before resuming. Default is 2147483648 (no sharding). +.TP .B SIGNKEY_LEGAL_DURATION For how long are signatures with signing keys legally valid? .TP .B MAX_KEYS_CACHING For how long should clients cache \fB/keys\fP responses at most? .TP +.B MAX_REQUESTS +How many requests should the HTTP server process at most before committing suicide? +.TP .B 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/". +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 \fBTERMS_ETAG\fP\&. The extension defines the mime type. -Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg", -"png" and "gif". For example, using a \fBTERMS_ETAG\fP of "0", the structure +Supported extensions include “html”, “htm”, “txt”, “pdf”, “jpg”, “jpeg”, +“png” and “gif”. For example, using a \fBTERMS_ETAG\fP of “0”, the structure could be the following: .INDENT 7.0 .IP \(bu 2 @@ -169,7 +330,7 @@ $TERMS_DIR/de/0.txt .TP .B TERMS_ETAG Basename of the file(s) in the \fBTERMS_DIR\fP with the current terms of service. -The value is also used for the "Etag" in the HTTP request to control +The value is also used for the “Etag” in the HTTP request to control caching. Whenever the terms of service change, the \fBTERMS_ETAG\fP 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 @@ -183,13 +344,164 @@ Works the same as \fBTERMS_DIR\fP, just for the privacy policy. .B PRIVACY_ETAG Works the same as \fBTERMS_ETAG\fP, just for the privacy policy. .UNINDENT +.SS EXCHANGE KYC PROVIDER OPTIONS +.sp +The following options must be in the section “[kyc\-provider\-XXX]” sections. +.INDENT 0.0 +.TP +.B COST +Relative cost of the KYC provider, non\-negative number. +.TP +.B LOGIC +API type of the KYC provider. +.TP +.B USER_TYPE +Type of user this provider is for, either INDIVIDUAL or BUSINESS. +.TP +.B PROVIDED_CHECKS +List of checks performed by this provider. Space\-separated names of checks, must match check names in legitimization rules. +.UNINDENT +.SS EXCHANGE KYC OAUTH2 OPTIONS +.sp +The following options must be in the section “[kyc\-provider\-XXX]” sections with “LOGIC = oauth2”. +.INDENT 0.0 +.TP +.B KYC_OAUTH2_VALIDITY +Duration (e.g. “12 months”) of the validity of the performed KYC check. Can be “forever”. +.TP +.B KYC_OAUTH2_AUTHORIZE_URL +URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: “\fI\%http://localhost:8888/oauth/v2/authorize\fP”. To use the plugin in combination with the Challenger service’s \fB/setup\fP step, append “#setup”, thus “\fI\%https://challenger.example.com/authorize#setup\fP”. Here, “#setup” is not a fragment but merely a hint to the logic to determine the full authorization URL via the \fB/setup/$CLIENT_ID\fP handler. +.TP +.B KYC_OAUTH2_TOKEN_URL +URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a “bearer” token). Example: “\fI\%http://localhost:8888/oauth/v2/token\fP” (or just “/token”) +.TP +.B KYC_OAUTH2_INFO_URL +URL of the OAuth2\-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: “\fI\%http://localhost:8888/api/user/me\fP” or “\fI\%http://localhost:8888/oauth/v2/info\fP” +.TP +.B KYC_OAUTH2_CLIENT_ID +Client ID of the exchange when it talks to the KYC OAuth2 endpoint. +.TP +.B KYC_OAUTH2_CLIENT_SECRET +Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. +.TP +.B KYC_OAUTH2_POST_URL +URL to which the exchange will redirect the client’s browser after successful authorization/login for the KYC process. Example: “\fI\%http://example.com/thank\-you\fP” +.TP +.B KYC_OAUTH2_CONVERTER_HELPER +Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider. +.TP +.B KYC_OAUTH2_DEBUG_MODE +Set to YES to allow error responses to include potentially +sensitive private information (such as full responses +from the OAuth 2.0 server) that might aid in debugging +problems. Should be set to “NO” in production. +.UNINDENT +.SS EXCHANGE KYC KYCAID OPTIONS +.sp +The following options must be in the section “[kyc\-provider\-XXX]” sections with “LOGIC = kycaid”. +.INDENT 0.0 +.TP +.B KYC_KYCAID_VALIDITY +Duration (e.g. “12 months”) of the validity of the performed KYC check. Can be “forever”. +.TP +.B KYC_KYCAID_AUTH_TOKEN +Authentication token to access the KYC service. +.TP +.B KYC_KYCAID_FORM_ID +ID that specifies the form to use for the KYC process. +.TP +.B KYC_KYCAID_POST_URL +URL to which the exchange will redirect the client’s browser after successful authorization/login for the KYC process. +.UNINDENT +.SS EXCHANGE KYC PERSONA OPTIONS +.sp +The following options must be in the section “[kyc\-provider\-XXX]” sections with “LOGIC = persona”. +.INDENT 0.0 +.TP +.B KYC_PERSONA_VALIDITY +Duration (e.g. “12 months”) of the validity of the performed KYC check. Can be “forever”. +.TP +.B KYC_PERSONA_AUTH_TOKEN +Authentication token to access the KYC service. +.TP +.B KYC_PERSONA_SALT +Salt value to use for request idempotency. Optional, generated at random per process if not given. +.TP +.B KYC_PERSONA_SUBDOMAIN +Subdomain to use under Persona. +.TP +.B KYC_PERSONA_CONVERTER_HELPER +Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to “taler\-exchange\-kyc\-persona\-converter.sh”. +.TP +.B KYC_PERSONA_POST_URL +URL to which the exchange will redirect the client’s browser after successful authorization/login for the KYC process. +.TP +.B KYC_PERSONA_TEMPLATE_ID +ID of the Persona template to use. +.UNINDENT +.SS EXCHANGE KYC PERSONA GLOBAL OPTIONS +.sp +The following option must be in the section “[kyclogic\-persona]”. +.INDENT 0.0 +.TP +.B WEBHOOK_AUTH_TOKEN +Authentication token Persona must supply to our webhook. This is an optional setting. +.UNINDENT +.SS EXCHANGE EXTENSIONS OPTIONS +.sp +The functionality of the exchange can be extended by extensions. Those are +shared libraries which implement the extension\-API of the exchange and are +located under \fB$LIBDIR\fP, starting with prefix \fBlibtaler_extension_\fP\&. Each +extension can be enabled by adding a dedicated section +“[exchange\-extension\-<extensionname>]” and the following option: +.INDENT 0.0 +.TP +.B ENABLED +If set to \fBYES\fP the extension \fB<extensionsname>\fP is enabled. Extension\-specific +options might be set in the same section. +.UNINDENT +.SS EXCHANGE EXTENSION FOR AGE RESTRICTION +.sp +The extension for age restriction support can be enabled by adding a section +“[exchange\-extension\-age_restriction]” with the following options: +.INDENT 0.0 +.TP +.B ENABLE +Must be set to \fBYES\fP in order to activate the extension. +.TP +.B AGE_GROUPS +A colon\-seperated string of increasing non\-negative integers, defining the +buckets of age groups supported by the exchange. Each integer marks the +beginning of the next age group. The zero’th age group implicitly starts +with 0. For example, the string “10:18” would define three age groups: +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP 1. 3 +Group 0: ages 0 through 9 (including) +.IP 2. 3 +Group 1: ages 10 through 17 (including) +.IP 3. 3 +Group 2: ages 18 and above +.UNINDENT +.UNINDENT +.UNINDENT +.sp +If not provided, the default value is “8:10:12:14:16:18:21”. +.UNINDENT +.sp +\fBNote\fP: Age restriction is bound to specific denominations and must be +enabled for each selected denomination in the corresponding section by adding +the option \fBAGE_RESTRICTED = YES\fP, see \fI\%EXCHANGE COIN OPTIONS\fP\&. However, the +age groups are defined globally for all denominations. .SS EXCHANGE OFFLINE SIGNING OPTIONS .sp -The following options must be in the section "[exchange\-offline]". +The following options must be in the section “[exchange\-offline]”. .INDENT 0.0 .TP .B MASTER_PRIV_FILE -Where to store the offline private key of the exchange. +Location of the master private key on disk. Only used by tools that +can be run offline (as the master key is for offline signing). Mandatory. .TP .B SECM_TOFU_FILE @@ -211,7 +523,7 @@ this option will also be ignored. .UNINDENT .SS EXCHANGE RSA CRYPTO HELPER OPTIONS .sp -The following options must be in the section "[taler\-exchange\-secmod\-rsa]". +The following options must be in the section “[taler\-exchange\-secmod\-rsa]”. .INDENT 0.0 .TP .B LOOKAHEAD_SIGN @@ -236,9 +548,36 @@ On which path should the security module listen for signing requests? .sp Note that the \fBtaler\-exchange\-secmod\-rsa\fP also evaluates the \fB[coin_*]\fP configuration sections described below. +.SS EXCHANGE CS CRYPTO HELPER OPTIONS +.sp +The following options must be in the section “[taler\-exchange\-secmod\-cs]”. +.INDENT 0.0 +.TP +.B LOOKAHEAD_SIGN +How long do we generate denomination and signing keys ahead of time? +.TP +.B 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 \fBDURATION_WITHDRAW\fP period +must be longer than this value. +.TP +.B SM_PRIV_KEY +Where should the security module store its long\-term private key? +.TP +.B KEY_DIR +Where should the security module store the private keys it manages? +.TP +.B UNIXPATH +On which path should the security module listen for signing requests? +.UNINDENT +.sp +Note that the \fBtaler\-exchange\-secmod\-cs\fP also evaluates the \fB[coin_*]\fP +configuration sections described below. .SS EXCHANGE EDDSA CRYPTO HELPER OPTIONS .sp -The following options must be in the section "[taler\-exchange\-secmod\-eddsa]". +The following options must be in the section “[taler\-exchange\-secmod\-eddsa]”. .INDENT 0.0 .TP .B LOOKAHEAD_SIGN @@ -265,7 +604,7 @@ On which path should the security module listen for signing requests? .UNINDENT .SS EXCHANGE DATABASE OPTIONS .sp -The following options must be in the section "[exchangedb]". +The following options must be in the section “[exchangedb]”. .INDENT 0.0 .TP .B IDLE_RESERVE_EXPIRATION_TIME @@ -273,6 +612,14 @@ After which time period should reserves be closed if they are idle? .TP .B LEGAL_RESERVE_EXPIRATION_TIME After what time do we forget about (drained) reserves during garbage collection? +.TP +.B AGGREGATOR_SHIFT +Delay between a deposit being eligible for aggregation and +the aggregator actually triggering. +.TP +.B DEFAULT_PURSE_LIMIT +Number of concurrent purses that a reserve may have active +if it is paid to be opened for a year. .UNINDENT .SS EXCHANGE POSTGRES BACKEND DATABASE OPTIONS .sp @@ -289,8 +636,7 @@ How to access the database, e.g.\ “postgres:///taler” to use the An exchange (or merchant) can have multiple bank accounts. The following options are for sections named “[exchange\-account\-SOMETHING]”. The \fBSOMETHING\fP is arbitrary and should be chosen to uniquely identify the bank account for -the operator. These options are used by the \fBtaler\-exchange\-transfer\fP -and \fBtaler\-exchange\-wirewatch\fP tools. +the operator. These options are used by the \fBtaler\-exchange\-aggregator\fP, \fBtaler\-exchange\-closer\fP, \fBtaler\-exchange\-transfer\fP and \fBtaler\-exchange\-wirewatch\fP tools. .INDENT 0.0 .TP .B PAYTO_URI @@ -301,12 +647,25 @@ Specifies the payto://\-URL of the account. The general format is \fBpayto://iban/DE67830654080004822650/\fP (providing the BIC is optional). Note: only the wire\-method is actually used from the URI. .TP +.B ENABLE_DEBIT +Must be set to \fBYES\fP for the accounts that the +\fBtaler\-exchange\-aggregator\fP and \fBtaler\-exchange\-closer\fP should debit. +.TP +.B ENABLE_CREDIT +Must be set to \fBYES\fP for the accounts that the \fBtaler\-exchange\-wirewatch\fP +should check for credits. It is yet uncertain if the merchant +implementation may check this flag as well. +.UNINDENT +.sp +Additionally, for each enabled account there MUST be another matching section named “[exchange\-accountcredentials\-SOMETHING]”. This section SHOULD be in a \fBsecret/\fP configuration file that is only readable for the \fBtaler\-exchange\-wirewatch\fP and \fBtaler\-exchange\-transfer\fP processes. It contains the credentials to access the bank account: +.INDENT 0.0 +.TP .B WIRE_GATEWAY_URL URL of the wire gateway. Typically of the form \fBhttps://$HOSTNAME[:$PORT]/taler\-wire\-gateway/$USERNAME/\fP where $HOSTNAME is the hostname of the system running the bank (such as the Taler Python bank or the Nexus) and \fB$USERNAME\fP is -the username of the exchange\(aqs bank account (usually matching +the username of the exchange’s bank account (usually matching the \fBUSERNAME\fP option used for authentication). Example: \fBhttps://bank.demo.taler.net/taler\-wire\-gateway/Exchange/\fP\&. .TP @@ -319,19 +678,10 @@ User name for \fBbasic\fP authentication with the wire gateway. .TP .B PASSWORD Password for \fBbasic\fP authentication with the wire gateway. -.TP -.B ENABLE_DEBIT -Must be set to \fBYES\fP for the accounts that the -\fBtaler\-exchange\-aggregator\fP and \fBtaler\-exchange\-closer\fP should debit. -.TP -.B ENABLE_CREDIT -Must be set to \fBYES\fP for the accounts that the \fBtaler\-exchange\-wirewatch\fP -should check for credits. It is yet uncertain if the merchant -implementation may check this flag as well. .UNINDENT .SS EXCHANGE COIN OPTIONS .sp -The following options must be in sections starting with \fB"[coin_]"\fP and are +The following options must be in sections starting with \fB\(dq[coin_]\(dq\fP and are largely used by \fBtaler\-exchange\-httpd\fP to determine the meta data for the denomination keys. Some of the options are used by the \fBtaler\-exchange\-secmod\-rsa\fP to determine which RSA keys to create (and of @@ -369,8 +719,18 @@ What fee is charged for refreshing? What fee is charged for refunds? When a coin is refunded, the deposit fee is returned. Instead, the refund fee is charged to the customer. .TP +.B 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. +.TP .B RSA_KEYSIZE -What is the RSA keysize modulos (in bits)? +What is the RSA keysize modulos (in bits)? Only used if “CIPHER=RSA”. +.TP +.B AGE_RESTRICTED +Setting this option to \fBYES\fP marks the denomination as age restricted +(default is \fBNO\fP). For this option to be accepted the extension for age +restriction MUST be enabled (see \fI\%EXCHANGE EXTENSION FOR AGE RESTRICTION\fP). .UNINDENT .SS MERCHANT OPTIONS .sp @@ -381,9 +741,24 @@ merchant backend. .B DB Plugin to use for the database, e.g._“postgres”. .TP +.B SERVE +Should the HTTP server listen on a UNIX domain socket (set option to “unix”) or on a TCP socket (set option to “tcp”)? +.TP +.B BASE_URL +Which base URL should the merchant backend assume for itself in the protocol. Optional. If not given, the base URL will be constructed from X\-Forwarded\-Host, X\-Forwarded\-Port and X\-Forwarded\-Prefix headers that a reverse\-proxy should be setting. +.TP +.B UNIXPATH +Path to listen on if we “SERVE” is set to “unix”. +.TP +.B UNIXPATH_MODE +Access permission mask to use for the “UNIXPATH”. +.TP .B PORT Port on which the HTTP server listens, e.g.\ 8080. .TP +.B BIND_TO +Hostname to which the merchant HTTP server should be bound to, e.g. “localhost”. +.TP .B LEGAL_PRESERVATION How long do we keep data in the database for tax audits after the transaction has completed? Default is 10 years. @@ -417,7 +792,7 @@ Base URL of the exchange, e.g.\ “\fI\%https://exchange.demo.taler.net/\fP” .TP .B MASTER_KEY Crockford Base32 encoded master public key, public version of the -exchange\(aqs long\-time offline signing key. Can be omitted, in that +exchange’s long\-time offline signing key. Can be omitted, in that case the exchange will NOT be trusted unless it is audited by a known auditor. Omitting \fBMASTER_KEY\fP can be useful if we do not trust the exchange @@ -429,26 +804,9 @@ required by a client. Name of the currency for which this exchange is used, e.g.\ “KUDOS”. The entire section is ignored if the currency does not match the currency we use, which must be given in the \fB[taler]\fP section. -.UNINDENT -.SS KNOWN AUDITORS (for merchants) -.sp -The merchant configuration can include a list of known exchanges if the -merchant wants to specify that certain auditors are explicitly trusted. -For each trusted exchange, a section “[merchant\-auditor\-$NAME]” must exist, where -\fB$NAME\fP is a merchant\-given name for the auditor. The following options -must be given in each “[merchant\-auditor\-$NAME]” section. -.INDENT 0.0 .TP -.B AUDITOR_BASE_URL -Base URL of the auditor, e.g.\ “\fI\%https://auditor.demo.taler.net/\fP” -.TP -.B AUDITOR_KEY -Crockford Base32 encoded auditor public key. -.TP -.B CURRENCY -Name of the currency for which this auditor is trusted, e.g.\ “KUDOS” -The entire section is ignored if the currency does not match the currency -we use, which must be given in the \fB[taler]\fP section. +.B DISABLED +Set to YES to disable this exchange. Optional option, defaults to NO. .UNINDENT .SS AUDITOR OPTIONS .sp @@ -468,6 +826,21 @@ processes that do not have access to the (offline) auditor private key file. .TP .B BASE_URL Base URL of the auditor, e.g.\ “\fI\%https://auditor.demo.taler.net/\fP” +.TP +.B SERVE +Should the HTTP server listen on a UNIX domain socket (set option to “unix”) or on a TCP socket (set option to “tcp”)? +.TP +.B UNIXPATH +Path to listen on if we “SERVE” is set to “unix”. +.TP +.B UNIXPATH_MODE +Access permission mask to use for the “UNIXPATH”. +.TP +.B PORT +Port on which the HTTP server listens, e.g.\ 8080. +.TP +.B BIND_TO +Hostname to which the merchant HTTP server should be bound to, e.g. “localhost”. .UNINDENT .SS AUDITOR POSTGRES BACKEND DATABASE OPTIONS .sp @@ -476,8 +849,80 @@ The following options must be in section “[auditordb\-postgres]” if the .INDENT 0.0 .TP .B CONFIG -How to access the database, e.g.\ "postgres:///taler" to use the -"taler" database. Testcases use “talercheck”. +How to access the database, e.g.\ “postgres:///taler” to use the +“taler” database. Testcases use “talercheck”. +.UNINDENT +.SS Bank Options +.sp +The following options must be in section “[bank]” for the taler\-fakebank\-run(1) command. They are not used by the exchange or LibEuFin! +.INDENT 0.0 +.TP +.B HTTP_PORT +On which TCP port should the (fake)bank offer its REST API. +.TP +.B RAM_LIMIT +This gives the number of transactions to keep in memory. Older transactions will be overwritten and history requests for overwritten transactions will fail. +.UNINDENT +.SS Taler\-mdb Options +.sp +Taler\-mdb is a component to run GNU Taler as a payment system on +vending machines using the multi\-drop bus protocol. These options +are thus not useful for most users. Note that right now, the +cancel button is hard\-coded to be using GPIO pin 23. +.INDENT 0.0 +.TP +.B ADVERTISEMENT_COMMAND +Program to run while not vending, possibly useful to show advertisements on the screen (optional). +.TP +.B ESSID +ESSID to advertise to wallets for use as an open WiFi to make payments (optional). +.TP +.B FULFILLMENT_MSG +Message shown to users by their wallets upon successful payment. If “${PRODUCT_DESCRIPTION}” appears in the message, it will be replaced with the description of the product that was sold. +.TP +.B BACKEND_BASE_URL +Base URL (possibly including instance) for the Taler merchant backend used to process payments. +.TP +.B BACKEND_AUTHORIZATION +Full HTTP “Authorization” header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Mandatory. +.TP +.B FRAMEBUFFER_BACKLIGHT +Name of the file used to control brightness of the display. Optional. Defaults to “/sys/class/backlight/soc:backlight/brightness” if not given. +.TP +.B FRAMEBUFFER_DEVICE +Name of the framebuffer device to use. Defaults to “/dev/fb1” if not given. +.TP +.B UART_DEVICE +Name of the UART device to use. Defaults to “/dev/ttyAMA0” if not given. +.TP +.B FAIL_COMMAND +Command to run to display a failure to the user. If not given, errors will not be properly shown. +.UNINDENT +.sp +Each products being sold must be configured in a section where the name starts with “product\-“. +In these sections, the options that must be provided are: +.INDENT 0.0 +.TP +.B NUMBER +Number identifying the slot in the vending machine that corresponds to this product. +.TP +.B INSTANCE +Instance to use for the payment. Optional. If not given, the BACKEND_BASE_URL from “[taler\-mdb]” will be used. +.TP +.B BACKEND_AUTHORIZATION +Full HTTP “Authorization” header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Optional, will use global BACKEND_AUTHORIZATION setting from “[taler\-mdb]” if missing. +.TP +.B DESCRIPTION +Human\-readable description of the product. Use “empty” if the product is known to be sold out (only effective if selling out is enabled via command\-line). +.TP +.B PRICE +Actual price of the product, as a Taler amount (“$CURRENCY:$VALUE.$FRACTION”). +.TP +.B KEY +Key used to select the product from the console during testing. Optional. +.TP +.B THUMBNAIL +Name of a filename with a preview image of the product to be given to the wallet. Optional. Only “.png”, “.jpg”, “.jpeg” and “.svg” are supported at this time. .UNINDENT .SH SEE ALSO .sp @@ -490,6 +935,6 @@ mail to <\fI\%taler@gnu.org\fP>. .SH AUTHOR GNU Taler contributors .SH COPYRIGHT -2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) .\" Generated by docutils manpage writer. . diff --git a/texinfo/anastasis.texi b/texinfo/anastasis.texi index a35a6666..be8c50be 100644 --- a/texinfo/anastasis.texi +++ b/texinfo/anastasis.texi @@ -75,7 +75,7 @@ this difficult for everyone else. Furthermore, it is assumed that the user is unable to reliably remember any secret with sufficiently high entropy, so we cannot simply encrypt using some other key material in possession of the user. -To uniquely identify users, an "unforgettable" @strong{identifier} is used. This +To uniquely identify users, an “unforgettable” @strong{identifier} is used. This identifier should be difficult to guess for anybody but the user. However, the @strong{identifier} is not expected to have sufficient entropy or secrecy to be cryptographically secure. Examples for such identifier would be a @@ -83,8 +83,8 @@ concatenation of the full name of the user and their social security or passport number(s). For Swiss citizens, the AHV number could also be used. The adversary model of Anastasis has two types of adversaries: weak -adversaries which do not know the user's @strong{identifier}, and strong -adversaries which somehow do know a user's @strong{identifier}. For weak +adversaries which do not know the user’s @strong{identifier}, and strong +adversaries which somehow do know a user’s @strong{identifier}. For weak adversaries the system guarantees full confidentiality. For strong adversaries, breaking confidentiality additionally requires that Anastasis escrow providers must have colluded. The user is able to specify a set of @@ -95,7 +95,7 @@ to recover their core secret. A @strong{recovery document} includes all of the information a user needs to recover access to their core secret. It specifies a set of @strong{escrow methods}, which specify how the user should convince the Anastasis server -that they are "real". Escrow methods can for example include SMS-based +that they are “real”. Escrow methods can for example include SMS-based verification, video identification or a security question. For each escrow method, the Anastasis server is provided with @strong{truth}, that is data the Anastasis operator may learn during the recovery process to authenticate the @@ -110,9 +110,9 @@ escrow methods (A and B) suffice, and a second policy may permit (A and C). A different user may choose to use the policy that (A and B and C) are all required. Anastasis imposes no limit on the number of policies in a @strong{recovery document}, or the set of providers or escrow methods involved in -guarding a user's secret. Weak adversaries must not be able to deduce -information about a user's @strong{recovery document} (except for its length, which -may be exposed to an adversary which monitors the user's network traffic). +guarding a user’s secret. Weak adversaries must not be able to deduce +information about a user’s @strong{recovery document} (except for its length, which +may be exposed to an adversary which monitors the user’s network traffic). @menu * Anastasis DB Schema:: @@ -144,16 +144,16 @@ may be exposed to an adversary which monitors the user's network traffic). When a user needs to interact with Anastasis, the system first derives some key -material, but not the master secret, from the user's @strong{identifier} using +material, but not the master secret, from the user’s @strong{identifier} using different HKDFs. These HKDFs are salted using the respective escrow -provider's @strong{server salt}, which ensures that the accounts for the same user +provider’s @strong{server salt}, which ensures that the accounts for the same user cannot be easily correlated across the various Anastasis servers. Each Anastasis server uses an EdDSA @strong{account key} to identify the account of -the user. The account private key is derived from the user's @strong{identifier} using +the user. The account private key is derived from the user’s @strong{identifier} using a computationally expensive cryptographic hash function. Using an expensive hash algorithm is assumed to make it infeasible for a weak adversary to -determine account keys by brute force (without knowing the user's identifier). +determine account keys by brute force (without knowing the user’s identifier). However, it is assumed that a strong adversary performing a targeted attack can compute the account key pair. @@ -205,10 +205,10 @@ This identifier will be first hashed with Argon2, to provide a @strong{kdf_id} which will be used to derive other keys later. The Hash must also include the respective @strong{server_salt}. This also ensures that the @strong{kdf_id} is different on each server. The use of Argon2 and the respective @strong{server_salt} is intended -to make it difficult to brute-force @strong{kdf_id} values and help protect the user's +to make it difficult to brute-force @strong{kdf_id} values and help protect the user’s privacy. Also this ensures that the @strong{kdf_id}s on every server differs. However, we do not assume that the @strong{identifier} or the @strong{kdf_id} cannot be -determined by an adversary performing a targeted attack, as a user's +determined by an adversary performing a targeted attack, as a user’s @strong{identifier} is likely to always be known to state actors and may likely also be available to other actors. @@ -233,17 +233,17 @@ kdf_id := Argon2( identifier, server_salt, keysize ) @subsection Verification -For users to authorize "policy" operations we need an EdDSA key pair. As we +For users to authorize “policy” operations we need an EdDSA key pair. As we cannot assure that the corresponding private key is truly secret, such policy operations must never be destructive: Should an adversary learn the private -key, they could access (and with the @strong{kdf_id}, decrypt) the user's policy (but +key, they could access (and with the @strong{kdf_id}, decrypt) the user’s policy (but not the core secret), or upload a new version of the @strong{encrypted recovery document} (but not delete an existing version). For the generation of the private key we use the @strong{kdf_id} as the entropy source, hash it to derive a base secret which will then be processed to fit the requirements for EdDSA private keys. From the private key we can then -generate the corresponding public key. Here, "ver" is used as a salt for the +generate the corresponding public key. Here, “ver” is used as a salt for the HKDF to ensure that the result differs from other cases where we hash @strong{kdf_id}. @@ -261,7 +261,7 @@ eddsa_pub := get_EdDSA_Pub(eddsa_priv) @strong{ver_secret}: Derived key from the @code{kdf_id}, serves as intermediate step for the generation of the private key. -@strong{eddsa_d_to_a()}: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value @code{eddsa_priv} is in a 32-byte array "digest", the function clears and sets certain bits as follows: +@strong{eddsa_d_to_a()}: Function which converts the ver_key to a valid EdDSA private key. Specifically, assuming the value @code{eddsa_priv} is in a 32-byte array “digest”, the function clears and sets certain bits as follows: @example digest[0] = (digest[0] & 0x7f) | 0x40; @@ -296,7 +296,7 @@ key material using an HKDF over a @code{nonce} and the @code{kdf_id}. @strong{prekey}: Original key material. -@strong{nonce}: 32-byte nonce, must never match "ver" (which it cannot as the length is different). Of course, we must +@strong{nonce}: 32-byte nonce, must never match “ver” (which it cannot as the length is different). Of course, we must avoid key reuse. So, we have to use different nonces to get different keys and IVs (see below). @strong{key}: Symmetric key which is later used to encrypt the documents with AES256-GCM. @@ -327,7 +327,7 @@ From this the symmetric key is computed as described above. We use AES256-GCM for the encryption of the @strong{recovery document} and the @strong{key_share}. To ensure that the key derivation for the encryption of the @strong{recovery document} differs fundamentally from that of an -individual @strong{key share}, we use different salts ("erd" and "eks", respectively). +individual @strong{key share}, we use different salts (“erd” and “eks”, respectively). @example (iv0, key0) := HKDF(key_id, nonce0, "erd", keysize + ivsize) @@ -340,7 +340,7 @@ individual @strong{key share}, we use different salts ("erd" and "eks", respecti and the encrypted @strong{core secret}. @strong{nonce0}: Nonce which is used to generate @emph{key0} and @emph{iv0} which are used for the encryption of the @emph{recovery document}. -Nonce must contain the string "ERD". +Nonce must contain the string “ERD”. @strong{optional data}: Key material that optionally is contributed from the authentication method to further obfuscate the key share from the escrow provider. @@ -349,10 +349,10 @@ Here, @strong{i} must be a positive number used to iterate over the various @str at the various providers. @strong{nonce_i}: Nonce which is used to generate @emph{key_i} and @emph{iv_i} which are used for the encryption of the @strong{key share}. @strong{i} must be -the same number as specified above for @emph{encrypted_key_share_i}. Nonce must contain the string "EKS" plus the according @emph{i}. +the same number as specified above for @emph{encrypted_key_share_i}. Nonce must contain the string “EKS” plus the according @emph{i}. As a special rule, when a @strong{security question} is used to authorize access to an -@strong{encrypted_key_share_i}, then the salt "eks" is replaced with an (expensive) hash +@strong{encrypted_key_share_i}, then the salt “eks” is replaced with an (expensive) hash of the answer to the security question as an additional way to make the key share inaccessible to those who do not have the answer: @@ -372,7 +372,7 @@ ekss := HKDF("Anastasis-secure-question-uuid-salting", @strong{uuid}: UUID of the challenge associated with the security question and the encrypted key share. -@strong{ekss}: Replacement salt to be used instead of "eks" when deriving the key to encrypt/decrypt the key share. +@strong{ekss}: Replacement salt to be used instead of “eks” when deriving the key to encrypt/decrypt the key share. @node Signatures,,Encryption<2>,Key Usage @anchor{anastasis signatures}@anchor{9} @@ -403,7 +403,7 @@ ver_res := eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) @strong{anastasis-account-signature}: Signature over the SHA-512 hash of the body using the purpose code @code{TALER_SIGNATURE_ANASTASIS_POLICY_DOWNLOAD} (1401) (see GNUnet EdDSA signature API for the use of purpose). -@strong{version}: The version requested as a 64-bit integer, 2^64-1 for the "latest version". +@strong{version}: The version requested as a 64-bit integer, 2^64-1 for the “latest version”. @strong{ver_res}: A boolean value. True: Signature verification passed, False: Signature verification failed. @@ -414,7 +414,7 @@ ver_res := eddsa_verifiy(version, anastasis-account-signature, eddsa_pub) Anastasis considers two main threats against availability. First, the Anastasis server operators must be protected against denial-of-service attacks -where an adversary attempts to exhaust the operator's resources. The API protects +where an adversary attempts to exhaust the operator’s resources. The API protects against these attacks by allowing operators to set fees for all operations. Furthermore, all data stored comes with an expiration logic, so an attacker cannot force servers to store data indefinitely. @@ -430,7 +430,7 @@ merely create another version. This way, even if an adversary uploads a malicious policy, a user can still retrieve an older version of the policy to recover access to their data. This append-only storage for policies still leaves a strong adversary with the option of uploading many policies to -exhaust the Anastasis server's capacity. We limit this attack by requiring a +exhaust the Anastasis server’s capacity. We limit this attack by requiring a policy upload to include a reference to a @strong{payment identifier} from a payment made by the user. Thus, a policy upload requires both knowledge of the @strong{identity} and making a payment. This effectively prevents an adversary @@ -535,7 +535,7 @@ Obtain the terms of service provided by the escrow provider. @strong{Response:} Returns the terms of service of the provider, in the best language -and format available based on the client's request. +and format available based on the client’s request. @end deffn @anchor{anastasis get--privacy}@anchor{15} @@ -546,7 +546,7 @@ Obtain the privacy policy of the service provided by the escrow provider. @strong{Response:} Returns the privacy policy of the provider, in the best language -and format available based on the client's request. +and format available based on the client’s request. @end deffn @node Manage policy,Managing truth,Receiving Terms of Service,Anastasis REST API @@ -568,7 +568,7 @@ In the following, UUID is always defined and used according to RFC 4122@footnote @anchor{anastasis get--policy-$ACCOUNT_PUB[?version=$NUMBER]}@anchor{18} @deffn {HTTP Get} GET /policy/$ACCOUNT_PUB[?version=$NUMBER] -Get the customer's encrypted recovery document. If @code{version} +Get the customer’s encrypted recovery document. If @code{version} is not specified, the server returns the latest available version. If @code{version} is specified, returns the policy with the respective @code{version}. The response must begin with the nonce and @@ -613,7 +613,7 @@ The @code{$ACCOUNT_PUB} is not an EdDSA public key. @item 402 Payment Required@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}: -The account's balance is too low for the specified operation. +The account’s balance is too low for the specified operation. See the Taler payment protocol specification for how to pay. @item 403 Forbidden@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}: @@ -625,7 +625,7 @@ The required account signature was invalid. The requested resource was not found. @end table -@emph{Anastasis-Version}: $NUMBER --- The server must return actual version of the encrypted recovery document via this header. +@emph{Anastasis-Version}: $NUMBER — The server must return actual version of the encrypted recovery document via this header. If the client specified a version number in the header of the request, the server must return that version. If the client did not specify a version in the request, the server returns latest version of the @ref{19,,EncryptedRecoveryDocument}. @@ -640,8 +640,8 @@ The client SHOULD send this header with every request (except for the first requ @anchor{anastasis post--policy-$ACCOUNT_PUB}@anchor{1a} @deffn {HTTP Post} POST /policy/$ACCOUNT_PUB -Upload a new version of the customer's encrypted recovery document. -While the document's structure is described in JSON below, the upload +Upload a new version of the customer’s encrypted recovery document. +While the document’s structure is described in JSON below, the upload should just be the bytestream of the raw data (i.e. 32-byte nonce followed by 16-byte tag followed by the encrypted document). If the request has been seen before, the server should do nothing, and otherwise store the new version. @@ -657,7 +657,7 @@ minimum and maximum size limits. @itemize * @item -@code{pay} -- Optional argument, any non-empty value will do, +@code{pay} – Optional argument, any non-empty value will do, suggested is @code{y} for @code{yes}. The client insists on making a payment for the respective account, even if this is not yet required. The server @@ -670,7 +670,7 @@ option will be checked before the @code{304 Not modified} case. @item -@code{timeout_ms=NUMBER} -- @emph{Optional.} If specified, the Anastasis server will +@code{timeout_ms=NUMBER} – @emph{Optional.} If specified, the Anastasis server will wait up to @code{timeout_ms} milliseconds for completion of the payment before sending the HTTP response. A client must never rely on this behavior, as the backend may return a response immediately. @@ -686,7 +686,7 @@ the latest version already known to the server. @emph{Anastasis-Policy-Signature}: The client must provide Base-32 encoded EdDSA signature over hash of body with @code{$ACCOUNT_PRIV}, affirming desire to upload an encrypted recovery document. -@emph{Payment-Identifier}: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see @code{402} status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the @strong{kdf_id} might be known to an attacker). If this header is missing in the client's request (or the associated payment has exceeded the upload limit), the server must return a @code{402} response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. +@emph{Payment-Identifier}: Base-32 encoded 32-byte payment identifier that was included in a previous payment (see @code{402} status code). Used to allow the server to check that the client paid for the upload (to protect the server against DoS attacks) and that the client knows a real secret of financial value (as the @strong{kdf_id} might be known to an attacker). If this header is missing in the client’s request (or the associated payment has exceeded the upload limit), the server must return a @code{402} response. When making payments, the server must include a fresh, randomly-generated payment-identifier in the payment request. @strong{Response}: @@ -710,7 +710,7 @@ The response body MUST elaborate on the error using a Taler error code in the ty @item 402 Payment required@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.3}: -The account's balance is too low for the specified operation. +The account’s balance is too low for the specified operation. See the Taler payment protocol specification for how to pay. The response body MAY provide alternative means for payment. @@ -840,7 +840,7 @@ If request has been seen before, the server should do nothing, and otherwise sto @itemize * @item -@code{timeout_ms=NUMBER} -- @emph{Optional.} If specified, the Anastasis server will +@code{timeout_ms=NUMBER} – @emph{Optional.} If specified, the Anastasis server will wait up to @code{timeout_ms} milliseconds for completion of the payment before sending the HTTP response. A client must never rely on this behavior, as the backend may return a response immediately. @@ -955,7 +955,7 @@ The response body MAY provide alternative means for payment. @item 403 Forbidden@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4}: -The server requires a valid "response" to the challenge associated with the UUID. +The server requires a valid “response” to the challenge associated with the UUID. @item 404 Not found@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5}: @@ -1269,7 +1269,7 @@ process. In the following, the individual transitions will be specified in more detail. Note that we only show fields added by the reducer, typically the previous -state is preserved to enable "back" transitions to function smoothly. +state is preserved to enable “back” transitions to function smoothly. @menu * Initial state:: @@ -1310,7 +1310,7 @@ The initial states for backup and recovery processes are: @} @end example -Here, "continents" is an array of English strings with the names of the +Here, “continents” is an array of English strings with the names of the continents which contain countries for which Anastasis could function (based on having providers that are known to operate and rules being provided for user attributes from those countries). @@ -1409,7 +1409,7 @@ currency of the country, if a country has multiple currencies, it may appear multiple times in the list. In this case, the user should select the entry with the currency they intend to pay with. It is also possible for users to select a currency that does not match their country, but user interfaces -should by default try to use currencies that match the user's residence. +should by default try to use currencies that match the user’s residence. @strong{select_country:} @@ -1428,7 +1428,7 @@ Arguments (example): @end example The @code{country_code} must be an ISO 3166-1 alpha-2 country code from -the array of @code{countries} of the reducer's state. The @code{currency} +the array of @code{countries} of the reducer’s state. The @code{currency} field must be a valid currency accepted by the Taler payment system. The reducer returns a new state with the list of attributes the @@ -1561,7 +1561,7 @@ Translated descriptions may be provided under @strong{label_i18n}. different countries. Useful to preserve values should the user enter some attributes, and then switch to another country. Note that attributes must not be preserved if they merely have the same @strong{name}, -only the @strong{uuid} will be identical if the semantics is identicial. +only the @strong{uuid} will be identical if the semantics is identical. @item @strong{widget}: An optional name of a widget that is known to nicely render @@ -1632,11 +1632,11 @@ will match all of the fees. both recovery document and truth data) in megabytes. @item -@strong{provider_name}: Human-readable name of the provider's business. +@strong{provider_name}: Human-readable name of the provider’s business. @item @strong{salt}: Salt value used by the provider, used to derive the -user's identity at this provider. Should be unique per provider, +user’s identity at this provider. Should be unique per provider, and must never change for a given provider. The salt is base32 encoded. @end itemize @@ -1734,7 +1734,7 @@ port 8888 was now added: @strong{enter_user_attributes:} -This transition provides the user's personal attributes. The specific set of +This transition provides the user’s personal attributes. The specific set of attributes required depends on the country of residence of the user. Some attributes may be optional, in which case they should be omitted entirely (that is, not simply be set to @code{null} or an empty string). Example @@ -1787,7 +1787,7 @@ is specific to the failure, and optional details. Example: @} @end example -Clients may safely repeat this transition to validate the user's inputs +Clients may safely repeat this transition to validate the user’s inputs until they satisfy all of the constraints. This way, the user interface does not have to perform the input validation directly. @@ -1974,7 +1974,7 @@ An example for a possible argument would thus be: Note that the specified providers must already be in the @code{authentication_providers} of the state. You cannot add new providers at this stage. The reducer will simply attempt to append the suggested policy to -the "policies" array, returning an updated state: +the “policies” array, returning an updated state: @example @{ @@ -2235,7 +2235,7 @@ store information into its database. @strong{enter_user_attributes:} -This transition provides the user's personal attributes. The specific set of +This transition provides the user’s personal attributes. The specific set of attributes required depends on the country of residence of the user. Some attributes may be optional, in which case they should be omitted entirely (that is, not simply be set to @code{null} or an empty string). The @@ -2373,7 +2373,7 @@ which takes a provider URL and policy version as arguments: @} @end example -Note that using a version of 0 implies fetching "the latest version". The +Note that using a version of 0 implies fetching “the latest version”. The resulting states are the same as those of the @code{enter_user_attributes} transition, except that the recovery document version is not necessarily the latest available version at the provider. @@ -2720,7 +2720,7 @@ maximum permissible frequency. @section SMS (sms) -Sends an SMS with a code (prefixed with @code{A-}) to the user's phone, including +Sends an SMS with a code (prefixed with @code{A-}) to the user’s phone, including a UUID which identifies the challenge the code is for. The user must send this code back with his request (see @code{$RESPONSE} under @ref{1e,,Managing truth}). If the transmitted code is correct, the server responses with the requested @@ -2731,7 +2731,7 @@ encrypted key share. @section Email verification (email) -Sends an email with a code (prefixed with @code{A-}) to the user's mail address, +Sends an email with a code (prefixed with @code{A-}) to the user’s mail address, including a UUID which identifies the challenge the code is for. The user must send this code back with his request (see @code{$RESPONSE} under @ref{1e,,Managing truth}). If the transmitted code is correct, the server responses with the requested encrypted key share. @@ -2783,7 +2783,7 @@ storing the security question is malicious. Sends physical mail (snail mail) with a code (prefixed with @code{A-}) to the -user's mail address, including a UUID which identifies the challenge the code +user’s mail address, including a UUID which identifies the challenge the code is for. The user must send this code back with their request (see @code{$RESPONSE} under @ref{1e,,Managing truth}). If the transmitted code is correct, the server responds with the requested encrypted key share. diff --git a/texinfo/challenger-figures/challenger.png b/texinfo/challenger-figures/challenger.png Binary files differnew file mode 100644 index 00000000..3005af0e --- /dev/null +++ b/texinfo/challenger-figures/challenger.png diff --git a/texinfo/challenger.texi b/texinfo/challenger.texi new file mode 100644 index 00000000..75e90760 --- /dev/null +++ b/texinfo/challenger.texi @@ -0,0 +1,1533 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename challenger.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 5.3.0.@* +@end ifinfo +@settitle Taler Challenger Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory Network applications +@direntry +* GNU Taler Challenger: (challenger.info). Customer address validation service +@end direntry + +@c %**end of header + +@copying +@quotation +GNU Taler 0.9.4, Apr 12, 2024 + +GNU Taler team + +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Challenger Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Challenger Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-challenger-manual doc}@anchor{0} +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2023, 2024 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff +@c @author Florian Dold + +@menu +* Introduction:: +* Installation:: +* Configuration Fundamentals:: +* Deployment:: +* Template Customization:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About Challenger:: +* About this manual:: +* Architecture overview:: + +Installation + +* Installing from source:: +* Installing the Challenger binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. + +Configuration Fundamentals + +* Configuration format:: +* Fundamental Setup; Address validation: Fundamental Setup Address validation. +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Database Configuration:: + +Legal policies directory layout + +* Example:: + +Deployment + +* Serving:: +* Reverse Proxy Setup:: +* Launching Challenger:: +* Authorizing clients:: +* OAuth 2.0 integration: OAuth 2 0 integration. +* Database management:: + +Template Customization + +* enter-$ADDRESS_TYPE-form:: +* enter-tan-form:: +* invalid-pin:: +* validation-unknown:: +* invalid-request:: +* internal-error:: + +@end detailmenu +@end menu + +@node Introduction,Installation,Top,Top +@anchor{taler-challenger-manual challenger-operator-manual}@anchor{1}@anchor{taler-challenger-manual introduction}@anchor{2} +@chapter Introduction + + +@menu +* About Challenger:: +* About this manual:: +* Architecture overview:: + +@end menu + +@node About Challenger,About this manual,,Introduction +@anchor{taler-challenger-manual about-challenger}@anchor{3} +@section About Challenger + + +Challenger is an OAuth 2.0-compatible address validation service. +By redirecting a user-agent to a Challenger service a client can +have Challenger validate that the user is able to receive messages +at a particular address and obtain that address via the @code{/info} +endpoint. + +@node About this manual,Architecture overview,About Challenger,Introduction +@anchor{taler-challenger-manual about-this-manual}@anchor{4} +@section About this manual + + +This manual targets system administrators who want to install, +operate or integrate a challenger service. To report issues +or learn about known limitations, please check our +bug tracker@footnote{https://bugs.taler.net}. + +@node Architecture overview,,About this manual,Introduction +@anchor{taler-challenger-manual architecture-overview}@anchor{5} +@section Architecture overview + + +The following picture gives an overview of the Challenger +architecture and the main interactions: + +@image{challenger-figures/challenger,,,,png} + +Here, the `resource owner' is a user that is in control +of some `address' at a messaging service. This could be +an e-mail account, a mobile phone number (for SMS), or +a physical mail address (using the post office as the +messaging service). + +The `resource owner' makes some request that requires +some `client' to be in need of address validation. The +`client' is registered with the Challenger OAuth 2.0 +service and first authorizes an address validation to +be initiated. The client then redirects the resource +owner to the Challenger service. In step (2), the resource +owner submits the address that they claim to own. + +The Challenger service then creates a TAN code and +submits it to the given address via a configurable +`helper script' that is specific to the type of address +being validated. When the resource owner submits the +correct TAN code in step (6), they are given a token +that they can provide to the client. Using this token +the client can then finally obtain the now validated +address in step (8). + +Address data, TAN codes and meta-data such as the number +of failed attempts to submit a TAN code are recorded +in a Postgres database by the Challenger service. + +@node Installation,Configuration Fundamentals,Introduction,Top +@anchor{taler-challenger-manual challengerinstallation}@anchor{6}@anchor{taler-challenger-manual installation}@anchor{7} +@chapter Installation + + +In this guide’s shell-session fragments, the command prompt shows two pieces +of information: + + +@itemize * + +@item +Who is performing the command +(@code{$user} vs @code{root}, and ending character @code{$} vs @code{#}). +@end itemize + +@menu +* Installing from source:: +* Installing the Challenger binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. + +@end menu + +@node Installing from source,Installing the Challenger binary packages on Debian,,Installation +@anchor{taler-challenger-manual installing-from-source}@anchor{8} +@section Installing from source + + +The following instructions will show how to install libgnunetutil and +the core GNU Taler libraries from source. + +The package sources can be find in our +download directory@footnote{http://ftpmirror.gnu.org/taler/}. + +GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format. +The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match. +Exceptions to this general rule are documented in the release notes. +For example, Challenger 1.3.0 should be compatible with Taler exchange 1.4.x +as the MAJOR version matches. A MAJOR version of 0 indicates experimental +development, and you are expected to always run all of the `latest' releases +together (no compatibility guarantees). + +First, the following packages need to be installed before we can compile the +backend: + + +@itemize - + +@item +“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme} +on Debian-based systems (for GNUnet documentation support, can be +omitted if GNUnet is configured with @code{--disable-documentation}) + +@item +libsqlite3 >= 3.16.2 + +@item +GNU libunistring >= 0.9.3 + +@item +libcurl >= 7.26 (or libgnurl >= 7.26) + +@item +libqrencode >= 4.0.0 (Taler merchant only) + +@item +GNU libgcrypt >= 1.6 (1.10 or later highly recommended) + +@item +libsodium >= 1.0 + +@item +libargon2 >= 20171227 + +@item +libjansson >= 2.7 + +@item +PostgreSQL >= 15, including libpq + +@item +GNU libmicrohttpd >= 0.9.71 + +@item +GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) + +@item +Python3 with @code{jinja2} +@end itemize + +If you are on Debian stable or later, the following command may help you +install these dependencies: + +@example +# apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 +@end example + +Before you install GNUnet, you must download and install the dependencies +mentioned in the previous section, otherwise the build may succeed, but could +fail to export some of the tooling required by GNU Taler. + +On Ubuntu, you also need to install pkg-config, for example: + +@example +$ apt-get install pkg-config +@end example + +To install GNUnet, unpack the tarball and change +into the resulting directory, then proceed as follows: + +@example +$ ./configure [--prefix=GNUNETPFX] +$ # Each dependency can be fetched from non standard locations via +$ # the '--with-<LIBNAME>' option. See './configure --help'. +$ make +# make install +# ldconfig +@end example + +If you did not specify a prefix, GNUnet will install to @code{/usr/local}, +which requires you to run the last step as @code{root}. +The @code{ldconfig} command (also run as @code{root}) makes the +shared object libraries (@code{.so} files) +visible to the various installed programs. + +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +There is no need to actually run a GNUnet peer or a Taler exchange to use +Challenger – all Challenger needs from GNUnet and Taler are a number of +headers and libraries! + +After installing GNUnet, unpack the GNU Taler exchange tarball, +change into the resulting directory, and proceed as follows: + +@example +$ ./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 +@end example + +If you did not specify a prefix, the exchange will install to @code{/usr/local}, +which requires you to run the last step as @code{root}. You have to specify +@code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the +previous step. + +TBD. + +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +@node Installing the Challenger binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation +@anchor{taler-challenger-manual installing-the-challenger-binary-packages-on-debian}@anchor{9} +@section Installing the Challenger binary packages on Debian + + +To install the GNU Taler Debian packages, first ensure that you have +the right Debian distribution. At this time, the packages are built for +Debian bookworm. + +You need to add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main +@end example + +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Challenger, you can now simply run: + +@example +# apt install challenger +@end example + +Note that the package does not perform any configuration work except for +setting up the various users and the systemd service scripts. You still must +configure at least the database, HTTP reverse proxy (typically with TLS +certificates) and the terms of service. + +@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the Challenger binary packages on Debian,Installation +@anchor{taler-challenger-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{a} +@section Installing the GNU Taler binary packages on Trisquel + + +To install the GNU Taler Trisquel packages, first ensure that you have +the right Trisquel distribution. Packages are currently available for +Trisquel GNU/Linux 10.0. Simply follow the same instructions provided +for Ubuntu. + +@node Installing the GNU Taler binary packages on Ubuntu,Services users groups and file system hierarchy,Installing the GNU Taler binary packages on Trisquel,Installation +@anchor{taler-challenger-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{b} +@section Installing the GNU Taler binary packages on Ubuntu + + +To install the GNU Taler Ubuntu packages, first ensure that you have +the right Ubuntu distribution. At this time, the packages are built for +Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. + +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example + +For Ubuntu Mantic use this instead: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic +@end example + +The last line is crucial, as it adds the GNU Taler packages. + +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler exchange, you can now simply run: + +@example +# apt install challenger +@end example + +Note that the package does not perform any configuration work except for +setting up the various users and the systemd service scripts. You still must +configure at least the database, HTTP reverse proxy (typically with TLS +certificates), and the terms of service. + +@node Services users groups and file system hierarchy,,Installing the GNU Taler binary packages on Ubuntu,Installation +@anchor{taler-challenger-manual services-users-groups-and-file-system-hierarchy}@anchor{c} +@section Services, users, groups and file system hierarchy + + +The `challenger' package will use several system users +to compartmentalize different parts of the system: + + +@itemize * + +@item +@code{challenger-httpd}: runs the HTTP daemon with the core business logic. + +@item +@code{postgres}: runs the PostgreSQL database (from `postgresql' package). + +@item +@code{www-data}: runs the frontend HTTPS service with the TLS keys (from `nginx' package). +@end itemize + +The package will deploy a systemd service files in +@code{/usr/lib/systemd/system/} for Challenger: + + +@itemize * + +@item +@code{challenger-httpd.service}: the Challenger logic with the public REST API. +@end itemize + +@node Configuration Fundamentals,Deployment,Installation,Top +@anchor{taler-challenger-manual configuration-fundamentals}@anchor{d} +@chapter Configuration Fundamentals + + +This chapter provides fundamental details about the exchange configuration. + +The configuration for all Taler components uses a single configuration file +as entry point: @code{/etc/challenger/challenger.conf}. + +System defaults are automatically loaded from files in +@code{/usr/share/challenger/config.d}. These default files should never be modified. + +The default configuration @code{challenger.conf} configuration file also includes all +configuration files in @code{/etc/challenger/conf.d}. + +To view the entire configuration annotated with the source of each configuration option, you +can use the @code{challenger-config} helper: + +@example +[root@@exchange-online]# challenger-config --diagnostics +< ... annotated, full configuration ... > +@end example + +@cartouche +@quotation Warning +While @code{challenger-config} also supports rewriting configuration files, we strongly +recommend to edit configuration files manually, as @code{challenger-config} does not +preserve comments and, by default, rewrites @code{/etc/challenger/challenger.conf}. +@end quotation +@end cartouche + +@menu +* Configuration format:: +* Fundamental Setup; Address validation: Fundamental Setup Address validation. +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Database Configuration:: + +@end menu + +@node Configuration format,Fundamental Setup Address validation,,Configuration Fundamentals +@anchor{taler-challenger-manual configuration-format}@anchor{e} +@section Configuration format + + +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation +prefix. Different components must be installed to the same prefix. + +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the `-c' +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass @code{-c +/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf} +the primary location for the configuration. + +A config file is a text file containing sections, and each section +contains maps options to their values. Configuration files follow +basically the INI syntax: + +@example +[section1] +value1 = string +value2 = 23 + +[section2] +value21 = string +value22 = /path22 +@end example + +Comments start with a hash (@code{#}). Throughout the configuration, it is +possible to use @code{$}-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those +variables that are unset, by using the following syntax: +@code{$@{VAR:-default@}}. There are two ways a user can set the value +of @code{$}-prefixable variables: + +@quotation + + +@enumerate + +@item +by defining them under a @code{[paths]} section: +@end enumerate + +@quotation + +@example +[paths] +TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data +.. +[section-x] +path-x = $@{TALER_DEPLOYMENT_SHARED@}/x +@end example +@end quotation + + +@enumerate 2 + +@item +or by setting them in the environment: +@end enumerate + +@quotation + +@example +$ export VAR=/x +@end example +@end quotation +@end quotation + +The configuration loader will give precedence to variables set under +@code{[path]} over environment variables. + +The utility @code{taler-config}, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option @code{-f} is particularly useful to resolve +pathnames, when they use several levels of @code{$}-expanded variables. See +@code{taler-config --help}. + +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. + +@node Fundamental Setup Address validation,Legal conditions for using the service,Configuration format,Configuration Fundamentals +@anchor{taler-challenger-manual fundamental-setup-address-validation}@anchor{f} +@section Fundamental Setup: Address validation + + +Each challenger service is designed to validate one type of address. Possible +address types include: + +@quotation + + +@itemize * + +@item +phone numbers (via SMS) + +@item +e-mail addresses (via SMTP) + +@item +mail addresses (via postal service) +@end itemize +@end quotation + +In principle, additional types of addresses can easily be added by extending +the respective HTML and programs to send challenges to the new address type. + +To make different types of address validations possible, the Challenger +configuration contains two configuration options. + +@quotation + + +@enumerate + +@item +The @code{ADDRESS_TYPE} configuration option informs Challenger about the +type of address it is expected to validate. It is returned as part of +the OAuth 2.0 @code{/info} endpoint to the client, and is typically also +used when deciding how to render the HTML form for address entry that is +shown to the user. + +@item +The @code{AUTH_COMMAND} configuration option specifies which command +Challenger should run to send a challenge to an address. The actual +address is given to this subcommand as the first argument (@code{$1}), +while the text with the challenge is passed to standard input. +The subcommand should terminate with a status code of 0 on success. +@end enumerate +@end quotation + + +@float LiteralBlock + +@caption{/etc/challenger/challenger.conf} + +@example + [challenger] + ADDRESS_TYPE = email + AUTH_COMMAND = challenger-send-email.sh + # ... rest of file ... +@end example + +@end float + + +Challenger comes with @code{AUTH_COMMAND} shell scripts for sending e-mail, SMS +and postal mail. Note that for SMS and postal mail the Challenger scripts uses +third party services to actually send the SMS or print and mail the postal +mail. These third parties naturally charge money for their services, and thus +the Challenger administrator will need to add the respective credentials to +the SMS and postal mail scripts before they can function. In any case, these +scripts should be primarily seen as `examples' on how to write authentication +commands. + +@quotation + +..note: + +@example +We strongly welcome contributions for additional scripts with alternative +providers or for new types of addresses. +@end example +@end quotation + +@node Legal conditions for using the service,Terms of Service,Fundamental Setup Address validation,Configuration Fundamentals +@anchor{taler-challenger-manual legal-conditions-for-using-the-service}@anchor{10} +@section Legal conditions for using the service + + +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff + +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. + +@node Terms of Service,Privacy Policy,Legal conditions for using the service,Configuration Fundamentals +@anchor{taler-challenger-manual terms-of-service}@anchor{11} +@section Terms of Service + + +The service has an endpoint “/terms” to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. + +To configure the terms of service response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. +This value must be changed whenever the terms of service are +updated. A common value to use would be a version number. +Note that if you change the @code{TERMS_ETAG}, you MUST also provide +the respective files in @code{TERMS_DIR} (see below). + +@item +@code{TERMS_DIR}: The directory that contains the terms of service. +The files in the directory must be readable to the service +process. +@end itemize + +@node Privacy Policy,Legal policies directory layout,Terms of Service,Configuration Fundamentals +@anchor{taler-challenger-manual privacy-policy}@anchor{12} +@section Privacy Policy + + +The service has an endpoint “/pp” to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy. +This value must be changed whenever the privacy policy is +updated. A common value to use would be a version number. +Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide +the respective files in @code{PRIVACY_DIR} (see below). + +@item +@code{PRIVACY_DIR}: The directory that contains the privacy policy. +The files in the directory must be readable to the service +process. +@end itemize + +@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Configuration Fundamentals +@anchor{taler-challenger-manual legal-policies-directory-layout}@anchor{13} +@section Legal policies directory layout + + +The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using two-letter language codes +like “en”, “de”, or “jp”. Each of these directories would then hold +translations of the current terms of service into the respective language. +Empty directories are permitted in case translations are not available. + +Then, inside each language directory, files with the name of the value set as +the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present, +the service may show a warning on startup. + +@menu +* Example:: + +@end menu + +@node Example,,,Legal policies directory layout +@anchor{taler-challenger-manual example}@anchor{14} +@subsection Example + + +A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be: + + +@itemize - + +@item +TERMS_DIR/en/tos-v0.txt + +@item +TERMS_DIR/en/tos-v0.html + +@item +TERMS_DIR/en/tos-v0.pdf + +@item +TERMS_DIR/en/tos-v0.epub + +@item +TERMS_DIR/en/tos-v0.md + +@item +TERMS_DIR/de/tos-v0.txt + +@item +TERMS_DIR/de/tos-v0.html + +@item +TERMS_DIR/de/tos-v0.pdf + +@item +TERMS_DIR/de/tos-v0.epub + +@item +TERMS_DIR/de/tos-v0.md +@end itemize + +If the user requests an HTML format with language preferences “fr” followed by +“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +French. + +@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Configuration Fundamentals +@anchor{taler-challenger-manual generating-the-legal-terms}@anchor{15} +@section Generating the Legal Terms + + +The @code{taler-terms-generator} script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in @code{.rst} format and GNU gettext +translations in @code{.po} format. + +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective @code{ETAG}. The +resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document. + +Once you have written the @code{$ETAG.rst} file in English, you can +generate the first set of outputs: + +@example +$ taler-terms-generator -i $ETAG +@end example + +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in @code{$PREFIX/share/terms/}. The generator +has a few options which are documented in its man page. + +@node Adding translations,Updating legal documents,Generating the Legal Terms,Configuration Fundamentals +@anchor{taler-challenger-manual adding-translations}@anchor{16} +@section Adding translations + + +Translations must be available in subdirectories +@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}. +To start translating, you first need to add a new +language: + +@example +$ taler-terms-generator -i $ETAG -l $LANGUAGE +@end example + +Here, @code{$LANGUAGE} should be a two-letter language +code like @code{de} or @code{fr}. The command will generate +a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po} +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the @code{.po} +file. Afterwards, simply re-run + +@example +$ taler-terms-generator -i $ETAG +@end example + +to make the current translation(s) available to the +service. + +@cartouche +@quotation Note +You must restart the service whenever adding or updating legal documents or their translations. +@end quotation +@end cartouche + +@node Updating legal documents,Database Configuration,Adding translations,Configuration Fundamentals +@anchor{taler-challenger-manual updating-legal-documents}@anchor{17} +@section Updating legal documents + + +When making minor changes without legal implications, edit the @code{.rst} file, +then re-run the step to add a new language for each existing translation to +produce an updated @code{.po} file. Translate the sentences that have changed and +finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to +create the final files. + +When making major changes with legal implications, you should first rename (or +copy) the existing @code{.rst} file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the @code{.po} files, +complete the translations and re-create the final files. Finally, do not +forget to update the @code{ETAG} configuration option to the new name and to +restart the service. + +@node Database Configuration,,Updating legal documents,Configuration Fundamentals +@anchor{taler-challenger-manual database-configuration}@anchor{18} +@section Database Configuration + + +The access credentials for the Challenger database are configured in +@code{/etc/challenger/challenger.conf}. Currently, only PostgreSQL is +supported as a database backend. + +@cartouche +@quotation Note +The `challenger-dbconfig' tool can be used to automate the database +setup. When using the Debian/Ubuntu packages, the user should already have +been created, so you can just run the tool without any arguments and should +have a working database configuration. Subsequently, you should still run +`taler-challenger-dbinit' as the @code{challenger-httpd} user to +initialize the database schema. +@end quotation +@end cartouche + +To create a database for Challenger on the local system, run: + +@example +[root@@exchange-online]# su - postgres +[postgres@@exchange-online]# createuser challenger-httpd +[postgres@@exchange-online]# createdb -O challenger-httpd challenger +[postgres@@exchange-online]# exit +@end example + +This will create a @code{challenger} database owned by the @code{taler-httpd} user. +We will use that user later to perform database maintenance operations. + +Assuming the above database setup, the database credentials to configure +in the configuration file would simply be: + + +@float LiteralBlock + +@caption{/etc/challenger/challenger.conf} + +@example +[challenger] +DB = postgres + +[challenger-postgres] +CONFIG = postgres:///challenger +@end example + +@end float + + +If the database is run on a different host, please follow the instructions +from the PostgreSQL manual for configuring remote access. + +After configuring the database credentials, the Challenger database needs +to be initialized with the following command: + +@example +[root@@exchange-online]# sudo -u challenger-httpd challenger-dbinit + +..note:: + + To run this command, the user must have `@w{`}CREATE TABLE`@w{`}, `@w{`}CREATE + INDEX`@w{`}, `@w{`}ALTER TABLE`@w{`} and (in the future possibly even) `@w{`}DROP TABLE`@w{`} + permissions. Those permissions are only required for this step (which may + have to be repeated when upgrading a deployment). Afterwards, during + normal operation, permissions to `@w{`}CREATE`@w{`} or `@w{`}ALTER`@w{`} tables are not + required by Challenger and thus should not be granted. For more + information, see :doc:`manpages/challenger-dbinit.1`. +@end example + +@node Deployment,Template Customization,Configuration Fundamentals,Top +@anchor{taler-challenger-manual deployment}@anchor{19} +@chapter Deployment + + +This chapter describes how to deploy Challenger once the basic installation +and configuration are completed. + +@menu +* Serving:: +* Reverse Proxy Setup:: +* Launching Challenger:: +* Authorizing clients:: +* OAuth 2.0 integration: OAuth 2 0 integration. +* Database management:: + +@end menu + +@node Serving,Reverse Proxy Setup,,Deployment +@anchor{taler-challenger-manual challengerserving}@anchor{1a}@anchor{taler-challenger-manual serving}@anchor{1b} +@section Serving + + +The Challenger can serve HTTP over both TCP and UNIX domain socket. + +The following options are to be configured in the section @code{[challenger]}: + + +@itemize - + +@item +@code{SERVE}: Must be set to @code{tcp} to serve HTTP over TCP, or @code{unix} to serve +HTTP over a UNIX domain socket. + +@item +@code{PORT}: Set to the TCP port to listen on if @code{SERVE} is @code{tcp}. + +@item +@code{UNIXPATH}: Set to the UNIX domain socket path to listen on if @code{SERVE} is +@code{unix}. + +@item + +@table @asis + +@item @code{UNIXPATH_MODE}: Number giving the mode with the access permission mask + +for the @code{UNIXPATH} (i.e. 660 = @code{rw-rw---}). Make sure to set it in such +a way that your reverse proxy has permissions to access the UNIX domain +socket. The default (660) assumes that the reverse proxy is a member of +the group under which the exchange HTTP server is running. +@end table +@end itemize + +@node Reverse Proxy Setup,Launching Challenger,Serving,Deployment +@anchor{taler-challenger-manual challengerreverseproxy}@anchor{1c}@anchor{taler-challenger-manual reverse-proxy-setup}@anchor{1d} +@section Reverse Proxy Setup + + +By default, the @code{challenger-httpd} service listens for HTTP connections +on a UNIX domain socket. To make the service publicly available, a reverse +proxy such as nginx should be used. You must configure the reverse proxy +to use TLS as this is required by OAuth 2.0. + +The @code{challenger} package ships with a sample configuration that can be +enabled in nginx: + +@example +[root@@exchange-online]# vim /etc/nginx/sites-available/challenger +< ... customize configuration ... > +[root@@exchange-online]# ln -s /etc/nginx/sites-available/challenger \ + /etc/nginx/sites-enabled/challenger +[root@@exchange-online]# systemctl reload nginx +@end example + +@node Launching Challenger,Authorizing clients,Reverse Proxy Setup,Deployment +@anchor{taler-challenger-manual launching-challenger}@anchor{1e} +@section Launching Challenger + + +A running exchange requires starting the following processes: + + +@itemize - + +@item +@code{challenger-httpd} (needs database access) +@end itemize + +The processes should be started via a hypervisor like +@code{systemd} or @code{gnunet-arm} that automatically re-starts them should they +have terminated unexpectedly. Furthermore, the hypervisor +`should' periodically re-start the service (say once per hour) +to limit Postgres database memory utilization. + +@cartouche +@quotation Note +The @code{challenger-httpd} does not ship with HTTPS enabled by default. +It must thus be run behind an HTTPS reverse proxy that performs +TLS termination on the same system. Thus, it would typically be configured +to listen on a UNIX domain socket. +@end quotation +@end cartouche + +Given proper packaging, all of the above are realized via a simple systemd +target. This enables Challenger to be properly started using a simple command: + +@example +# systemctl start challenger-httpd.service +@end example + +@node Authorizing clients,OAuth 2 0 integration,Launching Challenger,Deployment +@anchor{taler-challenger-manual authorizing-clients}@anchor{1f} +@section Authorizing clients + + +Before clients can use Challenger, they must be explicitly configured. Each +client is identified via its OAuth 2.0 REDIRECT URI. Thus, a client must have +exactly one REDIRECT URI + +@quotation + +..note: + +@example +The OAuth 2.0 specification allows for a client to register +zero or multiple REDIRECT URIs. However, zero is insecure +as it creates an open redirector, and multiple REDIRECT URIs +can trivially be implemented with Challenger by adding more +clients. +@end example +@end quotation + +You can add or remove clients at any time; the Challenger service does not +need to be running, but if it is you can still add or remove clients without +restarting the service. To add (or remove) a client, you must use the +@code{challenger-admin} command: + +@example +# sudo -u challenger-httpd challenger-admin --add=$SECRET $REDIRECT_URI +@end example + +Here, @code{$SECRET} is the client secret of OAuth 2.0 which will be used in +various parts of the protocol to authenticate the client. The +@code{$REDIRECT_URI} is the URI where the user-agent will be redirected to upon +completion of the process. The @code{challenger-admin} command will +then output the `client ID', which will be a unique positive number. +The first time you run the command, you will thus likely see: +@code{Client added. Client ID is: 1}. This client ID, the @code{$SECRET} +and the @code{$REDIRECT_URI} will form the foundation for the OAuth 2.0 +configuration. + +@node OAuth 2 0 integration,Database management,Authorizing clients,Deployment +@anchor{taler-challenger-manual oauth-2-0-integration}@anchor{20} +@section OAuth 2.0 integration + + +When integrating Challenger into an OAuth 2.0 process, you need to provide the +three options from the previous section, but also the authorization, token and +info endpoints. For Challenger, these are @code{/authorize}, @code{/token} and +@code{/info}. However, the @code{/authorize} endpoint is special, as it is actually +@code{/authorize/$NONCE} where @code{$NONCE} is a nonce that must be first requested +by the client using the @code{/setup/$CLIENT_ID} endpoint! + +@quotation + +..note: + +@example +This extra step prevents user-agents from (ab)using the Challenger service +to send challenges to addresses even when there is no authorized client +that desires address validation. This is an important feature as address +validation could be expensive. +@end example +@end quotation + +Thus, to generate the authorization URL, a client must first POST to +@code{/setup/$CLIENT_ID} using their client secret in an @code{Authorization: Bearer $SECRET} +HTTP header to obtain a fresh @code{$NONCE}. + +In the GNU Taler exchange configuration, this is indicated by appending +@code{#setup} to the @code{KYC_OAUTH2_AUTHORIZE_URL} endpoint. Be careful to quote +the URL, as @code{#} is otherwise interpreted as the beginning of a comment by +the configuration file syntax: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-oauth2.conf} + +@example +[kyc-provider-example-oauth2] +LOGIC = oauth2 +# (generic options omitted) +KYC_OAUTH2_AUTHORIZE_URL = "https://challenger.example.com/authorize#setup" +KYC_OAUTH2_TOKEN_URL = "https://challenger.example.com/token" +KYC_OAUTH2_INFO_URL = "https://challenger.example.com/info" +KYC_OAUTH2_CLIENT_ID = 1 +KYC_OAUTH2_CLIENT_SECRET = "$SECRET" +@end example + +@end float + + +@node Database management,,OAuth 2 0 integration,Deployment +@anchor{taler-challenger-manual database-management}@anchor{21} +@section Database management + + +@quotation + +@cartouche +@quotation Note +We advise to make good backups before experimenting with +the database. +@end quotation +@end cartouche +@end quotation + +To update the Challenger database after upgrading to a newer +version of Challenger, you should simply re-run @code{challenger-dbinit}. +Without further options, this command is expected to preserve +all data and only migrate the existing database to the latest +schema: + +@example +$ challenger-dbinit +@end example + +To delete stale data from the Challenger database, you can use +garbage collection: + +@example +$ challenger-dbinit --garbagecollect +@end example + +The Challenger database can be re-initialized using: + +@example +$ challenger-dbinit --reset +@end example + +However, running this command will result in all data in the database +being lost. + +@node Template Customization,,Deployment,Top +@anchor{taler-challenger-manual challengercustomization}@anchor{22}@anchor{taler-challenger-manual template-customization}@anchor{23} +@chapter Template Customization + + +The Challenger service comes with various HTML templates that are shown to +guide users through the process. Challenger uses Mustach@footnote{https://gitlab.com/jbol/mustach} as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the @code{share/challenger/templates/} directory. The file names must be of +the form @code{$NAME.$LANG.must} where @code{$NAME} is the name of the template and +@code{$LANG} is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. The +subsection title is the @code{$NAME} of the respective template. + +@menu +* enter-$ADDRESS_TYPE-form:: +* enter-tan-form:: +* invalid-pin:: +* validation-unknown:: +* invalid-request:: +* internal-error:: + +@end menu + +@node enter-$ADDRESS_TYPE-form,enter-tan-form,,Template Customization +@anchor{taler-challenger-manual enter-address-type-form}@anchor{24} +@section enter-$ADDRESS_TYPE-form + + +These templates are used to ask the user to enter the address that challenger +is expected to validate. Here, @code{$ADDRESS_TYPE} will be replaced by the +@code{ADDRESS_TYPE} configuration option in the @code{[challenger]} section of the +configuration file. Typical values include @code{address} (for physical mailing +addresses), @code{phone} (for mobile phone numbers) and @code{email} (for email +addresses). For testing, @code{file} (where the TAN code is written into a local +file) is also supported. + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +restrictions: Object; map of keys (names of the fields of the address to be entered by the user) to objects with a “regex” (string) containing an extended Posix regular expression for allowed address field values, and a “hint”/”hint_i18n” giving a human-readable explanation to display if the value entered by the user does not match the regex. Keys that are not mapped to such an object have no restriction on the value provided by the user. See “ADDRESS_RESTRICTIONS” in the challenger configuration. + +@item +fix_address: boolean; indicates if the given address cannot be changed +anymore, the form should be read-only if set to true. + +@item +nonce: String; unique value identifying the challenge, should be shown +to the user so that they can recognize it when they receive the TAN code + +@item +last_address: Object; form values from the previous submission if available, +details depend on the @code{ADDRESS_TYPE}, should be used to pre-populate the form + +@item +changes_left: Integer; number of times the address can still be changed, +may or may not be shown to the user +@end itemize +@end quotation + +@node enter-tan-form,invalid-pin,enter-$ADDRESS_TYPE-form,Template Customization +@anchor{taler-challenger-manual enter-tan-form}@anchor{25} +@section enter-tan-form + + +This page should generate the HTML form for the user to enter the TAN code +that they received at the respective address. + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +nonce: String; unique value identifying the challenge, should be shown +to the user so that they can match it to the TAN code they received + +@item +attempts_left: Integer; how many more attempts are allowed, might be +shown to the user, highlighting might be appropriate for low values +such as 1 or 2 (the form will never be used if the value is zero) + +@item +address: Object; the address that is being validated, might be shown +or not + +@item +transmitted: boolean; true if we just retransmitted the challenge, +false if we sent a challenge recently and thus refused to transmit it +again this time; might make a useful hint to the user + +@item +next_tx_time: String; timestamp explaining when we would re-transmit +the challenge the next time (at the earliest) if requested by the user +@end itemize +@end quotation + +@node invalid-pin,validation-unknown,enter-tan-form,Template Customization +@anchor{taler-challenger-manual invalid-pin}@anchor{26} +@section invalid-pin + + +The user has provided an invalid TAN code (HTTP 403 Forbidden). + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +addresses_left: Integer; how many times is the user still allowed to +change the address; if 0, the user should not be shown a link to jump +to the address entry form + +@item +pin_transmissions_left: Integer; how many times might the PIN still +be retransmitted + +@item +auth_attempts_left: Integer; how many times might the user still try +entering the PIN code + +@item +exhausted: Bool; if true, the PIN was not even evaluated as the user previously exhausted the number of attempts + +@item +no_challenge: Bool; if true, the PIN was not even evaluated as no challenge was ever issued (the user must have skipped the step of providing their address first!) +@end itemize +@end quotation + +If both `pin_transmissions_left' and `auth_attempts_left' are zero, the link +to re-enter the PIN should be hidden and the user should only be allowed to +specify a different address. The form will never be generated if all three +values are zero. (Thus there is always at least one valid choice when the form +is shown.) + +@node validation-unknown,invalid-request,invalid-pin,Template Customization +@anchor{taler-challenger-manual validation-unknown}@anchor{27} +@section validation-unknown + + +The user has tried to access a validation process that is not known to the +backend (HTTP 404 Not Found). + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize +@end quotation + +@node invalid-request,internal-error,validation-unknown,Template Customization +@anchor{taler-challenger-manual invalid-request}@anchor{28} +@section invalid-request + + +The request of the client is invalid (HTTP 400 Bad Request). + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize +@end quotation + +@node internal-error,,invalid-request,Template Customization +@anchor{taler-challenger-manual internal-error}@anchor{29} +@section internal-error + + +The service experienced an internal error (HTTP 500 Internal Server Error). + +The template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize +@end quotation + +@c %**end of body +@bye diff --git a/texinfo/taler-auditor.texi b/texinfo/taler-auditor.texi index e1a0b384..92fee90d 100644 --- a/texinfo/taler-auditor.texi +++ b/texinfo/taler-auditor.texi @@ -3,29 +3,27 @@ @setfilename taler-auditor.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Auditor Manual @defindex ge @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-auditor.info). DESCRIPTION +* GNU Taler Auditor: (taler-auditor.info). External audit for Taler Exchange operation @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.9.4, Apr 12, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -50,17 +48,17 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-auditor-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2019-2020 Taler Systems SA +@c Copyright (C) 2019-2021 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the -@c terms of the GNU General Public License as published by the Free Software +@c terms of the GNU Affero General Public License as published by the Free Software @c Foundation; either version 2.1, or (at your option) any later version. @c @c TALER is distributed in the hope that it will be useful, but WITHOUT ANY @c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -@c A PARTICULAR PURPOSE. See the GNU General Public License for more details. +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. @c -@c You should have received a copy of the GNU General Public License along with +@c You should have received a copy of the GNU Affero General Public License along with @c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @c @c @author Christian Grothoff @@ -68,6 +66,7 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @menu * Introduction:: * Installation:: +* System setup:: * Configuration:: * Deployment:: * Operation:: @@ -88,15 +87,32 @@ Installation * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: + +System setup + +* UNIX accounts:: +* Databases and users:: Configuration * Configuration format:: -* Using taler-config:: +* Initial configuration:: * Keys:: -* Serving:: +* Configuring the auditor’s REST endpoint:: * Bank account:: * Database:: +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: + +Legal policies directory layout + +* Example:: Deployment @@ -121,7 +137,7 @@ Operation Auditor implementation guide -* The auditor's database:: +* The auditor’s database:: * Invariants checked by the auditor:: * Testing the auditor:: @@ -137,7 +153,7 @@ Invariants checked by the auditor @end menu @node Introduction,Installation,Top,Top -@anchor{taler-auditor-manual gnu-taler-auditor-operator-manual}@anchor{1}@anchor{taler-auditor-manual introduction}@anchor{2} +@anchor{taler-auditor-manual auditor-operator-manual}@anchor{1}@anchor{taler-auditor-manual introduction}@anchor{2} @chapter Introduction @@ -157,6 +173,21 @@ to become readable. @section About GNU Taler +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic @@ -189,21 +220,21 @@ to other parties. To perform this duty, you will need at least (read-only) access to the bank transactions of the exchange, as well as a continuously synchronized replica -of the exchange's database. The general assumption for running the auditor +of the exchange’s database. The general assumption for running the auditor is that this is done on a separate system controlled by the auditor. After all, the goal is to detect nerfarious activity of the exchange operator, which cannot be effectively done on a machine controlled by the exchange operator. -For this, every auditor needs to operate a Postgres database. The data +For this, every auditor needs to operate a PostgreSQL database. The data collected will include sensitive information about Taler users, including withdrawals made by consumers and income received by merchants. As a result, the auditor is expected to provide high confidentiality for the database. In general, the auditor does not have to offer high-availability: the exchange operator can continue operations without the auditor, and the auditor can -catch up with it later when the auditor's systems are restored. However, of +catch up with it later when the auditor’s systems are restored. However, of course any downtime would provide a window of opportunity for fraud and should -thus be minimized. Finally, the auditor's copy of the exchange's database can +thus be minimized. Finally, the auditor’s copy of the exchange’s database can be useful as a backup to the exchange in case the exchange experiences a loss of its own copies. Thus, business agreements between auditor and exchanges may include availability requirements as well. @@ -211,7 +242,7 @@ include availability requirements as well. Then, with the software provided, auditors can verify the cryptographic proofs collected by the exchange and detect if any improper bank transactions have been made. There are additional tasks which an auditor should perform. While this -manual only focuses on the audit of the exchange's database and wire transfers +manual only focuses on the audit of the exchange’s database and wire transfers with the existing tools, a proper auditor should also perform the following tasks: @@ -237,7 +268,7 @@ verification that the exchange properly implements the @code{/link} protocol @item verification that the exchange properly reports coins issued during the refresh protocol (by irregularly refreshing coins withdrawn by -the auditor and comparing against the exchange's database --- the +the auditor and comparing against the exchange’s database — the code required to support this is not yet implemented) @end itemize @@ -258,8 +289,8 @@ oversight function. Auditors should generally be independent third parties that verify that the exchange operates correctly. However, an exchange is likely to also run the auditing logic, as it is also used to calculate the exchange’s profits, risk -and liabilities. Furthermore, it's usually a good idea to not only rely on -third parties to verify one's own work. +and liabilities. Furthermore, it’s usually a good idea to not only rely on +third parties to verify one’s own work. The Taler software stack for an auditor consists of the following components: @@ -268,7 +299,7 @@ components: @itemize - @item -DBMS: Postgres +DBMS: PostgreSQL The auditor requires a DBMS to store a local copy of the transaction history for the Taler exchange, as well as for its own internal bookkeeping and checkpointing. @@ -278,7 +309,7 @@ fail to be imported due to constraint violations, this is an immediate serious concern that must be addressed manually. The software only verifies the content of a well-formed exchange database (well-formed with respect to SQL). For now, the GNU Taler reference implementation -only supports Postgres, but the code could be easily extended to +only supports PostgreSQL, but the code could be easily extended to support another DBMS. @item @@ -291,7 +322,7 @@ the auditor to detect if an exchange is underreporting deposits. In the future, the Web service should be extended to allow customers and merchants to automatically upload cryptographic proof of other violations of the specification by the exchange. However, for now it is assumed that -the respective cryptographic proofs are reported and verified manually --- +the respective cryptographic proofs are reported and verified manually — as with a well-behaved exchange this should obviously be a rare event. The main binary of this component is the @code{taler-auditor-httpd}. @@ -311,7 +342,7 @@ needs access to the wire gateway). The @code{taler-helper-auditor-wire} auditor verifies that the bank transactions performed by the exchange were done properly. This component must have access to the bank account -of the exchange, as well as to a copy of the exchange's database. +of the exchange, as well as to a copy of the exchange’s database. The @code{taler-auditor} script invokes the various helpers, each generating a JSON report. It then invokes the @code{taler-helper-auditor-render.py} @@ -326,7 +357,7 @@ of the report is required, as not every detail in the report is necessarily indicative of a problem. @end itemize -@node Installation,Configuration,Introduction,Top +@node Installation,System setup,Introduction,Top @anchor{taler-auditor-manual installation}@anchor{7} @chapter Installation @@ -334,6 +365,7 @@ indicative of a problem. @menu * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: @end menu @@ -349,6 +381,18 @@ exchange compilation. @itemize - @item +Python3 module @code{jinja2} +@end itemize + + +@itemize - + +@item +“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme} +on Debian-based systems (for GNUnet documentation support, can be +omitted if GNUnet is configured with @code{--disable-documentation}) + +@item libsqlite3 >= 3.16.2 @item @@ -358,10 +402,10 @@ GNU libunistring >= 0.9.3 libcurl >= 7.26 (or libgnurl >= 7.26) @item -libqrencode >= 4.0.0 +libqrencode >= 4.0.0 (Taler merchant only) @item -GNU libgcrypt >= 1.6 +GNU libgcrypt >= 1.6 (1.10 or later highly recommended) @item libsodium >= 1.0 @@ -373,13 +417,40 @@ libargon2 >= 20171227 libjansson >= 2.7 @item -Postgres >= 9.6, including libpq +PostgreSQL >= 15, including libpq @item GNU libmicrohttpd >= 0.9.71 @item -GNUnet >= 0.14.0 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) +GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) + +@item +Python3 with @code{jinja2} +@end itemize + +If you are on Debian stable or later, the following command may help you +install these dependencies: + +@example +# apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 +@end example + + +@itemize - @item GNU Taler exchange (from download directory@footnote{http://ftpmirror.gnu.org/taler/}, @@ -397,6 +468,12 @@ Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. +On Ubuntu, you also need to install pkg-config, for example: + +@example +$ apt-get install pkg-config +@end example + To install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows: @@ -432,45 +509,82 @@ which requires you to run the last step as @code{root}. You have to specify @code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the previous step. -@node Installing the GNU Taler binary packages on Debian,,Installing from source,Installation +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Ubuntu,Installing from source,Installation @anchor{taler-auditor-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{9} @section Installing the GNU Taler binary packages on Debian To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for -Sid, which means you should use a system which at least includes -unstable packages in its source list. We recommend using APT pinning -to limit unstable packages to those explicitly requested. To do this, -set your @code{/etc/apt/preferences} as follows: +Debian bookworm. + +You need to add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: @example -Package: * -Pin: release a=stable -Pin-Priority: 700 +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main +@end example -Package: * -Pin: release a=testing -Pin-Priority: 650 +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: -Package: * -Pin: release a=unstable -Pin-Priority: 600 +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler auditor, you can now simply run: + +@example +# apt install -t sid taler-auditor +@end example + +For the auditor, you must manually configure access to the exchange database, +the HTTP reverse proxy (typically with TLS certificates) and offline signing. + +Sample configuration files for the HTTP reverse proxy can be found in +@code{/etc/taler-auditor/}. -Package: * -Pin: release l=Debian-Security -Pin-Priority: 1000 +@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Debian,Installation +@anchor{taler-auditor-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{a} +@section Installing the GNU Taler binary packages on Ubuntu + + +To install the GNU Taler Ubuntu packages, first ensure that you have +the right Ubuntu distribution. At this time, the packages are built for +Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. + +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar @end example -A typical @code{/etc/apt/sources.list} file for this setup -would look like this: +For Ubuntu Mantic use this instead: @example -deb http://ftp.ch.debian.org/debian/ buster main -deb http://security.debian.org/debian-security buster/updates main -deb http://ftp.ch.debian.org/debian/ testing main -deb http://ftp.ch.debian.org/debian/ unstable main -deb https://deb.taler.net/apt/debian sid main +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic @end example The last line is crucial, as it adds the GNU Taler packages. @@ -479,7 +593,8 @@ Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: @example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg # apt update @end example @@ -492,52 +607,183 @@ You may want to verify the correctness of the Taler Systems key out-of-band. Now your system is ready to install the official GNU Taler binary packages using apt. -To install the Taler auditor, you can now simply run: +To install the Taler exchange, you can now simply run: @example -# apt install taler-auditor +# apt install -t focal-fossa taler-auditor @end example For the auditor, you must manually configure access to the exchange database, the HTTP reverse proxy (typically with TLS certificates) and offline signing. Sample configuration files for the HTTP reverse proxy can be found in -@code{/etc/taler-exchange/}. +@code{/etc/taler-auditor/}. -@node Configuration,Deployment,Installation,Top -@anchor{taler-auditor-manual configuration}@anchor{a} +@node System setup,Configuration,Installation,Top +@anchor{taler-auditor-manual system-setup}@anchor{b} +@chapter System setup + + +@menu +* UNIX accounts:: +* Databases and users:: + +@end menu + +@node UNIX accounts,Databases and users,,System setup +@anchor{taler-auditor-manual unix-accounts}@anchor{c} +@section UNIX accounts + + +For maximum security, you should setup multiple different users (possibly +on different machines) to run Taler auditor components. While it is possible +to skip some of these entirely, or to run all of them as the same user, this +is not recommended for security. The recommended set of users includes: + +@quotation + + +@itemize * + +@item +auditor — runs the main auditing process and HTTP backend + +@item +sync — synchronizes the ingres database with the production database + +@item +helper — runs taler-auditor-offline download and upload commands + +@item +auditor-ingres — imports database from exchange production system + +@item +auditor-wire — imports wire transfer data from bank production system + +@item +offline — manages the offline key, on a separate `offline' machine +@end itemize +@end quotation + +It is suggested that you setup the first five users on the target system(s) +using: + +@example +# add-user --disabled-password $USERNAME +@end example + +Additionally, there are two canonical system users of relevance (which your +distribution would typically create for you): + +@quotation + + +@itemize * + +@item +www-data — runs the HTTPS frontend (usually nginx or Apache) + +@item +postgres — runs the PostgreSQL database +@end itemize +@end quotation + +@node Databases and users,,UNIX accounts,System setup +@anchor{taler-auditor-manual databases-and-users}@anchor{d} +@section Databases and users + + +We recommend using the following databases for the auditor: + +@quotation + + +@itemize * + +@item +exchange-ingres — synchronized exchange database over the network + +@item +exchange-production — local copy of exchange database with trusted schema + +@item +auditor — auditor production database with current state of the audit + +@item +libeufin — local state of the auditor-wire tool for the bank transfer data import +@end itemize +@end quotation + +As the `postgres' user, you can create these databases using: + +@example +# As the 'postgres' user: +$ createdb -O auditor-ingres exchange-ingres +$ createdb -O sync exchange-production +$ createdb -O auditor auditor +$ createdb -O auditor-wire libeufin +@end example + +This will ensure that the correct users have write-access to their +respective database. Next, you need to grant read-only access to +some users to databases owned by other users: + +@example +# As the 'auditor-ingres' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO sync;' | psql exchange-ingres +# As the 'sync' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql exchange-production +# As the 'auditor-wire' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql libeufin +@end example + +@node Configuration,Deployment,System setup,Top +@anchor{taler-auditor-manual configuration}@anchor{e} @chapter Configuration -The auditor's configuration works the same way as the configuration of other +The auditor’s configuration works the same way as the configuration of other Taler components. This section discusses configuration options related to the auditor. @menu * Configuration format:: -* Using taler-config:: +* Initial configuration:: * Keys:: -* Serving:: +* Configuring the auditor’s REST endpoint:: * Bank account:: * Database:: +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: @end menu -@node Configuration format,Using taler-config,,Configuration -@anchor{taler-auditor-manual configuration-format}@anchor{b} +@node Configuration format,Initial configuration,,Configuration +@anchor{taler-auditor-manual configuration-format}@anchor{f} @section Configuration format -In Taler realm, any component obeys to the same pattern to get -configuration values. According to this pattern, once the component has -been installed, the installation deploys default values in -$@{prefix@}/share/taler/config.d/, in .conf files. In order to override -these defaults, the user can write a custom .conf file and either pass -it to the component at execution time, or name it taler.conf and place -it under $HOME/.config/. +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation +prefix. Different components must be installed to the same prefix. + +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the `-c' +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass @code{-c +/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf} +the primary location for the configuration. A config file is a text file containing sections, and each section -contains its values. The right format follows: +contains maps options to their values. Configuration files follow +basically the INI syntax: @example [section1] @@ -549,14 +795,23 @@ value21 = string value22 = /path22 @end example -Throughout any configuration file, it is possible to use @code{$}-prefixed -variables, like @code{$VAR}, especially when they represent filesystem -paths. It is also possible to provide defaults values for those +Comments start with a hash (@code{#}). Throughout the configuration, it is +possible to use @code{$}-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: -@code{$@{VAR:-default@}}. However, there are two ways a user can set -@code{$}-prefixable variables: +@code{$@{VAR:-default@}}. There are two ways a user can set the value +of @code{$}-prefixable variables: + +@quotation -by defining them under a @code{[paths]} section, see example below, + +@enumerate + +@item +by defining them under a @code{[paths]} section: +@end enumerate + +@quotation @example [paths] @@ -565,100 +820,71 @@ TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data [section-x] path-x = $@{TALER_DEPLOYMENT_SHARED@}/x @end example +@end quotation + + +@enumerate 2 +@item or by setting them in the environment: +@end enumerate + +@quotation @example $ export VAR=/x @end example +@end quotation +@end quotation The configuration loader will give precedence to variables set under -@code{[path]}, though. +@code{[path]} over environment variables. -The utility @code{taler-config}, which gets installed along with the -exchange, serves to get and set configuration values without directly -editing the .conf. The option @code{-f} is particularly useful to resolve +The utility @code{taler-config}, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option @code{-f} is particularly useful to resolve pathnames, when they use several levels of @code{$}-expanded variables. See @code{taler-config --help}. -Note that, in this stage of development, the file -@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the -component. For example, both an exchange and a bank can read values from -it. - -The repository @code{git://taler.net/deployment} contains examples of -configuration file used in our demos. See under @code{deployment/config}. - -@quotation - -@strong{Note} - -Expectably, some components will not work just by using default -values, as their work is often interdependent. For example, a -merchant needs to know an exchange URL, or a database name. -@end quotation - -@node Using taler-config,Keys,Configuration format,Configuration -@anchor{taler-auditor-manual using-taler-config}@anchor{c} -@section Using taler-config - - -The tool @code{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 - -@example -$ taler-config -s $SECTION -@end example - -to list all of the configuration values in section @code{$SECTION}. - -Run +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. -@example -$ taler-config -s $section -o $option -@end example +@node Initial configuration,Keys,Configuration format,Configuration +@anchor{taler-auditor-manual initial-configuration}@anchor{10}@anchor{taler-auditor-manual setupbaseurl}@anchor{11} +@section Initial configuration -to extract the respective configuration value for option @code{$option} in -section @code{$section}. -Finally, to change a setting, run +You need to tell the Taler auditor configuration where the +REST API of the auditor will be available to the public: @example -$ taler-config -s $section -o $option -V $value +# Both for the 'offline' *and* the 'auditor' user: +[auditor] +BASE_URL = https://auditor.example.com/ @end example -to set the respective configuration value to @code{$value}. Note that you -have to manually restart the Taler backend after you change the -configuration to make the new configuration go into effect. - -Some default options will use $-variables, such as @code{$DATADIR} within -their value. To expand the @code{$DATADIR} or other $-variables in the -configuration, pass the @code{-f} option to @code{taler-config}. For example, -compare: +The @code{helper} user that is used to download information from the exchange +needs to know details about the exchange. Similarly, the @code{offline} user +needs to check signatures signed with the exchange’s offline key. Hence, you +need to obtain the @code{MASTER_PUBLIC_KEY} from the exchange operator (they need +to run @code{taler-exchange-offline setup}) and the REST endpoint of the exchange +and configure these: @example -$ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE -$ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE +# As the 'helper' and 'offline' users: +[exchange] +BASE_URL = https://exchange.example.com/ +MASTER_PUBLIC_KEY = $SOMELONGBASE32VALUEHERE @end example -While the configuration file is typically located at -@code{$HOME/.config/taler.conf}, an alternative location can be specified -to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} -option. - -@node Keys,Serving,Using taler-config,Configuration -@anchor{taler-auditor-manual auditorkeys}@anchor{d}@anchor{taler-auditor-manual keys}@anchor{e} +@node Keys,Configuring the auditor’s REST endpoint,Initial configuration,Configuration +@anchor{taler-auditor-manual auditorkeys}@anchor{12}@anchor{taler-auditor-manual keys}@anchor{13} @section Keys The auditor works with one signing key to certify that it is auditing -a particular exchange's denomination keys. This key can and should -be kept @emph{offline} (and backed up adequately). As with the exchange's +a particular exchange’s denomination keys. This key can and should +be kept `offline' (and backed up adequately). As with the exchange’s offline key, it is only used for a few cryptographic signatures and thus the respective code can be run on modest hardware, like a Raspberry Pi. @@ -670,15 +896,39 @@ The following values are to be configured in the section @code{[auditor]}: @item @code{AUDITOR_PRIV_FILE}: Path to the auditor’s private key file. +@end itemize + +Note that the default value here should be fine and there is no clear +need to change it. What you do need to do as the @code{offine} user +is to extract the public key: + +@example +# As the 'offline' user: +$ taler-auditor-offline setup +@end example + +This public key must then be provided in the configuration file +of the @code{auditor} user in the @code{[auditor]]} configuration section: + + +@itemize - @item @code{PUBLIC_KEY}: Public key of the auditor, in Base32 encoding. Set from value printed by @code{taler-auditor-offline setup}. @end itemize -@node Serving,Bank account,Keys,Configuration -@anchor{taler-auditor-manual auditorserving}@anchor{f}@anchor{taler-auditor-manual serving}@anchor{10} -@section Serving +You can set this configuration value using: + +@example +# As the 'auditor' and 'helper' users: +[auditor] +PUBLIC_KEY = $SOMELONGBASE32VALUEHERE +@end example + +@node Configuring the auditor’s REST endpoint,Bank account,Keys,Configuration +@anchor{taler-auditor-manual auditorserving}@anchor{14}@anchor{taler-auditor-manual configuring-the-auditor-s-rest-endpoint}@anchor{15} +@section Configuring the auditor’s REST endpoint The auditor can serve HTTP over both TCP and UNIX domain socket. @@ -704,17 +954,17 @@ HTTP over a UNIX domain socket for @code{unixpath} (i.e. 660 = @code{rw-rw----}). @end itemize -@node Bank account,Database,Serving,Configuration -@anchor{taler-auditor-manual auditorbank-account}@anchor{11}@anchor{taler-auditor-manual bank-account}@anchor{12} +@node Bank account,Database,Configuring the auditor’s REST endpoint,Configuration +@anchor{taler-auditor-manual auditorbank-account}@anchor{16}@anchor{taler-auditor-manual bank-account}@anchor{17} @section Bank account -Bank accounts for the auditor are configured in exactly the -same way as bank accounts for the exchange. See the exchange -documentation for details. +Bank accounts for the auditor (user @code{auditor-wire}) are configured in +exactly the same way as bank accounts for the exchange. See the exchange (and +LibEuFin) documentation for details. -@node Database,,Bank account,Configuration -@anchor{taler-auditor-manual auditordatabaseconfiguration}@anchor{13}@anchor{taler-auditor-manual database}@anchor{14} +@node Database,Legal conditions for using the service,Bank account,Configuration +@anchor{taler-auditor-manual auditordatabaseconfiguration}@anchor{18}@anchor{taler-auditor-manual database}@anchor{19} @section Database @@ -730,7 +980,7 @@ choosing the backend, it is mandatory to supply the connection string via an environment variable: @code{TALER_AUDITORDB_POSTGRES_CONFIG}. @item -via configuration option @code{CONFIG}, under section @code{[auditordb-BACKEND]}. +via configuration option @code{CONFIG}, under section @code{[auditordb-$BACKEND]}. For example, the demo exchange is configured as follows: @example @@ -747,14 +997,14 @@ CONFIG = postgres:///auditordemo If an exchange runs its own auditor, it may use the same database for the auditor and the exchange itself. -The @code{taler-auditor-dbinit} tool is used to initialize the auditor's +The @code{taler-auditor-dbinit} tool is used to initialize the auditor’s tables. After running this tool, the rights to CREATE or DROP tables are no longer required and should be removed. Both the @code{taler-auditor-httpd} and the @code{taler-auditor} (and its helpers) also need (read-only) access to a (recent, current, synchronized) copy of the -exchange's database. The configuration options are the same that are also -used when configuring the exchange' database: +exchange’s database. The configuration options are the same that are also +used when configuring the exchange’ database: @quotation @@ -769,20 +1019,260 @@ CONFIG = postgres:///exchangedemo @end example @end quotation +@node Legal conditions for using the service,Terms of Service,Database,Configuration +@anchor{taler-auditor-manual legal-conditions-for-using-the-service}@anchor{1a} +@section Legal conditions for using the service + + +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff + +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. + +@node Terms of Service,Privacy Policy,Legal conditions for using the service,Configuration +@anchor{taler-auditor-manual terms-of-service}@anchor{1b} +@section Terms of Service + + +The service has an endpoint “/terms” to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. + +To configure the terms of service response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. +This value must be changed whenever the terms of service are +updated. A common value to use would be a version number. +Note that if you change the @code{TERMS_ETAG}, you MUST also provide +the respective files in @code{TERMS_DIR} (see below). + +@item +@code{TERMS_DIR}: The directory that contains the terms of service. +The files in the directory must be readable to the service +process. +@end itemize + +@node Privacy Policy,Legal policies directory layout,Terms of Service,Configuration +@anchor{taler-auditor-manual privacy-policy}@anchor{1c} +@section Privacy Policy + + +The service has an endpoint “/pp” to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy. +This value must be changed whenever the privacy policy is +updated. A common value to use would be a version number. +Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide +the respective files in @code{PRIVACY_DIR} (see below). + +@item +@code{PRIVACY_DIR}: The directory that contains the privacy policy. +The files in the directory must be readable to the service +process. +@end itemize + +@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Configuration +@anchor{taler-auditor-manual legal-policies-directory-layout}@anchor{1d} +@section Legal policies directory layout + + +The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using two-letter language codes +like “en”, “de”, or “jp”. Each of these directories would then hold +translations of the current terms of service into the respective language. +Empty directories are permitted in case translations are not available. + +Then, inside each language directory, files with the name of the value set as +the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present, +the service may show a warning on startup. + +@menu +* Example:: + +@end menu + +@node Example,,,Legal policies directory layout +@anchor{taler-auditor-manual example}@anchor{1e} +@subsection Example + + +A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be: + + +@itemize - + +@item +TERMS_DIR/en/tos-v0.txt + +@item +TERMS_DIR/en/tos-v0.html + +@item +TERMS_DIR/en/tos-v0.pdf + +@item +TERMS_DIR/en/tos-v0.epub + +@item +TERMS_DIR/en/tos-v0.md + +@item +TERMS_DIR/de/tos-v0.txt + +@item +TERMS_DIR/de/tos-v0.html + +@item +TERMS_DIR/de/tos-v0.pdf + +@item +TERMS_DIR/de/tos-v0.epub + +@item +TERMS_DIR/de/tos-v0.md +@end itemize + +If the user requests an HTML format with language preferences “fr” followed by +“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +French. + +@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Configuration +@anchor{taler-auditor-manual generating-the-legal-terms}@anchor{1f} +@section Generating the Legal Terms + + +The @code{taler-terms-generator} script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in @code{.rst} format and GNU gettext +translations in @code{.po} format. + +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective @code{ETAG}. The +resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document. + +Once you have written the @code{$ETAG.rst} file in English, you can +generate the first set of outputs: + +@example +$ taler-terms-generator -i $ETAG +@end example + +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in @code{$PREFIX/share/terms/}. The generator +has a few options which are documented in its man page. + +@node Adding translations,Updating legal documents,Generating the Legal Terms,Configuration +@anchor{taler-auditor-manual adding-translations}@anchor{20} +@section Adding translations + + +Translations must be available in subdirectories +@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}. +To start translating, you first need to add a new +language: + +@example +$ taler-terms-generator -i $ETAG -l $LANGUAGE +@end example + +Here, @code{$LANGUAGE} should be a two-letter language +code like @code{de} or @code{fr}. The command will generate +a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po} +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the @code{.po} +file. Afterwards, simply re-run + +@example +$ taler-terms-generator -i $ETAG +@end example + +to make the current translation(s) available to the +service. + +@cartouche +@quotation Note +You must restart the service whenever adding or updating legal documents or their translations. +@end quotation +@end cartouche + +@node Updating legal documents,,Adding translations,Configuration +@anchor{taler-auditor-manual updating-legal-documents}@anchor{21} +@section Updating legal documents + + +When making minor changes without legal implications, edit the @code{.rst} file, +then re-run the step to add a new language for each existing translation to +produce an updated @code{.po} file. Translate the sentences that have changed and +finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to +create the final files. + +When making major changes with legal implications, you should first rename (or +copy) the existing @code{.rst} file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the @code{.po} files, +complete the translations and re-create the final files. Finally, do not +forget to update the @code{ETAG} configuration option to the new name and to +restart the service. + @node Deployment,Operation,Configuration,Top -@anchor{taler-auditor-manual auditordeployment}@anchor{15}@anchor{taler-auditor-manual deployment}@anchor{16} +@anchor{taler-auditor-manual auditordeployment}@anchor{22}@anchor{taler-auditor-manual deployment}@anchor{23} @chapter Deployment -@anchor{taler-auditor-manual wallets}@anchor{17} -Before GNU Taler wallets will happily interact with an exchange, -the respective auditor's public key (to be obtained via @code{taler-auditor-offline setup}) -must be added under the respective currency to the wallet. This -is usually expected to be hard-coded into the Taler wallet. +@anchor{taler-auditor-manual wallets}@anchor{24} +Before GNU Taler wallets will happily interact with an exchange, the +respective auditor’s public key (as obtained via @code{taler-auditor-offline +setup} from the @code{offline} user) must be added under the respective currency +to the wallet. This is usually expected to be hard-coded into the Taler +wallet. Users can also manually add auditors for a particular currency via a Web page offering the respective pairing. -FIXME-DOLD: explain how that Web page works, once it works... +FIXME-DOLD: explain how that Web page works, once it works… @menu * Exchange:: @@ -792,49 +1282,52 @@ FIXME-DOLD: explain how that Web page works, once it works... @end menu @node Exchange,Signing Denominations,,Deployment -@anchor{taler-auditor-manual auditorexchange}@anchor{18}@anchor{taler-auditor-manual exchange}@anchor{19} +@anchor{taler-auditor-manual auditorexchange}@anchor{25}@anchor{taler-auditor-manual exchange}@anchor{26} @section Exchange -The next step is to add the exchange's master public key and the base -URL of the exchange to the list of exchanges audited by the auditor. -This is done using the @code{taler-auditor-exchange} tool. The tool -basically creates the respective record in the auditor's database. +The next step is to add the exchange’s master public key and the base URL of +the exchange to the list of exchanges audited by the auditor. This is done +using the @code{taler-auditor-exchange} tool. The tool basically creates the +respective record in the auditor’s database. -If this step is skipped, the auditor will malfunction at all future -stages with a foreign key violation, as it doesn't know the exchange's -master public key. +If this step is skipped, the auditor will malfunction at all future stages +with a foreign key violation, as it does not know the exchange’s master public +key. @example +# As the 'auditor' user: $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL @end example -The equivalent step must be performed by the exchange operator. -Here, the exchange operator must use the @code{taler-exchange-offline} -tool to add the auditor's public key, base URL and (business) name -to the list of approved auditors of the exchange. For details, -see Auditor-configuration in the exchange operator manual. +An equivalent step must be performed by the exchange operator. Here, the +exchange operator must use the @code{taler-exchange-offline} tool to add the +auditor’s public key, base URL and (business) name to the list of approved +auditors of the exchange. For details, see Auditor-configuration in the +exchange operator manual. @node Signing Denominations,Database<2>,Exchange,Deployment -@anchor{taler-auditor-manual signing-denominations}@anchor{1a}@anchor{taler-auditor-manual signingdenominations}@anchor{1b} +@anchor{taler-auditor-manual signing-denominations}@anchor{27}@anchor{taler-auditor-manual signingdenominations}@anchor{28} @section Signing Denominations @geindex maintenance -This step must be performed regularly whenever the exchange is +These steps must be performed `regularly' whenever the exchange is deploying new denomination keys. After the exchange operator has signed new keys using the @code{taler-exchange-offline} tool, each auditor should run: @example +# As the 'helper' user: $ taler-auditor-offline download > input.json @end example -to import the latest set of denomination keys. The key data -should then be inspected using: +to import the latest set of denomination keys. The key data should then be +copied to the offline system and there be inspected using: @example +# As the 'offline' user: $ taler-auditor-offline show < input.json @end example @@ -847,13 +1340,14 @@ process that is outside of the scope of this document. Note that the @code{input.json} does not contain any confidential data. However, signing the wrong keys would be fatal in that it may allow an illegitimate exchange to convince users that it is a trustworthy operator and subsequently -betray the user's trust that is anchored in the existence of a trustworthy +betray the user’s trust that is anchored in the existence of a trustworthy auditor. Given the verified JSON input, the auditor can then sign it (typically on its offline system) using: @example +# As the 'offline' user: $ taler-auditor-offline sign < input.json > output.json @end example @@ -861,6 +1355,7 @@ The resulting @code{output.json} should then be copied to an online system, and from there uploaded to the exchange using: @example +# As the 'helper' user: $ taler-auditor-offline upload < output.json @end example @@ -875,27 +1370,27 @@ Commands, like @code{taler-auditor-offline}, that support the @code{-l LOGFILE} command-line option, send logging output to standard error by default. @node Database<2>,,Signing Denominations,Deployment -@anchor{taler-auditor-manual auditordatabaseinitialization}@anchor{1c}@anchor{taler-auditor-manual id1}@anchor{1d} +@anchor{taler-auditor-manual auditordatabaseinitialization}@anchor{29}@anchor{taler-auditor-manual id1}@anchor{2a} @section Database The next key step for the auditor is to configure replication of the -@emph{exchange}'s database in-house. This should be performed in two steps +`exchange'’s database in-house. This should be performed in two steps as illustrated in the following figure: @image{taler-auditor-figures/replication,,,,png} -First, the exchange should use standard Postgres replication features to -enable the auditor to obtain a full copy of the exchange's database. -Second, the auditor should make a "trusted" local copy, ensuring that it +First, the exchange should use standard PostgreSQL replication features to +enable the auditor to obtain a full copy of the exchange’s database. +Second, the auditor should make a “trusted” local copy, ensuring that it never replicates malicious changes using @code{taler-auditor-sync}. Both of these steps are described in more detail below. We note that as a result of these steps, the auditor will have three databases: its own production primary database (as configured in -@code{auditordb-postgres}), its on production copy of the exchange's database -(@code{exchangedb-postgress}), and a third, untrusted "ingres" copy of the -exchange database. The untrusted database should run as a separate Postgres +@code{auditordb-postgres}), its on production copy of the exchange’s database +(@code{exchangedb-postgress}), and a third, untrusted “ingres” copy of the +exchange database. The untrusted database should run as a separate PostgreSQL instance and is only accessed via @code{taler-auditor-sync} and the replication mechanism driven by the exchange operator. @@ -906,11 +1401,15 @@ mechanism driven by the exchange operator. @end menu @node Ingres replication of the exchange production database,Safe replication of the ingres database into the auditor production database,,Database<2> -@anchor{taler-auditor-manual ingres-replication-of-the-exchange-production-database}@anchor{1e} +@anchor{taler-auditor-manual ingres-replication-of-the-exchange-production-database}@anchor{2b} @subsection Ingres replication of the exchange production database -The full copy can be obtained in various ways with Postgres. It is +Ingres operation should be done using the @code{auditor-ingres} user — or +depending on the setup parts of the operation may be done by the @code{postgres} +user directly. + +The full copy can be obtained in various ways with PostgreSQL. It is possible to use log shipping with streaming replication as described in @indicateurl{https://www.postgresql.org/docs/13/warm-standby.html}, or to use logical replication, as described in @@ -919,47 +1418,108 @@ that asynchronous replication should suffice. The resulting auditor database should be treated as read-only on the auditor side. The @code{taler-exchange-dbinit} tool can be used to setup the schema, or -the schema can be replicated using Postgres's standard mechanisms. The same +the schema can be replicated using PostgreSQL’s standard mechanisms. The same applies for schema upgrades: if logical replication is used (which does not replicate schema changes), @code{taler-exchange-dbinit} can be used to migrate -the schema(s) in both the ingres and production copies of the exchange's +the schema(s) in both the ingres and production copies of the exchange’s database as well. -For details, we refer to the Postgres manual. +On the exchange side, a database user must be created that has the right +to perform database replication. This is done using: + +@example +# As the 'postgres' user of the exchange: +$ createuser --replication egress +$ echo "ALTER ROLE egress WITH PASSWORD '$PASSWORD'; | psql +$ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange +@end example + +The exchange must share the password of the publication with the auditor. A +good @code{$NAME} relates to the auditor’s business unit name. A secure tunnel +must be setup between the exchange and the auditor, for example using SSH or +Wireguard. + +It is also necessary to edit @code{main.cf} of the exchange and on the auditor +side to enable logical replication. If an exchange has multiple auditors, it +should setup multiple @code{egress} accounts. The exchange must ensure that +the following lines are in the @code{main.cf} PostgreSQL configuration (the port +may differ) to enable replication over the network: + +@example +listen_addresses='*' +port = 5432 +wal_level= logical +@end example + +Equally, the auditor must configure logical replication in the @code{main.cf} +PostgreSQL configuration: + +@example +wal_level= logical +@end example + +Next, the @code{postgres} user of the auditor’s system must first initialize the +local tables: + +@example +# Configure database: +[exchange] +DB = "postgres" +[exchangedb-postgres] +CONFIG = "postgres:///taler-ingress" +@end example + +@example +# As the 'ingress' user of the exchange: +$ taler-exchange-dbinit +@end example + +To complete the replication, the @code{postgres} user of the auditor’s +system must subscribe: + +@example +# As the 'postgres' user of the exchange: +$ createuser --replication egress +$ echo "ALTER ROLE egress WITH PASSWORD '$PASSWORD'; | psql +$ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange +@end example + +For details, we refer to the PostgreSQL manual. @cartouche @quotation Note Depending on the replication method used, the exchange may perform unexpected changes to the schema or perform @code{UPDATE}, @code{DELETE} or @code{DROP} operations on the tables. Hence, the auditor cannot rely upon the -exchange's primary copy to respect schema constraints, especially as we +exchange’s primary copy to respect schema constraints, especially as we have to presume that the exchange could act maliciously. Furthermore, it -is unclear to what degree Postgres database replication mechanisms are +is unclear to what degree PostgreSQL database replication mechanisms are robust against a malicious master database. Thus, the auditor should -isolate its primary copy of the exchange database, including the Postgres +isolate its primary copy of the exchange database, including the PostgreSQL process, from its actual operational data. @end quotation @end cartouche @node Safe replication of the ingres database into the auditor production database,,Ingres replication of the exchange production database,Database<2> -@anchor{taler-auditor-manual safe-replication-of-the-ingres-database-into-the-auditor-production-database}@anchor{1f} +@anchor{taler-auditor-manual safe-replication-of-the-ingres-database-into-the-auditor-production-database}@anchor{2c} @subsection Safe replication of the ingres database into the auditor production database -Using @code{taler-auditor-sync}, the auditor should make a second "safe" copy of -the exchange's ingres database. @code{taler-auditor-sync} basically reads from one -exchange database and inserts all records found into a second exchange -database. If the source database violates invariants, the tool halts with an -error. This way, records violating invariants are never even copied, and in -particular schema changes and deletions or updates are not propagated into the -auditor's production database. +Using @code{taler-auditor-sync} as the @code{sync} user, the auditor should +make a second “safe” copy of the exchange’s ingres database. +@code{taler-auditor-sync} basically reads from one exchange database and inserts +all records found into a second exchange database. If the source database +violates invariants, the tool halts with an error. This way, records violating +invariants are never even copied, and in particular schema changes and +deletions or updates are not propagated into the auditor’s production +database. While @code{taler-auditor-sync} could in theory be run directly against the -exchange's production system, this is likely a bad idea due to the high +exchange’s production system, this is likely a bad idea due to the high latency from the network between auditor and exchange operator. Thus, we -recommend first making an "untrusted" ingress copy of the exchange's -production database using standard Postgres tooling, and then using -@code{taler-auditor-sync} to create a second "safe" copy. The "safe" copy used +recommend first making an “untrusted” ingress copy of the exchange’s +production database using standard PostgreSQL tooling, and then using +@code{taler-auditor-sync} to create a second “safe” copy. The “safe” copy used by the production system should also run under a different UID. Before @code{taler-auditor-sync} can be used, the target database must be @@ -970,17 +1530,42 @@ database, and a second with the options for accessing the destination database. In both cases, likely only the @code{[exchangedb]/CONFIG} option needs to be changed. +To run @code{taler-auditor-sync}, you must first configure two configuration +files that identify the source and destination databases: + +@example +# src.conf +[exchangedb] +CONFIG = "postgres:///auditor-ingres/" +@end example + +@example +# dst.conf +[exchangedb] +CONFIG = "postgres:///auditor/" +@end example + +Now you should be able to launch the synchronization process. You can run +the process via systemd in the background. For a first one-off test, you should +use the @code{-t} option which will cause the process to terminate once the two +databases are synchronized: + +@example +# As the 'sync' user: +$ taler-auditor-sync -s src.conf -d dst.cfg -t +@end example + When the exchange performs garbage collection to @code{DELETE} obsolete records, this change should be automatically replicated to the auditors untrusted -ingress database. However, as @code{taler-auditor-sync} tries to be "safe", -it will not replicate those deletions to the auditor's production database. +ingress database. However, as @code{taler-auditor-sync} tries to be “safe”, +it will not replicate those deletions to the auditor’s production database. Thus, it is necessary to (occasonally) run @code{taler-exchange-dbinit -g} on -the auditor's production database to garbage collect old data in the -auditor's production copy. We note that this does not have to be done +the auditor’s production database to garbage collect old data in the +auditor’s production copy. We note that this does not have to be done at the same time when the exchange runs its garbage collection. @node Operation,Auditor implementation guide,Deployment,Top -@anchor{taler-auditor-manual id2}@anchor{20}@anchor{taler-auditor-manual operation}@anchor{21} +@anchor{taler-auditor-manual id2}@anchor{2d}@anchor{taler-auditor-manual operation}@anchor{2e} @chapter Operation @@ -996,31 +1581,38 @@ at the same time when the exchange runs its garbage collection. @end menu @node Web service,Audit,,Operation -@anchor{taler-auditor-manual id3}@anchor{22}@anchor{taler-auditor-manual web-service}@anchor{23} +@anchor{taler-auditor-manual id3}@anchor{2f}@anchor{taler-auditor-manual web-service}@anchor{30} @section Web service The @code{taler-auditor-httpd} runs the required REST API for the auditor. The service must have @code{INSERT} (and @code{SELECT}) rights on the -@code{deposit_confirmations} table in the auditor's database. We expect that in +@code{deposit_confirmations} table in the auditor’s database. We expect that in future versions additional rights may be required. +For now, we recommend simply running the @code{taler-auditor-httpd} under the +@code{auditor} user. However, it is also possible (and might be more secure) to +create a separate user with more restrictive permissions for this purpose. + As the @code{taler-auditor-httpd} does not include HTTPS-support, it is advisable to run it behind a reverse proxy that offers TLS termination. @node Audit,Reading the report,Web service,Operation -@anchor{taler-auditor-manual audit}@anchor{24}@anchor{taler-auditor-manual id4}@anchor{25} +@anchor{taler-auditor-manual audit}@anchor{31}@anchor{taler-auditor-manual id4}@anchor{32} @section Audit -Performing an audit is done by invoking the @code{taler-auditor} shell script. +Performing an audit is done by invoking the @code{taler-auditor} shell script as +the @code{auditor} user. + The shell script invokes the various helper processes. For additional performance and security, one may want to run the various helpers individually and with the respective minimal set of access rights (only @code{taler-helper-auditor-wire} needs the credentials to query the bank for wire -transfers). The shell script combines the final JSON outputs of the various -helpers using the @code{taler-helper-auditor-render.py} script into the TeX -report. Regardless, the simplest way to obtain a report is to run: +transfers, alas if @code{auditor-wire} is used to talk to the bank, this issue is +already addressed). The shell script combines the final JSON outputs of the +various helpers using the @code{taler-helper-auditor-render.py} script into the +TeX report. Regardless, the simplest way to obtain a report is to run: @example $ taler-audit @@ -1041,11 +1633,11 @@ interactions with the bank (which may not even have the wire transfer records anymore), this is not recommended in a production setup. @node Reading the report,Database upgrades,Audit,Operation -@anchor{taler-auditor-manual reading-the-report}@anchor{26} +@anchor{taler-auditor-manual reading-the-report}@anchor{33} @section Reading the report -The auditor's report needs to be read carefully, as it includes +The auditor’s report needs to be read carefully, as it includes several categories of failures of different severity: @@ -1077,7 +1669,7 @@ Configuration issues (such was wire fees unavailable). @end itemize @node Database upgrades,Database reset,Reading the report,Operation -@anchor{taler-auditor-manual auditordatabaseupgrades}@anchor{27}@anchor{taler-auditor-manual database-upgrades}@anchor{28} +@anchor{taler-auditor-manual auditordatabaseupgrades}@anchor{34}@anchor{taler-auditor-manual database-upgrades}@anchor{35} @section Database upgrades @@ -1103,7 +1695,7 @@ halting the exchange business logic, @item allowing the replication and @code{taler-auditor-sync} to complete -(see also the @strong{-t} option of @code{taler-auditor-sync}) +(see also the `-t' option of @code{taler-auditor-sync}) @item completing a @code{taler-audit} run against the old schema @@ -1111,14 +1703,14 @@ completing a @code{taler-audit} run against the old schema @item migrating the exchange schema (@code{taler-exchange-dbinit}) of the master database, possibly the ingres database and the -auditor's production copy +auditor’s production copy @item migrating the auditor database (@code{taler-auditor-dbinit}) @item -resuming database replication between the exchange's master -database and the auditor's ingres copy +resuming database replication between the exchange’s master +database and the auditor’s ingres copy @item resuming @code{taler-auditor-sync} @@ -1132,7 +1724,7 @@ Regardless, the above is merely the general rule. Please review the specific release notes to ensure this procedure is correct for the specific upgrade. @node Database reset,Revocations,Database upgrades,Operation -@anchor{taler-auditor-manual database-reset}@anchor{29} +@anchor{taler-auditor-manual database-reset}@anchor{36} @section Database reset @@ -1143,14 +1735,14 @@ $ taler-auditor-dbinit -R @end example However, running this command will result in all data in the database being -@emph{lost}, including steps like enabling an exchange using +`lost', including steps like enabling an exchange using @code{taler-auditor-exchange}. Thus, doing so may result in significant commputation (and bandwidth consumption with the bank) when the auditor is next launched, as it will re-download and re-verify all historic transactions. Hence this should not be done in a production system. @node Revocations,Failures,Database reset,Operation -@anchor{taler-auditor-manual auditorrevocations}@anchor{2a}@anchor{taler-auditor-manual revocations}@anchor{2b} +@anchor{taler-auditor-manual auditorrevocations}@anchor{37}@anchor{taler-auditor-manual revocations}@anchor{38} @section Revocations @@ -1163,29 +1755,29 @@ For more information, see Revocations in the exchange operator manual. If all denominations of an exchange are revoked, the exchange includes logic to wire back all returned funds to the bank accounts from which they originate. If some denominations remain operational, wallets will generally -exchange old coins of revoked denominations for new coins -- while providing +exchange old coins of revoked denominations for new coins – while providing additional information to demonstrate that these coins were not forged from the compromised private key but obtained via a legitimate withdraw operation. @node Failures,,Revocations,Operation -@anchor{taler-auditor-manual failures}@anchor{2c} +@anchor{taler-auditor-manual failures}@anchor{39} @section Failures -Most audit failures are handled by the auditor's regular reporting functionality, +Most audit failures are handled by the auditor’s regular reporting functionality, creating a (hopefully descriptive) PDF report detailing the problems found. However, there is one category of errors where this is not possible, which -concerns arithmetic overflows for amounts. Taler's specification limits amount -values to at most 2^52. If, during the auditor's calculations, amounts are +concerns arithmetic overflows for amounts. Taler’s specification limits amount +values to at most 2^52. If, during the auditor’s calculations, amounts are encountered that exceed this threshold, the auditor will not generate a regular report, but instead write a log statement explaining where the problem happened -and exit with a status code of @emph{42}. +and exit with a status code of `42'. The most common expected case when this happens is a corrupted database. This could be because the exchange is actively malicious, or more likely due to some data corruption. The audit cannot continue until the corruption has been -addressed. If it is not possible to restore a fully @emph{correct} version of the +addressed. If it is not possible to restore a fully `correct' version of the database, the suggestion is to replace the corrupted (and likely very large) amounts with zero (Note: this does not apply to the value of denominations or fees, here it is crucial that the correct amounts are restored). While an @@ -1194,14 +1786,14 @@ calculations with zero instead. After patching the database, the audit can be restarted. A full reset is not required, as the audit transaction is aborted -when the auditor exits with code @emph{42}. After restarting, the resulting audit +when the auditor exits with code `42'. After restarting, the resulting audit report is likely to indicates errors relating to the corrupted fields (such as invalid signatures, arithmetic errors by the exchange, etc.), but at least the loss/gain calculations will be meaningful and actually indicative of the scope of the error created by the corrupted data. @node Auditor implementation guide,Index,Operation,Top -@anchor{taler-auditor-manual auditor-implementation-guide}@anchor{2d} +@anchor{taler-auditor-manual auditor-implementation-guide}@anchor{3a} @chapter Auditor implementation guide @@ -1209,15 +1801,15 @@ The auditor implementation is split into five main processes, called @code{taler-helper-auditor-XXX}. The split was done to realize the principle of least privilege and to enable independent logic to be possibly run in parallel. Only the taler-wire-auditor must have (read-only) access to the -exchange's bank account, the other components only need access to the +exchange’s bank account, the other components only need access to the database. All auditor subsystems basically start their audit from a certain transaction index (@code{BIG SERIAL}) in the auditor database which identifies where the last audit concluded. They then check that the transactions claimed in the -exchange's database match up internally, including the cryptographic +exchange’s database match up internally, including the cryptographic signatures and also with respect to amounts adding up. The auditor also -calculates the exchange's profits and expected bank balances. Once all +calculates the exchange’s profits and expected bank balances. Once all existing transactions are processed, the auditor processes store the current checkpoint in its database and generate a JSON report. @@ -1226,23 +1818,23 @@ uses Jinja2 with a TeX template to convert the five individual JSON reports into LaTeX and then into PDF. @menu -* The auditor's database:: +* The auditor’s database:: * Invariants checked by the auditor:: * Testing the auditor:: @end menu -@node The auditor's database,Invariants checked by the auditor,,Auditor implementation guide -@anchor{taler-auditor-manual the-auditor-s-database}@anchor{2e} -@section The auditor's database +@node The auditor’s database,Invariants checked by the auditor,,Auditor implementation guide +@anchor{taler-auditor-manual the-auditor-s-database}@anchor{3b} +@section The auditor’s database The database scheme used by the exchange looks as follows: @image{taler-auditor-figures/auditor-db,,,,png} -@node Invariants checked by the auditor,Testing the auditor,The auditor's database,Auditor implementation guide -@anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{2f} +@node Invariants checked by the auditor,Testing the auditor,The auditor’s database,Auditor implementation guide +@anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{3c} @section Invariants checked by the auditor @@ -1262,11 +1854,11 @@ pass where it might seem applicable. @end menu @node Invariants checked by the taler-helper-auditor-aggregation,Invariants checked by the taler-helper-auditor-coins,,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-aggregation}@anchor{30} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-aggregation}@anchor{3d} @subsection Invariants checked by the taler-helper-auditor-aggregation -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1374,11 +1966,11 @@ wire fee unavailable for given time @end itemize @node Invariants checked by the taler-helper-auditor-coins,Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the taler-helper-auditor-aggregation,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-coins}@anchor{31} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-coins}@anchor{3e} @subsection Invariants checked by the taler-helper-auditor-coins -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1386,9 +1978,9 @@ CodeBlau reports the following checks: @item check that all denominations used by the exchange have been signed using -this auditor's key. All denominations encountered in the database that +this auditor’s key. All denominations encountered in the database that this auditor did not officially sign for are reported (but still included -in the audit as they obviously may impact the exchange's bank balance). +in the audit as they obviously may impact the exchange’s bank balance). Depending on the business situation, this may be normal (say if an exchange is changing auditors and newer denominations are no longer supported until their end-of-life by the current auditor). @@ -1470,7 +2062,7 @@ recoup, denomination not revoked @end itemize @node Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the taler-helper-auditor-coins,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-deposits}@anchor{32} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-deposits}@anchor{3f} @subsection Invariants checked by the taler-helper-auditor-deposits @@ -1480,11 +2072,11 @@ exchange at the auditor. This is to ensure that the exchange cannot defraud merchants by simply not reporting deposits to the auditor. @node Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the taler-helper-auditor-wire,Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-reserves}@anchor{33} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-reserves}@anchor{40} @subsection Invariants checked by the taler-helper-auditor-reserves -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1541,16 +2133,16 @@ target account does not match origin account @end itemize @node Invariants checked by the taler-helper-auditor-wire,,Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-wire}@anchor{34} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-wire}@anchor{41} @subsection Invariants checked by the taler-helper-auditor-wire This auditor is special in that it is the only pass that is required to have -@emph{read-only} access to the exchange's bank account (privilege separation). Its -main role is to verify that the wire transfers in the exchange's database and +`read-only' access to the exchange’s bank account (privilege separation). Its +main role is to verify that the wire transfers in the exchange’s database and those reported by the bank are identical. -This is from CodeBlau's analysis. A proper write-up is pending. +This is from CodeBlau’s analysis. A proper write-up is pending. CodeBlau reports the following checks: @@ -1606,13 +2198,13 @@ closing fee above total amount @end itemize @node Testing the auditor,,Invariants checked by the auditor,Auditor implementation guide -@anchor{taler-auditor-manual testing-the-auditor}@anchor{35} +@anchor{taler-auditor-manual testing-the-auditor}@anchor{42} @section Testing the auditor The main objective of the auditor is to detect inconsistencies. Thus, the @code{test-auditor.sh} script deliberately introduces various inconsistencies into -a synthetic exchange database. For this, an "normal" exchange database is +a synthetic exchange database. For this, an “normal” exchange database is first generated using the @code{taler-wallet-cli}. Then, various fields or rows of that database are manipulated, and the auditor is let loose on the modified database. Afterwards, the test verifies that the JSON contains values @@ -1625,13 +2217,13 @@ cover as many code paths as possible in both the exchange and the auditor. It should also ideally create all interesting possible variations of the exchange database fields (within the constraints of the database schema). -In general, @code{test-auditor.sh} runs the tests against an "old" database where +In general, @code{test-auditor.sh} runs the tests against an “old” database where some transactions are past the due-date (and hence the aggregator would trigger wire transfers), as well as a freshly generated exchange database where the auditor would not perform any transfers. Auditor interactions can be made before or after the aggregator, depending on what is being tested. -The current script also rudimentarily tests the auditor's resume logic, +The current script also rudimentarily tests the auditor’s resume logic, by re-starting the auditor once against a database that the auditor has already seen. diff --git a/texinfo/taler-bank-figures/anastasis-db.png b/texinfo/taler-bank-figures/anastasis-db.png Binary files differdeleted file mode 100644 index 03eed9da..00000000 --- a/texinfo/taler-bank-figures/anastasis-db.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_challenge_payment.png b/texinfo/taler-bank-figures/anastasis_challenge_payment.png Binary files differdeleted file mode 100644 index a0593eba..00000000 --- a/texinfo/taler-bank-figures/anastasis_challenge_payment.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_challengecode.png b/texinfo/taler-bank-figures/anastasis_challengecode.png Binary files differdeleted file mode 100644 index fc30f4fe..00000000 --- a/texinfo/taler-bank-figures/anastasis_challengecode.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_reducer_backup.png b/texinfo/taler-bank-figures/anastasis_reducer_backup.png Binary files differdeleted file mode 100644 index 87b0a9b4..00000000 --- a/texinfo/taler-bank-figures/anastasis_reducer_backup.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_reducer_recovery.png b/texinfo/taler-bank-figures/anastasis_reducer_recovery.png Binary files differdeleted file mode 100644 index 7d3cc9ae..00000000 --- a/texinfo/taler-bank-figures/anastasis_reducer_recovery.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_truth.png b/texinfo/taler-bank-figures/anastasis_truth.png Binary files differdeleted file mode 100644 index 7f23fa21..00000000 --- a/texinfo/taler-bank-figures/anastasis_truth.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/anastasis_truth_payment.png b/texinfo/taler-bank-figures/anastasis_truth_payment.png Binary files differdeleted file mode 100644 index 70a6b3df..00000000 --- a/texinfo/taler-bank-figures/anastasis_truth_payment.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/arch-api.png b/texinfo/taler-bank-figures/arch-api.png Binary files differdeleted file mode 100644 index 8004f790..00000000 --- a/texinfo/taler-bank-figures/arch-api.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/auditor-db.png b/texinfo/taler-bank-figures/auditor-db.png Binary files differdeleted file mode 100644 index 3f10f3ab..00000000 --- a/texinfo/taler-bank-figures/auditor-db.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/exchange-db.png b/texinfo/taler-bank-figures/exchange-db.png Binary files differdeleted file mode 100644 index f99e2664..00000000 --- a/texinfo/taler-bank-figures/exchange-db.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/merchant-db.png b/texinfo/taler-bank-figures/merchant-db.png Binary files differdeleted file mode 100644 index cd5f7bd6..00000000 --- a/texinfo/taler-bank-figures/merchant-db.png +++ /dev/null diff --git a/texinfo/taler-bank-figures/replication.png b/texinfo/taler-bank-figures/replication.png Binary files differdeleted file mode 100644 index 855237fc..00000000 --- a/texinfo/taler-bank-figures/replication.png +++ /dev/null diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi deleted file mode 100644 index 74c701c3..00000000 --- a/texinfo/taler-bank.texi +++ /dev/null @@ -1,159 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename taler-bank.info -@documentencoding UTF-8 -@ifinfo -@*Generated by Sphinx 3.4.3.@* -@end ifinfo -@settitle Taler Bank Manual -@defindex ge -@paragraphindent 0 -@exampleindent 4 -@finalout -@dircategory CATEGORY -@direntry -* MENU ENTRY: (taler-bank.info). DESCRIPTION -@end direntry - -@definfoenclose strong,`,' -@definfoenclose emph,`,' -@c %**end of header - -@copying -@quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 - -GNU Taler team - -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) -@end quotation - -@end copying - -@titlepage -@title Taler Bank Manual -@insertcopying -@end titlepage -@contents - -@c %** start of user preamble - -@c %** end of user preamble - -@ifnottex -@node Top -@top Taler Bank Manual -@insertcopying -@end ifnottex - -@c %**start of body -@anchor{taler-bank-manual doc}@anchor{0} -@menu -* Introduction:: -* Headless Testing API Reference:: - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* About GNU Taler:: -* About this manual:: - -@end detailmenu -@end menu - -@node Introduction,Headless Testing API Reference,Top,Top -@anchor{taler-bank-manual gnu-taler-bank-manual}@anchor{1}@anchor{taler-bank-manual introduction}@anchor{2} -@chapter Introduction - - -@menu -* About GNU Taler:: -* About this manual:: - -@end menu - -@node About GNU Taler,About this manual,,Introduction -@anchor{taler-bank-manual about-gnu-taler}@anchor{3} -@section About GNU Taler - - -GNU Taler is an open protocol for an electronic payment system with a -free software reference implementation. GNU Taler offers secure, fast -and easy payment processing using well understood cryptographic -techniques. GNU Taler allows customers to remain anonymous, while -ensuring that merchants can be held accountable by governments. Hence, -GNU Taler is compatible with anti-money-laundering (AML) and -know-your-customer (KYC) regulation, as well as data protection -regulation (such as GDPR). - -@node About this manual,,About GNU Taler,Introduction -@anchor{taler-bank-manual about-this-manual}@anchor{4} -@section About this manual - - -This manual documents how the demonstrator bank interoperates with the -other GNU Taler components. The demonstrator bank implements a simple -closed banking system for the purpose of illustrating how GNU Taler -works in the Taler demo. It could also be used as a starting point for a -local/regional currency. Finally, “real” banks might use it as a -reference implementation for a tight integration with the GNU Taler -wallet. - -@node Headless Testing API Reference,,Introduction,Top -@anchor{taler-bank-manual headless-testing-api-reference}@anchor{5} -@chapter Headless Testing API Reference - - -The demonstrator bank offers the following APIs to allow automated testing. These APIs should -be switched off during a production deployment. -@anchor{taler-bank-manual bank-register}@anchor{6} -@anchor{taler-bank-manual post--register}@anchor{7} -@deffn {HTTP Post} POST /register - -This API provides programmatic user registration at the bank. - -@strong{Request} The body of this request must have the format of a -@ref{8,,BankRegistrationRequest}. - -@strong{Response} - - -@table @asis - -@item 200 OK@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1}: - -The new user has been correctly registered. - -@item 409 Conflict@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10}: - -The username requested by the client is not available anymore. - -@item 400 Bad request@footnote{http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1}: - -Unacceptable characters were given for the username. See -@indicateurl{https://docs.djangoproject.com/en/2.2/ref/contrib/auth/#django.contrib.auth.models.User.username} -for the accepted character set. -@end table -@end deffn - -@strong{Details} - -@example -interface BankRegistrationRequest @{ - - // Username to use for registration; max length is 150 chars. - username: string; - - // Password to associate with the username. Any characters and - // any length are valid; next releases will enforce a minimum length - // and a safer characters choice. - password: string; -@} -@end example -@anchor{8}@w{ } -@anchor{taler-bank-manual tsref-type-BankRegistrationRequest}@w{ } - -@c %**end of body -@bye diff --git a/texinfo/taler-developer-manual-figures/arch-api.png b/texinfo/taler-developer-manual-figures/arch-api.png Binary files differindex 8004f790..9e593ab4 100644 --- a/texinfo/taler-developer-manual-figures/arch-api.png +++ b/texinfo/taler-developer-manual-figures/arch-api.png diff --git a/texinfo/taler-developer-manual-figures/exchange-db.png b/texinfo/taler-developer-manual-figures/exchange-db.png Binary files differindex f99e2664..7a4050c6 100644 --- a/texinfo/taler-developer-manual-figures/exchange-db.png +++ b/texinfo/taler-developer-manual-figures/exchange-db.png diff --git a/texinfo/taler-developer-manual-figures/merchant-db.png b/texinfo/taler-developer-manual-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-developer-manual-figures/merchant-db.png +++ b/texinfo/taler-developer-manual-figures/merchant-db.png diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 4b51194f..1d333657 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.texi @@ -3,29 +3,27 @@ @setfilename taler-developer-manual.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Developer Manual @defindex ge @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-developer-manual.info). DESCRIPTION +* GNU Taler Development: (taler-developer-manual.info). Manual for GNU Taler contributors @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.9.4, Apr 12, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -50,32 +48,41 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-developer-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2014-2021 Taler Systems SA +@c Copyright (C) 2014-2023 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the -@c terms of the GNU General Public License as published by the Free Software +@c terms of the GNU Affero General Public License as published by the Free Software @c Foundation; either version 2.1, or (at your option) any later version. @c @c TALER is distributed in the hope that it will be useful, but WITHOUT ANY @c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -@c A PARTICULAR PURPOSE. See the GNU General Public License for more details. +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. @c -@c You should have received a copy of the GNU General Public License along with +@c You should have received a copy of the GNU Affero General Public License along with @c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @c @c @author Christian Grothoff +@cartouche +@quotation Note +This manual contains information for developers working on GNU Taler +and related components. It is not intended for a general audience. +@end quotation +@end cartouche + @menu -* GNU Taler Release Checklist:: -* GNU Taler Demo Upgrade Checklist:: +* Project Overview:: * Fundamentals:: +* Debian and Ubuntu Repositories:: * Language-Specific Guidelines:: * Taler Deployment on gv.taler.net: Taler Deployment on gv taler net. * Demo Upgrade Procedure:: * Environments and Builders on taler.net: Environments and Builders on taler net. +* QA Plans:: * Releases:: * Continuous integration:: * Internationalization:: +* iOS Apps:: * Android Apps:: * Code Coverage:: * Coding Conventions:: @@ -87,300 +94,234 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end menu -@node GNU Taler Release Checklist,GNU Taler Demo Upgrade Checklist,Top,Top -@anchor{checklist-release doc}@anchor{1}@anchor{checklist-release developer-s-manual}@anchor{2}@anchor{checklist-release gnu-taler-release-checklist}@anchor{3} -@chapter GNU Taler Release Checklist - - -Release checklists for GNU Taler: +@node Project Overview,Fundamentals,Top,Top +@anchor{taler-developer-manual developer-s-manual}@anchor{1}@anchor{taler-developer-manual project-overview}@anchor{2} +@chapter Project Overview -Wallet: +GNU Taler consists of a large (and growing) number of components +in various Git repositories. The following list gives a first +overview: -@itemize - - -@item -[ ] build wallet - -@item -[ ] verify wallet works against 'test.taler.net' +@quotation -@item -[ ] tag repo. -@item -[ ] upgrade 'demo.taler.net' to 'test.taler.net' - -@item -[ ] upload new wallet release to app store - -@item -[ ] Update bug tracker (mark release, resolved -> closed) +@itemize * @item -[ ] Send announcement to @email{taler@@gnu.org} +exchange: core payment processing logic with a REST API, plus various +helper processes for interaction with banks and cryptographic +computations. Also includes the logic for the auditor and an +in-memory “bank” API implementation for testing. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +libeufin: implementation of the “bank” API using the EBICS protocol +used by banks in the EU. Allows an exchange to interact with +European banks. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} -@end itemize - -For exchange: - - -@itemize - +deploymerization: implementation of the “bank” API on top of +blockchains, specifically Bitcoin and Ethereum. Allows an exchange +to interact with crypto-currencies. @item -[ ] check no compiler warnings at "-Wall" +merchant: payment processing backend to be run by merchants, +offering a REST API. @item -[ ] ensure Coverity static analysis passes +wallet-core: platform-independent implementation of a wallet to be run by +normal users. Includes also the WebExtension for various browsers. +Furthermore, includes various single-page apps used by other +components (especially as libeufin and merchant). Also includes +command-line wallet and tools for testing. @item -[ ] make check. +taler-android: Android Apps including the Android wallet, the +Android point-of-sale App and the Android casher app. @item -[ ] upgrade 'demo.taler.net' to 'test.taler.net' +taler-ios: iOS wallet App. @item -[ ] make dist, make check on result of 'make dist'. +sync: backup service, provides a simple REST API to allow users to +make encrypted backups of their wallet state. @item -[ ] Change version number in configure.ac. +anastasis: key escrow service, provides a simple REST API to allow +users to distribute encryption keys across multiple providers and +define authorization policies for key recovery. @item -[ ] make dist for release. +taler-mdb: integration of Taler with the multi-drop-bus (MDB) API +used by vending machines. Allows Taler payments to be integrated +with vending machines. @item -[ ] tag repo. +gnu-taler-payment-for-woocommerce: payment plugin for the +woocommerce (wordpress) E-commerce solution. @item -[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +twister: man-in-the-middle proxy for tests that require fuzzing a +REST/JSON protocol. Used for some of our testing. @item -[ ] Update bug tracker (mark release, resolved -> closed) +challenger: implementation of an OAuth 2.0 provider that can be used +to verify that a user can receive SMS or E-mail at particular addresses. +Used as part of KYC processes of the exchange. @item -[ ] Send announcement to @email{taler@@gnu.org} +taler-mailbox: messaging service used to store and forward payment +messages to Taler wallets. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +taldir: directory service used to lookup Taler wallet addresses for +sending invoices or payments to other wallets. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} +taler-merchant-demos: various demonstration services operated at +‘demo.taler.net’, including a simple shop and a donation page. @end itemize +@end quotation -For merchant (C backend): - - -@itemize - - -@item -[ ] check no compiler warnings at "-Wall" - -@item -[ ] ensure Coverity static analysis passes - -@item -[ ] make check. - -@item -[ ] upgrade 'demo.taler.net' to 'test.taler.net' +There are other important repositories without code, including: -@item -[ ] make dist, make check on result of 'make dist'. +@quotation -@item -[ ] Change version number in configure.ac. -@item -[ ] make dist for release. - -@item -[ ] tag repo. +@itemize * @item -[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +gana: Hosted on git.gnunet.org, this repository defines various +constants used in the GNU Taler project. @item -[ ] Update bug tracker (mark release, resolved -> closed) +docs: documentation, including this very document. @item -[ ] Send announcement to @email{taler@@gnu.org} +marketing: various presentations, papers and other resources for +outreach. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +large-media: very large data objects, such as videos. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} -@end itemize - -For bank: - - -@itemize - - -@item -TBD +www: the taler.net website. @end itemize +@end quotation -For Python merchant frontend: +@node Fundamentals,Debian and Ubuntu Repositories,Project Overview,Top +@anchor{taler-developer-manual fundamentals}@anchor{3} +@chapter Fundamentals -@itemize - +@menu +* Versioning:: +* Testing Tools:: +* Manual Testing Database Reset:: +* Bug Tracking:: +* Code Repositories:: +* Committing code:: +* Observing changes:: +* Communication:: +* What to put in bootstrap:: -@item -TBD -@end itemize +@end menu -For PHP merchant frontend: +@node Versioning,Testing Tools,,Fundamentals +@anchor{taler-developer-manual versioning}@anchor{4} +@section Versioning + + +A central rule is to never break anything for any dependency. To accomplish +this, we use versioning, of the APIs, database schema and the protocol. The +database versioning approach is described in the @ref{5,,Database schema versioning} section. Here, we will focus on API and +protocol versioning. + +The key issue we need to solve with protocols and APIs (and that does not +apply to database versioning) is being able to introduce and remove features +without requiring a flag day where all components must update at the same +time. For this, we use GNU libtool style versioning with MAJOR:REVISION:AGE +and `not' semantic versioning (SEMVER). With GNU libtool style versioning, +first the REVISION should be increased on every change to the respective code. +Then, each time a feature is introduced or deprecated, the MAJOR and AGE +numbers are increased. Whenever an API is actually removed the AGE number is +reduced to match the distance since the removed API was deprecated. Thus, if +some client implements version X of the protocol (including not using any APIs +that have been deprecated), it is compatible for any implementation where +MAJOR is larger or equal to X, and MAJOR minus AGE is smaller or equal to X. +REVISION is not used for expected compatibility issues and merely serves to +uniquely identify each version (in combination with MAJOR). + +To evolve any implementation, it is thus critical to first of all never +just break an existing API or endpoint. The only acceptable modifications +are to return additional information (being aware of binary compatibility!) +or to accept additional optional arguments (again, in a way that does not +break existing users). Thus, the most common way to introduce changes will +be the addition of new endpoints. Breaking existing endpoints is only ever +at best acceptable while in the process of introducing it and if you are +absolutely sure that there are zero users in other components. + +When removing endpoints (or fields being returned), you must first deprecate +the existing API (incrementing MAJOR and AGE) and then wait for all clients, +including all clients in operation (e.g. Android and iOS Apps, e-commerce +integrations, etc.) to upgrade to a protocol implementation above the +deprecated MAJOR revision. Only then you should remove the endpoint and reduce +AGE. + +To document these changes, please try to use @code{@@since} annotations in the API +specifications to explain the MAJOR revision when a feature became available, +but most importantly use @code{@@deprecated X} annotations to indicate that an API +was deprecated and will be removed once MAJOR minus AGE is above X. When using +an API, use the @code{/config} endpoints to check for compatibility and show a +warning if the version(s) you support and the version(s) offered by the server +are incompatible. + +@node Testing Tools,Manual Testing Database Reset,Versioning,Fundamentals +@anchor{taler-developer-manual testing-tools}@anchor{6} +@section Testing Tools + + +For full @code{make check} support, install these programs: @itemize - @item -TBD -@end itemize - -For auditor: - - -@itemize - +jq@footnote{https://github.com/stedolan/jq} @item -TBD -@end itemize - -For libebics: - - -@itemize - +curl@footnote{http://curl.haxx.se} @item -TBD +faketime@footnote{https://github.com/wolfcw/libfaketime} @end itemize -@node GNU Taler Demo Upgrade Checklist,Fundamentals,GNU Taler Release Checklist,Top -@anchor{checklist-demo-upgrade doc}@anchor{4}@anchor{checklist-demo-upgrade gnu-taler-demo-upgrade-checklist}@anchor{5} -@chapter GNU Taler Demo Upgrade Checklist +The @code{make check} should be able to function without them, but +their presence permits some tests to run that would otherwise be skipped. +@node Manual Testing Database Reset,Bug Tracking,Testing Tools,Fundamentals +@anchor{taler-developer-manual manual-testing-database-reset}@anchor{7} +@section Manual Testing Database Reset -Post-upgrade checks: - -@itemize - - -@item - Run @code{taler-deployment-arm -I} to verify that all services are running. - -@item - Run the headless wallet to check that services are actually working: +Sometimes @code{make check} will fail with some kind of database (SQL) +error, perhaps with a message like @code{OBJECT does not exist} in the +@code{test-suite.log} file, where @code{OBJECT} is the name of a table or function. +In that case, it may be necessary to reset the @code{talercheck} database +with the commands: @example -$ taler-wallet-cli integrationtest \ - -e https://exchange.demo.taler.net/ \ - -m https://backend.demo.taler.net/ \ - -b https://bank.demo.taler.net \ - -w "KUDOS:10" \ - -s "KUDOS:5" +$ dropdb talercheck +$ createdb talercheck @end example -@end itemize - -Basics: - - -@itemize - - -@item - Visit @indicateurl{https://demo.taler.net/} to see if the landing page is displayed correctly - -@item - Visit the wallet installation page, install the wallet, and see if the presence -indicator is updated correctly. - -@item - Visit @indicateurl{https://bank.demo.taler.net/}, register a new user and withdraw coins into the -browser wallet. -@end itemize - -Blog demo: - - -@itemize - - -@item - Visit @indicateurl{https://shop.demo.taler.net/} and purchase an article. - -@item - Verify that the balance in the wallet was updated correctly. - -@item - Go back to @indicateurl{https://shop.demo.taler.net/} and click on the same article -link. Verify that the article is shown and @strong{no} repeated payment is -requested. - -@item - Open the fulfillment page from the previous step in an anonymous browsing session -(without the wallet installed) and verify that it requests a payment again. - -@item - Delete cookies on @indicateurl{https://shop.demo.taler.net/} and click on the same article again. -Verify that the wallet detects that the article has already purchased and successfully -redirects to the article without spending more money. -@end itemize -Donation demo: +This is because, at the moment, there is no support for +doing these steps automatically in the @code{make check} flow. +(If @code{make check} still fails after the reset, file a bug report as usual.) -@itemize - - -@item - Make a donation on @indicateurl{https://donations.demo.taler.net} - -@item - Make another donation with the same parameters and verify -that the payment is requested again, instead of showing the previous -fulfillment page. -@end itemize - -Survey/Tipping: - - -@itemize - - -@item - Visit @indicateurl{https://survey.demo.taler.net/} and receive a tip. - -@item - Verify that the survey stats page (@indicateurl{https://survey.demo.taler.net/survey-stats}) is working, -and that the survey reserve has sufficient funds. -@end itemize - -@cartouche -@quotation Note -This manual contains information for developers working on GNU Taler -and related components. It is not intended for a general audience. -@end quotation -@end cartouche - -@node Fundamentals,Language-Specific Guidelines,GNU Taler Demo Upgrade Checklist,Top -@anchor{taler-developer-manual fundamentals}@anchor{6} -@chapter Fundamentals - - -@menu -* Bug Tracking:: -* Code Repositories:: -* Committing code:: -* Observing changes:: -* Communication:: - -@end menu - -@node Bug Tracking,Code Repositories,,Fundamentals -@anchor{taler-developer-manual bug-tracking}@anchor{7} +@node Bug Tracking,Code Repositories,Manual Testing Database Reset,Fundamentals +@anchor{taler-developer-manual bug-tracking}@anchor{8} @section Bug Tracking @@ -390,7 +331,7 @@ needed in order to use the bug tracker, only read access is granted without a login. @node Code Repositories,Committing code,Bug Tracking,Fundamentals -@anchor{taler-developer-manual code-repositories}@anchor{8} +@anchor{taler-developer-manual code-repositories}@anchor{9} @section Code Repositories @@ -405,13 +346,13 @@ A complete list of all the existing repositories is currently found at @indicateurl{https://git.taler.net/}. @node Committing code,Observing changes,Code Repositories,Fundamentals -@anchor{taler-developer-manual committing-code}@anchor{9} +@anchor{taler-developer-manual committing-code}@anchor{a} @section Committing code Before you can obtain Git write access, you must sign the copyright agreement. As we collaborate closely with GNUnet, we use their -copyright agreement -- with the understanding that your contributions +copyright agreement – with the understanding that your contributions to GNU Taler are included in the assignment. You can find the agreement on the GNUnet site@footnote{https://gnunet.org/en/copyright.html}. Please sign and mail it to Christian Grothoff as he currently collects @@ -474,7 +415,7 @@ $ git pull --rebase -S @end example @node Observing changes,Communication,Committing code,Fundamentals -@anchor{taler-developer-manual observing-changes}@anchor{a} +@anchor{taler-developer-manual observing-changes}@anchor{b} @section Observing changes @@ -486,19 +427,101 @@ our main dependencies, namely GNUnet and GNU libmicrohttpd. While it can be high volume, the lists is a good way to follow overall development. -@node Communication,,Observing changes,Fundamentals -@anchor{taler-developer-manual communication}@anchor{b} +@node Communication,What to put in bootstrap,Observing changes,Fundamentals +@anchor{taler-developer-manual communication}@anchor{c} @section Communication -We use the #taler channel on the Freenode IRC network and the @email{taler@@gnu.org} -public mailinglist for discussions. Not all developers are active on IRC, but -all developers should probably subscribe to the low-volume Taler mailinglist. -There are separate low-volume mailinglists for gnunet-developers (@@gnu.org) -and for libmicrohttpd (@@gnu.org). +For public discussions we use the @email{taler@@gnu.org} mailinglist. All developers +should subscribe to the low-volume Taler mailinglist. There are separate +low-volume mailinglists for gnunet-developers (@@gnu.org) and for libmicrohttpd +(@@gnu.org). For internal discussions we use @indicateurl{https://mattermost.taler.net/} +(invitation only, but also achieved). + +@node What to put in bootstrap,,Communication,Fundamentals +@anchor{taler-developer-manual what-to-put-in-bootstrap}@anchor{d} +@section What to put in bootstrap + -@node Language-Specific Guidelines,Taler Deployment on gv taler net,Fundamentals,Top -@anchor{taler-developer-manual language-specific-guidelines}@anchor{c} +Each repository has a @code{bootstrap} script, which contains commands for the +developer to run after a repository checkout (i.e., after @code{git clone} or +@code{git pull}). +Typically, this updates and initializes submodules, prepares the tool chain, +and runs @code{autoreconf}. +The last step generates the @code{configure} script, whether for immediate use or +for inclusion in the distribution tarball. + +One common submodule is @code{contrib/gana}, which pulls from the +GNUnet GANA repository@footnote{https://git.gnunet.org/gana.git/}. +For example, in the +Taler exchange repository@footnote{https://git.taler.net/exchange.git}, +the bootstrap script eventually runs the @code{git submodule update --init} command +early on, and later runs script @code{./contrib/gana-generate.sh}, which +generates files such as @code{src/include/taler_signatures.h}. + +Thus, to update that file, you need to: + + +@itemize - + +@item +(in GANA repo) Find a suitable (unused) name and number for the Signature +Purposes database. + +@item +Add it to GANA, in @code{gnunet-signatures/registry.rec}. +(You can check for uniqueness with the @code{recfix} utility.) + +@item +Commit the change, and push it to the GANA Git repo. + +@item +(in Taler Repo) Run the @code{contrib/gana-latest.sh} script. + +@item +Bootstrap, configure, do @code{make install}, @code{make check}, etc. +(Basically, make sure the change does not break anything.) + +@item +Commit the submodule change, and push it to the Taler exchange Git repo. +@end itemize + +A similar procedure is required for other databases in GANA. +See file @code{README} in the various directories for specific instructions. + +@node Debian and Ubuntu Repositories,Language-Specific Guidelines,Fundamentals,Top +@anchor{taler-developer-manual debian-and-ubuntu-repositories}@anchor{e} +@chapter Debian and Ubuntu Repositories + + +We package our software for Debian and Ubuntu. + +@menu +* Nightly Repositories:: + +@end menu + +@node Nightly Repositories,,,Debian and Ubuntu Repositories +@anchor{taler-developer-manual nightly-repositories}@anchor{f} +@section Nightly Repositories + + +To try the latest, unstable and untested versions of packages, +you can add the nightly package sources. + +@example +# For Ubuntu (focal-fossa) +$ echo "deb https://deb.taler.net/apt-nightly focal-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# For Debian (bullseye) +$ echo "deb https://deb.taler.net/apt-nightly bullseye-taler-nightly main" > /etc/apt/sources.list.d/taler.list + +# Both: Install signing key for nightly packages +$ wget -O - https://taler.net/taler-systems-nightly.gpg.key | apt-key add - +@end example + +@node Language-Specific Guidelines,Taler Deployment on gv taler net,Debian and Ubuntu Repositories,Top +@anchor{taler-developer-manual language-specific-guidelines}@anchor{10} @chapter Language-Specific Guidelines @@ -510,19 +533,15 @@ Python Guidelines @end itemize @node Taler Deployment on gv taler net,Demo Upgrade Procedure,Language-Specific Guidelines,Top -@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{d} +@anchor{taler-developer-manual taler-deployment-on-gv-taler-net}@anchor{11} @chapter Taler Deployment on gv.taler.net -This section describes the GNU Taler deployment on @code{gv.taler.net}. -@code{gv} is our server at BFH. It hosts the Git repositories, Web sites, -CI and other services. Developers can receive an SSH account and -e-mail alias for the system. As with Git, ask your primary team -contact for shell access if you think you need it. - -Our old server, @code{tripwire}, is currently offline and will likely -go back online to host @code{production} systems for operating real -Taler payments at BFH in the future. +This section describes the GNU Taler deployment on @code{gv.taler.net}. @code{gv} +is our server at BFH. It hosts the Git repositories, Web sites, CI and other +services. Developers can receive an SSH account and e-mail alias for the +system, you should contact Javier, Christian or Florian. As with Git, ask +your primary team contact for shell access if you think you need it. @menu * DNS:: @@ -531,16 +550,16 @@ Taler payments at BFH in the future. @end menu @node DNS,User Acccounts,,Taler Deployment on gv taler net -@anchor{taler-developer-manual dns}@anchor{e} +@anchor{taler-developer-manual dns}@anchor{12} @section DNS -DNS records for taler.net are controlled by the GNU Taler -maintainers, specifically Christian and Florian. If you -need a sub-domain to be added, please contact one of them. +DNS records for taler.net are controlled by the GNU Taler maintainers, +specifically Christian and Florian, and our system administrator, Javier. If +you need a sub-domain to be added, please contact one of them. @node User Acccounts,,DNS,Taler Deployment on gv taler net -@anchor{taler-developer-manual user-acccounts}@anchor{f} +@anchor{taler-developer-manual user-acccounts}@anchor{13} @section User Acccounts @@ -555,53 +574,96 @@ serve Taler on the Internet: built by Buildbot. @item -@code{taler-internal}: serves @code{*.int.taler.net}, and does @emph{NOT} get +@code{taler-internal}: serves @code{*.int.taler.net}, and does `NOT' get automatically built. + +@item +@code{demo}: serves @code{*.demo.taler.net}. Never automatically built. @end itemize -The following two users are @emph{never} automatically built, and they both -serve @code{*.demo.taler.net}. At any given time, only one is active and -serves the HTTP requests from the outside; the other one can so be -compiled without any downtime. If the compilation succeeds, the inactive -user can be switched to become active (see next section), and vice versa. +@node Demo Upgrade Procedure,Environments and Builders on taler net,Taler Deployment on gv taler net,Top +@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{14} +@chapter Demo Upgrade Procedure -@itemize - + +@enumerate @item -@code{demo-blue} +Login as the @code{demo} user on @code{gv.taler.net}. @item -@code{demo-green} -@end itemize +Pull the latest @code{deployment.git} code. -@node Demo Upgrade Procedure,Environments and Builders on taler net,Taler Deployment on gv taler net,Top -@anchor{taler-developer-manual demo-upgrade-procedure}@anchor{10} -@chapter Demo Upgrade Procedure +@item +Navigate to the @code{deployment.git/docker/demo} directory. +@item +Refer to the README, or the smaller cheat sheet below. +@end enumerate -Upgrading the @code{demo} environment should be done with care, and ideally be -coordinated on the mailing list before. It is our goal for @code{demo} to always -run a "working version" that is compatible with various published wallets. +The deployment is based on rootless Docker, managed by the +SystemD unit in userspace: @code{docker.service}. The running daemon +is reached by every Docker command at the address held into the +@code{DOCKER_HOST} environment variable. Normally, it points to +@code{unix:///run/user/$(id -u)/docker.sock}. Such variable is automatically +exported by @code{~/.bashrc}. + +@cartouche +@quotation Note +@quotation -Before deploying on @code{demo}, the same version of all components @strong{must} -be deployed @emph{and} tested on @code{int}. +Should the rootless Docker be installed, run the following command +or consult the official documentation@footnote{https://docs.docker.com/engine/security/rootless/}. +@end quotation + +@example +$ curl -fsSL https://get.docker.com/rootless | sh +@end example +@end quotation +@end cartouche -Please use the @ref{4,,demo upgrade checklist} to make +Upgrading the @code{demo} environment should be done with care, and ideally be +coordinated on the mailing list before. It is our goal for @code{demo} to always +run a “working version” that is compatible with various published wallets. +Please use the demo upgrade checklist to make sure everything is working. +Nginx is already configured to reach the services as exported by +Docker Compose. @menu +* Cheat sheet:: * Tagging components:: -* Environment Layout:: -* Using envcfg.py: Using envcfg py. -* Bootstrapping an Environment:: -* Upgrading an Existing Environment:: -* Switching Demo Colors:: +* GNU Taler Demo Upgrade Checklist:: @end menu -@node Tagging components,Environment Layout,,Demo Upgrade Procedure -@anchor{taler-developer-manual tagging-components}@anchor{11} +@node Cheat sheet,Tagging components,,Demo Upgrade Procedure +@anchor{taler-developer-manual cheat-sheet}@anchor{15} +@section Cheat sheet + + +All commands run from deployment.git/docker/demo. + +@example +# Start services. +$ docker-compose start --remove-orphans -d + +# Stop services. +$ docker-compose stop + +# Build base image (without tags-file builds master) +$ ./build_base.sh images/base/Dockerfile [tags-file] + +# Build all the services based on the latest base image +$ docker-compose build + +# View live logs of the daemonized services. +$ docker-compose logs +@end example + +@node Tagging components,GNU Taler Demo Upgrade Checklist,Cheat sheet,Demo Upgrade Procedure +@anchor{taler-developer-manual tagging-components}@anchor{16} @section Tagging components @@ -616,125 +678,456 @@ DD = day SS = serial @end example -@node Environment Layout,Using envcfg py,Tagging components,Demo Upgrade Procedure -@anchor{taler-developer-manual environment-layout}@anchor{12} -@section Environment Layout +@node GNU Taler Demo Upgrade Checklist,,Tagging components,Demo Upgrade Procedure +@anchor{taler-developer-manual gnu-taler-demo-upgrade-checklist}@anchor{17} +@section GNU Taler Demo Upgrade Checklist -Environments have the following layout: +@menu +* Domains:: +* Post-upgrade checks:: +* Wallets:: +* Basics:: +* Exchange AML SPA:: +* Blog demo:: +* Donation demo:: +* Merchant SPA:: +* P2P payments:: +* Shutdown:: -@example -$HOME/ - deployment (deployment.git checkout) - envcfg.py (configuration of the Taler environment) - activate (bash file, sourced to set environment variables) - logs/ (log files) - local/ (locally installed software) - sources/ (sources repos of locally build components) - sockets/ (unix domain sockets of running components) - taler-data (on-disk state, public and private keys) - .config/taler.conf (main Taler configuration file) -@end example +@end menu -On @code{demo-blue} and @code{demo-green}, @code{taler-data} is a symlink pointing to @code{$HOME/demo/shared-data} -instead of a directory. +@node Domains,Post-upgrade checks,,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual domains}@anchor{18} +@subsection Domains -@node Using envcfg py,Bootstrapping an Environment,Environment Layout,Demo Upgrade Procedure -@anchor{taler-developer-manual using-envcfg-py}@anchor{13} -@section Using envcfg.py +The checklist uses the @code{demo.taler.net} domains. However, +the same sandcastle demo can also be hosted at other domains. +The same instructions should apply. -The @code{$HOME/envcfg.py} file contains (1) the name of the environment and (2) the version -of all components we build (in the form of a git rev). +@node Post-upgrade checks,Wallets,Domains,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual post-upgrade-checks}@anchor{19} +@subsection Post-upgrade checks -The @code{envcfg.py} for demo looks like this: + + +@itemize - + +@item + Run the headless wallet to check that services are actually working: @example -env = "demo" -tag = "demo-2019-10-05-01: -tag_gnunet = tag -tag_libmicrohttpd = tag -tag_exchange = tag -tag_merchant = tag -tag_bank = tag -tag_twister = tag -tag_landing = tag -tag_donations = tag -tag_blog = tag -tag_survey = tag -tag_backoffice = tag -tag_sync = tag +taler-wallet-cli api 'runIntegrationTestV2' '@{"exchangeBaseUrl":"https://exchange.demo.taler.net", "corebankApiBaseUrl": "https://bank.demo.taler.net", "merchantBaseUrl": "https://backend.demo.taler.net", "merchantAuthToken":"secret-token:sandbox"@}' @end example +@end itemize -Currently only the variables @code{env} and @code{tag_$@{component@}} are used. +@node Wallets,Basics,Post-upgrade checks,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual wallets}@anchor{1a} +@subsection Wallets -When deploying to @code{demo}, the @code{envcfg.py} should be committed to @code{deployment.git/envcfg/envcfg-demo-YYYY-MM-DD-SS.py}. -@node Bootstrapping an Environment,Upgrading an Existing Environment,Using envcfg py,Demo Upgrade Procedure -@anchor{taler-developer-manual bootstrapping-an-environment}@anchor{14} -@section Bootstrapping an Environment +We consider the following published wallets to be “production wallets”: -@example -$ git clone https://git.taler.net/deployment.git ~/deployment -$ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py -$ ./deployment/bin/taler-deployment bootstrap -$ source ~/activate -$ taler-deployment build -$ taler-deployment-prepare -$ taler-deployment-start -$ taler-deployment-arm -I # check everything works -# The following command sets up the 'blog' and 'donations' instances. -$ taler-config-instances -@end example +@itemize * -@node Upgrading an Existing Environment,Switching Demo Colors,Bootstrapping an Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual upgrading-an-existing-environment}@anchor{15} -@section Upgrading an Existing Environment +@item +Browser: Firefox Add-On Store +@item +Browser: Chrome Web Store -@example -$ rm -rf ~/sources ~/local -$ git -C ~/deployment pull -$ cp ~/deployment/envcfg/$ENVCFGFILE ~/envcfg.py -$ taler-deployment bootstrap -$ taler-deployment build -$ taler-deployment-prepare -$ taler-deployment-restart -$ taler-deployment-arm -I # check everything works -@end example +@item +Android: Google Play -@node Switching Demo Colors,,Upgrading an Existing Environment,Demo Upgrade Procedure -@anchor{taler-developer-manual switching-demo-colors}@anchor{16} -@section Switching Demo Colors +@item +Android: F-Droid +@item +iOS: Apple Store / Testflight +@end itemize -As the @code{demo} user, to switch to color @code{$@{COLOR@}}, -run the following script from @code{deployment/bin}: +@node Basics,Exchange AML SPA,Wallets,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual basics}@anchor{1b} +@subsection Basics -@example -$ taler-deployment switch-demo -@end example -@node Environments and Builders on taler net,Releases,Demo Upgrade Procedure,Top -@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{17} + +@itemize - + +@item + Visit @indicateurl{https://demo.taler.net/} to see if the landing page is displayed correctly + +@item + landing language switcher + +@item + Visit the wallet installation page, install the wallet + +@item + see if the wallet presence indicator is updated correctly (in browsers). + +@item + Visit @indicateurl{https://bank.demo.taler.net/}, register a new user + +@item + bank language switcher + +@item + bank logout + +@item + bank login + +@item + bank-integrated withdraw process, abort in bank + +@item + transaction history: delete pending withdraw + +@item + do bank-integrated withdraw process (5 KUDOS) + +@item + do wallet-initiated withdraw process (5 KUDOS) + +@item + withdraw process of large amount (20 KUDOS) runs into KYC check + +@item + fail KYC check (if possible for the given setup) + +@item + pass KYC check (tests that 2nd attempt is possible) + +@item + withdraw process of very large amount (50 KUDOS) runs into AML check + +@item + visit exchange SPA, create AML officer key + +@item + register AML officer key with offline tool (if possible) + +@item + allow withdraw process blocked on AML to proceed (if possible) +@end itemize + +@node Exchange AML SPA,Blog demo,Basics,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual exchange-aml-spa}@anchor{1c} +@subsection Exchange AML SPA + + + +@itemize - + +@item + enter non-trivial form, change status to frozen + +@item + check account status in history is now frozen and shows in that category + +@item + enter another form, change status to normal, increase AML threshold + +@item + view forms in history, view previously submitted form + +@item + check account status in history is now normal and shows in that category + +@item + log out + +@item + check log in succeeds with correct password + +@item + check log in fails from different browser with same password +@end itemize + +@node Blog demo,Donation demo,Exchange AML SPA,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual blog-demo}@anchor{1d} +@subsection Blog demo + + + +@itemize - + +@item + Visit @indicateurl{https://shop.demo.taler.net/} + +@item + blog page article list renders + +@item + payment for blog article + +@item + Verify that the balance in the wallet was updated correctly. + +@item + Go back to @indicateurl{https://shop.demo.taler.net/} and click on the same article +link. Verify that the article is shown and `no' repeated payment is +requested. + +@item + Open the fulfillment page from the previous step in an anonymous browsing session +(without the wallet installed) and verify that it requests a payment again. + +@item + Delete cookies on @indicateurl{https://shop.demo.taler.net/} and click on the same article again. +Verify that the wallet detects that the article has already purchased and successfully +redirects to the article without spending more money. + +@item + payment for other blog article + +@item + refund of 2nd blog article (button at the end) + +@item + wallet transaction history rendering + +@item + delete refund history entry; check original purchase entry was also deleted + +@item + payment for other blog article + +@item + refund of 3rd blog article (button at the end) + +@item + wallet transaction history rendering + +@item + delete 3rd block purchase history entry; check refund entry was also deleted +@end itemize + +@node Donation demo,Merchant SPA,Blog demo,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual donation-demo}@anchor{1e} +@subsection Donation demo + + + +@itemize - + +@item + Reset wallet + +@item + Withdraw age-restricted coins (< 14) + +@item + Try to make a donation on @indicateurl{https://donations.demo.taler.net/}, fail due to age-restriction + +@item + Withdraw age-restricted coins (>= 14) + +@item + Make a donation on @indicateurl{https://donations.demo.taler.net/} + +@item + Make another donation with the same parameters and verify +that the payment is requested again, instead of showing the previous +fulfillment page. +@end itemize + +@node Merchant SPA,P2P payments,Donation demo,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual merchant-spa}@anchor{1f} +@subsection Merchant SPA + + + +@itemize - + +@item + test SPA loads + +@item + try to login with wrong password + +@item + try to login with correct password + +@item + create instance, check default is set to cover (STEFAN) fees + +@item + modify instance + +@item + add bank account + +@item + edit bank account + +@item + remove bank account + +@item + check order creation fails without bank account + +@item + add bank account again + +@item + add product with 1 in stock and preview image + +@item + add “advanced” order with inventory product and a 2 minute wire delay + +@item + claim order, check available stock goes down in inventory + +@item + create 2nd order, check this fails due to missing inventory + +@item + pay for 1st order with wallet + +@item + check transaction history for preview image + +@item + trigger partial refund + +@item + accept refund with wallet + +@item + create template with fixed summary, default editable price + +@item + scan template QR code, edit price and pay + +@item + add TOTP device (using some TOTP app to share secret with) + +@item + edit template to add TOTP device, set price to fixed, summary to be entered + +@item + scan template QR code, edit summary and pay + +@item + check displayed TOTP code matches TOTP app + +@item + do manual wire transfer in bank to establish reserve funding + +@item + check that partially refunded order is marked as awaiting wire transfer + +@item + check bank wired funds to merchant (if needed, wait) + +@item + add bank wire transfer manually to backend + +@item + change settings for merchant to not pay for (STEFAN) fees + +@item + create and pay for another order with 1 minute wire transfer delay + +@item + edit bank account details, adding revenue facade with credentials + +@item + wait and check if wire transfer is automatically imported + +@item + check that orders are marked as completed +@end itemize + +@node P2P payments,Shutdown,Merchant SPA,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual p2p-payments}@anchor{20} +@subsection P2P payments + + + +@itemize - + +@item + generating push payment (to self is OK) + +@item + accepting push payment (from self is OK) + +@item + generating pull payment (to self is OK) + +@item + accepting pull payment (from self is OK) + +@item + sending money back from wallet to bank account + +@item + wallet transaction history rendering + +@item + delete history entry +@end itemize + +@node Shutdown,,P2P payments,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual shutdown}@anchor{21} +@subsection Shutdown + + + +@itemize - + +@item + create two full wallets, fill one only via (a large) P2P transfer + +@item + revoke highest-value denomination + +@item + spend money in a wallet such that the balance falls below highest denomination value + +@item + revoke all remaining denominations + +@item + fail to spend any more money + +@item + if wallet was filled via p2p payments, wallet asks for target deposit account (exchange going out of business) + +@item + enter bank account (if possible) + +@item + wallet balance goes to zero + +@item + specified bank account receives remaining balance +@end itemize + +@node Environments and Builders on taler net,QA Plans,Demo Upgrade Procedure,Top +@anchor{taler-developer-manual environments-and-builders-on-taler-net}@anchor{22} @chapter Environments and Builders on taler.net @menu * Buildbot implementation:: +* Test builder:: +* Wallet builder:: * Documentation Builder:: * Website Builder:: * Code coverage:: -* Service Checker:: -* Tipping reserve top-up:: * Producing auditor reports:: * Database schema versioning:: @end menu -@node Buildbot implementation,Documentation Builder,,Environments and Builders on taler net -@anchor{taler-developer-manual buildbot-implementation}@anchor{18} +@node Buildbot implementation,Test builder,,Environments and Builders on taler net +@anchor{taler-developer-manual buildbot-implementation}@anchor{23} @section Buildbot implementation @@ -752,7 +1145,7 @@ The WORKER is the config that that lives on a shell account on a localhost (tale The WORKER running buildbot-worker receives these commands by authenticating and communicating with the buildbot server using parameters that were specified when the worker was created in that shell account with the @code{buildbot-worker} command. @item -The buildbot server's master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost. +The buildbot server’s master.cfg file contains FACTORY declarations which specify the commands that the WORKER will run on localhost. @item The FACTORY is tied to the WORKER in master.cfg by a BUILDER. @@ -770,7 +1163,7 @@ Best Practices: @itemize - @item -When creating a new WORKER in the @code{master.cfg} file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it's still good practice.) +When creating a new WORKER in the @code{master.cfg} file, leave a comment specifying the server and user account that this WORKER is called from. (At this time, taler.net is the only server used by this implementation, but it’s still good practice.) @item Create a worker from a shell account with this command: @code{buildbot-worker create-worker <workername> localhost <username> <password>} @@ -778,14 +1171,58 @@ Create a worker from a shell account with this command: @code{buildbot-worker cr Then make sure there is a WORKER defined in master.cfg like: @code{worker.Worker("<username>", "<password>")} -@node Documentation Builder,Website Builder,Buildbot implementation,Environments and Builders on taler net -@anchor{taler-developer-manual documentation-builder}@anchor{19} +@node Test builder,Wallet builder,Buildbot implementation,Environments and Builders on taler net +@anchor{taler-developer-manual test-builder}@anchor{24} +@section Test builder + + +This builder (@code{test-builder}) compiles and starts every Taler component. +The associated worker is run by the @code{taler-test} Gv user, via the SystemD +unit @code{buildbot-worker-taler}. The following commands start/stop/restart +the worker: + +@example +systemctl --user start buildbot-worker-taler +systemctl --user stop buildbot-worker-taler +systemctl --user restart buildbot-worker-taler +@end example + +@cartouche +@quotation Note +the mentioned unit file can be found at @code{deployment.git/systemd-services/} +@end quotation +@end cartouche + +@node Wallet builder,Documentation Builder,Test builder,Environments and Builders on taler net +@anchor{taler-developer-manual wallet-builder}@anchor{25} +@section Wallet builder + + +This builder (@code{wallet-builder}) compiles every Taler component +and runs the wallet integration tests. The associated worker is +run by the @code{walletbuilder} Gv user, via the SystemD unit @code{buildbot-worker-wallet}. +The following commands start/stop/restart the worker: + +@example +systemctl --user start buildbot-worker-wallet +systemctl --user stop buildbot-worker-wallet +systemctl --user restart buildbot-worker-wallet +@end example + +@cartouche +@quotation Note +the mentioned unit file can be found at @code{deployment.git/systemd-services/} +@end quotation +@end cartouche + +@node Documentation Builder,Website Builder,Wallet builder,Environments and Builders on taler net +@anchor{taler-developer-manual documentation-builder}@anchor{26} @section Documentation Builder All the Taler documentation is built by the user @code{docbuilder} that runs a Buildbot worker. The following commands set the @code{docbuilder} up, -starting with a empty home directory. +starting with an empty home directory. @example # Log-in as the 'docbuilder' user. @@ -801,13 +1238,13 @@ $ buildbot-worker start worker/ @end example @node Website Builder,Code coverage,Documentation Builder,Environments and Builders on taler net -@anchor{taler-developer-manual website-builder}@anchor{1a} +@anchor{taler-developer-manual website-builder}@anchor{27} @section Website Builder Taler Websites, @code{www.taler.net} and @code{stage.taler.net}, are built by the user @code{taler-websites} by the means of a Buildbot worker. The following -commands set the @code{taler-websites} up, starting with a empty home directory. +commands set the @code{taler-websites} up, starting with an empty home directory. @example # Log-in as the 'taler-websites' user. @@ -822,8 +1259,8 @@ $ ./deployment/bootstrap-sitesbuilder $ buildbot-worker start worker/ @end example -@node Code coverage,Service Checker,Website Builder,Environments and Builders on taler net -@anchor{taler-developer-manual code-coverage}@anchor{1b} +@node Code coverage,Producing auditor reports,Website Builder,Environments and Builders on taler net +@anchor{taler-developer-manual code-coverage}@anchor{28} @section Code coverage @@ -845,93 +1282,558 @@ $ buildbot-worker start worker/ The results are then published at @code{https://lcov.taler.net/}. -@node Service Checker,Tipping reserve top-up,Code coverage,Environments and Builders on taler net -@anchor{taler-developer-manual service-checker}@anchor{1c} -@section Service Checker +@node Producing auditor reports,Database schema versioning,Code coverage,Environments and Builders on taler net +@anchor{taler-developer-manual producing-auditor-reports}@anchor{29} +@section Producing auditor reports -The user @code{demo-checker} runs periodic checks to see if all the -@code{*.demo.taler.net} services are up and running. It is driven by -Buildbot, and can be bootstrapped as follows. +Both ‘test’ and ‘demo’ setups get their auditor reports compiled +by a Buildbot worker. The following steps get the reports compiler +prepared. @example -# Log-in as the 'demo-checker' user +# Log-in as <env>-auditor, with <env> being either 'test' or 'demo' -$ cd $HOME $ git clone git://git.taler.net/deployment -$ ./deployment/bootstrap-demochecker +$ ./deployment/buildbot/bootstrap-scripts/prepare-auditorreporter <env> -# If the previous step worked, the setup is -# complete and the Buildbot worker can be started. +# If the previous steps worked, then it should suffice to start +# the worker, with: $ buildbot-worker start worker/ @end example -@node Tipping reserve top-up,Producing auditor reports,Service Checker,Environments and Builders on taler net -@anchor{taler-developer-manual tipping-reserve-top-up}@anchor{1d} -@section Tipping reserve top-up +@node Database schema versioning,,Producing auditor reports,Environments and Builders on taler net +@anchor{taler-developer-manual database-schema-versioning}@anchor{2a}@anchor{taler-developer-manual databaseversioning}@anchor{5} +@section Database schema versioning -Both 'test' and 'demo' setups get their tip reserve topped up -by a Buildbot worker. The following steps get the reserve topper -prepared. +The PostgreSQL databases of the exchange and the auditor are versioned. +See the @code{versioning.sql} file in the respective directory for documentation. -@example -# Log-in as <env>-topper, with <env> being either 'test' or 'demo' +Every set of changes to the database schema must be stored in a new +versioned SQL script. The scripts must have contiguous numbers. After +any release (or version being deployed to a production or staging +environment), existing scripts MUST be immutable. -$ git clone git://git.taler.net/deployment -$ ./deployment/prepare-reservetopper <env> +Developers and operators MUST NOT make changes to database schema +outside of this versioning. All tables of a GNU Taler component should live in their own schema. -# If the previous steps worked, then it should suffice to start -# the worker, with: +@node QA Plans,Releases,Environments and Builders on taler net,Top +@anchor{taler-developer-manual qa-plans}@anchor{2b} +@chapter QA Plans -$ buildbot-worker start worker/ -@end example -@node Producing auditor reports,Database schema versioning,Tipping reserve top-up,Environments and Builders on taler net -@anchor{taler-developer-manual producing-auditor-reports}@anchor{1e} -@section Producing auditor reports +@menu +* Taler 0.9.4 QA Plan: Taler 0 9 4 QA Plan. +@end menu -Both 'test' and 'demo' setups get their auditor reports compiled -by a Buildbot worker. The following steps get the reports compiler -prepared. +@node Taler 0 9 4 QA Plan,,,QA Plans +@anchor{taler-developer-manual taler-0-9-4-qa-plan}@anchor{2c} +@section Taler 0.9.4 QA Plan -@example -# Log-in as <env>-auditor, with <env> being either 'test' or 'demo' -$ git clone git://git.taler.net/deployment -$ ./deployment/prepare-auditorreporter <env> +@menu +* Wallet Platforms:: +* Running Deployments:: +* Wallet Flows:: +* libeufin-bank Flows:: +* Merchant Backend SPA Flows:: +* Regio Deployment:: +* Android Merchant PoS:: +* Android Cashier App:: +* CI:: +* Debian Repository:: +* GNU Release:: -# If the previous steps worked, then it should suffice to start -# the worker, with: +@end menu -$ buildbot-worker start worker/ -@end example +@node Wallet Platforms,Running Deployments,,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-platforms}@anchor{2d} +@subsection Wallet Platforms -@node Database schema versioning,,Producing auditor reports,Environments and Builders on taler net -@anchor{taler-developer-manual database-schema-versioning}@anchor{1f} -@section Database schema versioning +Platforms listed here are the officially supported platforms for this release. -The Postgres databases of the exchange and the auditor are versioned. -See the 0000.sql file in the respective directory for documentation. -Every set of changes to the database schema must be stored in a new -versioned SQL script. The scripts must have contiguous numbers. After -any release (or version being deployed to a production or staging -environment), existing scripts MUST be immutable. +@itemize * -Developers and operators MUST NOT make changes to database schema -outside of this versioning. +@item +Overview / Installation Page + + +@itemize * + +@item +@indicateurl{https://taler.net/en/wallet.html} +@end itemize + +@item +Android + + +@itemize * + +@item +Google Play: @indicateurl{https://play.google.com/store/apps/details?id=net.taler.wallet} + +@item +F-Droid: @indicateurl{https://f-droid.org/en/packages/net.taler.wallet.fdroid/} + +@item +APK Download: TBD +@end itemize + +@item +Browser + + +@itemize * + +@item +Chrome: @indicateurl{https://chromewebstore.google.com/detail/gnu-taler-wallet/millncjiddlpgdmkklmhfadpacifaonc} + +@item +Firefox: @indicateurl{https://addons.mozilla.org/en-US/firefox/addon/taler-wallet/} +@end itemize + +@item +iOS +@end itemize + +@node Running Deployments,Wallet Flows,Wallet Platforms,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual running-deployments}@anchor{2e} +@subsection Running Deployments + + +These deployments are maintained by us and should work for the release: + + +@itemize * + +@item +Sandcastle-based: + + +@itemize * + +@item +demo.taler.net + +@item +test.taler.net +@end itemize + +@item +Regio-based: + + +@itemize * + +@item +regio-taler.fdold.eu +@end itemize +@end itemize + +@node Wallet Flows,libeufin-bank Flows,Running Deployments,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-flows}@anchor{2f} +@subsection Wallet Flows + + + +@itemize * + +@item +Bank-integrated withdrawal + + +@itemize * + +@item +webext: “Continue with Mobile Wallet” flow +@end itemize + +@item +Manual withdrawal + + +@itemize * + +@item +@code{taler://withdraw-exchange} flow -@node Releases,Continuous integration,Environments and Builders on taler net,Top -@anchor{taler-developer-manual releases}@anchor{20} +@item +Currency conversion withdrawal +@end itemize + +@item +Peer push payments (“Send Money”) + +@item +Peer pull payments (“Receive Money”) + +@item +Deposit into bank account + + +@itemize * + +@item +Check that deposit arrived +@end itemize + +@item +Payment at merchant + + +@itemize * + +@item +on blog merchant + +@item +on survey + +@item +directly initiated via merchant SPA + +@item +webext: “Pay with Mobile Wallet” flow +@end itemize + +@item +Pay templates + + +@itemize * + +@item +Payment TOTP codes +@end itemize + +@item +Exchange management + + +@itemize * + +@item +Reloading exchange keys + +@item +Deleting an exchange +@end itemize +@end itemize + +@node libeufin-bank Flows,Merchant Backend SPA Flows,Wallet Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual libeufin-bank-flows}@anchor{30} +@subsection libeufin-bank Flows + + + +@itemize * + +@item +Admin functionality + + +@itemize * + +@item +Login + +@item +Credential change + +@item +Conversion settings + +@item +Bank account creation + +@item +Test transfers +@end itemize + +@item +Normal account functionality + + +@itemize * + +@item +Transfers + + +@itemize * + +@item +Transfer to the exchange should bounce +@end itemize + +@item +Withdrawals + +@item +(conversion-only): Test cash-in + +@item +(conversion-only): Test cash-out + + +@itemize * + +@item +Lower cash-out limit enforced +@end itemize + +@item +2FA for withdrawals, cash-out +@end itemize +@end itemize + +@node Merchant Backend SPA Flows,Regio Deployment,libeufin-bank Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual merchant-backend-spa-flows}@anchor{31} +@subsection Merchant Backend SPA Flows + + + +@itemize * + +@item +Instance creation + +@item +Simple bank account setup + +@item +Order creation + + +@itemize * + +@item +Pay order (with short wire transfer deadline) + +@item +Check that money from order arrive at the bank with the right subject +@end itemize + +@item +Extended bank account setup + + +@itemize * + +@item +Add Taler Bank Revenue API + +@item +Check bank transfer list (for wire transfer of previously paid+wired order) + +@item +Check order payment status goes to “final” automatically +@end itemize + +@item +TOTP Device Management + + +@itemize * + +@item +Add device + +@item +Edit device (set new secret, export new secret as QR code) + +@item +Delete device +@end itemize + +@item +Templates + + +@itemize * + +@item +Add template + +@item +Edit template + +@item +Add TOTP device to template + +@item +Edit TOTP device associated with template + +@item +Pay template + +@item +Check TOTP code matches + +@item +Remove TOTP device from template + +@item +Delete template +@end itemize +@end itemize + +@node Regio Deployment,Android Merchant PoS,Merchant Backend SPA Flows,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual regio-deployment}@anchor{32} +@subsection Regio Deployment + + + +@itemize * + +@item +Deployment Automation (deployment.git/regional-currency) + + +@itemize * + +@item +Test with Debian bookworm + +@item +Test with Ubuntu mantic + +@item +Check logs for errors + +@item +Test with telesign (SMS) + +@item +Set up EBICS integration + +@item +Check that ToS is configured +@end itemize + +@item +Deployment Functionality + + +@itemize * + +@item +All flows of the wallet should work (see @code{Wallet Flows} above) + +@item +All flows of libeufin-bank should work (see @code{libeufin-bank Flows} above) + +@item +Merchant backend should work (see @code{Merchant Backend SPA Flows} above) + +@item +Check logs +@end itemize +@end itemize + +@node Android Merchant PoS,Android Cashier App,Regio Deployment,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-merchant-pos}@anchor{33} +@subsection Android Merchant PoS + + + +@itemize * + +@item +Test against demo.taler.net +@end itemize + +@node Android Cashier App,CI,Android Merchant PoS,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual android-cashier-app}@anchor{34} +@subsection Android Cashier App + + + +@itemize * + +@item +Test against demo.taler.net +@end itemize + +@node CI,Debian Repository,Android Cashier App,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual ci}@anchor{35} +@subsection CI + + + +@itemize * + +@item +@indicateurl{https://buildbot.taler.net/#/waterfall} + +@item +CI should pass +@end itemize + +@node Debian Repository,GNU Release,CI,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual debian-repository}@anchor{36} +@subsection Debian Repository + + + +@itemize * + +@item +Debian + + +@itemize * + +@item +repo at @indicateurl{https://deb.taler.net/apt/debian/} + +@item +supported codename(s): bookworm +@end itemize + +@item +Ubuntu: + + +@itemize * + +@item +repo at @indicateurl{https://deb.taler.net/apt/ubuntu/} + +@item +supported codename(s): mantic +@end itemize +@end itemize + +@node GNU Release,,Debian Repository,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual gnu-release}@anchor{37} +@subsection GNU Release + + + +@itemize * + +@item +Release announcement + +@item +FTP upload +@end itemize + +@node Releases,Continuous integration,QA Plans,Top +@anchor{taler-developer-manual releases}@anchor{38} @chapter Releases @menu -* Release Process and Checklists:: +* GNU Taler Release Checklist:: +* Release Process:: * Tagging:: * Database for tests:: * Exchange@comma{} merchant: Exchange merchant. @@ -941,12 +1843,387 @@ outside of this versioning. @end menu -@node Release Process and Checklists,Tagging,,Releases -@anchor{taler-developer-manual release-process-and-checklists}@anchor{21} -@section Release Process and Checklists +@node GNU Taler Release Checklist,Release Process,,Releases +@anchor{taler-developer-manual gnu-taler-release-checklist}@anchor{39} +@section GNU Taler Release Checklist -Please use the @ref{1,,release checklist} +For exchange: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + Change version number in configure.ac. + +@item + update man pages / info page documentation (prebuilt branch) + +@item + make dist for release + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For merchant (C backend): + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + update SPA (prebuilt branch) + +@item + Change version number in configure.ac. + +@item + make dist for release. + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For sync: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + Change version number in configure.ac. + +@item + make dist for release + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For taler-mdb: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + ensure Coverity static analysis passes + +@item + Change version number in configure.ac. + +@item + make dist for release. + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For taler-twister: + + +@itemize - + +@item + no compiler warnings at “-Wall” with gcc + +@item + no compiler warnings at “-Wall” with clang + +@item + ensure Coverity static analysis passes + +@item + make check. + +@item + make dist, make check on result of ‘make dist’. + +@item + Change version number in configure.ac. + +@item + make dist for release. + +@item + verify dist builds from source + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For libeufin: + + +@itemize - + +@item + update SPA of bank + +@item + build libeufin + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + make dist for release. + +@item + verify dist builds from source + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +For Python merchant frontend: + + +@itemize - + +@item + upgrade ‘demo.taler.net’ + +@item + run demo upgrade checklist + +@item + change ‘demo.taler.net’ deployment to use new tag. +@end itemize + +Wallet-core: + + +@itemize - + +@item + build wallet + +@item + run integration test + +@item + make dist for release. + +@item + verify dist builds from source + +@item + tag repo. + +@item + use ‘deployment.git/packaging/*-docker/’ to build Debian and Ubuntu packages + +@item + upload packages to ‘deb.taler.net’ (note: only Florian/Christian can sign) + +@item + change ‘demo.taler.net’ deployment to use new tag. + +@item + Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@end itemize + +Android-Wallet: + + +@itemize - + +@item + build wallet + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + upload new wallet release to app store +@end itemize + +Webextension-Wallet: + + +@itemize - + +@item + build wallet + +@item + run demo upgrade checklist + +@item + tag repo. + +@item + upload new wallet release to app store +@end itemize + +Release announcement: + + +@itemize - + +@item + Update bug tracker (mark release, resolved -> closed) + +@item + Send announcement to @email{taler@@gnu.org} + +@item + Send announcement to @email{info-gnu@@gnu.org} (major releases only) + +@item + Send announcement to @email{coordinator@@translationproject.org} +@end itemize + +@node Release Process,Tagging,GNU Taler Release Checklist,Releases +@anchor{taler-developer-manual release-process}@anchor{3a} +@section Release Process + This document describes the process for releasing a new version of the various Taler components to the official GNU mirrors. @@ -963,24 +2240,27 @@ taler-exchange (exchange.git) taler-merchant (merchant.git) @item -talerdonations (donations.git) +sync (sync.git) @item -talerblog (blog.git) +taler-mdb (taler-mdb.git) @item -taler-bank (bank.git) +libeufin (libeufin.git) @item -taler-wallet-webex (wallet-webex.git) +challenger (challenger.git) + +@item +wallet-core (wallet-core.git) @end itemize -@node Tagging,Database for tests,Release Process and Checklists,Releases -@anchor{taler-developer-manual tagging}@anchor{22} +@node Tagging,Database for tests,Release Process,Releases +@anchor{taler-developer-manual tagging}@anchor{3b} @section Tagging -Tag releases with an @strong{annotated} commit, like +Tag releases with an `annotated' commit, like @example $ git tag -a v0.1.0 -m "Official release v0.1.0" @@ -988,16 +2268,24 @@ $ git push origin v0.1.0 @end example @node Database for tests,Exchange merchant,Tagging,Releases -@anchor{taler-developer-manual database-for-tests}@anchor{23} +@anchor{taler-developer-manual database-for-tests}@anchor{3c} @section Database for tests For tests in the exchange and merchant to run, make sure that a database -@emph{talercheck} is accessible by @emph{$USER}. Otherwise tests involving the +`talercheck' is accessible by `$USER'. Otherwise tests involving the database logic are skipped. +@cartouche +@quotation Note +Taler may store sensitive business and customer data in the database. Any +operator SHOULD thus ensure that backup operations are encrypted and +secured from unauthorized access. +@end quotation +@end cartouche + @node Exchange merchant,Wallet WebExtension,Database for tests,Releases -@anchor{taler-developer-manual exchange-merchant}@anchor{24} +@anchor{taler-developer-manual exchange-merchant}@anchor{3d} @section Exchange, merchant @@ -1044,7 +2332,7 @@ For bootstrap, you will need to install GNU Recutils@footnote{https://www.gnu.org/software/recutils/}. For the exchange test cases to pass, @code{make install} must be run first. -Without it, test cases will fail because plugins can't be located. +Without it, test cases will fail because plugins can’t be located. @example $ ./bootstrap @@ -1056,12 +2344,12 @@ $ make install check @end example @node Wallet WebExtension,Upload to GNU mirrors,Exchange merchant,Releases -@anchor{taler-developer-manual wallet-webextension}@anchor{25} +@anchor{taler-developer-manual wallet-webextension}@anchor{3e} @section Wallet WebExtension -The version of the wallet is in @emph{manifest.json}. The @code{version_name} -should be adjusted, and @emph{version} should be increased independently on +The version of the wallet is in `manifest.json'. The @code{version_name} +should be adjusted, and `version' should be increased independently on every upload to the WebStore. @example @@ -1070,7 +2358,7 @@ $ make dist @end example @node Upload to GNU mirrors,Creating Debian packages,Wallet WebExtension,Releases -@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{26} +@anchor{taler-developer-manual upload-to-gnu-mirrors}@anchor{3f} @section Upload to GNU mirrors @@ -1082,12 +2370,13 @@ Directive file: version: 1.2 directory: taler filename: taler-exchange-0.1.0.tar.gz +symlink: taler-exchange-0.1.0.tar.gz taler-exchange-latest.tar.gz @end example -Upload the files in @strong{binary mode} to the ftp servers. +Upload the files in `binary mode' to the ftp servers. @node Creating Debian packages,,Upload to GNU mirrors,Releases -@anchor{taler-developer-manual creating-debian-packages}@anchor{27} +@anchor{taler-developer-manual creating-debian-packages}@anchor{40} @section Creating Debian packages @@ -1104,25 +2393,29 @@ $ dpkg-buildpackage -rfakeroot -b -uc -us in the respective source directory (GNUnet, exchange, merchant) to create the @code{.deb} files. Note that they will be created in the parent directory. This can be done on gv.taler.net, or on another (secure) machine. +Actual release builds should be done via the Docker images +that can be found in @code{deployment.git} under packaging. + +On @code{gv}, we use the @code{aptbuilder} user to manage the reprepro repository. Next, the @code{*.deb} files should be copied to gv.taler.net, say to -@code{/root/incoming}. Then, run +@code{/home/aptbuilder/incoming}. Then, run @example -# cd /var/www/repos/apt/debian/ -# reprepro includedeb sid /root/incoming/*.deb +# cd /home/aptbuilder/apt +# reprepro includedeb bullseye ~/incoming/*.deb @end example -to import all Debian files from @code{/root/incoming/} into the @code{sid} +to import all Debian files from @code{~/incoming/} into the @code{bullseye} distribution. If Debian packages were build against other distributions, reprepro may need to be first configured for those and the import command updated accordingly. -Finally, make sure to clean up @code{/root/incoming/} (by deleting the +Finally, make sure to clean up @code{~/incoming/} (by deleting the now imported @code{*.deb} files). @node Continuous integration,Internationalization,Releases,Top -@anchor{taler-developer-manual continuous-integration}@anchor{28} +@anchor{taler-developer-manual continuous-integration}@anchor{41} @chapter Continuous integration @@ -1130,21 +2423,21 @@ CI is done with Buildbot (@indicateurl{https://buildbot.net/}), and builds are triggered by the means of Git hooks. The results are published at @indicateurl{https://buildbot.taler.net/} . -In order to avoid downtimes, CI uses a "blue/green" deployment +In order to avoid downtimes, CI uses a “blue/green” deployment technique. In detail, there are two users building code on the system, -the "green" and the "blue" user; and at any given time, one is running +the “green” and the “blue” user; and at any given time, one is running Taler services and the other one is either building the code or waiting for that. There is also the possibility to trigger builds manually, but this is -only reserved to "admin" users. +only reserved to “admin” users. -@node Internationalization,Android Apps,Continuous integration,Top -@anchor{taler-developer-manual internationalization}@anchor{29} +@node Internationalization,iOS Apps,Continuous integration,Top +@anchor{taler-developer-manual internationalization}@anchor{42} @chapter Internationalization -Internationalization (a.k.a "Translation") is handled with Weblate (@indicateurl{https://weblate.org}) via our instance at @indicateurl{https://weblate.taler.net/} . +Internationalization (a.k.a “Translation”) is handled with Weblate (@indicateurl{https://weblate.org}) via our instance at @indicateurl{https://weblate.taler.net/} . At this time, this system is still very new for Taler.net and this documentation may be incorrect and is certainly incomplete. @@ -1161,14 +2454,14 @@ At this time, this system is still very new for Taler.net and this documentation @end menu @node Who can Register,About Privilege Levels,,Internationalization -@anchor{taler-developer-manual who-can-register}@anchor{2a} +@anchor{taler-developer-manual who-can-register}@anchor{43} @section Who can Register -At this time, anyone can register an account at @indicateurl{https://weblate.taler.net/} to create translations. Registered users default to the @strong{Users} and @strong{Viewers} privilege level. +At this time, anyone can register an account at @indicateurl{https://weblate.taler.net/} to create translations. Registered users default to the `Users' and `Viewers' privilege level. @node About Privilege Levels,Upgrading Privileges,Who can Register,Internationalization -@anchor{taler-developer-manual about-privilege-levels}@anchor{2b} +@anchor{taler-developer-manual about-privilege-levels}@anchor{44} @section About Privilege Levels @@ -1178,113 +2471,177 @@ This is the breakdown of privilege levels in Weblate: @itemize * @item -@strong{Users}/@strong{Viewers} = Can log in, view Translations (@emph{applies to new users}) +`Users'/`Viewers' = Can log in, view Translations (`applies to new users') @item -@strong{Reviewers} = Can contribute Translations to existing @emph{Components} +`Reviewers' = Can contribute Translations to existing `Components' @item -@strong{Managers} = Can create new @emph{Components} of existing @emph{Projects} +`Managers' = Can create new `Components' of existing `Projects' @item -@strong{Superusers} = Can create new @emph{Projects} +`Superusers' = Can create new `Projects' @end itemize @node Upgrading Privileges,How to Create a Project,About Privilege Levels,Internationalization -@anchor{taler-developer-manual upgrading-privileges}@anchor{2c} +@anchor{taler-developer-manual upgrading-privileges}@anchor{45} @section Upgrading Privileges -To upgrade from @strong{Users}/@strong{Viewers}, a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. +To upgrade from `Users'/`Viewers', a superuser must manually augment your privileges. At this time, superusers are Christian, Florian, and Buck. @node How to Create a Project,How to Create a Component,Upgrading Privileges,Internationalization -@anchor{taler-developer-manual how-to-create-a-project}@anchor{2d} +@anchor{taler-developer-manual how-to-create-a-project}@anchor{46} @section How to Create a Project -The @emph{GNU Taler} project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. +The `GNU Taler' project is probably the correct project for most Components and Translations falling under this guide. Please contact a superuser if you need another Project created. @node How to Create a Component,How to Create a Translation,How to Create a Project,Internationalization -@anchor{taler-developer-manual how-to-create-a-component}@anchor{2e} +@anchor{taler-developer-manual how-to-create-a-component}@anchor{47} @section How to Create a Component Reference: @indicateurl{https://docs.weblate.org/en/weblate-4.0.3/admin/projects.html#component-configuration} -In Weblate, a @emph{Component} is a subset of a @emph{Project} and each Component contains N translations. A Component is generally associated with a Git repo. +In Weblate, a `Component' is a subset of a `Project' and each Component contains N translations. A Component is generally associated with a Git repo. -To create a Component, log into @indicateurl{https://weblate.taler.net/} with your @emph{Manager} or higher credentials and choose @strong{+ Add} from the upper-right corner. +To create a Component, log into @indicateurl{https://weblate.taler.net/} with your `Manager' or higher credentials and choose `+ Add' from the upper-right corner. What follows is a sort of Wizard. You can find detailed docs at @indicateurl{https://docs.weblate.org/}. Here are some important notes about connecting your Component to the Taler Git repository: -Under @emph{https://weblate.taler.net/create/component/vcs/}: +Under `https://weblate.taler.net/create/component/vcs/': @itemize * @item -@strong{Source code repository} - Generally @code{git+ssh://git@@git.taler.net/<reponame>`}. Check with @code{git remote -v}. +`Source code repository' - Generally @code{git+ssh://git@@git.taler.net/<reponame>`}. Check with @code{git remote -v}. @item -@strong{Repository branch} - Choose the correct branch to draw from and commit to. +`Repository branch' - Choose the correct branch to draw from and commit to. @item -@strong{Repository push URL} - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}. +`Repository push URL' - This is generally @code{git+ssh://git@@git.taler.net/<reponame>`} Check with @code{git remote -v}. @item -@strong{Repository browser} - This is the www URL of the Git repo's file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string. +`Repository browser' - This is the www URL of the Git repo’s file browser. Example @code{https://git.taler.net/<repositoryname>.git/tree/@{@{filename@}@}?h=@{@{branch@}@}#n@{@{line@}@}} where @code{<repositoryname>} gets replaced but @code{@{@{filename@}@}} and other items in braces are actual variables in the string. @item -@strong{Merge style} - @emph{Rebase}, in line with GNU Taler development procedures +`Merge style' - `Rebase', in line with GNU Taler development procedures @item -@strong{Translation license} - @emph{GNU General Public License v3.0 or Later} +`Translation license' - `GNU Affero General Public License v3.0 or Later' @item -@strong{Adding new translation} - Decide how to handle adding new translations +`Adding new translation' - Decide how to handle adding new translations @end itemize @node How to Create a Translation,Translation Standards and Practices,How to Create a Component,Internationalization -@anchor{taler-developer-manual how-to-create-a-translation}@anchor{2f} +@anchor{taler-developer-manual how-to-create-a-translation}@anchor{48} @section How to Create a Translation 1 - Log into @indicateurl{https://weblate.taler.net} -2 - Navigate to @emph{Projects} > @emph{Browse all projects} +2 - Navigate to `Projects' > `Browse all projects' -3 - Choose the @emph{Project} you wish to contribute to. +3 - Choose the `Project' you wish to contribute to. -4 - Choose the @emph{Component} you wish to contribute to. +4 - Choose the `Component' you wish to contribute to. -5 - Find the language you want to translate into. Click "Translate" on that line. +5 - Find the language you want to translate into. Click “Translate” on that line. 6 - Find a phrase and translate it. You may also wish to refer to @indicateurl{https://docs.weblate.org/} . @node Translation Standards and Practices,GPG Signing of Translations,How to Create a Translation,Internationalization -@anchor{taler-developer-manual translation-standards-and-practices}@anchor{30} +@anchor{taler-developer-manual translation-standards-and-practices}@anchor{49} @section Translation Standards and Practices -By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the @emph{Component} you want to translate for, and click "Start new translation" to begin. If you require a privilege upgrade, please contact a superuser with your request. +By default, our Weblate instance is set to accept translations in English, French, German, Italian, Russian, Spanish, and Portuguese. If you want to contribute a translation in a different language, navigate to the `Component' you want to translate for, and click “Start new translation” to begin. If you require a privilege upgrade, please contact a superuser with your request. When asked, set the license to GPLv3 or later. Set commit/push to manual only. @node GPG Signing of Translations,,Translation Standards and Practices,Internationalization -@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{31} +@anchor{taler-developer-manual gpg-signing-of-translations}@anchor{4a} @section GPG Signing of Translations weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F2664BF474BFE502, and the corresponding public key can be found at @indicateurl{https://weblate.taler.net/keys/}. -This means that contributions made through weblate will not be signed with the individual contributor's key when they are checked into the Git repository, but with the weblate key. +This means that contributions made through weblate will not be signed with the individual contributor’s key when they are checked into the Git repository, but with the weblate key. + +@node iOS Apps,Android Apps,Internationalization,Top +@anchor{taler-developer-manual ios-apps}@anchor{4b} +@chapter iOS Apps + + +@menu +* Building Taler Wallet for iOS from source:: + +@end menu + +@node Building Taler Wallet for iOS from source,,,iOS Apps +@anchor{taler-developer-manual build-ios-from-source}@anchor{4c}@anchor{taler-developer-manual building-taler-wallet-for-ios-from-source}@anchor{4d} +@section Building Taler Wallet for iOS from source + + +The GNU Taler Wallet iOS app is in +the official Git repository@footnote{https://git.taler.net/taler-ios.git}. + +@menu +* Compatibility:: +* Building:: + +@end menu + +@node Compatibility,Building,,Building Taler Wallet for iOS from source +@anchor{taler-developer-manual compatibility}@anchor{4e} +@subsection Compatibility + + +The minimum version of iOS supported is 15.0. +This app runs on all iPhone models at least as new as the iPhone 6S. + +@node Building,,Compatibility,Building Taler Wallet for iOS from source +@anchor{taler-developer-manual building}@anchor{4f} +@subsection Building + + +Before building the iOS wallet, you must first checkout the +quickjs-tart repo@footnote{https://git.taler.net/quickjs-tart.git} +and the +wallet-core repo@footnote{https://git.taler.net/wallet-core.git}. + +Have all 3 local repos (wallet-core, quickjs-tart, and this one) adjacent at +the same level (e.g. in a “GNU_Taler” folder) +Taler.xcworkspace expects the QuickJS framework sub-project to be at +@code{../quickjs-tart/QuickJS-rt.xcodeproj}. + +Build wallet-core first: + +@example +$ cd wallet-core +$ make embedded +$ open packages/taler-wallet-embedded/dist +@end example + +then drag or move its product “taler-wallet-core-qjs.mjs” +into your quickjs-tart folder right at the top level. + +Open Taler.xcworkspace, and set scheme / target to Taler_Wallet. Build&run… + +Don’t open QuickJS-rt.xcodeproj or TalerWallet.xcodeproj and build anything +there - all needed libraries and frameworks will be built automatically from +Taler.xcworkspace. -@node Android Apps,Code Coverage,Internationalization,Top -@anchor{taler-developer-manual android-apps}@anchor{32} +@node Android Apps,Code Coverage,iOS Apps,Top +@anchor{taler-developer-manual android-apps}@anchor{50} @chapter Android Apps @@ -1297,7 +2654,7 @@ This means that contributions made through weblate will not be signed with the i @end menu @node Android App Nightly Builds,Building apps from source,,Android Apps -@anchor{taler-developer-manual android-app-nightly-builds}@anchor{33} +@anchor{taler-developer-manual android-app-nightly-builds}@anchor{51} @section Android App Nightly Builds @@ -1322,7 +2679,7 @@ Cashier Their git repositories are mirrored at Gitlab@footnote{https://gitlab.com/gnu-taler/taler-android} to utilize their CI -and F-Droid@footnote{https://f-droid.org}'s Gitlab integration +and F-Droid@footnote{https://f-droid.org}’s Gitlab integration to publish automatic nightly builds@footnote{https://f-droid.org/docs/Publishing_Nightly_Builds/} for each change on the @code{master} branch. @@ -1342,13 +2699,13 @@ GNU Taler Nightly F-Droid Repository@footnote{fdroidrepos://gnu-taler.gitlab.io/ @cartouche @quotation Note Nightly apps can be installed alongside official releases -and thus are meant @strong{only for testing purposes}. +and thus are meant `only for testing purposes'. Use at your own risk! @end quotation @end cartouche @node Building apps from source,Update translations,Android App Nightly Builds,Android Apps -@anchor{taler-developer-manual build-apps-from-source}@anchor{34}@anchor{taler-developer-manual building-apps-from-source}@anchor{35} +@anchor{taler-developer-manual build-apps-from-source}@anchor{52}@anchor{taler-developer-manual building-apps-from-source}@anchor{53} @section Building apps from source @@ -1372,7 +2729,7 @@ git unzip @end itemize -Then you can get the app's source code using git: +Then you can get the app’s source code using git: @example # Start by cloning the Android git repository @@ -1389,12 +2746,12 @@ The last command will return something like @code{compileSdkVersion 29}. So visit the Android Rebuilds@footnote{http://android-rebuilds.beuc.net/} project and look for that version of the Android SDK there. If the SDK version is not yet available as a free rebuild, -you can try to lower the @code{compileSdkVersion} in the app's @code{merchant-terminal/build.gradle} file. +you can try to lower the @code{compileSdkVersion} in the app’s @code{merchant-terminal/build.gradle} file. Note that this might break things or require you to also lower other versions such as @code{targetSdkVersion}. In our example, the version is @code{29} which is available, -so download the "SDK Platform" package of "Android 10.0.0 (API 29)" +so download the “SDK Platform” package of “Android 10.0.0 (API 29)” and unpack it: @example @@ -1427,18 +2784,18 @@ build-tools;29.0.3 Android SDK Build-Tools 29.0.3 @end table @end quotation -you can try changing the @code{buildToolsVersion} in the app's @code{merchant-terminal/build.gradle} file -to the latest "Android SDK build tools" version supported by the Android Rebuilds project. +you can try changing the @code{buildToolsVersion} in the app’s @code{merchant-terminal/build.gradle} file +to the latest “Android SDK build tools” version supported by the Android Rebuilds project. After the build finished successfully, you will find your APK in @code{merchant-terminal/build/outputs/apk/release/}. @node Update translations,Release process,Building apps from source,Android Apps -@anchor{taler-developer-manual update-translations}@anchor{36} +@anchor{taler-developer-manual update-translations}@anchor{54} @section Update translations -Translations are managed with Taler's weblate instance: +Translations are managed with Taler’s weblate instance: @indicateurl{https://weblate.taler.net/projects/gnu-taler/} To update translations, enter the taler-android git repository @@ -1468,7 +2825,7 @@ Afterwards, build the entire project from source and test the UI to ensure that no erroneous translations (missing placeholders) are breaking things. @node Release process,,Update translations,Android Apps -@anchor{taler-developer-manual release-process}@anchor{37} +@anchor{taler-developer-manual id1}@anchor{55} @section Release process @@ -1499,12 +2856,12 @@ $ git tag -s $APP-$VERSION @end menu @node F-Droid,Google Play,,Release process -@anchor{taler-developer-manual id1}@anchor{38} +@anchor{taler-developer-manual id2}@anchor{56} @subsection F-Droid Nightly builds get published automatically (see above) after pushing code to the official repo. -Actual releases get picked up by F-Droid's official repository via git tags. +Actual releases get picked up by F-Droid’s official repository via git tags. So ensure that all releases get tagged properly. Some information for F-Droid official repository debugging: @@ -1523,7 +2880,7 @@ PoS: [metadata@footnote{https://gitlab.com/fdroid/fdroiddata/-/blob/master/metad @end itemize @node Google Play,,F-Droid,Release process -@anchor{taler-developer-manual google-play}@anchor{39} +@anchor{taler-developer-manual google-play}@anchor{57} @subsection Google Play @@ -1545,7 +2902,7 @@ All uploads are going to the beta track by default. These can be promoted to production later or immediately after upload if you feel daring. @node Code Coverage,Coding Conventions,Android Apps,Top -@anchor{taler-developer-manual id2}@anchor{3a}@anchor{taler-developer-manual id3}@anchor{3b} +@anchor{taler-developer-manual id3}@anchor{58}@anchor{taler-developer-manual id4}@anchor{59} @chapter Code Coverage @@ -1555,22 +2912,24 @@ nightly (once a day) by a Buildbot worker. The coverage results are then published at @indicateurl{https://lcov.taler.net/} . @node Coding Conventions,Testing library,Code Coverage,Top -@anchor{taler-developer-manual coding-conventions}@anchor{3c} +@anchor{taler-developer-manual coding-conventions}@anchor{5a} @chapter Coding Conventions -GNU Taler is developed primarily in C, Kotlin, Python and TypeScript. +GNU Taler is developed primarily in C, Kotlin, Python, Swift and TypeScript. @menu * Components written in C:: * Shell Scripts:: * Kotlin:: * Python:: +* Swift:: +* TypeScript:: @end menu @node Components written in C,Shell Scripts,,Coding Conventions -@anchor{taler-developer-manual components-written-in-c}@anchor{3d} +@anchor{taler-developer-manual components-written-in-c}@anchor{5b} @section Components written in C @@ -1590,7 +2949,7 @@ by the GNUnet style: @indicateurl{https://docs.gnunet.org/handbook/gnunet.html#C @end menu @node Naming conventions,,,Components written in C -@anchor{taler-developer-manual naming-conventions}@anchor{3e} +@anchor{taler-developer-manual naming-conventions}@anchor{5c} @subsection Naming conventions @@ -1604,22 +2963,22 @@ include files (very similar to GNUnet): @itemize * @item -if installed, must start with "@code{taler_}" (exception: platform.h), +if installed, must start with “@code{taler_}” (exception: platform.h), and MUST live in src/include/ @item -if NOT installed, must NOT start with "@code{taler_}" and +if NOT installed, must NOT start with “@code{taler_}” and MUST NOT live in src/include/ and SHOULD NOT be included from outside of their own directory @item -end in "_lib" for "simple" libraries +end in “_lib” for “simple” libraries @item -end in "_plugin" for plugins +end in “_plugin” for plugins @item -end in "_service" for libraries accessing a service, i.e. the exchange +end in “_service” for libraries accessing a service, i.e. the exchange @end itemize @item @@ -1652,22 +3011,22 @@ logging @item tools use their full name in GNUNET_log_setup -(i.e. 'taler-exchange-offline') and log using plain 'GNUNET_log'. +(i.e. ‘taler-exchange-offline’) and log using plain ‘GNUNET_log’. @item -pure libraries (without associated service) use 'GNUNET_log_from' -with the component set to their library name (without lib or '.so'), -which should also be their directory name (i.e. 'util') +pure libraries (without associated service) use ‘GNUNET_log_from’ +with the component set to their library name (without lib or ‘.so’), +which should also be their directory name (i.e. ‘util’) @item -plugin libraries (without associated service) use 'GNUNET_log_from' -with the component set to their type and plugin name (without lib or '.so'), -which should also be their directory name (i.e. 'exchangedb-postgres') +plugin libraries (without associated service) use ‘GNUNET_log_from’ +with the component set to their type and plugin name (without lib or ‘.so’), +which should also be their directory name (i.e. ‘exchangedb-postgres’) @item -libraries with associated service) use 'GNUNET_log_from' +libraries with associated service) use ‘GNUNET_log_from’ with the name of the service, which should also be their -directory name (i.e. 'exchange') +directory name (i.e. ‘exchange’) @item for tools with @code{-l LOGFILE}, its absence means write logs to stderr @@ -1709,14 +3068,14 @@ structs: @itemize * @item -structs that are 'packed' and do not contain pointers and are +structs that are ‘packed’ and do not contain pointers and are thus suitable for hashing or similar operations are distinguished -by adding a "P" at the end of the name. (NEW) Note that this +by adding a “P” at the end of the name. (NEW) Note that this convention does not hold for the GNUnet-structs (yet). @item structs that are used with a purpose for signatures, additionally -get an "S" at the end of the name. +get an “S” at the end of the name. @end itemize @item @@ -1736,7 +3095,7 @@ testcases @itemize * @item -must be called "test_module-under-test_case-description.c" +must be called “test_module-under-test_case-description.c” @end itemize @item @@ -1746,12 +3105,12 @@ performance tests @itemize * @item -must be called "perf_module-under-test_case-description.c" +must be called “perf_module-under-test_case-description.c” @end itemize @end itemize @node Shell Scripts,Kotlin,Components written in C,Coding Conventions -@anchor{taler-developer-manual shell-scripts}@anchor{3f} +@anchor{taler-developer-manual shell-scripts}@anchor{5d} @section Shell Scripts @@ -1778,15 +3137,15 @@ $ set -eu @end example @node Kotlin,Python,Shell Scripts,Coding Conventions -@anchor{taler-developer-manual kotlin}@anchor{40} +@anchor{taler-developer-manual kotlin}@anchor{5e} @section Kotlin We so far have no specific guidelines, please follow best practices for the language. -@node Python,,Kotlin,Coding Conventions -@anchor{taler-developer-manual python}@anchor{41} +@node Python,Swift,Kotlin,Coding Conventions +@anchor{taler-developer-manual python}@anchor{5f} @section Python @@ -1798,14 +3157,14 @@ for the language. @end menu @node Supported Python Versions,Style,,Python -@anchor{taler-developer-manual supported-python-versions}@anchor{42} +@anchor{taler-developer-manual supported-python-versions}@anchor{60} @subsection Supported Python Versions Python code should be written and build against version 3.7 of Python. @node Style,Python for Scripting,Supported Python Versions,Python -@anchor{taler-developer-manual style}@anchor{43} +@anchor{taler-developer-manual style}@anchor{61} @subsection Style @@ -1815,7 +3174,7 @@ A reusable yapf style file can be found in @code{build-common}, which is intended to be used as a git submodule. @node Python for Scripting,,Style,Python -@anchor{taler-developer-manual python-for-scripting}@anchor{44} +@anchor{taler-developer-manual python-for-scripting}@anchor{62} @subsection Python for Scripting @@ -1832,12 +3191,26 @@ are useful: @code{pathlib} for path manipulation (part of the standard library) @item -@code{subprocess} for "shelling out" to other programs. Prefer @code{subprocess.run} +@code{subprocess} for “shelling out” to other programs. Prefer @code{subprocess.run} over the older APIs. @end itemize +@node Swift,TypeScript,Python,Coding Conventions +@anchor{taler-developer-manual swift}@anchor{63} +@section Swift + + +Please follow best practices for the language. + +@node TypeScript,,Swift,Coding Conventions +@anchor{taler-developer-manual typescript}@anchor{64} +@section TypeScript + + +Please follow best practices for the language. + @node Testing library,User-Facing Terminology,Coding Conventions,Top -@anchor{taler-developer-manual testing-library}@anchor{45} +@anchor{taler-developer-manual testing-library}@anchor{65} @chapter Testing library @@ -1845,7 +3218,7 @@ This chapter is a VERY ABSTRACT description of how testing is implemented in Taler, and in NO WAY wants to substitute the reading of the actual source code by the user. -In Taler, a test case is a array of @code{struct TALER_TESTING_Command}, +In Taler, a test case is an array of @code{struct TALER_TESTING_Command}, informally referred to as @code{CMD}, that is iteratively executed by the testing interpreter. This latter is transparently initiated by the testing library. @@ -1863,12 +3236,12 @@ former contains the main logic to test feature @code{x}, whereas the latter cleans the memory up after execution. In a test life, each CMD needs some internal state, made by values it -keeps in memory. Often, the test has to @emph{share} those values with other +keeps in memory. Often, the test has to `share' those values with other CMDs: for example, CMD1 may create some key material and CMD2 needs this key material to encrypt data. -The offering of internal values from CMD1 to CMD2 is made by @emph{traits}. A -trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains a array +The offering of internal values from CMD1 to CMD2 is made by `traits'. A +trait is a @code{struct TALER_TESTING_Trait}, and each CMD contains an array of traits, that it offers via the public trait interface to other commands. The definition and filling of such array happens transparently to the test developer. @@ -1902,7 +3275,7 @@ of supposedly well-behaved components. This is needed when, for example, we want the exchange to return some corrupted signature in order to check if the merchant backend detects it. -This alteration is accomplished by another service called @emph{twister}. The +This alteration is accomplished by another service called `twister'. The twister acts as a proxy between service A and B, and can be programmed to tamper with the data exchanged by A and B. @@ -1910,7 +3283,7 @@ Please refer to the Twister codebase (under the @code{test} directory) in order to see how to configure it. @node User-Facing Terminology,Developer Glossary,Testing library,Top -@anchor{taler-developer-manual user-facing-terminology}@anchor{46} +@anchor{taler-developer-manual user-facing-terminology}@anchor{66} @chapter User-Facing Terminology @@ -1924,7 +3297,7 @@ used in the user interface and help materials. @end menu @node Terms to Avoid,Terms to Use,,User-Facing Terminology -@anchor{taler-developer-manual terms-to-avoid}@anchor{47} +@anchor{taler-developer-manual terms-to-avoid}@anchor{67} @section Terms to Avoid @@ -1936,29 +3309,36 @@ used in the user interface and help materials. Refreshing is the internal technical terminology for the protocol to give change for partially spent coins -@strong{Use instead}: "Obtaining change" +`Use instead': “Obtaining change” + +@item Charge + +Charge has two opposite meanings (charge to a credit card vs. charge a battery). +This can confuse users. + +`Use instead': “Obtain”, “Credit”, “Debit”, “Withdraw”, “Top up” @item Coin Coins are an internal construct, the user should never be aware that their balance -is represented by coins if different denominations. +is represented by coins of different denominations. -@strong{Use instead}: "(Digital) Cash" or "(Wallet) Balance" +`Use instead': “(Digital) Cash” or “(Wallet) Balance” @item Consumer Has bad connotation of consumption. -@strong{Use instead}: Customer or user. +`Use instead': Customer or user. @item Proposal The term used to describe the process of the merchant facilitating the download of the signed contract terms for an order. -@strong{Avoid}. Generally events that relate to proposal downloads +`Avoid'. Generally events that relate to proposal downloads should not be shown to normal users, only developers. Instead, use -"communication with mechant failed" if a proposed order can't be downloaded. +“communication with mechant failed” if a proposed order can’t be downloaded. @item Anonymous E-Cash @@ -1966,14 +3346,14 @@ Should be generally avoided, since Taler is only anonymous for the customer. Also some people are scared of anonymity (which as a term is also way too absolute, as anonymity is hardly ever perfect). -@strong{Use instead}: "Privacy-preserving", "Privacy-friendly" +`Use instead': “Privacy-preserving”, “Privacy-friendly” @item Payment Replay The process of proving to the merchant that the customer is entitled to view a digital product again, as they already paid for it. -@strong{Use instead}: In the event history, "re-activated digital content purchase" +`Use instead': In the event history, “re-activated digital content purchase” could be used. (FIXME: this is still not nice.) @item Session ID @@ -1984,7 +3364,7 @@ See Payment Replay. Too ambiguous in the wallet. -@strong{Use instead}: Purchase +`Use instead': Purchase @item Fulfillment URL @@ -1993,7 +3373,7 @@ with their payment. Can also be something like a donation receipt. @end table @node Terms to Use,,Terms to Avoid,User-Facing Terminology -@anchor{taler-developer-manual terms-to-use}@anchor{48} +@anchor{taler-developer-manual terms-to-use}@anchor{68} @section Terms to Use @@ -2009,16 +3389,16 @@ Regulatory entity that certifies exchanges and oversees their operation. The entity/service that gives out digital cash in exchange for some other means of payment. -In some contexts, using "Issuer" could also be appropriate. +In some contexts, using “Issuer” could also be appropriate. When showing a balance breakdown, -we can say "100 Eur (issued by exchange.euro.taler.net)". -Sometimes we may also use the more generic term "Payment Service Provider" -when the concept of an "Exchange" is still unclear to the reader. +we can say “100 Eur (issued by exchange.euro.taler.net)”. +Sometimes we may also use the more generic term “Payment Service Provider” +when the concept of an “Exchange” is still unclear to the reader. @item Refund -A refund is given by a merchant to the customer (rather the customer's wallet) -and "undoes" a previous payment operation. +A refund is given by a merchant to the customer (rather the customer’s wallet) +and “undoes” a previous payment operation. @item Payment @@ -2026,12 +3406,12 @@ The act of sending digital cash to a merchant to pay for an order. @item Purchase -Used to refer to the "result" of a payment, as in "view purchase". -Use sparsingly, as the word doesn't fit for all payments, such as donations. +Used to refer to the “result” of a payment, as in “view purchase”. +Use sparsingly, as the word doesn’t fit for all payments, such as donations. @item Contract Terms -Partially machine-readable representation of the merchant's obligation after the +Partially machine-readable representation of the merchant’s obligation after the customer makes a payment. @item Merchant @@ -2040,12 +3420,12 @@ Party that receives a payment. @item Wallet -Also "Taler Wallet". Software component that manages the user's digital cash +Also “Taler Wallet”. Software component that manages the user’s digital cash and payments. @end table @node Developer Glossary,Developer Tools,User-Facing Terminology,Top -@anchor{taler-developer-manual developer-glossary}@anchor{49} +@anchor{taler-developer-manual developer-glossary}@anchor{69} @chapter Developer Glossary @@ -2054,560 +3434,487 @@ use when talking to end users or even system administrators. @table @asis -@anchor{taler-developer-manual term-absolute-time}@anchor{4a} +@anchor{taler-developer-manual term-absolute-time}@anchor{6a} @geindex absolute time @item absolute time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{6b,,GNUnet} where the time is represented as the number of microseconds since 1.1.1970 (UNIX epoch). Called -absolute time in contrast to @ref{4c,,relative time}. -@anchor{taler-developer-manual term-aggregate}@anchor{4d} +absolute time in contrast to @ref{6c,,relative time}. +@anchor{taler-developer-manual term-aggregate}@anchor{6d} @geindex aggregate @item aggregate -the @ref{4e,,exchange} combines multiple payments received by the -same @ref{4f,,merchant} into one larger @ref{50,,wire transfer} to -the respective merchant's @ref{51,,bank} account -@anchor{taler-developer-manual term-auditor}@anchor{52} +the @ref{6e,,exchange} combines multiple payments received by the +same @ref{6f,,merchant} into one larger @ref{70,,wire transfer} to +the respective merchant’s @ref{71,,bank} account +@anchor{taler-developer-manual term-auditor}@anchor{72} @geindex auditor @item auditor -trusted third party that verifies that the @ref{4e,,exchange} is operating correctly -@anchor{taler-developer-manual term-bank}@anchor{51} +trusted third party that verifies that the @ref{6e,,exchange} is operating correctly +@anchor{taler-developer-manual term-bank}@anchor{71} @geindex bank @item bank -traditional financial service provider who offers wire @ref{53,,transfers} between accounts -@anchor{taler-developer-manual term-buyer}@anchor{54} +traditional financial service provider who offers +@ref{70,,wire transfers} between accounts +@anchor{taler-developer-manual term-buyer}@anchor{73} @geindex buyer @item buyer -individual in control of a Taler @ref{55,,wallet}, usually using it to -@ref{56,,spend} the @ref{57,,coins} on @ref{58,,contracts} (see also @ref{59,,customer}). -@anchor{taler-developer-manual term-close}@anchor{5a} +individual in control of a Taler @ref{74,,wallet}, usually using it to +@ref{75,,spend} the @ref{76,,coins} on @ref{77,,contracts} (see also @ref{78,,customer}). +@anchor{taler-developer-manual term-close}@anchor{79} @geindex close -@item close@anchor{taler-developer-manual term-closes}@anchor{5b} -@geindex closes - -@itemx closes@anchor{taler-developer-manual term-closed}@anchor{5c} -@geindex closed - -@itemx closed@anchor{taler-developer-manual term-closing}@anchor{5d} -@geindex closing +@item close -@itemx closing - -operation an @ref{4e,,exchange} performs on a @ref{5e,,reserve} that has not been -@ref{5f,,drained} by @ref{60,,withdraw} operations. When closing a reserve, the -exchange wires the remaining funds back to the customer, minus a @ref{61,,fee} +operation an @ref{6e,,exchange} performs on a @ref{7a,,reserve} that has not been +@ref{7b,,emptied} by @ref{7c,,withdraw} operations. When closing a reserve, the +exchange wires the remaining funds back to the customer, minus a @ref{7d,,fee} for closing -@anchor{taler-developer-manual term-coin}@anchor{62} +@anchor{taler-developer-manual term-coin}@anchor{76} @geindex coin -@item coin@anchor{taler-developer-manual term-coins}@anchor{57} -@geindex coins - -@itemx coins - -coins are individual token representing a certain amount of value, also known as the @ref{63,,denomination} of the coin -@anchor{taler-developer-manual term-commitment}@anchor{64} -@geindex commitment - -@item commitment@anchor{taler-developer-manual term-refresh-commitment}@anchor{65} -@geindex refresh commitment +@item coin -@itemx refresh commitment - -data that the wallet commits to during the @ref{66,,melt} stage of the -@ref{67,,refresh} protocol where it -has to prove to the @ref{4e,,exchange} that it is deriving the @ref{68,,fresh} -coins as specified by the Taler protocol. The commitment is verified -probabilistically (see: @ref{69,,kappa}) during the @ref{6a,,reveal} stage. -@anchor{taler-developer-manual term-contract}@anchor{6b} +coins are individual token representing a certain amount of value, also known as the @ref{7e,,denomination} of the coin +@anchor{taler-developer-manual term-contract}@anchor{77} @geindex contract -@item contract@anchor{taler-developer-manual term-contracts}@anchor{58} -@geindex contracts - -@itemx contracts +@item contract -formal agreement between @ref{4f,,merchant} and @ref{59,,customer} specifying the -@ref{6c,,contract terms} and signed by the merchant and the @ref{57,,coins} of the +formal agreement between @ref{6f,,merchant} and @ref{78,,customer} specifying the +@ref{7f,,contract terms} and signed by the merchant and the @ref{76,,coins} of the customer -@anchor{taler-developer-manual term-contract-terms}@anchor{6c} +@anchor{taler-developer-manual term-contract-terms}@anchor{7f} @geindex contract terms @item contract terms the individual clauses specifying what the buyer is purchasing from the -@ref{4f,,merchant} -@anchor{taler-developer-manual term-customer}@anchor{59} +@ref{6f,,merchant} +@anchor{taler-developer-manual term-customer}@anchor{78} @geindex customer @item customer individual that directs the buyer (perhaps the same individual) to make a purchase -@anchor{taler-developer-manual term-denomination}@anchor{63} +@anchor{taler-developer-manual term-denomination}@anchor{7e} @geindex denomination @item denomination -unit of currency, specifies both the currency and the face value of a @ref{62,,coin}, +unit of currency, specifies both the currency and the face value of a @ref{76,,coin}, as well as associated fees and validity periods -@anchor{taler-developer-manual term-denomination-key}@anchor{6d} +@anchor{taler-developer-manual term-denomination-key}@anchor{80} @geindex denomination key @item denomination key -(RSA) key used by the exchange to certify that a given @ref{62,,coin} is valid and of a -particular @ref{63,,denomination} -@anchor{taler-developer-manual term-deposit}@anchor{6e} +(RSA) key used by the exchange to certify that a given @ref{76,,coin} is valid and of a +particular @ref{7e,,denomination} +@anchor{taler-developer-manual term-deposit}@anchor{81} @geindex deposit -@item deposit@anchor{taler-developer-manual term-deposits}@anchor{6f} -@geindex deposits - -@itemx deposits@anchor{taler-developer-manual term-depositing}@anchor{70} -@geindex depositing - -@itemx depositing +@item deposit operation by which a merchant passes coins to an exchange, expecting the exchange to credit his bank account in the future using an -@ref{4d,,aggregate} @ref{50,,wire transfer} -@anchor{taler-developer-manual term-dirty}@anchor{71} +@ref{6d,,aggregate} @ref{70,,wire transfer} +@anchor{taler-developer-manual term-dirty}@anchor{82} @geindex dirty -@item dirty@anchor{taler-developer-manual term-dirty-coin}@anchor{72} -@geindex dirty coin +@item dirty -@itemx dirty coin - -a coin is dirty if its public key may be known to an entity other than +a @ref{76,,coin} is dirty if its public key may be known to an entity other than the customer, thereby creating the danger of some entity being able to -link multiple transactions of coin's owner if the coin is not refreshed -@anchor{taler-developer-manual term-drain}@anchor{73} +link multiple transactions of coin’s owner if the coin is not refreshed +@anchor{taler-developer-manual term-drain}@anchor{83} @geindex drain -@item drain@anchor{taler-developer-manual term-drained}@anchor{5f} -@geindex drained +@item drain + +process by which an exchange operator takes the profits +(from @ref{7d,,fees}) out of the escrow account and moves them into +their regular business account +@anchor{taler-developer-manual term-empty}@anchor{7b} +@geindex empty -@itemx drained +@item empty -a @ref{5e,,reserve} is being drained when a @ref{55,,wallet} is using the -reserve's private key to @ref{60,,withdraw} coins from it. This reduces +a @ref{7a,,reserve} is being emptied when a @ref{74,,wallet} is using the +reserve’s private key to @ref{7c,,withdraw} coins from it. This reduces the balance of the reserve. Once the balance reaches zero, we say that -the reserve has been (fully) drained. Reserves that are not drained -(which is the normal process) are @ref{5c,,closed} by the exchange. -@anchor{taler-developer-manual term-exchange}@anchor{4e} +the reserve has been (fully) emptied. Reserves that are not emptied +(which is the normal process) are @ref{79,,closed} by the exchange. +@anchor{taler-developer-manual term-exchange}@anchor{6e} @geindex exchange @item exchange -Taler's payment service operator. Issues electronic coins during +Taler’s payment service operator. Issues electronic coins during withdrawal and redeems them when they are deposited by merchants -@anchor{taler-developer-manual term-expired}@anchor{74} +@anchor{taler-developer-manual term-expired}@anchor{84} @geindex expired -@item expired@anchor{taler-developer-manual term-expiration}@anchor{75} -@geindex expiration - -@itemx expiration +@item expired Various operations come with time limits. In particular, denomination keys come with strict time limits for the various operations involving the coin issued under the denomination. The most important limit is the deposit expiration, which specifies until when wallets are allowed to -use the coin in deposit or refreshing operations. There is also a "legal" +use the coin in deposit or refreshing operations. There is also a “legal” expiration, which specifies how long the exchange keeps records beyond the deposit expiration time. This latter expiration matters for legal disputes in courts and also creates an upper limit for refreshing operations on special zombie coin -@anchor{taler-developer-manual term-fakebank}@anchor{76} +@anchor{taler-developer-manual term-fakebank}@anchor{85} @geindex fakebank @item fakebank -implementation of the @ref{51,,bank} API in memory to be used only for test +implementation of the @ref{71,,bank} API in memory to be used only for test cases. -@anchor{taler-developer-manual term-fee}@anchor{61} +@anchor{taler-developer-manual term-fee}@anchor{7d} @geindex fee @item fee -an @ref{4e,,exchange} charges various fees for its service. The different +an @ref{6e,,exchange} charges various fees for its service. The different fees are specified in the protocol. There are fees per coin for -@ref{77,,withdrawing}, @ref{70,,depositing}, @ref{78,,melting}, and -@ref{79,,refunding}. Furthermore, there are fees per wire transfer -for @ref{5d,,closing} a @ref{5e,,reserve}: and for -@ref{4d,,aggregate} @ref{7a,,wire transfers} to the @ref{4f,,merchant}. -@anchor{taler-developer-manual term-fresh}@anchor{68} +@ref{7c,,withdrawing}, @ref{81,,depositing}, @ref{86,,melting}, and +@ref{87,,refunding}. Furthermore, there are fees per wire transfer +when a @ref{7a,,reserve} is @ref{79,,closed} +and for @ref{6d,,aggregate} @ref{70,,wire transfers} +to the @ref{6f,,merchant}. +@anchor{taler-developer-manual term-fresh}@anchor{88} @geindex fresh -@item fresh@anchor{taler-developer-manual term-fresh-coin}@anchor{7b} -@geindex fresh coin +@item fresh -@itemx fresh coin - -a coin is fresh if its public key is only known to the customer -@anchor{taler-developer-manual term-GNUnet}@anchor{4b} +a @ref{76,,coin} is fresh if its public key is only known to the customer +@anchor{taler-developer-manual term-GNUnet}@anchor{6b} @geindex GNUnet @item GNUnet Codebase of various libraries for a better Internet, some of which GNU Taler depends upon. -@anchor{taler-developer-manual term-json}@anchor{7c} -@geindex json - -@item json@anchor{taler-developer-manual term-JSON}@anchor{7d} +@anchor{taler-developer-manual term-JSON}@anchor{89} @geindex JSON -@itemx JSON@anchor{taler-developer-manual term-JavaScript-Object-Notation}@anchor{7e} -@geindex JavaScript Object Notation - -@itemx JavaScript Object Notation +@item JSON +JavaScript Object Notation (JSON) is a serialization format derived from the JavaScript language which is commonly used in the Taler protocol as the payload of HTTP requests and responses. -@anchor{taler-developer-manual term-kappa}@anchor{69} +@anchor{taler-developer-manual term-kappa}@anchor{8a} @geindex kappa @item kappa -security parameter used in the @ref{67,,refresh} protocol. Defined to be 3. +security parameter used in the @ref{8b,,refresh} protocol. Defined to be 3. The probability of successfully evading the income transparency with the refresh protocol is 1:kappa. -@anchor{taler-developer-manual term-LibEuFin}@anchor{7f} -@geindex LibEuFin +@anchor{taler-developer-manual term-libeufin}@anchor{8c} +@geindex libeufin -@item LibEuFin +@item libeufin -FIXME: explain -@anchor{taler-developer-manual term-link}@anchor{80} +Kotlin component that implements a regional currency bank and an +adapter to communicate via EBICS with European core banking systems. +@anchor{taler-developer-manual term-link}@anchor{8d} @geindex link -@item link@anchor{taler-developer-manual term-linking}@anchor{81} -@geindex linking - -@itemx linking +@item link -specific step in the @ref{67,,refresh} protocol that an exchange must offer -to prevent abuse of the @ref{67,,refresh} mechanism. The link step is +specific step in the @ref{8b,,refresh} protocol that an exchange must offer +to prevent abuse of the @ref{8b,,refresh} mechanism. The link step is not needed in normal operation, it just must be offered. -@anchor{taler-developer-manual term-master-key}@anchor{82} +@anchor{taler-developer-manual term-master-key}@anchor{8e} @geindex master key @item master key offline key used by the exchange to certify denomination keys and message signing keys -@anchor{taler-developer-manual term-melt}@anchor{66} +@anchor{taler-developer-manual term-melt}@anchor{86} @geindex melt -@item melt@anchor{taler-developer-manual term-melted}@anchor{83} -@geindex melted - -@itemx melted@anchor{taler-developer-manual term-melting}@anchor{78} -@geindex melting +@item melt -@itemx melting - -step of the @ref{67,,refresh} protocol where a @ref{72,,dirty coin} -is invalidated to be reborn @ref{68,,fresh} in a subsequent -@ref{6a,,reveal} step. -@anchor{taler-developer-manual term-merchant}@anchor{4f} +step of the @ref{8b,,refresh} protocol where a @ref{82,,dirty} @ref{76,,coin} +is invalidated to be reborn @ref{88,,fresh} in a subsequent +@ref{8f,,reveal} step. +@anchor{taler-developer-manual term-merchant}@anchor{6f} @geindex merchant @item merchant party receiving payments (usually in return for goods or services) -@anchor{taler-developer-manual term-message-signing-key}@anchor{84} +@anchor{taler-developer-manual term-message-signing-key}@anchor{90} @geindex message signing key @item message signing key key used by the exchange to sign online messages, other than coins -@anchor{taler-developer-manual term-order}@anchor{85} +@anchor{taler-developer-manual term-order}@anchor{91} @geindex order @item order -FIXME: to be written! -@anchor{taler-developer-manual term-owner}@anchor{86} +offer made by the merchant to a wallet; pre-cursor to +a contract where the wallet is not yet fixed. Turns +into a @ref{77,,contract} when a wallet claims the order. +@anchor{taler-developer-manual term-owner}@anchor{92} @geindex owner @item owner a coin is owned by the entity that knows the private key of the coin -@anchor{taler-developer-manual term-planchet}@anchor{87} +@anchor{taler-developer-manual term-planchet}@anchor{93} @geindex planchet @item planchet -precursor data for a @ref{62,,coin}. A planchet includes the coin's internal +precursor data for a @ref{76,,coin}. A planchet includes the coin’s internal secrets (coin private key, blinding factor), but lacks the RSA signature -of the @ref{4e,,exchange}. When @ref{77,,withdrawing}, a @ref{55,,wallet} +of the @ref{6e,,exchange}. When @ref{7c,,withdrawing}, a @ref{74,,wallet} creates and persists a planchet before asking the exchange to sign it to get the coin. -@anchor{taler-developer-manual term-privacy-policy}@anchor{88} +@anchor{taler-developer-manual term-privacy-policy}@anchor{94} @geindex privacy policy @item privacy policy Statement of an operator how they will protect the privacy of users. -@anchor{taler-developer-manual term-proof}@anchor{89} +@anchor{taler-developer-manual term-proof}@anchor{95} @geindex proof @item proof Message that cryptographically demonstrates that a particular claim is correct. -@anchor{taler-developer-manual term-proposal}@anchor{8a} +@anchor{taler-developer-manual term-proposal}@anchor{96} @geindex proposal @item proposal -a list of @ref{6c,,contract terms} that has been completed and signed by the +a list of @ref{7f,,contract terms} that has been completed and signed by the merchant backend. -@anchor{taler-developer-manual term-purchase}@anchor{8b} +@anchor{taler-developer-manual term-purchase}@anchor{97} @geindex purchase @item purchase -Refers to the overall process of negotiating a @ref{6b,,contract} and then -making a payment with @ref{57,,coins} to a @ref{4f,,merchant}. -@anchor{taler-developer-manual term-recoup}@anchor{8c} +Refers to the overall process of negotiating a @ref{77,,contract} and then +making a payment with @ref{76,,coins} to a @ref{6f,,merchant}. +@anchor{taler-developer-manual term-recoup}@anchor{98} @geindex recoup @item recoup Operation by which an exchange returns the value of coins affected -by a @ref{8d,,revocation} to their @ref{86,,owner}, either by allowing the owner to -withdraw new coins or wiring funds back to the bank account of the @ref{86,,owner}. -@anchor{taler-developer-manual term-refresh}@anchor{67} +by a @ref{99,,revocation} to their @ref{92,,owner}, either by allowing the owner to +withdraw new coins or wiring funds back to the bank account of the @ref{92,,owner}. +@anchor{taler-developer-manual term-refresh}@anchor{8b} @geindex refresh -@item refresh@anchor{taler-developer-manual term-refreshing}@anchor{8e} -@geindex refreshing +@item refresh + +operation by which a @ref{82,,dirty} @ref{76,,coin} is converted into one or more +@ref{88,,fresh} coins. Involves @ref{86,,melting} the @ref{82,,dirty} coins and +then @ref{8f,,revealing} so-called @ref{9a,,transfer keys}. +@anchor{taler-developer-manual term-refresh-commitment}@anchor{9b} +@geindex refresh commitment -@itemx refreshing +@item refresh commitment -operation by which a @ref{72,,dirty coin} is converted into one or more -@ref{68,,fresh} coins. Involves @ref{78,,melting} the @ref{72,,dirty coin} and -then @ref{8f,,revealing} so-called @ref{90,,transfer keys}. -@anchor{taler-developer-manual term-refund}@anchor{91} +data that the wallet commits to during the @ref{86,,melt} stage of the +@ref{8b,,refresh} protocol where it +has to prove to the @ref{6e,,exchange} that it is deriving the @ref{88,,fresh} +coins as specified by the Taler protocol. The commitment is verified +probabilistically (see: @ref{8a,,kappa}) during the @ref{8f,,reveal} stage. +@anchor{taler-developer-manual term-refund}@anchor{87} @geindex refund -@item refund@anchor{taler-developer-manual term-refunding}@anchor{79} -@geindex refunding - -@itemx refunding +@item refund operation by which a merchant steps back from the right to funds that he -obtained from a @ref{6e,,deposit} operation, giving the right to the funds back +obtained from a @ref{81,,deposit} operation, giving the right to the funds back to the customer -@anchor{taler-developer-manual term-refund-transaction-id}@anchor{92} +@anchor{taler-developer-manual term-refund-transaction-id}@anchor{9c} @geindex refund transaction id @item refund transaction id -unique number by which a merchant identifies a @ref{91,,refund}. Needed +unique number by which a merchant identifies a @ref{87,,refund}. Needed as refunds can be partial and thus there could be multiple refunds for -the same @ref{8b,,purchase}. -@anchor{taler-developer-manual term-relative-time}@anchor{4c} +the same @ref{97,,purchase}. +@anchor{taler-developer-manual term-relative-time}@anchor{6c} @geindex relative time @item relative time -method of keeping time in @ref{4b,,GNUnet} where the time is represented +method of keeping time in @ref{6b,,GNUnet} where the time is represented as a relative number of microseconds. Thus, a relative time specifies an offset or a duration, but not a date. Called relative time in -contrast to @ref{4a,,absolute time}. -@anchor{taler-developer-manual term-reserve}@anchor{5e} +contrast to @ref{6a,,absolute time}. +@anchor{taler-developer-manual term-reserve}@anchor{7a} @geindex reserve @item reserve accounting mechanism used by the exchange to track customer funds -from incoming @ref{7a,,wire transfers}. A reserve is created whenever +from incoming @ref{70,,wire transfers}. A reserve is created whenever a customer wires money to the exchange using a well-formed public key -in the subject. The exchange then allows the customer's @ref{55,,wallet} -to @ref{60,,withdraw} up to the amount received in @ref{68,,fresh} -@ref{57,,coins} from the reserve, thereby draining the reserve. If a -reserve is not drained, the exchange eventually @ref{5b,,closes} it. +in the subject. The exchange then allows the customer’s @ref{74,,wallet} +to @ref{7c,,withdraw} up to the amount received in @ref{88,,fresh} +@ref{76,,coins} from the reserve, thereby emptying the reserve. If a +reserve is not emptied, the exchange will eventually @ref{79,,close} it. Other definition: Funds set aside for future use; either the balance of a customer at the exchange ready for withdrawal, or the funds kept in the exchange;s bank account to cover obligations from coins in circulation. -@anchor{taler-developer-manual term-reveal}@anchor{6a} +@anchor{taler-developer-manual term-reveal}@anchor{8f} @geindex reveal -@item reveal@anchor{taler-developer-manual term-revealing}@anchor{8f} -@geindex revealing +@item reveal -@itemx revealing - -step in the @ref{67,,refresh} protocol where some of the transfer private +step in the @ref{8b,,refresh} protocol where some of the transfer private keys are revealed to prove honest behavior on the part of the wallet. -In the reveal step, the exchange returns the signed @ref{68,,fresh} coins. -@anchor{taler-developer-manual term-revoke}@anchor{93} +In the reveal step, the exchange returns the signed @ref{88,,fresh} coins. +@anchor{taler-developer-manual term-revoke}@anchor{99} @geindex revoke -@item revoke@anchor{taler-developer-manual term-revocation}@anchor{8d} -@geindex revocation - -@itemx revocation +@item revoke exceptional operation by which an exchange withdraws a denomination from circulation, either because the signing key was compromised or because the exchange is going out of operation; unspent coins of a revoked denomination are subjected to recoup. -@anchor{taler-developer-manual term-sharing}@anchor{94} +@anchor{taler-developer-manual term-sharing}@anchor{9d} @geindex sharing @item sharing -users can share ownership of a @ref{62,,coin} by sharing access to the coin's +users can share ownership of a @ref{76,,coin} by sharing access to the coin's private key, thereby allowing all co-owners to spend the coin at any time. -@anchor{taler-developer-manual term-spend}@anchor{56} +@anchor{taler-developer-manual term-spend}@anchor{75} @geindex spend -@item spend@anchor{taler-developer-manual term-spending}@anchor{95} -@geindex spending - -@itemx spending +@item spend operation by which a customer gives a merchant the right to deposit coins in return for merchandise -@anchor{taler-developer-manual term-terms}@anchor{96} +@anchor{taler-developer-manual term-terms}@anchor{9e} @geindex terms @item terms the general terms of service of an operator, possibly including -the @ref{88,,privacy policy}. Not to be confused with the -@ref{6c,,contract terms} which are about the specific purchase. -@anchor{taler-developer-manual term-transaction}@anchor{97} +the @ref{94,,privacy policy}. Not to be confused with the +@ref{7f,,contract terms} which are about the specific purchase. +@anchor{taler-developer-manual term-transaction}@anchor{9f} @geindex transaction @item transaction method by which ownership is exclusively transferred from one entity -@anchor{taler-developer-manual term-transfer}@anchor{53} -@geindex transfer - -@item transfer@anchor{taler-developer-manual term-transfers}@anchor{98} -@geindex transfers - -@itemx transfers@anchor{taler-developer-manual term-wire-transfer}@anchor{50} -@geindex wire transfer - -@itemx wire transfer@anchor{taler-developer-manual term-wire-transfers}@anchor{7a} -@geindex wire transfers - -@itemx wire transfers - -method of sending funds between @ref{51,,bank} accounts -@anchor{taler-developer-manual term-transfer-key}@anchor{99} +@anchor{taler-developer-manual term-transfer-key}@anchor{9a} @geindex transfer key -@item transfer key@anchor{taler-developer-manual term-transfer-keys}@anchor{90} -@geindex transfer keys - -@itemx transfer keys +@item transfer key -special cryptographic key used in the @ref{67,,refresh} protocol, some of which -are revealed during the @ref{6a,,reveal} step. Note that transfer keys have, -despite the name, no relationship to @ref{7a,,wire transfers}. They merely -help to transfer the value from a @ref{72,,dirty coin} to a @ref{7b,,fresh coin} -@anchor{taler-developer-manual term-user}@anchor{9a} +special cryptographic key used in the @ref{8b,,refresh} protocol, some of which +are revealed during the @ref{8f,,reveal} step. Note that transfer keys have, +despite the name, no relationship to @ref{70,,wire transfers}. They merely +help to transfer the value from a @ref{82,,dirty} coin to a @ref{88,,fresh} coin +@anchor{taler-developer-manual term-user}@anchor{a0} @geindex user @item user any individual using the Taler payment system -(see @ref{59,,customer}, @ref{54,,buyer}, @ref{4f,,merchant}). -@anchor{taler-developer-manual term-version}@anchor{9b} +(see @ref{78,,customer}, @ref{73,,buyer}, @ref{6f,,merchant}). +@anchor{taler-developer-manual term-version}@anchor{a1} @geindex version @item version Taler uses various forms of versioning. There is a database schema version (stored itself in the database, see *-0000.sql) describing -the state of the table structure in the database of an @ref{4e,,exchange}, -@ref{52,,auditor} or @ref{4f,,merchant}. There is a protocol +the state of the table structure in the database of an @ref{6e,,exchange}, +@ref{72,,auditor} or @ref{6f,,merchant}. There is a protocol version (CURRENT:REVISION:AGE, see GNU libtool) which specifies -the network protocol spoken by an @ref{4e,,exchange} or @ref{4f,,merchant} +the network protocol spoken by an @ref{6e,,exchange} or @ref{6f,,merchant} including backwards-compatibility. And finally there is the software release version (MAJOR.MINOR.PATCH, see @indicateurl{https://semver.org/}) of the respective code base. -@anchor{taler-developer-manual term-wallet}@anchor{55} +@anchor{taler-developer-manual term-wallet}@anchor{74} @geindex wallet @item wallet -software running on a customer's computer; withdraws, stores and +software running on a customer’s computer; withdraws, stores and spends coins -@anchor{taler-developer-manual term-WebExtension}@anchor{9c} +@anchor{taler-developer-manual term-WebExtension}@anchor{a2} @geindex WebExtension @item WebExtension Cross-browser API used to implement the GNU Taler wallet browser extension. -@anchor{taler-developer-manual term-wire-gateway}@anchor{9d} +@anchor{taler-developer-manual term-wire-gateway}@anchor{a3} @geindex wire gateway @item wire gateway -FIXME: explain -@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{9e} -@geindex wire transfer identifier +API used by the exchange to talk with some real-time gross settlement system +(core banking system, blockchain) to notice inbound credits wire transfers +(during withdraw) and to trigger outbound debit wire transfers (primarily +for deposits). +@anchor{taler-developer-manual term-wire-transfer}@anchor{70} +@geindex wire transfer -@item wire transfer identifier@anchor{taler-developer-manual term-wtid}@anchor{9f} -@geindex wtid +@item wire transfer -@itemx wtid +a wire transfer is a method of sending funds between @ref{71,,bank} accounts +@anchor{taler-developer-manual term-wire-transfer-identifier}@anchor{a4} +@geindex wire transfer identifier + +@item wire transfer identifier Subject of a wire transfer from the exchange to a merchant; set by the aggregator to a random nonce which uniquely identifies the transfer. -@anchor{taler-developer-manual term-withdraw}@anchor{60} +@anchor{taler-developer-manual term-withdraw}@anchor{7c} @geindex withdraw -@item withdraw@anchor{taler-developer-manual term-withdrawing}@anchor{77} -@geindex withdrawing - -@itemx withdrawing@anchor{taler-developer-manual term-withdrawal}@anchor{a0} -@geindex withdrawal +@item withdraw -@itemx withdrawal - -operation by which a @ref{55,,wallet} can convert funds from a @ref{5e,,reserve} to +operation by which a @ref{74,,wallet} can convert funds from a @ref{7a,,reserve} to fresh coins -@anchor{taler-developer-manual term-zombie}@anchor{a1} +@anchor{taler-developer-manual term-zombie}@anchor{a5} @geindex zombie -@item zombie@anchor{taler-developer-manual term-zombie-coin}@anchor{a2} -@geindex zombie coin - -@itemx zombie coin +@item zombie -coin where the respective @ref{6d,,denomination key} is past its -@ref{6e,,deposit} @ref{75,,expiration} time, but which is still (again) valid -for an operation because it was @ref{83,,melted} while it was still -valid, and then later again credited during a @ref{8c,,recoup} process +@ref{76,,coin} where the respective @ref{80,,denomination key} is past its +@ref{81,,deposit} @ref{84,,expiration} time, but which is still (again) valid +for an operation because it was @ref{86,,melted} while it was still +valid, and then later again credited during a @ref{98,,recoup} process @end table @node Developer Tools,Index,Developer Glossary,Top -@anchor{taler-developer-manual developer-tools}@anchor{a3} +@anchor{taler-developer-manual developer-tools}@anchor{a6} @chapter Developer Tools @@ -2615,110 +3922,20 @@ This section describes various internal programs to make life easier for the developer. @menu -* taler-config-generate:: +* taler-harness:: @end menu -@node taler-config-generate,,,Developer Tools -@anchor{taler-developer-manual taler-config-generate}@anchor{a4} -@section taler-config-generate - - -@strong{taler-config-generate} - tool to simplify Taler configuration generation - -@strong{taler-config-generate} -[@strong{-C} @emph{CURRENCY} | @strong{––currency=}@emph{CURRENCY}] -[@strong{-c} @emph{FILENAME} | @strong{––config=}@emph{FILENAME}] -[@strong{-e} | @strong{––exchange}] -[@strong{-f} @emph{AMOUNT} | @emph{––wirefee=}@emph{AMOUNT}] -[@strong{-h} | @strong{––help}] -[@strong{-J} @emph{JSON} | @strong{––wire-json-exchange=}@emph{JSON}] -[@strong{-j} @emph{JSON} | @strong{––wire-json-merchant=}@emph{JSON}] -[@strong{-L} @emph{LOGLEVEL} | @strong{––loglevel=}@emph{LOGLEVEL}] -[@strong{-m} | @strong{––merchant}] -[@strong{-t} | @strong{––trusted}] -[@strong{-v} | @strong{––version}] -[@strong{-w} @emph{WIREFORMAT} | @strong{––wire} @emph{WIREFORMAT}] -[@strong{––bank-uri}] -[@strong{––exchange-bank-account}] -[@strong{––merchant-bank-account}] - -@strong{taler-config-generate} can be used to generate configuration files -for the Taler exchange or Taler merchants. - - -@table @asis - -@item @strong{-C} @emph{CURRENCY} | @strong{––currency=}@emph{CURRENCY} - -Which currency should we use in the configuration. - -@item @strong{-c} @emph{FILENAME} | @strong{––config=}@emph{FILENAME} - -Location where to write the generated configuration. Existing file -will be updated, not overwritten. - -@item @strong{-e} | @strong{––exchange} - -Generate configuration for a Taler exchange. - -@item @strong{-f} @emph{AMOUNT} | @emph{-wirefee=}@emph{AMOUNT} - -Setup wire transfer fees for the next 5 years for the exchange (for -all wire methods). +@node taler-harness,,,Developer Tools +@anchor{taler-developer-manual taler-harness}@anchor{a7} +@section taler-harness -@item @strong{-h} | @strong{––help} -Shows this man page. +`taler-harness deployment gen-coin-config' is a tool to simplify Taler configuration generation. -@item @strong{-J} @emph{JSON} | @strong{––wire-json-exchange=}@emph{JSON} - -Wire configuration to use for the exchange. - -@item @strong{-j} @emph{JSON} | @strong{––wire-json-merchant=}@emph{JSON} - -Wire configuration to use for the merchant. - -@item @strong{-L} @emph{LOGLEVEL} | @strong{––loglevel=}@emph{LOGLEVEL} - -Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and -ERROR. - -@item @strong{-m} | @strong{––merchant} - -Generate configuration for a Taler merchant. - -@item @strong{-t} | @strong{––trusted} - -Setup current exchange as trusted with current merchant. Generally -only useful when configuring for testcases. - -@item @strong{-v} | @strong{––version} - -Print version information. - -@item @strong{-w} @emph{WIREFORMAT} | @strong{––wire} @emph{WIREFORMAT} - -Specifies which wire format to use (i.e. “test” or “sepa”) - -@item @strong{––bank-uri} - -Alternative to specify wire configuration to use for the exchange and -merchant for the “test” wire method. Only useful if WIREFORMAT was -set to “test”. Specifies the URI of the bank. - -@item @strong{––exchange-bank-account} - -Alternative to specify wire configuration to use for the exchange for -the “test” wire method. Only useful if WIREFORMAT was set to “test”. -Specifies the bank account number of the exchange. - -@item @strong{––merchant-bank-account} - -Alternative to specify wire configuration to use for the merchant for -the “test” wire method. Only useful if WIREFORMAT was set to “test”. -Specifies the bank account number of the merchant. -@end table +`taler-harness deployment gen-coin-config' +[`-min-amount**='`VALUE'] +[`-max-amount**='`VALUE'] @node Index,,Developer Tools,Top @unnumbered Index diff --git a/texinfo/taler-exchange-figures/exchange-db.png b/texinfo/taler-exchange-figures/exchange-db.png Binary files differindex f99e2664..7a4050c6 100644 --- a/texinfo/taler-exchange-figures/exchange-db.png +++ b/texinfo/taler-exchange-figures/exchange-db.png diff --git a/texinfo/taler-exchange-figures/kyc-process.png b/texinfo/taler-exchange-figures/kyc-process.png Binary files differnew file mode 100644 index 00000000..563418b1 --- /dev/null +++ b/texinfo/taler-exchange-figures/kyc-process.png diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi index b953b187..16f3a2d9 100644 --- a/texinfo/taler-exchange.texi +++ b/texinfo/taler-exchange.texi @@ -3,29 +3,27 @@ @setfilename taler-exchange.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Exchange Manual @defindex ge @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-exchange.info). DESCRIPTION +* GNU Taler Exchange: (taler-exchange.info). Taler payment service provider @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.9.4, Apr 12, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -50,29 +48,39 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-exchange-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2014-2020 Taler Systems SA +@c Copyright (C) 2014-2024 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the -@c terms of the GNU General Public License as published by the Free Software +@c terms of the GNU Affero General Public License as published by the Free Software @c Foundation; either version 2.1, or (at your option) any later version. @c @c TALER is distributed in the hope that it will be useful, but WITHOUT ANY @c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -@c A PARTICULAR PURPOSE. See the GNU General Public License for more details. +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. @c -@c You should have received a copy of the GNU General Public License along with +@c You should have received a copy of the GNU Affero General Public License along with @c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @c @c @author Christian Grothoff +@c @author Florian Dold @menu * Introduction:: * Installation:: -* Configuration: Configuration<2>. +* Configuration Fundamentals:: +* Exchange Database Setup:: +* Basic Setup; Currency@comma{} Denominations and Keys: Basic Setup Currency Denominations and Keys. +* Wire Gateway Setup:: +* Legal Setup:: +* KYC Configuration:: * Deployment:: -* Testing a deployment:: -* Diagnostics:: +* Offline Signing Setup@comma{} Key Maintenance and Tear-Down: Offline Signing Setup Key Maintenance and Tear-Down. +* AML Configuration:: +* Setup Linting:: +* Testing and Troubleshooting:: +* Template Customization:: * Benchmarking:: +* FIXMEs:: * Index:: @detailmenu @@ -84,6 +92,7 @@ Introduction * About this manual:: * Organizational prerequisites:: * Architecture overview:: +* Key Types:: * Offline keys:: * Online signing key security:: @@ -96,64 +105,118 @@ Online signing key security Installation +* Before you start:: * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: * Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. -Configuration +Configuration Fundamentals * Configuration format:: -* Using taler-config:: -* Keying:: -* Serving:: -* Currency:: -* Database:: + +Basic Setup: Currency, Denominations and Keys + * Coins (denomination keys): Coins denomination keys. * Sign keys:: +* Setting up the offline signing key:: + +Wire Gateway Setup + +* Exchange Bank Account Configuration:: + +Legal Setup + +* Legal conditions for using the service:: * Terms of Service:: -* Bank account:: -* Auditor configuration:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: -Terms of Service +Legal policies directory layout * Example:: -Bank account +KYC Configuration -* Wire fee structure:: +* Taler KYC Terminology:: +* KYC Configuration Options:: +* OAuth 2.0 specifics: OAuth 2 0 specifics. +* Persona specifics:: +* KYC AID specifics:: Deployment +* Serving:: +* Reverse Proxy Setup:: * Launching an exchange:: -* Keys generation:: -* Private key storage:: -* Database upgrades:: -Database upgrades +Offline Signing Setup, Key Maintenance and Tear-Down +* Signing the online signing keys:: +* Account signing:: +* Wire fee structure:: +* Auditor configuration:: * Revocations:: -Diagnostics +AML Configuration + +* AML Officer Setup:: +* AML Triggers:: +* AML Forms:: + +Testing and Troubleshooting +* taler-config:: +* Using taler-config:: +* Private key storage:: * Internal audits:: * Database Scheme:: +* Database upgrades:: + +Template Customization + +* Generic Errors Templates:: +* kycaid-invalid-request:: +* oauth2-authentication-failure:: +* oauth2-authorization-failure:: +* oauth2-authorization-failure-malformed:: +* oauth2-bad-request:: +* oauth2-conversion-failure:: +* oauth2-provider-failure:: +* persona-exchange-unauthorized:: +* persona-load-failure:: +* persona-exchange-unpaid:: +* persona-logic-failure:: +* persona-invalid-response:: +* persona-network-timeout:: +* persona-kyc-failed:: +* persona-provider-failure:: + +Benchmarking + +* Choosing a bank:: +* taler-bank-benchmark:: +* taler-exchange-benchmark:: +* taler-aggregator-benchmark:: @end detailmenu @end menu @node Introduction,Installation,Top,Top -@anchor{taler-exchange-manual gnu-taler-exchange-operator-manual}@anchor{1}@anchor{taler-exchange-manual introduction}@anchor{2} +@anchor{taler-exchange-manual exchange-operator-manual}@anchor{1}@anchor{taler-exchange-manual introduction}@anchor{2} @chapter Introduction -This manual is an early draft that still needs significant editing work -to become readable. - @menu * About GNU Taler:: * About this manual:: * Organizational prerequisites:: * Architecture overview:: +* Key Types:: * Offline keys:: * Online signing key security:: @@ -164,6 +227,21 @@ to become readable. @section About GNU Taler +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic @@ -173,18 +251,12 @@ GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR). -GNU Taler is not yet production-ready, after following this manual you -will have a backend that can process payments in “KUDOS”, but not -regular currencies. This is not so much because of limitations in the -backend, but because we are not aware of a Taler exchange operator -offering regular currencies today. - @node About this manual,Organizational prerequisites,About GNU Taler,Introduction @anchor{taler-exchange-manual about-this-manual}@anchor{4} @section About this manual -This tutorial targets system administrators who want to install and +This manual targets system administrators who want to install and operate a GNU Taler exchange. @node Organizational prerequisites,Architecture overview,About this manual,Introduction @@ -192,61 +264,75 @@ operate a GNU Taler exchange. @section Organizational prerequisites -Operating a GNU Taler exchange means that you are operating a payment -service provider, which means that you will most likely need a bank -license and/or follow applicable financial regulation. +Operating a GNU Taler exchange means that you are operating a payment service +provider, which means that you will most likely need a bank license and/or +follow applicable financial regulation. Exceptions may apply, especially if +you are operating a regional currency or a payment system for an event with a +closed user group. -GNU Taler payment service providers generally need to ensure high -availability and have @emph{really} good backups (synchronous replication, -asynchronous remote replication, off-site backup, 24/7 monitoring, -etc.). This manual will not cover these aspects of operating a -payment service provider. +GNU Taler payment service providers generally need to ensure high availability +and should have `really' good backups (synchronous replication, asynchronous +remote replication, off-site backup, 24/7 monitoring, etc.). This manual will +not cover these aspects of operating a payment service provider. -We will assume that you can operate a (high-availability, -high-assurance) Postgres database. Furthermore, we expect some moderate +We will assume that you can operate a (sufficiently high-availability, +high-assurance) PostgreSQL database. Furthermore, we expect some moderate familiarity with the compilation and installation of free software -packages. You need to understand the cryptographic concepts of private -and public keys and must be able to protect private keys stored in files -on disk. +packages. You need to understand the cryptographic concepts of private and +public keys and must be able to protect private keys stored in files on disk. + +@cartouche +@quotation Note +Taler may store sensitive business and customer data in the database. Any +operator SHOULD thus ensure that backup operations are encrypted and +secured from unauthorized access. +@end quotation +@end cartouche -@node Architecture overview,Offline keys,Organizational prerequisites,Introduction +@node Architecture overview,Key Types,Organizational prerequisites,Introduction @anchor{taler-exchange-manual architecture-overview}@anchor{6} @section Architecture overview -Taler is a pure payment system, not a new crypto-currency. As such, it -operates in a traditional banking context. In particular, this means -that in order to receive funds via Taler, the merchant must have a -regular bank account, and payments can be executed in ordinary -currencies such as USD or EUR. Similarly, the Taler exchange must -interact with a bank. The bank of the exchange holds the exchange’s -funds in an escrow account. - -Note that, given the technical burden (XML-based communications, -additional cryptography, and a vast variety of standards) due to -interact with banks, the exchange uses a intermediary system to talk -to its bank. Such intermediary system abstracts the native banking -protocol by exposing the @emph{Taler Wire Gateway API}; this way, the exchange -can conduct its banking operations in a simplified and JSON-based style. - -When customers wire money to the escrow account, the bank notifies the -exchange about the incoming wire transfers. The exchange then creates a -@emph{reserve} based on the subject of the wire transfer. The wallet which -knows the secret key matching the wire transfer subject can then -withdraw coins from the reserve, thereby draining it. The liability of -the exchange against the reserve is thereby converted into a liability -against digital coins issued by the exchange. When the customer later -spends the coins at a merchant, and the merchant @emph{deposits} the coins at -the exchange, the exchange first @emph{aggregates} the amount from multiple -deposits from the same merchant and then instructs its bank to make a -wire transfer to the merchant, thereby fulfilling its obligation and -eliminating the liability. The exchange charges @emph{fees} for some or all -of its operations to cover costs and possibly make a profit. - -@emph{Auditors} are third parties, for example financial regulators, that -verify that the exchange operates correctly. The same software is also -used to calculate the exchange’s profits, risk and liabilities by the -accountants of the exchange. +GNU Taler is a pure payment system, not a crypto-currency. As such, it +operates in a traditional banking context. In particular, this means that +payments can be executed in ordinary currencies such as USD or EUR. +Furthermore, a typical merchant in Taler has a regular bank account, and would +use it to receive funds via Taler. + +Consequently, a typical Taler exchange must interact with a bank. The bank of +the exchange holds funds in an account where the balance is basically +equivalent to the value of all coins in circulation. (Small mismatches arise +whenever customers are about to withdraw coins and have already send the funds +into the bank account, or if merchants just deposited coins and are about to +receive wire transfers for deposited coins, or due to fees charged by the +exchange and the operator not yet having drained the fees from the account.) + +The exchange uses an intermediary system to talk to its bank. This shifts the +technical burden (XML-based communications, additional cryptography, and a +vast variety of standards) for this interaction into another bank-specific +subsystem. Such intermediary system abstracts the native banking protocol by +exposing the `Taler Wire Gateway API'; this way, the exchange can conduct its +banking operations in a simplified and JSON-based style. + +When customers wire money to the exchange's bank account, the Taler Wire +Gateway API must notify the exchange about the incoming wire transfers. The +exchange then creates a `reserve' based on the subject of the wire +transfer. The wallet which knows the secret key matching the wire transfer +subject can then withdraw coins from the reserve, thereby draining it. The +liability of the exchange against the reserve is thereby converted into a +liability against digital coins issued by the exchange. When the customer +later spends the coins at a merchant, and the merchant `deposits' the coins at +the exchange, the exchange first `aggregates' the amount from multiple +deposits from the same merchant and then instructs its bank to make a wire +transfer to the merchant, thereby fulfilling its obligation and eliminating +the liability. The exchange charges `fees' for some or all of its operations +to cover costs and possibly make a profit. + +`Auditors' are third parties, for example financial regulators, that verify +that the exchange operates correctly. The same software is also used to +calculate the exchange’s profits, risk and liabilities by the accountants of +the exchange. The Taler software stack for an exchange consists of the following components: @@ -255,7 +341,7 @@ components: @itemize - @item -HTTP frontend +`HTTP frontend': The HTTP frontend interacts with Taler wallets and merchant backends. It is used to withdraw coins, deposit coins, refresh coins, issue refunds, map wire transfers to Taler transactions, inquire about the @@ -263,15 +349,16 @@ exchange’s bank account details, signing keys and fee structure. The binary is the @code{taler-exchange-httpd}. @item -Crypto-Helpers -The @code{taler-exchange-secmod-rsa} and @code{taler-exchange-secmod-eddsa} -are two programs that are responsible for managing the exchange’s +`Crypto-Helpers': +The @code{taler-exchange-secmod-rsa}, @code{taler-exchange-secmod-cs} and +@code{taler-exchange-secmod-eddsa} +are three programs that are responsible for managing the exchange's online signing keys. They must run on the same machine as the @code{taler-exchange-httpd} as the HTTP frontend communicates with the crypto helpers using UNIX Domain Sockets. @item -Aggregator +`Aggregator': The aggregator combines multiple deposits made by the same merchant and (eventually) triggers wire transfers for the aggregate amount. The merchant can control how quickly wire transfers are made. The @@ -280,15 +367,15 @@ excessively frequent transfers. The binary is the @code{taler-exchange-aggregator}. @item -Closer +`Closer': The @code{taler-exchange-closer} tool check that reserves are properly closed. If a customer wires funds to an exchange and then fails to withdraw them, the closer will (eventually) trigger a wire -transfer that sends the customer’s funds back to the originating +transfer that sends the customer's funds back to the originating wire account. @item -Transfer +`Transfer': The @code{taler-exchange-transfer} tool is responsible for actually executing the aggregated wire transfers. It is the only process that needs to have the credentials to execute outgoing wire @@ -299,7 +386,7 @@ by LibEuFin. LibEuFin is an adapter which maps the Taler Wire REST API to traditional banking protocols like EBICS and FinTS. @item -Wirewatch +`Wirewatch': The @code{taler-exchange-wirewatch} tool is responsible for observing incoming wire transfers to the exchange. It needs to have the credentials to obtain a list of incoming wire transfers. @@ -309,42 +396,47 @@ making outgoing wire transfers is done via different bank accounts and/or credentials. @item -Wire adapter +`Wire adapter': A wire adapter is a component that enables exchange to talk to a bank. +Each wire adapter must implement the Taler Wire Gateway API. Three +wire adapters are currently provided: @enumerate @item -The libtalerfakebank implements a bank with a wire adapter API -inside of a testcase. +The `libtalerfakebank' implements a bank with a wire adapter API +inside of a testcase. @code{taler-fakebank-run} is a stand-alone +process using libtalerfakebank. Note that this adapter is only +useful for tests, as all transaction data is kept in memory. @item -For the demonstration Web site (or local currencies), -the Python bank provides a bank that directly provides -the wire adapter API. +For production, `libeufin''s @code{libeufin-nexus} component +implements a wire adapter towards the traditional SEPA banking +system with IBAN accounts using the EBICS protocol. @item -For production, libeufin’s Nexus component implements a wire -adapter towards the traditional SEPA banking system with IBAN -accounts. +To use GNU Taler with blockchains, the `Depolymerization' +component provides a wire gateway API that runs on top of +blockchains like Bitcoin and Ethereum. @end enumerate -The client-side wire adapter API is implemented in libtalerbank and -is used by the transfer to execute wire transfers and for the -auditor to query bank transaction histories. +The client-side wire adapter API is implemented in `libtalerbank' and +is used by @code{taler-exchange-transfer} to execute wire transfers and by +@code{taler-exchange-wirewatch} and the Taler auditor auditor to query bank +transaction histories. @item -DBMS +`DBMS': The exchange requires a DBMS to stores the transaction history for the Taler exchange and aggregator, and a (typically separate) DBMS for the Taler auditor. For now, the GNU Taler reference implementation -only supports Postgres, but the code could be easily extended to +only supports PostgreSQL, but the code could be easily extended to support another DBMS. -.. index:: Postgres +.. index:: PostgreSQL @item -Auditor +`Auditor': The auditor verifies that the transactions performed by the exchange were done properly. It checks the various signatures, totals up the amounts and alerts the operator to any inconsistencies. It also @@ -352,17 +444,49 @@ computes the expected bank balance, revenue and risk exposure of the exchange operator. The main binary is the @code{taler-auditor}. Aside from the key setup procedures, the most critical setup for deploying an auditor is providing the auditor with an up-to-date -copy of the database. +copy of the exchange's database. @end itemize -@node Offline keys,Online signing key security,Architecture overview,Introduction -@anchor{taler-exchange-manual offline-keys}@anchor{7} +@node Key Types,Offline keys,Architecture overview,Introduction +@anchor{taler-exchange-manual key-types}@anchor{7}@anchor{taler-exchange-manual keytypes}@anchor{8} +@section Key Types + + +The exchange works with four types of keys: + + +@itemize - + +@item +master key (kept offline, configured manually at merchants and wallets) + +@item +online message signing keys (signs normal messages from the exchange) + +@item +denomination keys (signs digital coins) + +@item +security module keys (signs online message signing keys and denomination keys) +@end itemize + +Additionally, the exchange is sometimes concerned with the auditor's public +key (to verify messages signed by auditors approved by the exchange operator) +and the merchant's public key (to verify refunds are authorized by the +merchant). + +Most of the keys are managed fully automatically or configured as part of the +denomination configuration. Some configuration settings must be manually +set with regards to the exchange's master key. + +@node Offline keys,Online signing key security,Key Types,Introduction +@anchor{taler-exchange-manual offline-keys}@anchor{9} @section Offline keys -The exchange (and ideally also auditors) uses a long-term offline master +The exchange (and ideally also its auditor(s)) uses a long-term offline master siging key that identifies the operator and is used to authenticate critical -information, such as the exchange’s bank account and the actual keys the +information, such as the exchange's bank account and the actual keys the exchange uses online. Interactions with the offline system are performed using the @@ -373,20 +497,20 @@ computing power, a Raspberry-Pi is perfectly sufficient and the form-factor might be good for safe-keeping! (You should keep a copy of the (encrypted) private offline key on more than one physical medium though.) -Exchange operators are strongly advised to secure your private master key and -any copies on encrypted, always-offline computers. Again, we assume that you -are familiar with good best practices in operational security, including -securing key material. +Exchange operators are strongly advised to secure their private master key and +any copies on encrypted, always-offline computers. Again, this manual assumes +that you are familiar with good best practices in operational security, +including securing key material. @node Online signing key security,,Offline keys,Introduction -@anchor{taler-exchange-manual online-signing-key-security}@anchor{8} +@anchor{taler-exchange-manual online-signing-key-security}@anchor{a} @section Online signing key security -To provide an additional level of protection for the private @emph{online} signing +To provide an additional level of protection for the private `online' signing keys used by the exchange, the actual cryptographic signing operations are -performed by two helper processes, the @code{taler-exchange-secmod-rsa} and the -@code{taler-exchange-secmod-eddsa}. +performed by three helper processes, @code{taler-exchange-secmod-rsa}, +@code{taler-exchange-secmod-cs} and @code{taler-exchange-secmod-eddsa}. The current implementation does not yet support the use of a hardware security module (HSM). If you have such a device with adequate functionality and are @@ -402,12 +526,14 @@ integration support. @end menu @node Functionality,Security goals,,Online signing key security -@anchor{taler-exchange-manual functionality}@anchor{9} +@anchor{taler-exchange-manual functionality}@anchor{b} @subsection Functionality -The UNIX domain sockets have mode 0620 (u+rw, g+w). The exchange process -MUST be in the same group as the crypto helper processes. +The UNIX domain sockets of the `secmod' helpers have mode 0620 (u+rw, g+w). +The exchange process MUST thus be in the same group as the crypto helper +processes to enable access to the keys. No other users should be in that +group! The two helper processes will create the required private keys, and allow anyone with access to the UNIX domain socket to sign arbitrary messages with @@ -416,12 +542,12 @@ are also responsible for deleting the private keys if their validity period expires or if they are informed about a key having been revoked. @node Security goals,Setup,Functionality,Online signing key security -@anchor{taler-exchange-manual security-goals}@anchor{a} +@anchor{taler-exchange-manual security-goals}@anchor{c} @subsection Security goals -From a security point of view, the helpers are designed to @emph{only} make it -harder for an attacker who took control of the HTTP daemon’s account to +From a security point of view, the helpers are designed to `only' make it +harder for an attacker who took control of the HTTP daemon's account to extract the private keys, limiting the attackers ability to creating signatures to the duration of their control of that account. @@ -433,46 +559,157 @@ to track the total number of signatures they have made for the various keys. @end cartouche @node Setup,Configuration,Security goals,Online signing key security -@anchor{taler-exchange-manual setup}@anchor{b} +@anchor{taler-exchange-manual setup}@anchor{d} @subsection Setup The helper processes should be run under a user ID that is separate from that -of the user running the main @code{taler-exchange-httpd} service. For security, -it is important that helpers run under a different user ID than the main HTTP -frontend, in fact ideally each helper should run under its own user ID. The -@code{taler-exchange-httpd} service’s will securely communicate with the helpers -using UNIX domain sockets. To enable access to the keys, the service’s user -must be in the group of the helper processes (and no other users should be in -that group). +of the user running the main @code{taler-exchange-httpd} service. To get any +security benefit from this, it is important that helpers run under a different +user ID than the main HTTP frontend. In fact, ideally, each helper should run +under its own user ID. The @code{taler-exchange-httpd} service's will securely +communicate with the helpers using UNIX domain sockets. @node Configuration,,Setup,Online signing key security -@anchor{taler-exchange-manual configuration}@anchor{c} +@anchor{taler-exchange-manual configuration}@anchor{e} @subsection Configuration -The helpers and the HTTP service need both access to the same configuration -information. Having divergent configurations may result in run-time failures. -It is recommended that the configuration file (@code{-c} option) is simply shared -between all of the different processes, even though they run as different -system users. The configuration does not contain any sensitive information. +The helpers and the exchange HTTP service need both access to the same +configuration information. Having divergent configurations may result in +run-time failures. It is recommended that the configuration file (@code{-c} +option) is simply shared between all of the different processes, even though +they run as different system users. The configuration does not contain any +sensitive information. -@node Installation,Configuration<2>,Introduction,Top -@anchor{taler-exchange-manual installation}@anchor{d} +@node Installation,Configuration Fundamentals,Introduction,Top +@anchor{taler-exchange-manual exchangeinstallation}@anchor{f}@anchor{taler-exchange-manual installation}@anchor{10} @chapter Installation -Before installing a Taler exchange, please make sure that your -system does not have swap space enabled. Swap space is a security -risk that Taler does not try to mitigate against. +Before installing a Taler exchange, please make sure that your system does not +have swap space enabled. Swap space is a security risk that Taler does not +try to mitigate against. + +We recommend the setup of offline signing keys to be done on a second machine that +does not have Internet access. + +In this guide's shell-session fragments, the command prompt shows two pieces +of information: -Please install the following packages before proceeding with the -exchange compilation. + +@itemize * + +@item +Who is performing the command +(@code{$user} vs @code{root}, and ending character @code{$} vs @code{#}). + +@item +Host where the command is supposed to be executed +(@code{exchange-offline} vs @code{exchange-online}). +It is possible to do the entire setup on one machine, +but we do not recommend this for security reasons. +@end itemize + +@menu +* Before you start:: +* Installing from source:: +* Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. + +@end menu + +@node Before you start,Installing from source,,Installation +@anchor{taler-exchange-manual before-you-start}@anchor{11} +@section Before you start + + +To deploy this with a real bank, you need: + +@quotation + + +@itemize * + +@item +IBAN of the bank account to use + +@item +BIC of the bank + +@item +EBICS host, user and partner IDs +@end itemize +@end quotation + +Information to write down during the installation: + +@quotation + + +@itemize * + +@item +LibEuFin Nexus superuser password + +@item +Taler facade base URL + +@item +exchange Nexus username and password +@end itemize +@end quotation + +@node Installing from source,Installing the GNU Taler binary packages on Debian,Before you start,Installation +@anchor{taler-exchange-manual installing-from-source}@anchor{12} +@section Installing from source + + +The following instructions will show how to install libgnunetutil and +the GNU Taler exchange from source. + +The package sources can be find in our +download directory@footnote{http://ftpmirror.gnu.org/taler/}. + +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff + +GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format. +The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match. +Exceptions to this general rule are documented in the release notes. +For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x +as the MAJOR version matches. A MAJOR version of 0 indicates experimental +development, and you are expected to always run all of the `latest' releases +together (no compatibility guarantees). + +First, the following packages need to be installed before we can compile the +backend: @itemize - @item +"Sphinx RTD Theme" Python package aka @code{python3-sphinx-rtd-theme} +on Debian-based systems (for GNUnet documentation support, can be +omitted if GNUnet is configured with @code{--disable-documentation}) + +@item libsqlite3 >= 3.16.2 @item @@ -482,10 +719,10 @@ GNU libunistring >= 0.9.3 libcurl >= 7.26 (or libgnurl >= 7.26) @item -libqrencode >= 4.0.0 +libqrencode >= 4.0.0 (Taler merchant only) @item -GNU libgcrypt >= 1.6 +GNU libgcrypt >= 1.6 (1.10 or later highly recommended) @item libsodium >= 1.0 @@ -497,42 +734,48 @@ libargon2 >= 20171227 libjansson >= 2.7 @item -Postgres >= 9.6, including libpq +PostgreSQL >= 15, including libpq @item GNU libmicrohttpd >= 0.9.71 @item -GNUnet >= 0.14.0 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) +GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) @item -GNU Taler exchange (from download directory@footnote{http://ftpmirror.gnu.org/taler/}, -see release announcement@footnote{https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late}) +Python3 with @code{jinja2} @end itemize -Except for the last two, these are available in most GNU/Linux -distributions and should just be installed using the respective package -manager. - -@menu -* Installing from source:: -* Installing the GNU Taler binary packages on Debian:: -* Installing the GNU Taler binary packages on Ubuntu:: - -@end menu - -@node Installing from source,Installing the GNU Taler binary packages on Debian,,Installation -@anchor{taler-exchange-manual installing-from-source}@anchor{e} -@section Installing from source - +If you are on Debian stable or later, the following command may help you +install these dependencies: -The following instructions will show how to install libgnunetutil and -the GNU Taler exchange from source. +@example +# apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 +@end example Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. +On Ubuntu, you also need to install pkg-config, for example: + +@example +$ apt-get install pkg-config +@end example + To install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows: @@ -551,6 +794,17 @@ The @code{ldconfig} command (also run as @code{root}) makes the shared object libraries (@code{.so} files) visible to the various installed programs. +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +There is no need to actually run a GNUnet peer to use the Taler merchant +backend -- all the merchant needs from GNUnet is a number of headers and +libraries! + After installing GNUnet, unpack the GNU Taler exchange tarball, change into the resulting directory, and proceed as follows: @@ -568,60 +822,42 @@ which requires you to run the last step as @code{root}. You have to specify @code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the previous step. -@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Ubuntu,Installing from source,Installation -@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{f} +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation +@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{13} @section Installing the GNU Taler binary packages on Debian To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for -Sid, which means you should use a system which at least includes -unstable packages in its source list. We recommend using APT pinning -to limit unstable packages to those explicitly requested. To do this, -set your @code{/etc/apt/preferences} as follows: - -@example -Package: * -Pin: release a=stable -Pin-Priority: 700 - -Package: * -Pin: release a=testing -Pin-Priority: 650 +Debian bookworm. -Package: * -Pin: release a=unstable -Pin-Priority: 600 - -Package: * -Pin: release l=Debian-Security -Pin-Priority: 1000 -@end example - -A typical @code{/etc/apt/sources.list} file for this setup -would look like this: +You need to add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: @example -deb http://ftp.ch.debian.org/debian/ buster main -deb http://security.debian.org/debian-security buster/updates main -deb http://ftp.ch.debian.org/debian/ testing main -deb http://ftp.ch.debian.org/debian/ unstable main -deb https://deb.taler.net/apt/debian sid main +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main @end example -The last line is crucial, as it adds the GNU Taler packages. - Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: @example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg # apt update @end example @cartouche @quotation Note -You may want to verify the correctness of the Taler Systems key out-of-band. +You may want to verify the correctness of the Taler Systems SA key out-of-band. @end quotation @end cartouche @@ -631,7 +867,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install taler-exchange +[root@@exchange-online]# apt install taler-exchange @end example Note that the package does not perform any configuration work except for @@ -640,33 +876,44 @@ configure at least the database, HTTP reverse proxy (typically with TLS certificates), denomination and fee structure, bank account, auditor(s), offline signing and the terms of service. -Sample configuration files for the HTTP reverse proxy can be found in -@code{/etc/taler-exchange/}. +On the offline system, you should run at least: + +@example +[root@@exchange-offline]# apt install taler-exchange-offline +@end example + +@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation +@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{14} +@section Installing the GNU Taler binary packages on Trisquel + -@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Debian,Installation -@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{10} +To install the GNU Taler Trisquel packages, first ensure that you have +the right Trisquel distribution. Packages are currently available for +Trisquel GNU/Linux 10.0. Simply follow the same instructions provided +for Ubuntu. + +@node Installing the GNU Taler binary packages on Ubuntu,Services users groups and file system hierarchy,Installing the GNU Taler binary packages on Trisquel,Installation +@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{15} @section Installing the GNU Taler binary packages on Ubuntu To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for -Ubuntu 20.04 LTS (Focal Fossa). +Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. -A typical @code{/etc/apt/sources.list} file for this setup -would look like this: +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: @example -deb http://ch.archive.ubuntu.com/ubuntu/ focal main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security multiverse restricted +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example + +For Ubuntu Mantic use this instead: -deb https://deb.taler.net/apt/ubuntu/ focal-fossa main +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic @end example The last line is crucial, as it adds the GNU Taler packages. @@ -675,7 +922,8 @@ Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: @example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-sign add - +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg # apt update @end example @@ -691,7 +939,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install taler-exchange +[root@@exchange-online]# apt install taler-exchange @end example Note that the package does not perform any configuration work except for @@ -700,296 +948,446 @@ configure at least the database, HTTP reverse proxy (typically with TLS certificates), denomination and fee structure, bank account, auditor(s), offline signing and the terms of service. -Sample configuration files for the HTTP reverse proxy can be found in -@code{/etc/taler-exchange/}. +On the offline system, you should run at least: -@node Configuration<2>,Deployment,Installation,Top -@anchor{taler-exchange-manual id1}@anchor{11} -@chapter Configuration +@example +[root@@exchange-offline]# apt install taler-exchange-offline +@end example +@node Services users groups and file system hierarchy,,Installing the GNU Taler binary packages on Ubuntu,Installation +@anchor{taler-exchange-manual services-users-groups-and-file-system-hierarchy}@anchor{16} +@section Services, users, groups and file system hierarchy -This chapter provides an overview of the exchange configuration. Or at -least eventually will do so, for now it is a somewhat wild description -of some of the options. -@menu -* Configuration format:: -* Using taler-config:: -* Keying:: -* Serving:: -* Currency:: -* Database:: -* Coins (denomination keys): Coins denomination keys. -* Sign keys:: -* Terms of Service:: -* Bank account:: -* Auditor configuration:: +The `taler-exchange' package will create several system users +to compartmentalize different parts of the system: -@end menu -@node Configuration format,Using taler-config,,Configuration<2> -@anchor{taler-exchange-manual configuration-format}@anchor{12} -@section Configuration format +@itemize * +@item +@code{taler-exchange-httpd}: runs the HTTP daemon with the core business logic. -In Taler realm, any component obeys to the same pattern to get -configuration values. According to this pattern, once the component has -been installed, the installation deploys default values in -$@{prefix@}/share/taler/config.d/, in .conf files. In order to override -these defaults, the user can write a custom .conf file and either pass -it to the component at execution time, or name it taler.conf and place -it under $HOME/.config/. +@item +@code{taler-exchange-secmod-rsa}: manages the RSA private online signing keys. -A config file is a text file containing sections, and each section -contains its values. The right format follows: +@item +@code{taler-exchange-secmod-cs}: manages the CS private online signing keys. -@example -[section1] -value1 = string -value2 = 23 +@item +@code{taler-exchange-secmod-eddsa}: manages the EdDSA private online signing keys. -[section2] -value21 = string -value22 = /path22 -@end example +@item +@code{taler-exchange-closer}: closes idle reserves by triggering wire transfers that refund the originator. -Throughout any configuration file, it is possible to use @code{$}-prefixed -variables, like @code{$VAR}, especially when they represent filesystem -paths. It is also possible to provide defaults values for those -variables that are unset, by using the following syntax: -@code{$@{VAR:-default@}}. However, there are two ways a user can set -@code{$}-prefixable variables: +@item +@code{taler-exchange-aggregator}: aggregates deposits into larger wire transfer requests. -by defining them under a @code{[paths]} section, see example below, +@item +@code{taler-exchange-transfer}: performs wire transfers with the bank (via LibEuFin/Nexus). -@example -[paths] -TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data -.. -[section-x] -path-x = $@{TALER_DEPLOYMENT_SHARED@}/x -@end example +@item +@code{taler-exchange-wirewatch}: checks for incoming wire transfers with the bank (via LibEuFin/Nexus). -or by setting them in the environment: +@item +@code{postgres}: runs the PostgreSQL database (from `postgresql' package). -@example -$ export VAR=/x -@end example +@item +@code{www-data}: runs the frontend HTTPS service with the TLS keys (from `nginx' package). +@end itemize -The configuration loader will give precedence to variables set under -@code{[path]}, though. +@cartouche +@quotation Note +The `taler-merchant' package additionally creates a @code{taler-merchant-httpd} user +to run the HTTP daemon with the merchant business logic. +@end quotation +@end cartouche -The utility @code{taler-config}, which gets installed along with the -exchange, serves to get and set configuration values without directly -editing the .conf. The option @code{-f} is particularly useful to resolve -pathnames, when they use several levels of @code{$}-expanded variables. See -@code{taler-config --help}. +The exchange setup uses the following system groups: -Note that, in this stage of development, the file -@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the -component. For example, both an exchange and a bank can read values from -it. -The repository @code{git://taler.net/deployment} contains examples of -configuration file used in our demos. See under @code{deployment/config}. +@itemize * -@quotation +@item +@code{taler-exchange-db}: group for all Taler users with direct database access, specifically taler-exchange-httpd, taler-exchange-wirewatch, taler-exchange-closer and taler-exchange-aggregator. -@strong{Note} +@item +@code{taler-exchange-secmod}: group for processes with access to online signing keys; this group must have four users: taler-exchange-secmod-rsa, taler-exchange-secmod-cs, taler-exchange-secmod-eddsa and taler-exchange-httpd. -Expectably, some components will not work just by using default -values, as their work is often interdependent. For example, a -merchant needs to know an exchange URL, or a database name. -@end quotation +@item +@code{taler-exchange-offline}: group for the access to the offline private key (only used on the offline host and not used on the online system). +@end itemize -@node Using taler-config,Keying,Configuration format,Configuration<2> -@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{13}@anchor{taler-exchange-manual using-taler-config}@anchor{14} -@section Using taler-config +The package will deploy systemd service files in +@code{/usr/lib/systemd/system/} for the various components: -The tool @code{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. +@itemize * -Run +@item +@code{taler-exchange-aggregator.service}: service that schedules wire transfers +which combine multiple deposits to the same merchant. -@example -$ taler-config -s $SECTION -@end example +@item +@code{taler-exchange-closer.service}: service that watches for reserves that have been abandoned and schedules wire transfers to send the money back to the originator. -to list all of the configuration values in section @code{$SECTION}. +@item +@code{taler-exchange-httpd.service}: main Taler exchange logic with the public REST API. -Run +@item +@code{taler-exchange-httpd.socket}: systemd socket activation for the Taler exchange HTTP daemon. -@example -$ taler-config -s $section -o $option -@end example +@item +@code{taler-exchange-secmod-eddsa.service}: software security module for making EdDSA signatures. -to extract the respective configuration value for option @code{$option} in -section @code{$section}. +@item +@code{taler-exchange-secmod-rsa.service}: software security module for making RSA signatures. -Finally, to change a setting, run +@item +@code{taler-exchange-secmod-cs.service}: software security module for making CS signatures. -@example -$ taler-config -s $section -o $option -V $value -@end example +@item +@code{taler-exchange-transfer.service}: service that triggers outgoing wire transfers (pays merchants). -to set the respective configuration value to @code{$value}. Note that you -have to manually restart the Taler backend after you change the -configuration to make the new configuration go into effect. +@item +@code{taler-exchange-wirewatch.service}: service that watches for incoming wire transfers (first step of withdraw). -Some default options will use $-variables, such as @code{$DATADIR} within -their value. To expand the @code{$DATADIR} or other $-variables in the -configuration, pass the @code{-f} option to @code{taler-config}. For example, -compare: +@item +@code{taler-exchange.target}: Main target for the Taler exchange to be operational. +@end itemize + +The deployment creates the following key locations in the system: + + +@itemize * + +@item +@code{/etc/taler/}: configuration files. + +@item +@code{/run/taler/}: contains the UNIX domain sockets for inter-process communication (IPC). + +@item +@code{/var/lib/taler/}: serves as the $HOME for all Taler users and contains sub-directories +with the private keys; which keys are stored here depends on the host: + + +@itemize * + +@item +online system: exchange-secmod-eddsa, exchange-secmod-cs and exchange-secmod-rsa keys. + +@item +offline system: exchange-offline keys. +@end itemize +@end itemize + +@node Configuration Fundamentals,Exchange Database Setup,Installation,Top +@anchor{taler-exchange-manual configuration-fundamentals}@anchor{17} +@chapter Configuration Fundamentals + + +This chapter provides fundamental details about the exchange configuration. + +The configuration for all Taler components uses a single configuration file +as entry point: @code{/etc/taler/taler.conf}. + +System defaults are automatically loaded from files in +@code{/usr/share/taler/config.d}. These default files should never be modified. + +The default configuration @code{taler.conf} configuration file also includes all +configuration files in @code{/etc/taler/conf.d}. The settings from files in +@code{conf.d} are only relevant to particular components of Taler, while +@code{taler.conf} contains settings that affect all components. + +The directory @code{/etc/taler/secrets} contains configuration file snippets with +values that should only be readable to certain users. They are included with the @code{@@inline-secret@@} +directive and should end with @code{.secret.conf}. + +To view the entire configuration annotated with the source of each configuration option, you +can use the @code{taler-config} helper: @example -$ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE -$ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE +[root@@exchange-online]# taler-config --diagnostics +< ... annotated, full configuration ... > @end example -While the configuration file is typically located at -@code{$HOME/.config/taler.conf}, an alternative location can be specified -to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} -option. +@cartouche +@quotation Warning +While @code{taler-config} also supports rewriting configuration files, we strongly +recommend to edit configuration files manually, as @code{taler-config} does not +preserve comments and, by default, rewrites @code{/etc/taler/taler.conf}. +@end quotation +@end cartouche -@node Keying,Serving,Using taler-config,Configuration<2> -@anchor{taler-exchange-manual id2}@anchor{15}@anchor{taler-exchange-manual keying}@anchor{16} -@section Keying +@menu +* Configuration format:: +@end menu -The exchange works with four types of keys: +@node Configuration format,,,Configuration Fundamentals +@anchor{taler-exchange-manual configuration-format}@anchor{18} +@section Configuration format -@itemize - +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation +prefix. Different components must be installed to the same prefix. -@item -master key (kept offline) +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the `-c' +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass @code{-c +/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf} +the primary location for the configuration. -To create a master key, use: +A config file is a text file containing sections, and each section +contains maps options to their values. Configuration files follow +basically the INI syntax: @example -$ taler-exchange-offline setup +[section1] +value1 = string +value2 = 23 + +[section2] +value21 = string +value22 = /path22 @end example -@item -sign keys (signs normal messages from the exchange) +Comments start with a hash (@code{#}). Throughout the configuration, it is +possible to use @code{$}-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those +variables that are unset, by using the following syntax: +@code{$@{VAR:-default@}}. There are two ways a user can set the value +of @code{$}-prefixable variables: + +@quotation -@item -denomination keys (signs electronic coins, see section Coins) + +@enumerate @item -security module keys (signs sign keys and denomination keys) -@end itemize +by defining them under a @code{[paths]} section: +@end enumerate -Additionally, the exchange is sometimes concerned with the auditor’s public -key (to verify messages signed by auditors approved by the exchange operator) -and the merchant’s public key (to verify refunds are authorized by the -merchant). +@quotation -Key options include: +@example +[paths] +TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data +.. +[section-x] +path-x = $@{TALER_DEPLOYMENT_SHARED@}/x +@end example +@end quotation -@itemize - +@enumerate 2 @item -@code{[exchange-offline/MASTER_PRIV_FILE]}: Path to the exchange’s master private file. Only needs to be provided on the offline system where the @code{taler-exchange-offline} command is used. +or by setting them in the environment: +@end enumerate -@item -@code{[exchange/MASTER_PUBLIC_KEY]}: Must specify the exchange’s master public key. Needed for the exchange to verify information signed by the offline system. -@end itemize +@quotation -@node Serving,Currency,Keying,Configuration<2> -@anchor{taler-exchange-manual id3}@anchor{17}@anchor{taler-exchange-manual serving}@anchor{18} -@section Serving +@example +$ export VAR=/x +@end example +@end quotation +@end quotation +The configuration loader will give precedence to variables set under +@code{[path]} over environment variables. -The exchange can serve HTTP over both TCP and UNIX domain socket. +The utility @code{taler-config}, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option @code{-f} is particularly useful to resolve +pathnames, when they use several levels of @code{$}-expanded variables. See +@code{taler-config --help}. -The following options are to be configured in the section @code{[exchange]}: +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. +@node Exchange Database Setup,Basic Setup Currency Denominations and Keys,Configuration Fundamentals,Top +@anchor{taler-exchange-manual exchange-database-setup}@anchor{19} +@chapter Exchange Database Setup + + +The access credentials for the exchange's database are configured in +@code{/etc/taler/secrets/exchange-db.secret.conf}. Currently, only PostgreSQL is +supported as a database backend. + +The following users must have access to the exchange database: -@itemize - + +@itemize * @item -@code{SERVE}: Must be set to @code{tcp} to serve HTTP over TCP, or @code{unix} to serve -HTTP over a UNIX domain socket. +taler-exchange-httpd @item -@code{PORT}: Set to the TCP port to listen on if @code{SERVE} is @code{tcp}. +taler-exchange-wire @item -@code{UNIXPATH}: Set to the UNIX domain socket path to listen on if @code{SERVE} is -@code{unix}. +taler-exchange-aggregator @item -@code{UNIXPATH_MODE}: Number giving the mode with the access permission mask -for the @code{UNIXPATH} (i.e. 660 = @code{rw-rw---}). +taler-exchange-closer @end itemize -@node Currency,Database,Serving,Configuration<2> -@anchor{taler-exchange-manual currency}@anchor{19}@anchor{taler-exchange-manual id4}@anchor{1a} -@section Currency - +These users are all in the taler-exchange-db group, and the +@code{exchange-db.secret.conf} should be only readable by users in +this group. -The exchange supports only one currency. This data is set under the -respective option @code{CURRENCY} in section @code{[taler]}. +@cartouche +@quotation Note +The `taler-exchange-dbconfig' tool can be used to automate the database +setup. When using the Debian/Ubuntu packages, the users should already have +been created, so you can just run the tool without any arguments and should +have a working database configuration. The rest of this section only +explains what the `taler-exchange-dbconfig' shell script fully automates. +@end quotation +@end cartouche -@node Database,Coins denomination keys,Currency,Configuration<2> -@anchor{taler-exchange-manual database}@anchor{1b}@anchor{taler-exchange-manual id5}@anchor{1c} -@section Database +To create a database for the Taler exchange on the local system, run: +@example +[root@@exchange-online]# su - postgres +[postgres@@exchange-online]# createuser taler-exchange-httpd +[postgres@@exchange-online]# createuser taler-exchange-wire +[postgres@@exchange-online]# createuser taler-exchange-aggregator +[postgres@@exchange-online]# createuser taler-exchange-closer +[postgres@@exchange-online]# createdb -O taler-exchange-httpd taler-exchange +[postgres@@exchange-online]# exit +@end example -The option @code{DB} in section @code{[exchange]} gets the database backend’s name the -exchange is going to use. So far, only @code{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: +This will create a @code{taler-exchange} database owned by the +@code{taler-exchange-httpd} user. We will use that user later to perform +database maintenance operations. +Assuming the above database setup, the database credentials to configure +in the configuration file would simply be: -@itemize - -@item -via an environment variable: @code{TALER_EXCHANGEDB_POSTGRES_CONFIG}. +@float LiteralBlock -@item -via configuration option @code{CONFIG}, under section @code{[exchangedb-BACKEND]}. -For example, the demo exchange is configured as follows: -@end itemize +@caption{/etc/taler/secrets/exchange-db.secret.conf} @example [exchange] -... DB = postgres -... [exchangedb-postgres] -CONFIG = postgres:///talerdemo +CONFIG=postgres:///taler-exchange @end example -Given this database configuration, the database can be initialized using: +@end float + + +If the database is run on a different host, please follow the instructions +from the PostgreSQL manual for configuring remote access. + +After configuring the database credentials, the exchange database needs +to be initialized with the following command: @example -$ taler-exchange-dbinit +[root@@exchange-online]# sudo -u taler-exchange-httpd taler-exchange-dbinit + +..note:: + + To run this command, the user must have `@w{`}CREATE TABLE`@w{`}, `@w{`}CREATE + INDEX`@w{`}, `@w{`}ALTER TABLE`@w{`} and (in the future possibly even) `@w{`}DROP TABLE`@w{`} + permissions. Those permissions are only required for this step (which may + have to be repeated when upgrading a deployment). Afterwards, during + normal operation, permissions to `@w{`}CREATE`@w{`} or `@w{`}ALTER`@w{`} tables are not + required by any of the Taler exchange processes and thus should not be + granted. For more information, see + :doc:`manpages/taler-exchange-dbinit.1`. +@end example + +Finally we need to grant the other accounts limited access: + +@example +[root@@exchange-online]# sudo -u taler-exchange-httpd bash +[taler-exchange-httpd@@exchange-online]# echo 'GRANT SELECT,INSERT,UPDATE ON ALL TABLES IN SCHEMA exchange TO "taler-exchange-aggregator";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# echo 'GRANT SELECT,INSERT,UPDATE ON ALL TABLES IN SCHEMA exchange TO "taler-exchange-closer";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# echo 'GRANT SELECT,INSERT,UPDATE ON ALL TABLES IN SCHEMA exchange TO "taler-exchange-wire";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# echo 'GRANT USAGE ON ALL SEQUENCES IN SCHEMA exchange TO "taler-exchange-aggregator";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# echo 'GRANT USAGE ON ALL SEQUENCES IN SCHEMA exchange TO "taler-exchange-closer";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# echo 'GRANT USAGE ON ALL SEQUENCES IN SCHEMA exchange TO "taler-exchange-wire";' \ + | psql taler-exchange +[taler-exchange-httpd@@exchange-online]# exit +@end example + +@cartouche +@quotation Note +The above instructions for changing database permissions only work `after' +having initialized the database with @code{taler-exchange-dbinit}, as +the tables need to exist before permissions can be granted on them. The +@code{taler-exchange-dbinit} tool cannot setup these permissions, as it +does not know which users will be used for which processes. +@end quotation +@end cartouche + +@node Basic Setup Currency Denominations and Keys,Wire Gateway Setup,Exchange Database Setup,Top +@anchor{taler-exchange-manual basic-setup-currency-denominations-and-keys}@anchor{1a} +@chapter Basic Setup: Currency, Denominations and Keys + + +A Taler exchange only supports a single currency. The currency +and the smallest currency unit supported by the bank system +must be specified in @code{/etc/taler/taler.conf}. + + +@float LiteralBlock + +@caption{/etc/taler/taler.conf} + +@example + [taler] + CURRENCY = EUR + CURRENCY_ROUND_UNIT = EUR:0.01 + + # ... rest of file ... @end example -Note that to run this command, the user must have @code{CREATE TABLE}, @code{CREATE -INDEX}, @code{ALTER TABLE} and (in the future possibly even) @code{DROP TABLE} -permissions. Those permissions are only required for this step (which may -have to be repeated when upgrading a deployment). Afterwards, during normal -operation, permissions to @code{CREATE} or @code{ALTER} tables are not required by -any of the Taler exchange processes and thus should not be granted. -For more information, see manpages/taler-exchange-dbinit.1. +@end float + + +@cartouche +@quotation Warning +@quotation + +When editing @code{/etc/taler/taler.conf}, take care to not accidentally remove +the @code{@@inline-matching@@} directive to include the configuration files in @code{conf.d}. +@end quotation +@anchor{taler-exchange-manual coins-denomination-keys}@anchor{1b} +@end quotation +@end cartouche -Commands, like @code{taler-exchange-dbinit}, that support the @code{-l LOGFILE} -command-line option, send logging output to standard error by default. +@menu +* Coins (denomination keys): Coins denomination keys. +* Sign keys:: +* Setting up the offline signing key:: -@node Coins denomination keys,Sign keys,Database,Configuration<2> -@anchor{taler-exchange-manual coins-denomination-keys}@anchor{1d}@anchor{taler-exchange-manual id6}@anchor{1e} +@end menu + +@node Coins denomination keys,Sign keys,,Basic Setup Currency Denominations and Keys +@anchor{taler-exchange-manual id1}@anchor{1c} @section Coins (denomination keys) +Next, the electronic cash denominations that the exchange offers must be +specified. + Sections specifying denomination (coin) information start with @code{coin_}. By convention, the name continues with @code{$CURRENCY_[$SUBUNIT]_$VALUE_$REVISION}, i.e. @code{[coin_eur_ct_10_0]} for a 10 cent piece. However, only the @code{coin_} @@ -1003,7 +1401,7 @@ must then have the following options: @item @code{VALUE}: How much is the coin worth, the format is -CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is “EUR:0.10”. +CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10". @item @code{DURATION_WITHDRAW}: How long can a coin of this type be withdrawn? @@ -1034,11 +1432,25 @@ the same format as value. Specified using the same format as value. @item +@code{CIPHER}: Which cipher to use for this coin? Must be either @code{RSA} or +@code{CS}. + +@item @code{RSA_KEYSIZE}: How many bits should the RSA modulus (product of the two primes) have for this type of coin. + +@item + +@table @asis + +@item @code{AGE_RESTRICTED}: Set to @code{YES} to make this a denomination with support + +for age restrictions. See age restriction extension below for details. +This option is optional and defaults to @code{NO}. +@end table @end itemize -See manpages/taler.conf.5 for information on @emph{duration} values +See manpages/taler.conf.5 for information on `duration' values (i.e. @code{DURATION_WITHDRAW} and @code{DURATION_SPEND} above, and @code{OVERLAP_DURATION} and @code{DURATION} below). Additionally, there are two global configuration options of note: @@ -1079,8 +1491,26 @@ to the same configuration file! @end quotation @end cartouche -@node Sign keys,Terms of Service,Coins denomination keys,Configuration<2> -@anchor{taler-exchange-manual id7}@anchor{1f}@anchor{taler-exchange-manual sign-keys}@anchor{20} +The @code{taler-wallet-cli} has a helper command that generates a +reasonable denomination structure. + +@example +[root@@exchange-online]# taler-wallet-cli deployment gen-coin-config \ + --min-amount EUR:0.01 \ + --max-amount EUR:100 \ + > /etc/taler/conf.d/exchange-coins.conf +@end example + +You can manually review and edit the generated configuration file. The main +change that is possibly required is updating the various fees. Note that you +MUST NOT edit a coin configuration section after the initial setup. If you +must @code{change} the values, you must instead create a new section with a +different unique name (still with the @code{coin-} prefix) and comment out or +remove the existing section. Do take care to not introduce the name of the +disabled section again in the future. + +@node Sign keys,Setting up the offline signing key,Coins denomination keys,Basic Setup Currency Denominations and Keys +@anchor{taler-exchange-manual id2}@anchor{1d}@anchor{taler-exchange-manual sign-keys}@anchor{1e} @section Sign keys @@ -1117,96 +1547,140 @@ delayed. @end quotation @end cartouche -@node Terms of Service,Bank account,Sign keys,Configuration<2> -@anchor{taler-exchange-manual terms-of-service}@anchor{21} -@section Terms of Service +@node Setting up the offline signing key,,Sign keys,Basic Setup Currency Denominations and Keys +@anchor{taler-exchange-manual offlineconfiguration}@anchor{1f}@anchor{taler-exchange-manual setting-up-the-offline-signing-key}@anchor{20} +@section Setting up the offline signing key -The exchange has an endpoint “/terms” to return the terms of service -(in legal language) of the exchange operator. The wallet will show -those terms of service to the user when the user is first withdrawing -coins. Terms of service are optional for experimental deployments, -if none are configured, the exchange will return a simple statement -saying that there are no terms of service available. +Before launching an exchange, the offline signing (master) key must be +generated and set in the configuration. The offline signing keys of the +exchange should be stored on a different machine. The responsibilities of +this offline signing machine are: -To configure the terms of service response, there are two options -in the @code{[exchange]} section: + +@itemize * + +@item +Generation of the exchange's offline master signing key. + +@item +Secure storage of the exchange's offline master signing key. + +@item +Generation of certificates (signed with the offline master signing key) that will be imported by the exchange. + +@item +Revocation of keys when the online system was compromised or is being terminated +@end itemize + +Configuration file options related to the master key are: @itemize - @item -@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. -This value must be changed whenever the terms of service are -updated. A common value to use would be a version number. -Note that if you change the @code{TERMS_ETAG}, you MUST also provide -the respective files in @code{TERMS_DIR} (see below). + +@table @asis + +@item @code{[exchange-offline/MASTER_PRIV_FILE]}: Path to the exchange’s master + +private file. Only needs to be provided on the offline system where the +@code{taler-exchange-offline} command is used. The default value is usually +fine and does not require adjustment. +@end table @item -@code{TERMS_DIR}: The directory that contains the terms of service. -The files in the directory must be readable to the exchange -process. + +@table @asis + +@item @code{[exchange/MASTER_PUBLIC_KEY]}: Must specify the exchange’s master public + +key. Needed for the exchange to verify information signed by the offline +system. This value must almost always be set explicitly by hand. +@end table @end itemize -The @code{TERMS_DIR} directory structure must follow a particular layout. -First, inside of @code{TERMS_DIR}, there should be sub-directories using -two-letter language codes like “en”, “de”, or “jp”. Each of these -directories would then hold translations of the current terms of -service into the respective language. Empty directories are -permitted in case translations are not available. +@example +[root@@exchange-offline]# taler-exchange-offline setup +< ... prints the exchange master public key > +@end example -Then, inside each language directory, files with the name of the -value set as the @code{TERMS_ETAG} must be provided. The extension of -each of the files should be typical for the respective mime type. -The set of supported mime types is currently hard-coded in the -exchange, and includes HTML, PDF and TXT files. If other files are -present, the exchange may show a warning on startup. +The public key printed as the output of this command must be put into the +configuration of the online machine: -@menu -* Example:: -@end menu +@float LiteralBlock -@node Example,,,Terms of Service -@anchor{taler-exchange-manual example}@anchor{22} -@subsection Example +@caption{/etc/taler/conf.d/exchange-business.conf} +@example + [exchange] + MASTER_PUBLIC_KEY = YE6Q6TR1ED... -A sample file structure for a @code{TERMS_ETAG} of “v1” would be: + # ... rest of file ... +@end example +@end float -@itemize - -@item -TERMS_DIR/en/v1.txt +@node Wire Gateway Setup,Legal Setup,Basic Setup Currency Denominations and Keys,Top +@anchor{taler-exchange-manual wire-gateway-setup}@anchor{21} +@chapter Wire Gateway Setup -@item -TERMS_DIR/en/v1.html + +The Taler Wire Gateway is an API that +connects the Taler exchange to the underlying core banking system. There are +several implementations of wire gateways: + +@quotation + + +@itemize * @item -TERMS_DIR/en/v1.pdf +Project deploymerization@footnote{https://git.taler.net/depolymerization.git} implements a wire gateway on top of Bitcoin or Ethereum @item -TERMS_DIR/de/v1.txt +The libeufin-bank provides a wire gateway interface on top of a regional currency bank @item -TERMS_DIR/de/v1.html +The `taler-fakebank-run' command is an in-memory bank simulator with a wire gateway interface for testing +@end itemize +@end quotation + +@c FIXME :ref:`libeufin-nexus <libeufin-nexus>` is an implementation of the Wire Gateway API for the EBICS protocol. Add to list above once nexus implements the TWG directly! + +Before continuing, you need to decide which wire gateway you want to use, +and install and configure it on your system. Afterwards, you need to +have two key pieces of information from that setup: + +@quotation + + +@itemize * @item -TERMS_DIR/de/v1.pdf +The username and password to access the exchange's account in the system. @item -TERMS_DIR/fr/v1.pdf +The @code{payto://} URI of that account (see RFC 8905@footnote{https://www.rfc-editor.org/rfc/rfc8905}). @end itemize +@end quotation -If the user requests an HTML format with language preferences “fr” followed by “en”, -the exchange would return @code{TERMS_DIR/en/v1.html} lacking an HTML version in -French. +@menu +* Exchange Bank Account Configuration:: -@node Bank account,Auditor configuration,Terms of Service,Configuration<2> -@anchor{taler-exchange-manual bank-account}@anchor{23}@anchor{taler-exchange-manual id8}@anchor{24} -@section Bank account +@end menu +@node Exchange Bank Account Configuration,,,Wire Gateway Setup +@anchor{taler-exchange-manual exchange-bank-account-configuration}@anchor{22}@anchor{taler-exchange-manual id3}@anchor{23} +@section Exchange Bank Account Configuration + + +An exchange must be configured with the right settings to access its bank +account via a Taler wire gateway. An +exchange can be configured to use multiple bank accounts by using multiple +wire gateways. Typically only one wire gateway is used. To configure a bank account in Taler, we need to furnish two pieces of information: @@ -1221,8 +1695,8 @@ account. Examples for such URIs include an IBAN or @code{payto://x-taler-bank/localhost:8080/2} for the 2nd bank account a the Taler bank demonstrator running at @code{localhost} on port 8080. -The first part of the URI following @code{payto://} (“iban” or -“x-taler-bank”) is called the wire method. +The first part of the URI following @code{payto://} (@code{iban} or +@code{x-taler-bank}) is called the wire method. @item The @code{taler-exchange-wirewatch} and @code{taler-exchange-transfer} @@ -1232,18 +1706,39 @@ authentication information is currently a username and password for HTTP basic authentication. @end itemize +Each Taler wire gateway is configured in a configuration section that follows +the pattern @code{exchange-account-$id}, where @code{$id} is an internal identifier +for the bank account accessed by the exchange. The basic information for an +account should be put in @code{/etc/taler/conf.d/exchange-business.conf}. The +secret credentials to access the Taler Wire Gateway API should be put into a +corresponding @code{exchange-accountcredentials-$id} section in +@code{/etc/taler/secrets/exchange-accountcredentials.conf}. The latter file +should be only readable for the @code{taler-exchange-wire} user. Only the +@code{taler-exchange-wirewatch} and @code{taler-exchange-transfer} services should +run as the @code{taler-exchange-wire} user. Other exchange processes do not need +to have access to the account credentials. + You can configure multiple accounts for an exchange by creating sections -starting with “exchange-account-” for the section name. You can ENABLE for -each account whether it should be used, and for what (incoming or outgoing -wire transfers): +starting with @code{exchange-account-} for the section name. You must specify +@code{ENABLE_}-settings for each account whether it should be used, and for what +(incoming or outgoing wire transfers): + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-business.conf} @example [exchange-account-1] -# With x-taler-bank (say for PyBank) -PAYTO_URI = "payto://x-taler-bank/bank.demo.taler.net/Exchange" - +# Account identifier in the form of an RFC-8905 payto:// URI. +# For SEPA, looks like payto://iban/$IBAN?receiver-name=$NAME +# Make sure to URL-encode spaces in $NAME! +# +# With x-taler-bank (for Fakebank) +# PAYTO_URI = "payto://x-taler-bank/bank.demo.taler.net/Exchange?receiver-name=exop" +# # Example using IBAN (for use with LibEuFin) -# PAYTO_URI = "payto://iban/CH9300762011623852957" +PAYTO_URI = "payto://iban/CH9300762011623852957?receiver=name=exop" # URL for talking to the bank wire the wire API. WIRE_GATEWAY_URL = https://bank.demo.taler.net/taler-wire-gateway/Exchange @@ -1253,107 +1748,777 @@ ENABLE_DEBIT = YES # Use for exchange-wirewatch (and listed in /wire) ENABLE_CREDIT = YES -# Authentication options for exchange bank account go here. -# (Next sections have examples of authentication mechanisms) +@@inline-secret@@ exchange-accountcredentials-1 ../secrets/exchange-accountcredentials.secret.conf +@end example + +@end float + + + +@float LiteralBlock + +@caption{/etc/taler/secrets/exchange-accountcredentials.secret.conf} + +@example +[exchange-accountcredentials-1] + +# LibEuFin expects basic auth. WIRE_GATEWAY_AUTH_METHOD = basic -USERNAME = exchange -PASSWORD = super-secure + +# Username and password to access the Taler wire gateway. +USERNAME = ... +PASSWORD = ... + +# Base URL of the Taler wire gateway. +WIRE_GATEWAY_URL = ... @end example -The command line tool @code{taler-exchange-offline} must be used to -sign the @code{payto://} URI in a way suitable to convince wallets that -this is the correct address to wire funds to. -For example, the utility may be invoked as -follows to enable a wire account: +@end float + + +Such a wire gateway configuration can be tested with the following commands: @example -$ taler-exchange-offline enable-account payto://iban/CH9300762011623852957 +[root@@exchange-online]# taler-exchange-wire-gateway-client \ + --section exchange-accountcredentials-1 --debit-history +[root@@exchange-online]# taler-exchange-wire-gateway-client \ + --section exchange-accountcredentials-1 --credit-history @end example -The resulting JSON output must be uploaded to the exchange using -@code{taler-exchange-offline upload}. -For details, see manpages/taler-exchange-offline.1. +On success, you will see some of your account's transaction history (or an +empty history), while on failure you should see an error message. + +@node Legal Setup,KYC Configuration,Wire Gateway Setup,Top +@anchor{taler-exchange-manual legal-setup}@anchor{24}@anchor{taler-exchange-manual legalsetup}@anchor{25} +@chapter Legal Setup + + +This chapter describes how to setup certain legal aspects of a GNU Taler +exchange. Users that just want to set up an exchange as an experiment without +legal requirements can safely skip these steps. @menu -* Wire fee structure:: +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: @end menu -@node Wire fee structure,,,Bank account -@anchor{taler-exchange-manual id9}@anchor{25}@anchor{taler-exchange-manual wire-fee-structure}@anchor{26} -@subsection Wire fee structure +@node Legal conditions for using the service,Terms of Service,,Legal Setup +@anchor{taler-exchange-manual legal-conditions-for-using-the-service}@anchor{26} +@section Legal conditions for using the service -@geindex wire fee +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff -@geindex fee +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. -For each wire method (“sepa” or “x-taler-wire”) the -exchange must know about applicable wire fees. This is also done -using the @code{taler-exchange-offline} tool: +@node Terms of Service,Privacy Policy,Legal conditions for using the service,Legal Setup +@anchor{taler-exchange-manual terms-of-service}@anchor{27} +@section Terms of Service + + +The service has an endpoint "/terms" to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. + +To configure the terms of service response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{TERMS_ETAG}: The current "Etag" to return for the terms of service. +This value must be changed whenever the terms of service are +updated. A common value to use would be a version number. +Note that if you change the @code{TERMS_ETAG}, you MUST also provide +the respective files in @code{TERMS_DIR} (see below). + +@item +@code{TERMS_DIR}: The directory that contains the terms of service. +The files in the directory must be readable to the service +process. +@end itemize + +@node Privacy Policy,Legal policies directory layout,Terms of Service,Legal Setup +@anchor{taler-exchange-manual privacy-policy}@anchor{28} +@section Privacy Policy + + +The service has an endpoint "/pp" to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{PRIVACY_ETAG}: The current "Etag" to return for the privacy policy. +This value must be changed whenever the privacy policy is +updated. A common value to use would be a version number. +Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide +the respective files in @code{PRIVACY_DIR} (see below). + +@item +@code{PRIVACY_DIR}: The directory that contains the privacy policy. +The files in the directory must be readable to the service +process. +@end itemize + +@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Legal Setup +@anchor{taler-exchange-manual legal-policies-directory-layout}@anchor{29} +@section Legal policies directory layout + + +The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using two-letter language codes +like "en", "de", or "jp". Each of these directories would then hold +translations of the current terms of service into the respective language. +Empty directories are permitted in case translations are not available. + +Then, inside each language directory, files with the name of the value set as +the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present, +the service may show a warning on startup. + +@menu +* Example:: + +@end menu + +@node Example,,,Legal policies directory layout +@anchor{taler-exchange-manual example}@anchor{2a} +@subsection Example + + +A sample file structure for a @code{TERMS_ETAG} of "tos-v0" would be: + + +@itemize - + +@item +TERMS_DIR/en/tos-v0.txt + +@item +TERMS_DIR/en/tos-v0.html + +@item +TERMS_DIR/en/tos-v0.pdf + +@item +TERMS_DIR/en/tos-v0.epub + +@item +TERMS_DIR/en/tos-v0.md + +@item +TERMS_DIR/de/tos-v0.txt + +@item +TERMS_DIR/de/tos-v0.html + +@item +TERMS_DIR/de/tos-v0.pdf + +@item +TERMS_DIR/de/tos-v0.epub + +@item +TERMS_DIR/de/tos-v0.md +@end itemize + +If the user requests an HTML format with language preferences "fr" followed by +"en", the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +French. + +@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Legal Setup +@anchor{taler-exchange-manual generating-the-legal-terms}@anchor{2b} +@section Generating the Legal Terms + + +The @code{taler-terms-generator} script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in @code{.rst} format and GNU gettext +translations in @code{.po} format. + +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective @code{ETAG}. The +resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document. + +Once you have written the @code{$ETAG.rst} file in English, you can +generate the first set of outputs: @example -$ taler-exchange-offline wire-fee iban 2040 EUR:0.05 EUR:0.10 +$ taler-terms-generator -i $ETAG @end example -The above sets the wire fees for wire transfers involving @code{iban} accounts -(in Euros) in the year 2040 to 5 cents (wire fee) and 10 cents (closing fee). -The tool only supports setting fees that applies for the entire calendar year. +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in @code{$PREFIX/share/terms/}. The generator +has a few options which are documented in its man page. -We recommend provisioning an exchange with wire fees at least for the next two -years. Note that once the fees have been set for a year, they cannot be -changed (basically, by signing the fees the exchange makes a legally binding -offer to the customers). +@node Adding translations,Updating legal documents,Generating the Legal Terms,Legal Setup +@anchor{taler-exchange-manual adding-translations}@anchor{2c} +@section Adding translations -@geindex maintenance + +Translations must be available in subdirectories +@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}. +To start translating, you first need to add a new +language: + +@example +$ taler-terms-generator -i $ETAG -l $LANGUAGE +@end example + +Here, @code{$LANGUAGE} should be a two-letter language +code like @code{de} or @code{fr}. The command will generate +a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po} +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the @code{.po} +file. Afterwards, simply re-run + +@example +$ taler-terms-generator -i $ETAG +@end example + +to make the current translation(s) available to the +service. @cartouche @quotation Note -Provisioning future wire fees, like provisioning future denomination -and signing keys, are key regular maintenance procedures for every -exchange operator. We recommend setting automated reminders for -this maintenance activity! +You must restart the service whenever adding or updating legal documents or their translations. @end quotation @end cartouche -@node Auditor configuration,,Bank account,Configuration<2> -@anchor{taler-exchange-manual auditor-configuration}@anchor{27}@anchor{taler-exchange-manual id10}@anchor{28} -@section Auditor configuration +@node Updating legal documents,,Adding translations,Legal Setup +@anchor{taler-exchange-manual updating-legal-documents}@anchor{2d} +@section Updating legal documents + + +When making minor changes without legal implications, edit the @code{.rst} file, +then re-run the step to add a new language for each existing translation to +produce an updated @code{.po} file. Translate the sentences that have changed and +finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to +create the final files. + +When making major changes with legal implications, you should first rename (or +copy) the existing @code{.rst} file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the @code{.po} files, +complete the translations and re-create the final files. Finally, do not +forget to update the @code{ETAG} configuration option to the new name and to +restart the service. + +@node KYC Configuration,Deployment,Legal Setup,Top +@anchor{taler-exchange-manual kyc-configuration}@anchor{2e} +@chapter KYC Configuration + + +To legally operate, Taler exchange operators may have to comply with KYC +regulation that requires financial institutions to identify parties involved +in transactions at certain points. + +Taler permits an exchange to require KYC data under the following circumstances: + +@quotation + +@itemize * -The exchange must be informed about any auditor that is expected to provision -it with auditor signatures. This is also done using the -@code{taler-exchange-offline} tool on the offline system. First, the auditor -must be configured and provide the exchange operator with its public key and -the URL of it’s REST API. The exchange operator also needs a human-readable -name that may be shown to users to identify the auditor. Given this -information, the exchange operator can enable the auditor: +@item +Customer withdraws money over a threshold + +@item +Wallet receives (via refunds) money resulting in a balance over a threshold + +@item +Wallet receives money via P2P payments over a threshold + +@item +Merchant receives money over a threshold + +@item +Reserve is "opened" for invoicing (`planned feature') +@end itemize +@end quotation + +Any of the above requests can trigger the KYC process, +which can be illustrated as follows: + +@image{taler-exchange-figures/kyc-process,,,,png} + +At the end of the KYC process, the wallet re-tries the +original request, and assuming KYC was successful, the +request should then succeed. + +@menu +* Taler KYC Terminology:: +* KYC Configuration Options:: +* OAuth 2.0 specifics: OAuth 2 0 specifics. +* Persona specifics:: +* KYC AID specifics:: + +@end menu + +@node Taler KYC Terminology,KYC Configuration Options,,KYC Configuration +@anchor{taler-exchange-manual taler-kyc-terminology}@anchor{2f} +@section Taler KYC Terminology + + + +@itemize * + +@item +`Check': A check establishes a particular attribute of a user, such as +their name based on an ID document and lifeness, mailing address, phone +number, taxpayer identity, etc. + +@item +`Type of operation': The operation type determines which Taler-specific +operation has triggered the KYC requirement. We support four types of +operation: withdraw (by customer), deposit (by merchant), P2P receive (by +wallet) and (high) wallet balance. + +@item +`Condition': A condition specifies when KYC is required. Conditions +include the `type of operation', a threshold amount (e.g. above EUR:1000) +and possibly a time period (e.g. over the last month). + +@item +`Cost': Metric for the business expense for a KYC check at a certain +`provider'. Not in any currency, costs are simply relative and non-negative +values. Costs are considered when multiple choices are allowed by the +`configuration'. + +@item +`Expiration': KYC legitimizations may be outdated. Expiration rules +determine when `checks' have to be performed again. + +@item +`Legitimization rules': The legitimization rules determine under which +`conditions' which `checks' must be performend and the `expiration' time +period for the `checks'. + +@item +`Logic': Logic refers to a specific bit of code (realized as an exchange +plugin) that enables the interaction with a specific `provider'. Logic +typically requires configuration for access control (such as an +authorization token) and possibly the endpoint of the specific `provider' +implementing the respective API. + +@item +`Provider': A provider performs a specific set of `checks' at a certain +`cost'. Interaction with a provider is performed by provider-specific +`logic'. +@end itemize + +@node KYC Configuration Options,OAuth 2 0 specifics,Taler KYC Terminology,KYC Configuration +@anchor{taler-exchange-manual kyc-configuration-options}@anchor{30} +@section KYC Configuration Options + + +The KYC configuration determines the `legitimization rules', and specifies +which providers offer which `checks' at what `cost'. + +The configuration specifies a set of providers, one per configuration section. The names of the configuration +sections must being with @code{kyc-proider-} followed by +an arbitrary @code{$PROVIDER_ID}: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-kyc-providers.conf} @example -$ taler-exchange-offline enable-auditor $PUB_KEY $REST_URL "$AUDITOR_NAME" > auditor.json +[kyc-provider-$PROVIDER_ID] +# How expensive is it to use this provider? +# Used to pick the cheapest provider possible. +COST = 42 +# Which plugin is responsible for this provider? +# Choices include "oauth2", "kycaid" and "persona". +LOGIC = oauth2 +# Which type of user does this provider handle? +# Either INDIVIDUAL or BUSINESS. +USER_TYPE = INDIVIDUAL +# Which checks does this provider provide? +# List of strings, no specific semantics. +PROVIDED_CHECKS = SMS GOVID PHOTO +# Plus additional logic-specific options, e.g.: +AUTHORIZATION_TOKEN = superdupersecret +FORM_ID = business_legi_form +# How long is the check considered valid? +EXPIRATION = 3650d +@end example + +@end float + + +The configuration also must specify a set of legitimization requirements, again one +per configuration section: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-kyc-rules.conf} + +@example +[kyc-legitimization-$RULE_NAME] +# Operation that triggers this legitimization. +# Must be one of WITHDRAW, DEPOSIT, P2P-RECEIVE +# or WALLET-BALANCE. +OPERATION_TYPE = WITHDRAW +# Required checks to be performed. +# List of strings, must individually match the +# strings in one or more provider's PROVIDED_CHECKS. +REQUIRED_CHECKS = SMS GOVID +# Threshold amount above which the legitimization is +# triggered. The total must be exceeded in the given +# timeframe. +THRESHOLD = KUDOS:100 +# Timeframe over which the amount to be compared to +# the THRESHOLD is calculated. Can be 'forever'. +# Ignored for WALLET-BALANCE. +TIMEFRAME = 30d @end example -As before, the @emph{auditor.json} file must then be copied from the offline system -to a system connected to the exchange and there @code{uploaded} to the exchange. +@end float + + +@node OAuth 2 0 specifics,Persona specifics,KYC Configuration Options,KYC Configuration +@anchor{taler-exchange-manual oauth-2-0-specifics}@anchor{31} +@section OAuth 2.0 specifics + + +In terms of configuration, the OAuth 2.0 logic requires the respective client +credentials to be configured apriori to enable access to the legitimization +service. The OAuth 2.0 configuration options are: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-oauth2.conf} + +@example +[kyc-provider-example-oauth2] +LOGIC = oauth2 +# (generic options omitted) +# How long is the KYC check valid? +KYC_OAUTH2_VALIDITY = forever + +# URL to which we redirect the user for the login process +KYC_OAUTH2_AUTHORIZE_URL = "http://kyc.example.com/authorize" +# URL where we POST the user's authentication information +KYC_OAUTH2_TOKEN_URL = "http://kyc.example.com/token" +# URL of the user info access point. +KYC_OAUTH2_INFO_URL = "http://kyc.example.com/info" + +# Where does the client get redirected upon completion? +KYC_OAUTH2_POST_URL = "http://example.com/thank-you" + +# For authentication to the OAuth2.0 service +KYC_OAUTH2_CLIENT_ID = testcase +KYC_OAUTH2_CLIENT_SECRET = password + +# Mustach template that converts OAuth2.0 data about the user +# into GNU Taler standardized attribute data. +KYC_OAUTH2_CONVERTER_HELPER = taler-exchange-kyc-oauth2-challenger.sh +@end example + +@end float + + +The converter helper is expected to be customized to the selected OAuth2.0 +service: different services may return different details about the user or +business, hence there cannot be a universal converter for all purposes. The +default shell script uses the @code{jq} tool to convert the JSON returned by the +service into the KYC attributes (also in JSON) expected by the exchange. The +script will need to be adjusted based on the attributes collected by the +specific backend. + +The Challenger service for address validation supports OAuth2.0, but does not +have a static AUTHORIZE_URL. Instead, the AUTHORIZE_URL must be enabled by the client +using a special authenticated request to the Challenger's @code{/setup} endpoint. +The exchange supports this by appending @code{#setup} to the AUTHORIZE_URL (note +that fragments are illegal in OAuth2.0 URLs). Be careful to quote the URL, +as @code{#} is otherwise interpreted as the beginning of a comment by the +configuration file syntax. + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-challenger-oauth2.conf} + +@example +[kyc-provider-challenger-oauth2] +LOGIC = oauth2 +KYC_OAUTH2_AUTHORIZE_URL = "http://challenger.example.com/authorize/#setup" +KYC_OAUTH2_TOKEN_URL = "http://challenger.example.com/token" +KYC_OAUTH2_INFO_URL = "http://challenger.example.com/info" +@end example + +@end float + + +When using OAuth 2.0, the `CLIENT REDIRECT URI' must be set to the +@code{/kyc-proof/$PROVIDER_SECTION} endpoint. For example, given the +configuration above and an exchange running on the host +@code{exchange.example.com}, the redirect URI would be +@code{https://exchange.example.com/kyc-proof/kyc-provider-challenger-oauth2/}. + +@node Persona specifics,KYC AID specifics,OAuth 2 0 specifics,KYC Configuration +@anchor{taler-exchange-manual persona-specifics}@anchor{32} +@section Persona specifics + + +We use the hosted flow. The Persona endpoints return a @code{request-id}, which +we log for diagnosis. + +Persona should be configured to use the @code{/kyc-webhook/} endpoint of the +exchange to notify the exchange about the completion of KYC processes. The +webhook is authenticated using a shared secret, which should be in the +configuration. To use the Persona webhook, you must set the webhook URL in +the Persona service to @code{$EXCHANGE_BASE_URL/kyc-webhook/$SECTION_NAME/} where +@code{$SECTION_NAME} is the name of the configuration section. You should also +extract the authentication token for the webhook and put it into the +configuration as shown above. + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-persona.conf} -@node Deployment,Testing a deployment,Configuration<2>,Top -@anchor{taler-exchange-manual deployment}@anchor{29}@anchor{taler-exchange-manual id11}@anchor{2a} +@example +[kyclogic-persona] +# Webhook authorization token. Global for all uses +# of the persona provider! +WEBHOOK_AUTH_TOKEN = wbhsec_698b5a19-c790-47f6-b396-deb572ec82f9 + +[kyc-provider-example-persona] +LOGIC = persona +# (generic options omitted) + +# How long is the KYC check valid? +KYC_PERSONA_VALIDITY = 365d + +# Which subdomain is used for our API? +KYC_PERSONA_SUBDOMAIN = taler + +# Authentication token to use. +KYC_PERSONA_AUTH_TOKEN = persona_sandbox_42XXXX + +# Form to use. +KYC_PERSONA_TEMPLATE_ID = itempl_Uj6Xxxxx + +# Where do we redirect to after KYC finished successfully. +KYC_PERSONA_POST_URL = "https://taler.net/kyc-done" + +# Salt to give to requests for idempotency. +# Optional. +# KYC_PERSONA_SALT = salt + +# Helper to convert JSON with KYC data returned by Persona into GNU Taler +# internal format. Should probably always be set to some variant of +# "taler-exchange-kyc-persona-converter.sh". +KYC_PERSONA_CONVERTER_HELPER = "taler-exchange-kyc-persona-converter.sh" +@end example + +@end float + + +The converter helper is expected to be customized to the +selected template: different templates may return different details +about the user or business, hence there cannot be a universal converter +for all purposes. The default shell script uses the @code{jq} tool to +convert the JSON returned by Persona into the KYC attributes (also +in JSON) expected by the exchange. The script will need to be adjusted +based on the attributes collected by the specific template. + +@node KYC AID specifics,,Persona specifics,KYC Configuration +@anchor{taler-exchange-manual kyc-aid-specifics}@anchor{33} +@section KYC AID specifics + + +We use the hosted flow. + +KYCAID must be configured to use the @code{/kyc-webhook/$SECTION_NAME/} endpoint +of the exchange to notify the exchange about the completion of KYC processes. + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-kycaid.conf} + +@example +[kyc-provider-example-kycaid] +LOGIC = kycaid +# (generic options omitted) + +# How long is the KYC check valid? +KYC_KYCAID_VALIDITY = 365d + +# Authentication token to use. +KYC_KYCAID_AUTH_TOKEN = XXX + +# Form to use. +KYC_KYCAID_FORM_ID = XXX + +# URL to go to after the process is complete. +KYC_KYCAID_POST_URL = "https://taler.net/kyc-done" + +# Script to convert the KYCAID data into the Taler format. +KYC_KYCAID_CONVERTER_HELPER = taler-exchange-kyc-kycaid-converter.sh +@end example + +@end float + + +The converter helper is expected to be customized to the selected template: +different templates may return different details about the user or business, +hence there cannot be a universal converter for all purposes. The default +shell script uses the @code{jq} tool to convert the JSON returned by Persona into +the KYC attributes (also in JSON) expected by the exchange. The script will +need to be adjusted based on the attributes collected by the specific +template. + +@node Deployment,Offline Signing Setup Key Maintenance and Tear-Down,KYC Configuration,Top +@anchor{taler-exchange-manual deployment}@anchor{34}@anchor{taler-exchange-manual id4}@anchor{35} @chapter Deployment -This chapter describes how to deploy the exchange once it has been -configured. +This chapter describes how to deploy the exchange once the basic installation +and configuration are completed. @menu +* Serving:: +* Reverse Proxy Setup:: * Launching an exchange:: -* Keys generation:: -* Private key storage:: -* Database upgrades:: @end menu -@node Launching an exchange,Keys generation,,Deployment -@anchor{taler-exchange-manual launch}@anchor{2b}@anchor{taler-exchange-manual launching-an-exchange}@anchor{2c} +@node Serving,Reverse Proxy Setup,,Deployment +@anchor{taler-exchange-manual id5}@anchor{36}@anchor{taler-exchange-manual serving}@anchor{37} +@section Serving + + +The exchange can serve HTTP over both TCP and UNIX domain socket. + +The following options are to be configured in the section @code{[exchange]}: + + +@itemize - + +@item +@code{SERVE}: Must be set to @code{tcp} to serve HTTP over TCP, or @code{unix} to serve +HTTP over a UNIX domain socket. + +@item +@code{PORT}: Set to the TCP port to listen on if @code{SERVE} is @code{tcp}. + +@item +@code{UNIXPATH}: Set to the UNIX domain socket path to listen on if @code{SERVE} is +@code{unix}. + +@item + +@table @asis + +@item @code{UNIXPATH_MODE}: Number giving the mode with the access permission mask + +for the @code{UNIXPATH} (i.e. 660 = @code{rw-rw---}). Make sure to set it in such +a way that your reverse proxy has permissions to access the UNIX domain +socket. The default (660) assumes that the reverse proxy is a member of +the group under which the exchange HTTP server is running. +@end table +@end itemize + +@node Reverse Proxy Setup,Launching an exchange,Serving,Deployment +@anchor{taler-exchange-manual reverse-proxy-setup}@anchor{38}@anchor{taler-exchange-manual reverseproxy}@anchor{39} +@section Reverse Proxy Setup + + +By default, the @code{taler-exchange-httpd} service listens for HTTP connections +on a UNIX domain socket. To make the service publicly available, a reverse +proxy such as nginx should be used. We strongly recommend to configure nginx +to use TLS. + +The public URL that the exchange will be served under should +be put in @code{/etc/taler/conf.d/exchange-business.conf} configuration file. + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-business.conf} + +@example + [exchange] + BASE_URL = https://example.com/ + + # ... rest of file ... +@end example + +@end float + + +The @code{taler-exchange} package ships with a sample configuration that can be +enabled in nginx: + +@example +[root@@exchange-online]# vim /etc/nginx/sites-available/taler-exchange +< ... customize configuration ... > +[root@@exchange-online]# ln -s /etc/nginx/sites-available/taler-exchange \ + /etc/nginx/sites-enabled/taler-exchange +[root@@exchange-online]# systemctl reload nginx +@end example + +Note that the reverse proxy must set a HTTP @code{X-Forwarded-Host} header to +refer to the hostname used by nginx and a HTTP @code{X-Forwarded-Proto} header to +inform the exchange whether the external protocol was @code{http} or @code{https}. +Thus, depending on your setup, you will likely have to edit those parts of the +provided @code{taler-exchange} configuration file. + +With this last step, we are finally ready to launch the +main exchange process. + +@node Launching an exchange,,Reverse Proxy Setup,Deployment +@anchor{taler-exchange-manual launch}@anchor{3a}@anchor{taler-exchange-manual launching-an-exchange}@anchor{3b} @section Launching an exchange @@ -1366,6 +2531,9 @@ A running exchange requires starting the following processes: @code{taler-exchange-secmod-rsa} (as special user, sharing group with the HTTPD) @item +@code{taler-exchange-secmod-cs} (as special user, sharing group with the HTTPD) + +@item @code{taler-exchange-secmod-eddsa} (as special user, sharing group with the HTTPD) @item @@ -1384,24 +2552,24 @@ A running exchange requires starting the following processes: @code{taler-exchange-transfer} (needs credentials to initiate outgoing wire transfers and database access) @end itemize -The crypto helpers must be started before the @code{taler-exchange-httpd} and +The crypto helpers (@code{secmod}) must be started before the @code{taler-exchange-httpd} and they should use the same configuration file. For the most secure deployment, we recommend using separate users for each of these processes to minimize information disclosures should any of them be -compromised. The helpers do not need access to the Postgres database (and +compromised. The helpers do not need access to the PostgreSQL database (and thus also should not have it). The processes that require access to the bank account need to have a configuration file with the respective credentials in it. We recommend using a separate configuration at least for @code{taler-exchange-transfer} which is the -@emph{only} process that needs to know the credentials to execute outgoing wire +`only' process that needs to know the credentials to execute outgoing wire transfers. All of these processes should also be started via a hypervisor like @code{systemd} or @code{gnunet-arm} that automatically re-starts them should they have terminated unexpectedly. If the bank is down (say for maintenance), it is -@emph{possible} to halt the @code{taler-exchange-wirewatch} and/or +`possible' to halt the @code{taler-exchange-wirewatch} and/or @code{taler-exchange-transfer} processes (to avoid them making requests to the bank API that can only fail) without impacting other operations of the exchange. Naturally, incoming wire transfers will only be observed once @@ -1424,24 +2592,106 @@ attack surface.) @end quotation @end cartouche -@node Keys generation,Private key storage,Launching an exchange,Deployment -@anchor{taler-exchange-manual id12}@anchor{2d}@anchor{taler-exchange-manual keys-generation}@anchor{2e} -@section Keys generation +Given proper packaging, all of the above are realized via a simple systemd +target. This enables the various processes of an exchange service to be +started using a simple command: +@example +[root@@exchange-online]# systemctl start taler-exchange.target +@end example -Once the configuration is properly set up, all the keys can be signed using -the offline key on the offline system by the tool @code{taler-exchange-offline}. -To do this, one must first start the crypto helpers and the @code{taler-exchange-httpd} -process (the tools for wire transfers may also be started, but do not have to -run yet). +@cartouche +@quotation Note +At this point, the exchange service is not yet fully operational. +@end quotation +@end cartouche -Next, the @emph{future} key material should be downloaded using: +To check whether the exchange is running correctly under the advertised +base URL, run: + +@example +[root@@exchange-online]# export BASE_URL=$(taler-config -s exchange -o base_url) +[root@@exchange-online]# wget $@{BASE_URL@}management/keys +@end example + +The request might take some time to complete on slow machines, because +a lot of key material will be generated. + +@node Offline Signing Setup Key Maintenance and Tear-Down,AML Configuration,Deployment,Top +@anchor{taler-exchange-manual offline-signing-setup-key-maintenance-and-tear-down}@anchor{3c} +@chapter Offline Signing Setup, Key Maintenance and Tear-Down + + +The exchange HTTP service must be running before you can complete the +following offline signing procedure. Note that when an exchange is running +without offline keys its not fully operational. To make the exchange HTTP +service fully operational, the following steps involving the offline signing +machine must be completed: + +@quotation + + +@enumerate + +@item +The public keys of various online keys used by the exchange service are exported +via a management HTTP API. + +@item +The offline signing system validates this request and signs it. +Additionally, the offline signing system signs policy messages +to configure the exchange's bank accounts and associated fees. + +@item +The messages generated by the offline signing system are uploaded +via the management API of the exchange HTTP service. +@end enumerate +@end quotation + +A typical minimal setup would look something like this: + +@example +[anybody@@exchange-online]# taler-exchange-offline \ + download > sig-request.json + +[root@@exchange-offline]# taler-exchange-offline \ + sign < sig-request.json > sig-response.json +[root@@exchange-offline]# taler-exchange-offline \ + enable-account payto://iban/$IBAN?receiver-name=$NAME > acct-response.json +[root@@exchange-offline]# taler-exchange-offline \ + wire-fee now iban EUR:0 EUR:0 > fee-response.json +[root@@exchange-offline]# taler-exchange-offline \ + global-fee now EUR:0 EUR:0 EUR:0 4w 6y 4 > global-response.json + +[anybody@@exchange-online]# taler-exchange-offline upload < sig-response.json +[anybody@@exchange-online]# taler-exchange-offline upload < acct-response.json +[anybody@@exchange-online]# taler-exchange-offline upload < fee-response.json +[anybody@@exchange-online]# taler-exchange-offline upload < global-response.json +@end example + +The following sections will discuss these steps in more depth. + +@menu +* Signing the online signing keys:: +* Account signing:: +* Wire fee structure:: +* Auditor configuration:: +* Revocations:: + +@end menu + +@node Signing the online signing keys,Account signing,,Offline Signing Setup Key Maintenance and Tear-Down +@anchor{taler-exchange-manual keys-generation}@anchor{3d}@anchor{taler-exchange-manual signing-the-online-signing-keys}@anchor{3e} +@section Signing the online signing keys + + +To sign the online signing keys, first the `future' key material should be downloaded using: @example $ taler-exchange-offline download > future-keys.json @end example -Afterwards, @emph{future-keys.json} contains data about denomination and +Afterwards, `future-keys.json' contains data about denomination and online signing keys that the exchange operator needs to sign with the offline tool. The file should be copied to the offline system. There, the operator should run: @@ -1452,74 +2702,120 @@ $ taler-exchange-offline show < future-keys.json and verify that the output contains the fee structure and key lifetimes they expect to see. They should also note the public keys being shown -and communicate those to the @emph{auditors} over a secure channel. Once +and communicate those to the `auditors' over a secure channel. Once they are convinced the file is acceptable, they should run: @example $ taler-exchange-offline sign < future-keys.json > offline-sigs.json @end example -The @emph{offline-sigs.json} file must then be copied to an online system +The `offline-sigs.json' file must then be copied to an online system that is able to again communicate with the exchange. On that system, run: @example $ taler-exchange-offline upload < offline-sigs.json @end example -to provision the signatures to the exchange. At this point, the -exchange will be able to use those keys, but wallets and merchants -may not yet trust them! Thus, the next step is for the auditor -to affirm that they are auditing this exchange. Details about -this are described in taler-auditor-manual. +to provision the signatures to the exchange. -The simplistic (without using offline keys for the auditor) way -to do this would be: +The @code{download sign upload} sequence in the commands above has to be done +periodically, as it signs the various online signing keys of the exchange +which periodically expire. -@example -$ taler-auditor-offline download sign upload -@end example +@node Account signing,Wire fee structure,Signing the online signing keys,Offline Signing Setup Key Maintenance and Tear-Down +@anchor{taler-exchange-manual account-signing}@anchor{3f}@anchor{taler-exchange-manual exchange-account-signing}@anchor{40} +@section Account signing -For more information, see manpages/taler-auditor-offline.1. -@node Private key storage,Database upgrades,Keys generation,Deployment -@anchor{taler-exchange-manual private-key-storage}@anchor{2f} -@section Private key storage +The @code{enable-account} step is important to must be used to sign the +@code{payto://} URI in a way suitable to convince wallets that this is the +correct address to wire funds to. Note that for each bank account, additional +options `must' be set in the configuration file to tell the exchange how to +access the bank account. The offline tool `only' configures the externally +visible portions of the setup. The chapter on bank account configuration@footnote{_exchange-bank-account-configuration} has further details. +taler-exchange-offline accepts additional options to configure the use of the +account. For example, additional options can be used to add currency +conversion or to restrict interactions to bank accounts from certain +countries: -Keeping the private keys the helpers create secret is paramount. If the -private keys are lost, it is easy to provision fresh keys (with the help of -the auditor). Thus, we recommend that the private keys of the crypto helpers -are @emph{not} backed up: in the rare event of a disk failure, they can be -regenerated. However, we do recommend using RAID (1+1 or 1+1+1) for all -disks of the system. +@example +$ taler-exchange-offline \ + enable-account payto://iban/CH9300762011623852957 + conversion-url https://conversion.example.com/ +@end example -@node Database upgrades,,Private key storage,Deployment -@anchor{taler-exchange-manual database-upgrades}@anchor{30}@anchor{taler-exchange-manual id13}@anchor{31} -@section Database upgrades +For details on optional @code{enable-account} arguments, +see manpages/taler-exchange-offline.1. +@node Wire fee structure,Auditor configuration,Account signing,Offline Signing Setup Key Maintenance and Tear-Down +@anchor{taler-exchange-manual id6}@anchor{41}@anchor{taler-exchange-manual wire-fee-structure}@anchor{42} +@section Wire fee structure -Currently, there is no way to upgrade the database between Taler -versions. -The exchange database can be re-initialized using: +@geindex wire fee + +@geindex fee + +For each wire method (“iban” or “x-taler-bank”) the +exchange must know about applicable wire fees. This is also done +using the @code{taler-exchange-offline} tool: @example -$ taler-exchange-dbinit -r +$ taler-exchange-offline wire-fee 2040 iban EUR:0.05 EUR:0.10 @end example -However, running this command will result in all data in the database -being lost, which may result in significant financial liabilities as the -exchange can then not detect double-spending. Hence this operation must -not be performed in a production system. +The above sets the wire fees for wire transfers involving @code{iban} accounts +(in Euros) in the year 2040 to 5 cents (wire fee) and 10 cents (closing fee). +The tool only supports setting fees that applies for the entire calendar year. -@menu -* Revocations:: +We recommend provisioning an exchange with wire fees at least for the next two +years. Note that once the fees have been set for a year, they cannot be +changed (basically, by signing the fees the exchange makes a legally binding +offer to the customers). -@end menu +@geindex maintenance -@node Revocations,,,Database upgrades -@anchor{taler-exchange-manual id14}@anchor{32}@anchor{taler-exchange-manual revocations}@anchor{33} -@subsection Revocations +@cartouche +@quotation Note +Provisioning future wire fees, like provisioning future denomination +and signing keys, are key regular maintenance procedures for every +exchange operator. We recommend setting automated reminders for +this maintenance activity! +@end quotation +@end cartouche + +@node Auditor configuration,Revocations,Wire fee structure,Offline Signing Setup Key Maintenance and Tear-Down +@anchor{taler-exchange-manual auditor-configuration}@anchor{43}@anchor{taler-exchange-manual id7}@anchor{44} +@section Auditor configuration + + +At this point, the exchange will be able to use those keys, but wallets and +merchants may not yet trust them! Thus, the next step is for an auditor to +affirm that they are auditing this exchange. Before an auditor can do this, +the exchange service must be informed about any auditor that is expected to +provision it with auditor signatures. + +This is also done using the @code{taler-exchange-offline} tool on the offline +system. First, the auditor must be configured and provide the exchange +operator with its public key (using @code{taler-auditor-offline setup}) and the +URL of it's REST API. The exchange operator also needs a human-readable name +that may be shown to users to identify the auditor. For more information on +how to setup and operate an auditor, see +manpages/taler-auditor-offline.1 and taler-auditor-manual. + +Given this information, the exchange operator can enable the auditor: + +@example +$ taler-exchange-offline enable-auditor $PUB_KEY $REST_URL "$AUDITOR_NAME" > auditor.json +@end example + +As before, the `auditor.json' file must then be copied from the offline system +to a system connected to the exchange and there @code{uploaded} to the exchange using @code{taler-exchange-offline upload}. + +@node Revocations,,Auditor configuration,Offline Signing Setup Key Maintenance and Tear-Down +@anchor{taler-exchange-manual id8}@anchor{45}@anchor{taler-exchange-manual revocations}@anchor{46} +@section Revocations When an exchange goes out of business or detects that the private key of @@ -1538,7 +2834,7 @@ value, the key revocation can be approved on the offline system: $ taler-exchange-offline revoke-denominatin $HDP > revocation.json @end example -The resulting @emph{revocation.json} must be copied to a system connected to the +The resulting `revocation.json' must be copied to a system connected to the exchange and uploaded to the exchange using the @code{upload} subcommand of @code{taler-exchange-offline}. @@ -1550,39 +2846,359 @@ operation. @end quotation @end cartouche -@node Testing a deployment,Diagnostics,Deployment,Top -@anchor{taler-exchange-manual testing-a-deployment}@anchor{34} -@chapter Testing a deployment +@node AML Configuration,Setup Linting,Offline Signing Setup Key Maintenance and Tear-Down,Top +@anchor{taler-exchange-manual aml-configuration}@anchor{47} +@chapter AML Configuration + + +The AML configuration steps are used to add or remove keys of exchange +operator staff that are responsible for anti-money laundering (AML) +compliance. These AML officers are shown suspicious transactions and are +granted access to the KYC data of an exchange. They can then investigate the +transaction and decide on freezing or permitting the transfer. They may also +request additional KYC data from the consumer and can change the threshold +amount above which a further AML review is triggered. + +@menu +* AML Officer Setup:: +* AML Triggers:: +* AML Forms:: + +@end menu + +@node AML Officer Setup,AML Triggers,,AML Configuration +@anchor{taler-exchange-manual aml-officer-setup}@anchor{48} +@section AML Officer Setup + + +To begin the AML setup, AML staff should launch the GNU Taler +exchange AML SPA Web interface. (FIXME-Sebastian: how?). The +SPA will generate a public-private key pair and store it in the +local storage of the browser. The public key will be displayed +and must be securely transmitted to the offline system for +approval. Using the offline system, one can then configure +which staff has access to the AML operations: + +@example +[root@@exchange-offline]# taler-exchange-offline \ + aml-enable $PUBLIC_KEY "Legal Name" rw > aml.json +[root@@exchange-online]# taler-exchange-offline \ + upload < aml.json +@end example + +The above commands would add an AML officer with the given "Legal Name" with +read-write (rw) access to the AML officer database. Using "ro" instead of +"rw" would grant read-only access to the data, leaving out the ability to +actually make AML decisions. Once AML access has been granted, the AML +officer can use the SPA to review cases and (with "rw" access) take AML +decisions. + +Access rights can be revoked at any time using: + +@example +[root@@exchange-offline]# taler-exchange-offline \ + aml-disable $PUBLIC_KEY "Legal Name" > aml-off.json +[root@@exchange-online]# taler-exchange-offline \ + upload < aml-off.json +@end example + +@node AML Triggers,AML Forms,AML Officer Setup,AML Configuration +@anchor{taler-exchange-manual aml-triggers}@anchor{49} +@section AML Triggers + + +AML decision processes are automatically triggered under certain configurable +conditions. The primary condition that `must' be configured is the +@code{AML_THRESHOLD}: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-business.conf} + +@example +[exchange] +# Accounts or wallets with monthly transaction volumes above this threshold +# are considered suspicious and are automatically flagged for AML review +# and put on hold until an AML officer has reached a decision. +AML_THRESHOLD = "EUR:1000000" +@end example + +@end float + + +Additionally, certain KYC attributes (such as the user being a +politically exposed person) may lead to an account being +flagged for AML review. The specific logic is configured by +providing the exchange with an external helper program that +makes the decision given the KYC attributes: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-business.conf} + +@example +[exchange] +# Specifies a program to run on KYC attribute data to decide +# whether we should immediately flag an account for AML review. +KYC_AML_TRIGGER = taler-exchange-kyc-aml-pep-trigger.sh +@end example + +@end float + + +The given program will be given the KYC attributes in JSON format on standard +input, and must return 0 to continue without AML and non-zero to flag the +account for manual review. To disable this trigger, simply leave the option to +its default value of '[/usr/bin/]true'. To flag all new users for manual +review, simply set the program to '[/usr/bin/]false'. + +@node AML Forms,,AML Triggers,AML Configuration +@anchor{taler-exchange-manual aml-forms}@anchor{4a} +@section AML Forms + + +AML forms are defined by the DD 54 dynamic forms. +The shipped implementation with of the exchange is installed in + +@example +$@{INSTALL_PREFIX@}/share/taler/exchange/spa/forms.js +@end example + +The variable @code{form} contains the list of all form available. For +every entry in the list the next properties are expected to be present: + +@code{label}: used in the UI as the name of the form + +@code{id}: identification name, this will be saved in the exchange database +along with the values to correctly render the form again. +It should simple, short and without any character outside numbers, +letters and underscore. + +@code{version}: when editing a form, instead of just replacing fields +it will be better to create a new form with the same id and new version. +That way old forms in the database will used old definition of the form. +It should be a number. + +@code{impl} : a function that returns the design and behavior of form. +See DD 54 dynamic forms. + +@cartouche +@quotation Attention +do not remove a form the list if it has been used. Otherwise you +won't be able to see the information save in the exchange database. +@end quotation +@end cartouche + +To add a new one you can simply copy and paste one element, and edit it. + +It is much easier to download @code{@@gnu-taler/aml-backoffice-ui} source +from @code{https://git.taler.net/wallet-core.git/}, compile and copy the file +from the @code{dist/prod}. + +@node Setup Linting,Testing and Troubleshooting,AML Configuration,Top +@anchor{taler-exchange-manual setup-linting}@anchor{4b} +@chapter Setup Linting + + +The @code{taler-wallet-cli} package comes with an experimental tool that runs various +checks on the current GNU Taler exchange deployment: + +@example +[root@@exchange-online]# apt install taler-wallet-cli +[root@@exchange-online]# taler-wallet-cli deployment lint-exchange +@end example + +You can optionally pass the @code{--debug} option to get more verbose output, and +@code{--continue} to continue with further checks even though a previous one has +failed. + +@node Testing and Troubleshooting,Template Customization,Setup Linting,Top +@anchor{taler-exchange-manual testing-and-troubleshooting}@anchor{4c} +@chapter Testing and Troubleshooting We recommend testing whether an exchange deployment is functional by using the Taler wallet command line interface. The tool can be used to withdraw and deposit electronic cash via the exchange without having to deploy and operate a -separate merchant backend and storefront. For more information, see -taler-wallet-cli-manual. +separate merchant backend and storefront. + +The following shell session illustrates how the wallet can be used to withdraw +electronic cash from the exchange and subsequently spend it. For these steps, +a merchant backend is not required, as the wallet acts as a merchant. + +@example +# This will now output a payto URI that money needs to be sent to in order to allow withdrawal +# of taler coins. +$ taler-wallet-cli advanced withdraw-manually --exchange $EXCHANGE_URL --amount EUR:10.50 +@end example + +Show the status of the manual withdrawal operation. + +@example +$ taler-wallet-cli transactions +@end example + +At this point, a bank transfer to the exchange's bank account +needs to be made with the correct subject / remittance information +as instructed by the wallet after the first step. With the +above configuration, it should take about 5 minutes after the +wire transfer for the incoming transfer to be observed by the +Nexus. + +Run the following command to check whether the exchange received +an incoming bank transfer: + +@example +[root@@exchange-online]# taler-exchange-wire-gateway-client \ + --section exchange-accountcredentials-1 --credit-history +@end example + +Once the transfer has been made, try completing the withdrawal +using: + +@example +$ taler-wallet-cli run-pending +@end example + +Afterwards, check the status of transactions and show the +current wallet balance: + +@example +$ taler-wallet-cli transactions +$ taler-wallet-cli balance +@end example + +Now, we can directly deposit coins via the exchange into a target +account. (Usually, a payment is made via a merchant. The wallet +provides this functionality for testing.) + +@example +$ taler-wallet-cli deposit create EUR:5 \ + payto://iban/$IBAN?receiver-name=Name +$ taler-wallet-cli run-pending +@end example + +Check if this transaction was successful (from the perspective +of the wallet): + +@example +$ taler-wallet-cli transactions +@end example + +If the transaction failed, fix any open issue(s) with the exchange and +run the "run-pending" command. -@node Diagnostics,Benchmarking,Testing a deployment,Top -@anchor{taler-exchange-manual diagnostics}@anchor{35}@anchor{taler-exchange-manual id15}@anchor{36} -@chapter Diagnostics +The wallet can also track if the exchange wired the money to the merchant +account. The "deposit group id" can be found in the output of the +transactions list. +@example +$ taler-wallet-cli deposit track $DEPOSIT_GROUP_ID +@end example + +You can also check using the exchange-tools whether the exchange sent +the an outgoing transfer: + +@example +[root@@exchange-online]# taler-exchange-wire-gateway-client \ + --section exchange-accountcredentials-1 --debit-history +@end example -This chapter includes various sections on specific topics that might be -helpful to understand how the exchange operates. The information may also be -helpful for diagnostics. +After enough time has passed, the money should arrive at the specified IBAN. + +For more information on the taler-wallet-cli tool, see +taler-wallet. @menu +* taler-config:: +* Using taler-config:: +* Private key storage:: * Internal audits:: * Database Scheme:: +* Database upgrades:: @end menu -@node Internal audits,Database Scheme,,Diagnostics -@anchor{taler-exchange-manual internal-audit}@anchor{37}@anchor{taler-exchange-manual internal-audits}@anchor{38} +@node taler-config,Using taler-config,,Testing and Troubleshooting +@anchor{taler-exchange-manual taler-config}@anchor{4d} +@section taler-config + + +@node Using taler-config,Private key storage,taler-config,Testing and Troubleshooting +@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{4e}@anchor{taler-exchange-manual using-taler-config}@anchor{4f} +@section Using taler-config + + +The tool @code{taler-config} can be used to extract or manipulate configuration +values; however, the configuration use the well-known INI file format and is +generally better edited by hand to preserve comments and structure. Thus, @code{taler-config} should primarily be used +to inspect or understand a configuration that is in place, +and not to update it! + +Run + +@example +$ taler-config -s $SECTION +@end example + +to list all of the configuration values in section @code{$SECTION}. + +Run + +@example +$ taler-config -s $SECTION -o $OPTION +@end example + +to extract the respective configuration value for option @code{$OPTION} in +section @code{$SECTION}. + +Finally, to change a setting and clobber your entire +configuration file structure, inlining all values and +removing all comments, run + +@example +$ taler-config -s $SECTION -o $OPTION -V $VALUE +@end example + +to set the respective configuration value to @code{$VALUE}. Note that you +have to manually restart affected Taler components after you change the +configuration to make the new configuration go into effect. + +Some default options will use $-variables, such as @code{$DATADIR} within +their value. To expand the @code{$DATADIR} or other $-variables in the +configuration, pass the @code{-f} option to @code{taler-config}. For example, +compare: + +@example +$ taler-config --section exchange-offline --option MASTER_PRIV_FILE +$ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE +@end example + +While the configuration file is typically located at +@code{$HOME/.config/taler.conf}, an alternative location can be specified to any +GNU Taler component using the @code{-c} option. + +@node Private key storage,Internal audits,Using taler-config,Testing and Troubleshooting +@anchor{taler-exchange-manual private-key-storage}@anchor{50} +@section Private key storage + + +Keeping the private keys the helpers create secret is paramount. If the +private keys are lost, it is easy to provision fresh keys (with the help of +the auditor). Thus, we recommend that the private keys of the crypto helpers +are `not' backed up: in the rare event of a disk failure, they can be +regenerated. However, we do recommend using RAID (1+1 or 1+1+1) for all +disks of the system. + +@node Internal audits,Database Scheme,Private key storage,Testing and Troubleshooting +@anchor{taler-exchange-manual internal-audit}@anchor{51}@anchor{taler-exchange-manual internal-audits}@anchor{52} @section Internal audits While an exchange should use an external auditor to attest to regulators that -it is operating correctly, an exchange operator can also use the auditor’s +it is operating correctly, an exchange operator can also use the auditor's logic to perform internal checks. For this, an exchange operator can generally follow the auditor guide. However, instead of using @code{taler-auditor-sync}, an internal audit can and likely should be performed either directly against @@ -1594,7 +3210,7 @@ the database invariants. Running the auditor against a the original the production database (without using @code{taler-auditor-sync}) enables the auditing logic to perform a few additional checks that can detect inconsistencies. These checks are enabled -by passing the @strong{-i} option to the @code{taler-auditor} command. As always, +by passing the `-i' option to the @code{taler-auditor} command. As always, the resulting report should be read carefully to see if there are any problems with the setup. @@ -1604,8 +3220,8 @@ While it is possible to reset the auditor database and to restart the audit from the very beginning, this is generally not recommended as this may be too expensive. -@node Database Scheme,,Internal audits,Diagnostics -@anchor{taler-exchange-manual database-scheme}@anchor{39}@anchor{taler-exchange-manual id16}@anchor{3a} +@node Database Scheme,Database upgrades,Internal audits,Testing and Troubleshooting +@anchor{taler-exchange-manual database-scheme}@anchor{53}@anchor{taler-exchange-manual id9}@anchor{54} @section Database Scheme @@ -1620,74 +3236,767 @@ The database scheme used by the exchange looks as follows: @image{taler-exchange-figures/exchange-db,,,,png} -@node Benchmarking,Index,Diagnostics,Top -@anchor{taler-exchange-manual benchmarking}@anchor{3b}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{3c} -@chapter Benchmarking - - -This chapter describes how to run the Taler exchange benchmark. The benchmark -can be used to measure the performance of the exchange by running a (possibly -large) number of simulated clients against one Taler deployment with a bank, -exchange and auditor. For the bank, both a “fakebank” (@code{-f}) and a -“Pythonbank” deployment are currently supported. The -@code{taler-exchange-benchmark} program can launch all required services and -clients, or only launch the parallel clients (@code{-m}), for example for -distributed testing over a network. +@node Database upgrades,,Database Scheme,Testing and Troubleshooting +@anchor{taler-exchange-manual database-upgrades}@anchor{55}@anchor{taler-exchange-manual id10}@anchor{56} +@section Database upgrades -For each @emph{parallel} (@code{-p}) client, a number of @emph{reserves} (@code{-r}) is first established by -@strong{transferring} money from a “user” account (42) to the Exchange’s account -with the respective reserve public key as wire subject. Next, the -client will @strong{withdraw} a @emph{number of coins} (@code{-n}) from the reserve and -@strong{deposit} them. Additionally, a @emph{fraction} (@code{-R}) of the dirty coins will then be -subject to @strong{refreshing}. For some deposits, the auditor will receive -@strong{deposit confirmations}. -Operations that are not covered today include closing reserves, refunds and -recoups. +Before installing a new exchange version, you should probably make a backup of +the existing database and study the release notes on migration. In general, +the way to migrate is to stop all existing Taler exchange processes and run: -The existing @code{benchmark.conf} file in @code{src/benchmark/} can be used as a -starting point for a configuration to run the benchmark. The existing -configuration file only requires that the @code{talercheck} database already -exists and will launch all required services locally as needed. +@example +$ taler-exchange-dbinit +@end example -You can run a first simple benchmark using: +This will migrate the existing schema to the new schema. You also may need +to grant Taler exchange processes the rights to the new tables (see last +step of database setup). @cartouche @quotation Note -FIXME-TTN/CG: these instructions are incomplete and untested for the -current iteration of the code… +The `taler-exchange-dbconfig' tool can be used to automate the database +migration. In general, simply invoking it again should trigger the +migration including `taler-exchange-dbinit' and setting the permissions. @end quotation @end cartouche +If you do not want to keep any data from the previous installation, the +exchange database can be fully re-initialized using: + +@example +$ taler-exchange-dbinit --reset +@end example + +However, running this command will result in all data in the database +being lost, which may result in significant financial liabilities as the +exchange can then not detect double-spending. Hence this operation must +not be performed in a production system. You still also need to then +grant the permissions to the other exchange processes again. + +@node Template Customization,Benchmarking,Testing and Troubleshooting,Top +@anchor{taler-exchange-manual exchangetemplatecustomization}@anchor{57}@anchor{taler-exchange-manual template-customization}@anchor{58} +@chapter Template Customization + + +The Exchange comes with various HTML templates that are shown to +guide users through the KYC process. The Exchange uses Mustach@footnote{https://gitlab.com/jbol/mustach} as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the @code{share/taler/exchange/templates/} directory. The file names must be of +the form @code{$NAME.$LANG.must} where @code{$NAME} is the name of the template and +@code{$LANG} is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. Most +subsection titles are the @code{$NAME} of the respective template. + +@menu +* Generic Errors Templates:: +* kycaid-invalid-request:: +* oauth2-authentication-failure:: +* oauth2-authorization-failure:: +* oauth2-authorization-failure-malformed:: +* oauth2-bad-request:: +* oauth2-conversion-failure:: +* oauth2-provider-failure:: +* persona-exchange-unauthorized:: +* persona-load-failure:: +* persona-exchange-unpaid:: +* persona-logic-failure:: +* persona-invalid-response:: +* persona-network-timeout:: +* persona-kyc-failed:: +* persona-provider-failure:: + +@end menu + +@node Generic Errors Templates,kycaid-invalid-request,,Template Customization +@anchor{taler-exchange-manual generic-errors-templates}@anchor{59} +@section Generic Errors Templates + + +A number of templates are used for generic errors. These are: + +@quotation + + +@itemize * + +@item +kyc-proof-already-done (KYC process already completed) + +@item +kyc-bad-request (400 Bad Request) + +@item +kyc-proof-endpoint-unknown (404 Not Found for KYC logic) + +@item +kyc-proof-internal-error (500 Internal Server Error) + +@item +kyc-proof-target-unknown (404 Not Found for KYC operation) +@end itemize +@end quotation + +All of these templates are instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +message: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize +@end quotation + +@node kycaid-invalid-request,oauth2-authentication-failure,Generic Errors Templates,Template Customization +@anchor{taler-exchange-manual kycaid-invalid-request}@anchor{5a} +@section kycaid-invalid-request + + +The KYCaid plugin does not support requests to the +@code{/kyc-proof/} endpoint (HTTP 400 bad request). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +error: String; error code from the server + +@item +error_details: String; optional error description from the server + +@item +error_uri: optional URI with further details about the error from the server +@end itemize +@end quotation + +@node oauth2-authentication-failure,oauth2-authorization-failure,kycaid-invalid-request,Template Customization +@anchor{taler-exchange-manual oauth2-authentication-failure}@anchor{5b} +@section oauth2-authentication-failure + + +The OAuth2 server said that the request was not +properly authenticated (HTTP 403 Forbidden). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error +@end itemize +@end quotation + +@node oauth2-authorization-failure,oauth2-authorization-failure-malformed,oauth2-authentication-failure,Template Customization +@anchor{taler-exchange-manual oauth2-authorization-failure}@anchor{5c} +@section oauth2-authorization-failure + + +The OAuth2 server refused to return the KYC data +because the authorization code provided was +invalid (HTTP 403 Forbidden). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +error: String; error code from the server + +@item +error_message: String; error message from the server +@end itemize +@end quotation + +@node oauth2-authorization-failure-malformed,oauth2-bad-request,oauth2-authorization-failure,Template Customization +@anchor{taler-exchange-manual oauth2-authorization-failure-malformed}@anchor{5d} +@section oauth2-authorization-failure-malformed + + +The server refused the authorization, but then provided +a malformed response (HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +debug: Bool; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information + +@item +server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the use if "debug" is true +@end itemize +@end quotation + +@node oauth2-bad-request,oauth2-conversion-failure,oauth2-authorization-failure-malformed,Template Customization +@anchor{taler-exchange-manual oauth2-bad-request}@anchor{5e} +@section oauth2-bad-request + + +The client made an invalid request (HTTP 400 Bad Request). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +message: String; additional error message elaborating on what was bad about the request +@end itemize +@end quotation + +@node oauth2-conversion-failure,oauth2-provider-failure,oauth2-bad-request,Template Customization +@anchor{taler-exchange-manual oauth2-conversion-failure}@anchor{5f} +@section oauth2-conversion-failure + + +Converting the KYC data into the exchange's internal +format failed (HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +debug: Bool; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information + +@item +converter: String; name of the conversion command that failed which was used by the Exchange + +@item +attributes: Object; attributes returned by the conversion command, often NULL (after all, conversion failed) + +@item +message: error message elaborating on the conversion failure +@end itemize +@end quotation + +@node oauth2-provider-failure,persona-exchange-unauthorized,oauth2-conversion-failure,Template Customization +@anchor{taler-exchange-manual oauth2-provider-failure}@anchor{60} +@section oauth2-provider-failure + + +We did not get an acceptable response from the OAuth2 +provider (HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +message: String; could be NULL; text elaborating on the details of the failure +@end itemize +@end quotation + +@node persona-exchange-unauthorized,persona-load-failure,oauth2-provider-failure,Template Customization +@anchor{taler-exchange-manual persona-exchange-unauthorized}@anchor{61} +@section persona-exchange-unauthorized + + +The Persona server refused our request (HTTP 403 Forbidden from Persona, returned as a HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-load-failure,persona-exchange-unpaid,persona-exchange-unauthorized,Template Customization +@anchor{taler-exchange-manual persona-load-failure}@anchor{62} +@section persona-load-failure + + +The Persona server refused our request (HTTP 429 Too Many Requests from Persona, returned as a HTTP 503 Service Unavailable). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-exchange-unpaid,persona-logic-failure,persona-load-failure,Template Customization +@anchor{taler-exchange-manual persona-exchange-unpaid}@anchor{63} +@section persona-exchange-unpaid + + +The Persona server refused our request (HTTP 402 Payment REquired from Persona, returned as a HTTP 503 Service Unavailable). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-logic-failure,persona-invalid-response,persona-exchange-unpaid,Template Customization +@anchor{taler-exchange-manual persona-logic-failure}@anchor{64} +@section persona-logic-failure + + +The Persona server refused our request (HTTP 400, 403, 409, 422 from Persona, returned as a HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-invalid-response,persona-network-timeout,persona-logic-failure,Template Customization +@anchor{taler-exchange-manual persona-invalid-response}@anchor{65} +@section persona-invalid-response + + +The Persona server refused our request in an +unexpected way; returned as a HTTP 502 Bad Gateway. + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +debug: Bool; true if we are running in debug mode and are allowed to return HTML with potentially sensitive information + +@item +server_response: Object; could be NULL; this includes the (malformed) OAuth2 server response, it should be shown to the use if "debug" is true +@end itemize +@end quotation + +@node persona-network-timeout,persona-kyc-failed,persona-invalid-response,Template Customization +@anchor{taler-exchange-manual persona-network-timeout}@anchor{66} +@section persona-network-timeout + + +The Persona server refused our request (HTTP 408 from Persona, returned as a HTTP 504 Gateway Timeout). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-kyc-failed,persona-provider-failure,persona-network-timeout,Template Customization +@anchor{taler-exchange-manual persona-kyc-failed}@anchor{67} +@section persona-kyc-failed + + +The Persona server indicated a problem with the KYC process, saying it was not completed. + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +persona_inquiry_id: String; internal ID of the inquiry within Persona, useful for further diagnostics by staff + +@item +data: Object; could be NULL; this includes the server response, it contains extensive diagnostics, see Persona documentation on their @code{/api/v1/inquiries/$ID}. + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node persona-provider-failure,,persona-kyc-failed,Template Customization +@anchor{taler-exchange-manual persona-provider-failure}@anchor{68} +@section persona-provider-failure + + +The Persona server refused our request (HTTP 500 from Persona, returned as a HTTP 502 Bad Gateway). + +This template is instantiated using the following information: + +@quotation + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +data: Object; data returned from Persona service, optional + +@item +persona_http_status: Integer; HTTP status code returned by Persona +@end itemize +@end quotation + +@node Benchmarking,FIXMEs,Template Customization,Top +@anchor{taler-exchange-manual benchmarking}@anchor{69}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{6a} +@chapter Benchmarking + + +This chapter describes how to run various benchmarks against a Taler exchange. +These benchmark can be used to measure the performance of the exchange by +running a (possibly large) number of simulated clients against one Taler +deployment with a bank, exchange and (optionally) auditor. + +Real benchmarks that are intended to demonstrate the scalability of GNU Taler +should not use the tools presented in this section: they may be suitable for +microbenchmarking and tuning, but the setup is inherently not optimzied for +performance or realism, both for the load generation and the server side. +Thus, we do not recommend using these performance numbers to assess the +scalability of GNU Taler. That said, the tools can be useful to help identify +performance issues. + +The @code{taler-unified-setup.sh} script can be used to launch all required +services and clients. However, the resulting deployment is simplistic +(everything on the local machine, one single-threaded process per service +type) and not optimized for performance at all. However, this can still be +useful to assess the performance impact of changes +to the code or configuration. + +The various configuration files used in the code snippets in this section can +be found in the @code{src/benchmark/} directory of the exchange. These are +generally intended as starting points. Note that the configuration files +ending in @code{.edited} are created by @code{taler-unified-setup.sh} and contain +some options that are determined at runtime by the setup logic provided by +@code{taler-unified-setup.sh}. + +@menu +* Choosing a bank:: +* taler-bank-benchmark:: +* taler-exchange-benchmark:: +* taler-aggregator-benchmark:: + +@end menu + +@node Choosing a bank,taler-bank-benchmark,,Benchmarking +@anchor{taler-exchange-manual benchmark-choose-bank}@anchor{6b}@anchor{taler-exchange-manual choosing-a-bank}@anchor{6c} +@section Choosing a bank + + +For the bank, both a fakebank (@code{-f}) and libeufin-based (@code{-ns}) +bank deployment are currently supported by all benchmark tools and +configuration templates. + +Fakebank is an ultra-fast in-memory implementation of the Taler bank API. It +is suitable when the goal is to benchmark the core GNU Taler payment system +and to ignore the real-time gross settlement (RTGS) system typically provided +by an existing bank. When using the fakebank, @code{taler-unified-setup.sh} must +be started with the @code{-f} option and be told to use the right exchange bank +account from the configuration files via @code{-u exchange-account-1}. + @example -$ createdb talercheck # if it does not yet exist -$ taler-exchange-dbinit -c benchmark.conf -$ taler-exchange-httpd -c benchmark.conf & -$ HTTPD_PID=$! -$ taler-exchange-offline -c benchmark.conf \ - download sign \ - enable-account FIXME-DETAILS-MISING-HERE \ - wire-fee FIXME-DETAILS-MISING-HERE \ - upload -$ kill -TERM $HTTPD_PID -$ taler-exchange-benchmark -c benchmark.conf -p 4 -r 1 -n 10 +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -emwt -c $CONF -f -u exchange-account-1 @end example -This will run 4 parallel clients withdrawing 10 coins from 1 reserve and then -depositing those coins. The default refresh probability is 10 percent. Note -that the tiny run should only take a few seconds, most of it will be spent in -the setup of the original key material. For meaningful runs, all three values -should likely be increased. +libeufin is GNU Taler's adapter to the core banking system using the EBICS +banking protocol standard. It uses a Postgres database to persist data and is +thus much slower than fakebank. If your GNU Taler deployment uses libeufin in +production, it likely makes sense to benchmark with libeufin. When using the +fakebank, @code{taler-unified-setup.sh} must be started with the @code{-ns} options +(starting libeufin-nexus and libeufin-bank) and be told to use the right +exchange bank account from the configuration files via @code{-u +exchange-account-2}. Note that @code{taler-unified-setup.sh} currently cannot +reset a libeufin database, and also will not run if the database is already +initialized. Thus, you must re-create the database every time before +running the command: + +@example +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -emwt -c $CONF -ns -u exchange-account-2 +@end example + +@node taler-bank-benchmark,taler-exchange-benchmark,Choosing a bank,Benchmarking +@anchor{taler-exchange-manual taler-bank-benchmark}@anchor{6d} +@section taler-bank-benchmark + + +This is the simplest benchmarking tool, simulating only the bank +interaction. + +@example +$ CONF="benchmark-cs.conf" +$ # or with libeufin +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -emwt -c "$CONF" -f -u exchange-account-1 +$ # Once <<READY>>, in another shell (remember to set $CONF): +$ time taler-bank-benchmark -c "$CONF" -r 40 -p 4 -P4 -u exchange-account-1 -f +$ # or with libeufin +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -emwt -c "$CONF" -ns -u exchange-account-2 +$ # Once <<READY>>, in another shell (remember to set $CONF): +$ time taler-bank-benchmark -c "$CONF" -r 40 -p 1 -P1 -u exchange-account-2 +@end example + +For each `parallel' (@code{-p}) client, a number of `reserves' (@code{-r}) is first +established by `transferring' money from a "user" account (42) to the +Exchange's account with the respective reserve public key as wire subject. +Processing is then handled by `parallel' (@code{-P}) service workers. + +@node taler-exchange-benchmark,taler-aggregator-benchmark,taler-bank-benchmark,Benchmarking +@anchor{taler-exchange-manual taler-exchange-benchmark}@anchor{6e} +@section taler-exchange-benchmark + + +This is the benchmarking tool simulates a number of clients withdrawing, +depositing and refreshing coins. Operations that are not covered by the +@code{taler-exchange-benchmark} tool today include closing reserves, refunds, +recoups and P2P payments. + +@example +$ CONF="benchmark-cs.conf" # -rsa also makes sense +$ # With fakebank +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -aemwt -c "$CONF" -f -u exchange-account-1 +$ # Once <<READY>>, in another shell (remember to set $CONF): +$ taler-exchange-benchmark -c "$CONF".edited -u exchange-account-1 -n 1 -p1 -r 5 -f +$ # +$ # With libeufin +$ dropdb talercheck; createdb talercheck +$ taler-unified-setup.sh -aemwt -c "$CONF" -ns -u exchange-account-2 +$ # Once <<READY>>, in another shell (remember to set $CONF): +$ taler-exchange-benchmark -c "$CONF".edited -u exchange-account-2 -L WARNING -n 1 -p1 -r 5 +@end example + +For each `parallel' (@code{-p}) client, a number of `reserves' (@code{-r}) is first +established by `transferring' money from a "user" account (42) to the +Exchange's account with the respective reserve public key as wire subject. +Next, the client will `withdraw' a `number of coins' (@code{-n}) from the +reserve and `deposit' them. Additionally, a `fraction' (@code{-R}) of the dirty +coins will then be subject to `refreshing'. For some deposits, the auditor +will receive `deposit confirmations'. The output of @code{taler-exchange-benchmark} will include for each parallel client the total time spent in each of the major operations, possible repetitions (i.e. if the operation failed the first time), total execution time (operating system and user space) and other details. -Naturally, additional instrumentation (including using features of the -Postgres database itself) may help discover performance issues. +@node taler-aggregator-benchmark,,taler-exchange-benchmark,Benchmarking +@anchor{taler-exchange-manual taler-aggregator-benchmark}@anchor{6f} +@section taler-aggregator-benchmark + + +This is another simple benchmark tool that merely prepares an exchange +database to run a stand-alone benchmark of the @code{taler-exchange-aggregator} +tool. After preparing a database and running the tool, you can then +run one or more @code{taler-exchange-aggregator} processes and measure how +quickly they perform the aggregation work. + +@example +$ CONF=benchmark-rsa.conf +$ taler-exchange-dbinit -c "$CONF" --reset +$ ./taler-aggregator-benchmark -c "$CONF" -m 500 -r 10 -d 100 +$ time taler-exchange-aggregator -c "$CONF" --test +@end example + +This above commands will first create 100 deposits with 10 refunds into each +of 500 merchant accounts using randomized time stamps. Afterwards, it will +time a single aggregator process in @code{--test} mode (asking it to terminate +as soon as there is no more pending work). + +@node FIXMEs,Index,Benchmarking,Top +@anchor{taler-exchange-manual fixmes}@anchor{70} +@chapter FIXMEs + + + +@itemize * + +@item +We should have some summary with the inventory of services that should be +running. Systemd by default doesn't show this nicely. Maybe suggest running +"systemd list-dependencies taler-exchange.target"? + +@item +What happens when the TWG doesn't like one particular outgoing transaction? +How to recover from that as a sysadmin when it happens in practice? +@end itemize -@node Index,,Benchmarking,Top +@node Index,,FIXMEs,Top @unnumbered Index diff --git a/texinfo/taler-merchant-api-tutorial-figures/arch-api.png b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png Binary files differindex 8004f790..9e593ab4 100644 --- a/texinfo/taler-merchant-api-tutorial-figures/arch-api.png +++ b/texinfo/taler-merchant-api-tutorial-figures/arch-api.png diff --git a/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png Binary files differindex f99e2664..7a4050c6 100644 --- a/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png +++ b/texinfo/taler-merchant-api-tutorial-figures/exchange-db.png diff --git a/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png b/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png +++ b/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi index 3f51b138..28b57ecc 100644 --- a/texinfo/taler-merchant-api-tutorial.texi +++ b/texinfo/taler-merchant-api-tutorial.texi @@ -3,29 +3,27 @@ @setfilename taler-merchant-api-tutorial.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Merchant API Tutorial @defindex ge @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-merchant-api-tutorial.info). DESCRIPTION +* GNU Taler Merchant API: (taler-merchant-api-tutorial.info). Tutorial for using the merchant backend API @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.9.4, Apr 12, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -49,17 +47,17 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @c %**start of body @anchor{taler-merchant-api-tutorial doc}@anchor{0} @c This file is part of GNU TALER. -@c Copyright (C) 2014-2020 Taler Systems SA +@c Copyright (C) 2014-2023 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the -@c terms of the GNU General Public License as published by the Free Software +@c terms of the GNU Affero General Public License as published by the Free Software @c Foundation; either version 2.1, or (at your option) any later version. @c @c TALER is distributed in the hope that it will be useful, but WITHOUT ANY @c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -@c A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. @c -@c You should have received a copy of the GNU Lesser General Public License along with +@c You should have received a copy of the GNU Affero General Public License along with @c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @c @c @author Marcello Stanisci @@ -71,7 +69,6 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) * Merchant Payment Processing:: * Giving Refunds:: * Repurchase detection and fulfillment URLs:: -* Giving Customers Tips:: * Advanced topics:: * Index:: @@ -101,7 +98,7 @@ Advanced topics @end menu @node Introduction,Merchant Payment Processing,Top,Top -@anchor{taler-merchant-api-tutorial gnu-taler-merchant-api-tutorial}@anchor{1}@anchor{taler-merchant-api-tutorial introduction}@anchor{2}@anchor{taler-merchant-api-tutorial merchant-api-tutorial}@anchor{3} +@anchor{taler-merchant-api-tutorial id1}@anchor{1}@anchor{taler-merchant-api-tutorial introduction}@anchor{2}@anchor{taler-merchant-api-tutorial merchant-api-tutorial}@anchor{3} @chapter Introduction @@ -134,7 +131,7 @@ regulation (such as GDPR). This tutorial addresses how to process payments using the GNU Taler merchant -Backend. The audience for this tutorial are @emph{developers} of merchants (such +Backend. The audience for this tutorial are `developers' of merchants (such as Web shops) that are working on integrating GNU Taler with the customer-facing Frontend and the staff-facing Backoffice. @@ -160,11 +157,6 @@ that accepts donations for software projects and gives donation receipts. @item -The -survey@footnote{https://git.taler.net/taler-merchant-demos.git/tree/talermerchantdemos/survey} -that gives users who answer a question a small reward. - -@item The WooCommerce plugin@footnote{https://git.taler.net/gnu-taler-payment-for-woocommerce.git/} which is a comprehensive integration into a Web shop including the refund business process. @@ -237,12 +229,12 @@ configuration. See taler-merchant-manual. The public sandbox backend @indicateurl{https://backend.demo.taler.net/} uses an API key in the @code{Authorization} header. The value of this header must be -@code{ApiKey sandbox} for the public sandbox backend. +@code{Bearer secret-token:sandbox} for the public sandbox backend. @example >>> import requests ->>> requests.get("https://backend.demo.taler.net", -... headers=@{"Authorization": "ApiKey sandbox"@}) +>>> requests.get("https://backend.demo.taler.net/private/orders", +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) <Response [200]> @end example @@ -261,10 +253,10 @@ imaginary currency. Coins denominated in @code{KUDOS} can be withdrawn from @section Merchant Instances -The same Taler merchant backend server can be used by multiple separate +A single Taler merchant backend server can be used by multiple merchants that are separate business entities. Each of these separate -business entities is called a @emph{merchant instance}, and is identified by -an alphanumeric @emph{instance id}. If the instance is omitted, the instance +business entities is assigned a `merchant instance' which is identified by +an alphanumeric `instance id'. If the instance is omitted, the instance id @code{default} is assumed. The following merchant instances are configured on @@ -297,7 +289,7 @@ All endpoints for instances offer the same API. Thus, which instance to be used is simply included in the base URL of the merchant backend. @node Merchant Payment Processing,Giving Refunds,Introduction,Top -@anchor{taler-merchant-api-tutorial id1}@anchor{9}@anchor{taler-merchant-api-tutorial merchant-payment-processing}@anchor{a} +@anchor{taler-merchant-api-tutorial id2}@anchor{9}@anchor{taler-merchant-api-tutorial merchant-payment-processing}@anchor{a} @chapter Merchant Payment Processing @@ -314,7 +306,7 @@ to be used is simply included in the base URL of the merchant backend. @section Creating an Order for a Payment -Payments in Taler revolve around an @emph{order}, which is a machine-readable +Payments in Taler revolve around an `order', which is a machine-readable description of the business transaction for which the payment is to be made. Before accepting a Taler payment as a merchant you must create such an order. @@ -362,10 +354,10 @@ A minimal Python snippet for creating an order would look like this: >>> body = dict(order=dict(amount="KUDOS:10", ... summary="Donation", ... fulfillment_url="https://example.com/thanks.html"), -... create_token=false) ->>> response = requests.post("https://backend.demo.taler.net/private/order", +... create_token=False) +>>> response = requests.post("https://backend.demo.taler.net/private/orders", ... json=body, -... headers=@{"Authorization": "ApiKey sandbox"@}) +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) <Response [200]> @end example @@ -373,7 +365,7 @@ A minimal Python snippet for creating an order would look like this: The backend will fill in some details missing in the order, such as the address of the merchant instance. The full details are called the -@emph{contract terms}. +`contract terms'. @geindex contract terms @@ -386,19 +378,23 @@ given below to include the claim token. @end quotation @end cartouche -After successfully @code{POST}ing to @code{/private/orders}, an @code{order_id} will be -returned. Together with the merchant @code{instance}, the order id uniquely -identifies the order within a merchant backend. Using the order ID, you -can trivially construct the respective @code{taler://pay/} URI that must -be provided to the wallet. Let @code{example.com} be the domain name where -the public endpoints of the instance are reachable. The Taler pay URI is -then simply @code{taler://pay/example.com/$ORDER_ID/} where @code{$ORDER_ID} -must be replaced with the ID of the order that was returned. +After successfully @code{POST}ing to @code{/private/orders}, a JSON with just an +@code{order_id} field with a string representing the order ID will be returned. +If you also get a claim token, please double-check that you used the request +as described above. + +Together with the merchant @code{instance}, the order id uniquely identifies the +order within a merchant backend. Using the order ID, you can trivially +construct the respective @code{taler://pay/} URI that must be provided to the +wallet. Let @code{example.com} be the domain name where the public endpoints of +the instance are reachable. The Taler pay URI is then simply +@code{taler://pay/example.com/$ORDER_ID/} where @code{$ORDER_ID} must be replaced +with the ID of the order that was returned. You can put the @code{taler://} URI as the target of a link to open the Taler wallet via the @code{taler://} schema, or put it into a QR code. However, for a Web shop, the easiest way is to simply redirect the browser to -@code{https://example.com/orders/$ORDER_ID/}. That page will then trigger the +@code{https://example.com/orders/$ORDER_ID}. That page will then trigger the Taler wallet. Here the backend generates the right logic to trigger the wallet, supporting the various types of Taler wallets in existence. Instead of constructing the above URL by hand, it is best to obtain it by checking for @@ -410,11 +406,11 @@ the payment status as described in the next section. Given the order ID, the status of a payment can be checked with the -@code{/private/orders/$ORDER_ID/} endpoint. If the payment is yet to be completed +@code{/private/orders/$ORDER_ID} endpoint. If the payment is yet to be completed by the customer, @code{/private/orders/$ORDER_ID} will give the frontend a URL (under the name @code{payment_redirect_url}) that will trigger the customer’s wallet to execute the payment. This is basically the -@code{https://example.com/orders/$ORDER_ID/} URL we discussed above. +@code{https://example.com/orders/$ORDER_ID} URL we discussed above. Note that the best way to obtain the @code{payment_redirect_url} is to check the status of the payment, even if you know that the user did not pay yet. There @@ -424,7 +420,7 @@ backend to do it is the safest method. @example >>> import requests >>> r = requests.get("https://backend.demo.taler.net/private/orders/" + order_id, -... headers=@{"Authorization": "ApiKey sandbox"@}) +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) >>> print(r.json()) @end example @@ -453,7 +449,7 @@ the merchant’s obligations under the contract. @cartouche @quotation Note You do not need to keep querying to notice changes -to the order's transaction status. The endpoints +to the order’s transaction status. The endpoints support long polling, simply specify a @code{timeout_ms} query parameter with how long you want to wait at most for the order status to change to @code{paid}. @@ -463,7 +459,7 @@ for the order status to change to @code{paid}. @geindex refunds @node Giving Refunds,Repurchase detection and fulfillment URLs,Merchant Payment Processing,Top -@anchor{taler-merchant-api-tutorial id2}@anchor{f} +@anchor{taler-merchant-api-tutorial id3}@anchor{f} @chapter Giving Refunds @@ -488,7 +484,7 @@ The refund request JSON object has only two fields: @code{refund}: Amount to be refunded. If a previous refund was authorized for the same order, the new amount must be higher, otherwise the operation has no effect. The value indicates the total amount to be -refunded, @emph{not} an increase in the refund. +refunded, `not' an increase in the refund. @item @code{reason}: Human-readable justification for the refund. The reason is @@ -508,14 +504,14 @@ This code snipped illustrates giving a refund: ... reason="Customer did not like the product") >>> requests.post("https://backend.demo.taler.net/private/orders/" ... + order_id + "/refund", json=refund_req, -... headers=@{"Authorization": "ApiKey sandbox"@}) +... headers=@{"Authorization": "Bearer secret-token:sandbox"@}) <Response [200]> @end example @cartouche @quotation Note After granting a refund, the public -@code{https://example.com/orders/$ORDER_ID/} endpoint will +@code{https://example.com/orders/$ORDER_ID} endpoint will change its wallet interaction from requesting payment to offering a refund. Thus, frontends may again redirect browsers to this endpoint. However, to do so, a @@ -529,7 +525,7 @@ under the @code{h_contract} field. @geindex repurchase -@node Repurchase detection and fulfillment URLs,Giving Customers Tips,Giving Refunds,Top +@node Repurchase detection and fulfillment URLs,Advanced topics,Giving Refunds,Top @anchor{taler-merchant-api-tutorial repurchase}@anchor{10}@anchor{taler-merchant-api-tutorial repurchase-detection-and-fulfillment-urls}@anchor{11} @chapter Repurchase detection and fulfillment URLs @@ -544,15 +540,15 @@ for the article again. If the customer then opens the @code{taler://} link in th wallet that did previously pay for the article (for example by scanning the QR code on the desktop with the Android App), the wallet will claim the contract, detect that the fulfillment URL is identical to one that it already has made a -payment for in the past, and initiate @strong{repurchase redirection}: Here, the +payment for in the past, and initiate `repurchase redirection': Here, the wallet will contact the merchant and replay the previous payment, except this time using the (current) session ID of the browser (it learns the session ID from the QR code). The merchant backend then updates the session ID of the existing order to the current session ID of the browser. When the payment status for the -"new" unpaid order is checked (or already in long-polling), the backend -detects that for the browser's @emph{session ID} and @emph{fulfillment URL} there is an +“new” unpaid order is checked (or already in long-polling), the backend +detects that for the browser’s `session ID' and `fulfillment URL' there is an existing paid contract. It then tells the browser to immediately redirect to the fulfillment URL where the already paid article is available. @@ -565,81 +561,13 @@ the same digital product where repurchase detection is desired. Note that changing the session ID to a different device requires the involvement of the wallet that made the payment, thus reasonably limiting the possibility of broadly sharing the digital purchases. Repurchase detection is -also @emph{only} done for HTTP(S) fulfillment URLs. In particular, this means +also `only' done for HTTP(S) fulfillment URLs. In particular, this means fulfillment URIs like @code{taler://fulfillment-success/$MESSAGE} are not considered to identify a resource you can pay for and thus do not have to be unique. -@anchor{taler-merchant-api-tutorial giving-customers-tips}@anchor{12} -@geindex tips - -@node Giving Customers Tips,Advanced topics,Repurchase detection and fulfillment URLs,Top -@anchor{taler-merchant-api-tutorial id4}@anchor{13} -@chapter Giving Customers Tips - -GNU Taler allows Web sites to grant small amounts directly to the -visitor. The idea is that some sites may want incentivize actions such -as filling out a survey or trying a new feature. It is important to note -that tips are not enforceable for the visitor, as there is no contract. -It is simply a voluntary gesture of appreciation of the site to its -visitor. However, once a tip has been granted, the visitor obtains full -control over the funds provided by the site. - -The “merchant” backend of the site must be properly configured for -tipping, and sufficient funds must be made available for tipping See -Taler Merchant Operating Manual. - -To check if tipping is configured properly and if there are sufficient -funds available for tipping, query the @code{/tip-query} endpoint: - -@example ->>> import requests ->>> requests.get("https://backend.demo.taler.net/tip-query?instance=default", -... headers=@{"Authorization": "ApiKey sandbox"@}) -<Response [200]> -@end example -@anchor{taler-merchant-api-tutorial authorize-tip}@anchor{14} -To authorize a tip, @code{POST} to @code{/tip-authorize}. The following fields -are recognized in the JSON request object: - - -@itemize - - -@item -@code{amount}: Amount that should be given to the visitor as a tip. - -@item -@code{instance}: Merchant instance that grants the tip (each instance may -have its own independent tipping funds configured). - -@item -@code{justification}: Description of why the tip was granted. Human-readable -text not exposed to the customer, but used by the Back Office. - -@item -@code{next_url}: The URL that the user’s browser should be redirected to by -the wallet, once the tip has been processed. -@end itemize - -The response from the backend contains a @code{tip_redirect_url}. The -customer’s browser must be redirected to this URL for the wallet to pick -up the tip. -@anchor{taler-merchant-api-tutorial pick-up-tip}@anchor{15} -This code snipped illustrates giving a tip: - -@example ->>> import requests ->>> tip_req = dict(amount="KUDOS:0.5", -... instance="default", -... justification="User filled out survey", -... next_url="https://merchant.com/thanks.html") ->>> requests.post("https://backend.demo.taler.net/tip-authorize", json=tip_req, -... headers=@{"Authorization": "ApiKey sandbox"@}) -<Response [200]> -@end example - -@node Advanced topics,Index,Giving Customers Tips,Top -@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{16}@anchor{taler-merchant-api-tutorial id6}@anchor{17} +@node Advanced topics,Index,Repurchase detection and fulfillment URLs,Top +@anchor{taler-merchant-api-tutorial advanced-topics}@anchor{12}@anchor{taler-merchant-api-tutorial id4}@anchor{13} @chapter Advanced topics @@ -651,7 +579,7 @@ This code snipped illustrates giving a tip: @end menu @node Session-Bound Payments,Product Identification,,Advanced topics -@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{18}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{19} +@anchor{taler-merchant-api-tutorial session-002dbound-payments}@anchor{14}@anchor{taler-merchant-api-tutorial session-bound-payments}@anchor{15} @section Session-Bound Payments @@ -688,7 +616,7 @@ receipt is in the user’s wallet is also available as @code{last_session_id} in the response to @code{/check-payment}. @node Product Identification,The Taler Order Format,Session-Bound Payments,Advanced topics -@anchor{taler-merchant-api-tutorial id8}@anchor{1a}@anchor{taler-merchant-api-tutorial product-identification}@anchor{1b} +@anchor{taler-merchant-api-tutorial id5}@anchor{16}@anchor{taler-merchant-api-tutorial product-identification}@anchor{17} @section Product Identification @@ -709,7 +637,7 @@ contract with the same @code{resource_url} before, and if so replay the previous payment. @node The Taler Order Format,,Product Identification,Advanced topics -@anchor{taler-merchant-api-tutorial id9}@anchor{1c}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{1d} +@anchor{taler-merchant-api-tutorial id6}@anchor{18}@anchor{taler-merchant-api-tutorial the-taler-order-format}@anchor{19} @section The Taler Order Format @@ -1020,8 +948,8 @@ render fields that they do not understand as a key-value list. @printindex ge -@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ } @anchor{c}@w{ } +@anchor{taler-merchant-api-tutorial The-Taler-Order-Format}@w{ } @c %**end of body @bye diff --git a/texinfo/taler-merchant-figures/arch-api.png b/texinfo/taler-merchant-figures/arch-api.png Binary files differindex 8004f790..9e593ab4 100644 --- a/texinfo/taler-merchant-figures/arch-api.png +++ b/texinfo/taler-merchant-figures/arch-api.png diff --git a/texinfo/taler-merchant-figures/create_orders.png b/texinfo/taler-merchant-figures/create_orders.png Binary files differnew file mode 100644 index 00000000..74814c72 --- /dev/null +++ b/texinfo/taler-merchant-figures/create_orders.png diff --git a/texinfo/taler-merchant-figures/enter_instance_details.png b/texinfo/taler-merchant-figures/enter_instance_details.png Binary files differnew file mode 100644 index 00000000..f2177091 --- /dev/null +++ b/texinfo/taler-merchant-figures/enter_instance_details.png diff --git a/texinfo/taler-merchant-figures/exchange-db.png b/texinfo/taler-merchant-figures/exchange-db.png Binary files differindex f99e2664..7a4050c6 100644 --- a/texinfo/taler-merchant-figures/exchange-db.png +++ b/texinfo/taler-merchant-figures/exchange-db.png diff --git a/texinfo/taler-merchant-figures/instance_iban_config.png b/texinfo/taler-merchant-figures/instance_iban_config.png Binary files differnew file mode 100644 index 00000000..03fa8f36 --- /dev/null +++ b/texinfo/taler-merchant-figures/instance_iban_config.png diff --git a/texinfo/taler-merchant-figures/merchant-db.png b/texinfo/taler-merchant-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-merchant-figures/merchant-db.png +++ b/texinfo/taler-merchant-figures/merchant-db.png diff --git a/texinfo/taler-merchant-figures/merchant_first_login.png b/texinfo/taler-merchant-figures/merchant_first_login.png Binary files differnew file mode 100644 index 00000000..0baa0801 --- /dev/null +++ b/texinfo/taler-merchant-figures/merchant_first_login.png diff --git a/texinfo/taler-merchant-figures/no_default_account_yet.png b/texinfo/taler-merchant-figures/no_default_account_yet.png Binary files differnew file mode 100644 index 00000000..c97c231d --- /dev/null +++ b/texinfo/taler-merchant-figures/no_default_account_yet.png diff --git a/texinfo/taler-merchant-figures/payment_links.png b/texinfo/taler-merchant-figures/payment_links.png Binary files differnew file mode 100644 index 00000000..0c58b286 --- /dev/null +++ b/texinfo/taler-merchant-figures/payment_links.png diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi index 4cc52001..8e7582b9 100644 --- a/texinfo/taler-merchant.texi +++ b/texinfo/taler-merchant.texi @@ -3,29 +3,27 @@ @setfilename taler-merchant.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 3.4.3.@* +@*Generated by Sphinx 5.3.0.@* @end ifinfo @settitle Taler Merchant Manual @defindex ge @paragraphindent 0 @exampleindent 4 @finalout -@dircategory CATEGORY +@dircategory Network applications @direntry -* MENU ENTRY: (taler-merchant.info). DESCRIPTION +* GNU Taler Merchant: (taler-merchant.info). Backend for merchants accepting Taler payments @end direntry -@definfoenclose strong,`,' -@definfoenclose emph,`,' @c %**end of header @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.9.4, Apr 12, 2024 GNU Taler team -Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -48,18 +46,35 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @c %**start of body @anchor{taler-merchant-manual doc}@anchor{0} +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff + @menu * Introduction:: * Terminology:: * Installation:: -* How to configure the merchant’s backend:: +* How to configure the merchant backend:: * Instance setup:: +* Instance account setup:: +* Manually creating an order using the SPA:: * Secure setup:: * Customization:: * Upgrade procedure:: -* Tipping visitors:: * Advanced topics:: -* Advanced experimental features:: * Temporarily Abandoned Features:: * Index:: @@ -75,31 +90,24 @@ Introduction Terminology * Instances:: -* Accounts:: +* Instance Bank Accounts:: * Inventory:: * Orders and Contracts:: +* Templates:: +* OTP Devices:: * Transfers:: -* Tipping:: -* Reserves:: +* Webhooks:: Installation -* Generic instructions for installation from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: * Installing the GNU Taler binary packages on Ubuntu:: -* Installing Taler on Debian GNU/Linux from source:: - -Generic instructions for installation from source - -* Installation of dependencies:: -* Installing GNUnet:: -* Installing the GNU Taler exchange:: -* Installing the GNU Taler merchant backend:: +* Installing from source:: -How to configure the merchant’s backend +How to configure the merchant backend * Configuration format:: -* Using taler-config:: * Backend options:: * Sample backend configuration:: * Launching the backend:: @@ -110,57 +118,68 @@ Backend options * Currency:: * Database:: * Exchange:: -* Auditor:: Instance setup -* KUDOS Accounts:: -* IBAN Accounts:: -* Setup:: +* Instance setup with the SPA:: +* Instance setup without the Web interface:: + +Instance account setup + +* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. +* Automatic Settlement Data Import:: Secure setup * Using UNIX domain sockets:: * Reverse proxy configuration:: * Access control:: +* Status code remapping:: Reverse proxy configuration * Nginx:: * Apache:: -Access control +Status code remapping * Nginx: Nginx<2>. * Apache: Apache<2>. Customization -* Templates:: +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Template Customization:: * Static files:: * Internationalization:: * Limitations:: -Tipping visitors +Legal policies directory layout -* Fund the reserve:: -* Authorize a tip:: -* Picking up of the tip:: +* Example:: -Advanced topics +Template Customization -* Database Scheme:: -* Configuration format: Configuration format<2>. +* request_payment:: +* offer_refund:: +* show_order_details:: -Configuration format +Advanced topics -* Using taler-config: Using taler-config<2>. +* taler-config:: +* Using taler-config:: +* Database Scheme:: +* Benchmarking:: -Advanced experimental features +Benchmarking -* Benchmarking:: -* Benchmark setup:: -* Running the benchmark command:: +* Running taler-merchant-benchmark:: Temporarily Abandoned Features @@ -170,7 +189,7 @@ Temporarily Abandoned Features @end menu @node Introduction,Terminology,Top,Top -@anchor{taler-merchant-manual ffoobar}@anchor{1}@anchor{taler-merchant-manual gnu-taler-merchant-backend-operator-manual}@anchor{2}@anchor{taler-merchant-manual introduction}@anchor{3} +@anchor{taler-merchant-manual introduction}@anchor{1}@anchor{taler-merchant-manual merchant-backend-operator-manual}@anchor{2}@anchor{taler-merchant-manual taler-merchant-backend-operator-manual}@anchor{3} @chapter Introduction @@ -186,6 +205,21 @@ Temporarily Abandoned Features @section About GNU Taler +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + GNU Taler is an open protocol for an electronic payment system with a free software reference implementation. GNU Taler offers secure, fast and easy payment processing using well understood cryptographic @@ -195,35 +229,18 @@ GNU Taler is compatible with anti-money-laundering (AML) and know-your-customer (KYC) regulation, as well as data protection regulation (such as GDPR). -GNU Taler is not yet production-ready: after following this manual you -will have a backend that can process payments in “KUDOS”, but not -regular currencies. This is not so much because of limitations in the -backend, but because we are not aware of a Taler exchange operator -offering regular currencies today. - @node About this manual,Architecture overview,About GNU Taler,Introduction @anchor{taler-merchant-manual about-this-manual}@anchor{5}@anchor{taler-merchant-manual id1}@anchor{6} @section About this manual This manual targets system administrators who want to install a GNU -Taler merchant @emph{backend}. +Taler merchant `backend'. We expect some moderate familiarity with the compilation and installation of Free Software packages. An understanding of cryptography is not required. -This first chapter of the manual will give a brief overview of the -overall Taler architecture, describing the environment in which the -Taler backend operates. The second chapter then explains how to install -the software, including key dependencies. The third chapter will explain -how to configure the backend, including in particular the configuration -of the bank account details of the merchant. - -The last chapter gives some additional information about advanced topics -which will be useful for system administrators but are not necessary for -operating a basic backend. - @node Architecture overview,,About this manual,Introduction @anchor{taler-merchant-manual architecture-overview}@anchor{7}@anchor{taler-merchant-manual id2}@anchor{8} @section Architecture overview @@ -234,11 +251,11 @@ operating a basic backend. @geindex KUDOS Taler is a pure payment system, not a new crypto-currency. As such, it -operates in a traditional banking context. In particular, this means -that in order to receive funds via Taler, the merchant must have a -regular bank account, and payments can be executed in ordinary -currencies such as USD or EUR. For testing purposes, Taler uses a -special currency “KUDOS” and includes its own special bank. +operates in a traditional banking context. In particular, this means that in +order to receive funds via Taler, the merchant must have a regular bank +account, and payments can be executed in ordinary currencies such as USD or +EUR. Taler can also be used as a regional currency; for such scenarios, the +Taler system also includes its own stand-alone bank. @geindex frontend @@ -248,16 +265,15 @@ special currency “KUDOS” and includes its own special bank. @geindex DBMS -@geindex Postgres +@geindex PostgreSQL -The Taler software stack for a merchant consists of four main -components: +The Taler software stack for a merchant consists of four main components: @itemize - @item -A @emph{frontend} which interacts with the customer’s browser. The frontend +A `frontend' which interacts with the customer’s browser. The frontend enables the customer to build a shopping cart and place an order. Upon payment, it triggers the respective business logic to satisfy the order. This component is not included with Taler, but rather @@ -266,7 +282,7 @@ The Merchant API Tutorial gives an introduction for how to integrate Taler with Web shop frontends. @item -A @emph{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 @@ -275,15 +291,15 @@ the API specification that should be reviewed to integrate such a back-office with the Taler backend. @item -A Taler-specific payment @emph{backend} which makes it easy for the frontend +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. @item -A @emph{DBMS} which stores the transaction history for the Taler backend. +A `DBMS' which stores the transaction history for the Taler backend. For now, the GNU Taler reference implementation only supports -Postgres, but the code could be easily extended to support another -DBMS. Please review the Postgres documentation for details on +PostgreSQL, but the code could be easily extended to support another +DBMS. Please review the PostgreSQL documentation for details on how to configure the database. @end itemize @@ -300,13 +316,12 @@ 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 are encapsulated within -the Taler backend. +the Taler merchant backend. A typical deployment will additionally include a full-blown Web server (like -Apache or Nginx). Such a Web server would be responsible for TLS termination -and access control to the @code{/private/} API endpoints of the merchant backend. -Please carefully review the section on @ref{9,,Secure setup} before -deploying a Taler merchant backend to production. +Apache or Nginx). Such a Web server would be responsible for TLS termination and +access control to the @code{/private/} and @code{/management/} API endpoints of the +merchant backend. Please carefully review the section on @ref{9,,secure setup} before deploying a Taler merchant backend into production. @node Terminology,Installation,Introduction,Top @anchor{taler-merchant-manual terminology}@anchor{a} @@ -317,42 +332,68 @@ This chapter describes some of the key concepts used throughout the manual. @menu * Instances:: -* Accounts:: +* Instance Bank Accounts:: * Inventory:: * Orders and Contracts:: +* Templates:: +* OTP Devices:: * Transfers:: -* Tipping:: -* Reserves:: +* Webhooks:: @end menu -@node Instances,Accounts,,Terminology +@node Instances,Instance Bank Accounts,,Terminology @anchor{taler-merchant-manual instances}@anchor{b} @section Instances @geindex instance -The backend allows the user to run multiple @emph{instances} of shops with distinct -business entities sharing a single backend. Each instance uses its own bank -accounts and key for signing contracts. All major accounting functionality is -separate per instance. What is shared is the database, HTTP(S) address and -the main Taler configuration (accepted currency, exchanges and auditors). +The backend allows a single HTTP server to support multiple independent shops +with distinct business entities sharing a single backend. An `instance' is +the name or identifier that allows the single HTTP server to determine which +shop a request is intended for. Each instance has its own base URL in the +REST API of the merchant backend (@code{/instances/$INSTANCE/}). Each instance +can use its own bank accounts and keys for signing contracts. All major +accounting functionality is separate per instance. Access to each instance is +controlled via a bearer token (to be set in the HTTP “Authorization” header). +All instances share the same `database', top-level HTTP(S) address and the +main Taler configuration (especially the accepted `currency' and `exchanges'). -@node Accounts,Inventory,Instances,Terminology -@anchor{taler-merchant-manual accounts}@anchor{c} -@section Accounts +@quotation +@cartouche +@quotation Note +This documentation does not use the term “user” or “username” in +conjunction with instances as that might create confusion between +instances with paying customers using the system. We also do not use the +term “account” in conjunction with instances, as that might cause +confusion with bank accounts. That said, conceptually it is of course +acceptable to consider instances to be the “users” or “accounts” of a +merchant backend and the bearer token is equivalent to a passphrase. +@end quotation +@end cartouche +@end quotation -@geindex account +@node Instance Bank Accounts,Inventory,Instances,Terminology +@anchor{taler-merchant-manual instance-bank-account}@anchor{c}@anchor{taler-merchant-manual instance-bank-accounts}@anchor{d} +@section Instance Bank Accounts + + +@geindex Bank account To receive payments, an instance must have configured one or more bank -@emph{accounts}. The backend does not have accounts for users, and instances are -also not really ‘accounts’. So whenever we use the term @emph{account}, it is about -a bank account of a merchant. +`accounts'. When configuring the bank account of an instance, one should +ideally also provide the address and credentials of an HTTP service +implementing the Taler Bank Revenue HTTP API. Given such a service, the GNU Taler merchant +backend can automatically reconcile wire transfers from the exchange to the +merchant’s bank account with the orders that are being settled. + +This documentation exclusively uses the term `account' for the bank +accounts of a merchant or shop that may be associated with an instance. -@node Inventory,Orders and Contracts,Accounts,Terminology -@anchor{taler-merchant-manual inventory}@anchor{d} +@node Inventory,Orders and Contracts,Instance Bank Accounts,Terminology +@anchor{taler-merchant-manual inventory}@anchor{e} @section Inventory @@ -367,25 +408,30 @@ a bank account of a merchant. @geindex order The Taler backend offers inventory management as an optional function. -Inventory is tracked per instance and consists of @emph{products} sold in -@emph{units}. Inventory can be finite or infinite (for digital products). -Products may include previews (images) to be shown to the user and other -meta-data. Inventory management allows the frontend to @emph{lock} products, -reserving them for a particular (unpaid) @emph{order}. The backend can keep -track of how many units of a product remain in stock and ensure that -the number of units sold does not exceed the number of units in stock. +Inventory is tracked per instance and consists of `products' sold in +`units'. Inventory can be finite (physical stock) or infinite (for digital +products). Products may include previews (images) to be shown to the user as +well as other meta-data. Inventory management allows the frontend to `lock' +products, reserving a number of units from stock for a particular (unpaid) +`order'. The backend can keep track of how many units of a product remain in +stock and ensure that the number of units sold does not exceed the number of +units in stock. Inventory management is optional, and it is possible for the frontend to -include products in orders that are not in the inventory, or to override -prices of products in the inventory. +include products in orders that are not in the inventory. The frontend +can also override prices of products in the inventory or set a total price +for an order that is different from the price of the sum of the products +in the order. -@node Orders and Contracts,Transfers,Inventory,Terminology -@anchor{taler-merchant-manual orders-and-contracts}@anchor{e} +@node Orders and Contracts,Templates,Inventory,Terminology +@anchor{taler-merchant-manual orders-and-contracts}@anchor{f} @section Orders and Contracts @geindex order +@geindex terms + @geindex contract @geindex claim @@ -400,10 +446,14 @@ prices of products in the inventory. @geindex legal expiration -In Taler, users pay merchants for orders. An order is first created by the -merchant, where the merchant specifies the specific terms of the order. +In Taler, users pay merchants for `orders'. An order is first created by the +merchant. To create an order, the merchant must specify the specific `terms' +of the order. Order `terms' include details such as the total amount to be +paid, payment fees the merchant is willing to cover, the set of products to +deliver, a delivery location and many other details. The merchant API specification@footnote{contract-terms} specifies the full set of possible order +terms. -After an order is created, it is @emph{claimed} by a wallet. Once an order is +After an order is created, it is `claimed' by a wallet. Once an order is claimed by a specific wallet, only that wallet will be able to pay for this order, to the exclusion of other wallets even if they see the same order URL. Sharing order URLs is explicitly allowed: if a user shares an order URL @@ -411,33 +461,96 @@ with another user, that other user should be given the opportunity to purchase the same product. To prevent unauthorized wallets from claiming an order, merchants can specify -that claims require authorization in the form of a @emph{claim token}. This is +that claims require authorization in the form of a `claim token'. This is useful in case the order ID is predictable (say because an existing order ID -scheme from the merchant frontend is used) and at the same time malicious -actors claiming orders is problematic (say because of limited stocks). The use -of claim tokens is optional, but if a claim token is used, it must be provided -to the wallet as part of the order URI. - -A wallet may @emph{pay} for a claimed order, at which point the order turns into -a (paid) contract. Orders have an expiration date after which the commercial -offer expires and any stock of products @emph{locked} by the order is released, -allowing the stock to be sold in other orders. +scheme with predictable order IDs from the merchant frontend is used) and at +the same time malicious actors claiming orders is problematic (say because of +limited stocks). The use of claim tokens is optional, but if a claim token is +used, it must be provided to the wallet as part of the order URI. + +Additionally, when stocks are limited, you can configure Taler to set a +`product lock' on items (say, while composing the shopping cart). These +locks will ensure that the limited stock is respected when making offers +to consumers. + +A wallet may `pay' for a claimed order, at which point the order turns into a +(paid) `contract'. Orders have a configurable expiration date (the +@code{pay_deadline}) after which the commercial offer expires and any stock of +products `locked' by the order will be automatically released, allowing the +stock to be sold in other orders. When an unpaid order expires, the customer +must request a fresh order if they still want to make a purchase. Once a contract has been paid, the merchant should fulfill the contract. It -is possible for the merchant to @emph{refund} a contract order, for example if the +is possible for the merchant to `refund' a contract order, for example if the contract cannot be fulfilled after all. Refunds are only possible after the -customer paid and before the exchange has @emph{wired} the payment to the +customer paid and before the exchange has `wired' the payment to the merchant. Once the funds have been wired, refunds are no longer allowed by the -Taler exchange. The @emph{wire deadline} specifies the latest time by which an -exchange must wire the funds, while the (earlier) @emph{refund deadline} specifies -the earliest time when an exchange may wire the funds. +Taler exchange. The `wire deadline' specifies the latest point in time by +which an exchange must wire the funds, while the (earlier) `refund deadline' +specifies the earliest point in time when an exchange may wire the funds. +Thus, refunds are always possible between the time of purchase and the +refund deadline, but may remain possible until the wire deadline. + +Contract information is kept for legal reasons in the merchant database. The +main legal reason is typically to provide tax records in case of a tax audit. +After the `legal expiration' (by default: a decade), contract information is +deleted when running the garbage collector using @code{taler-merchant-dbinit}. + +@node Templates,OTP Devices,Orders and Contracts,Terminology +@anchor{taler-merchant-manual template}@anchor{10}@anchor{taler-merchant-manual templates}@anchor{11} +@section Templates -Contract information is kept for legal reasons, typically to provide tax -records in case of a tax audit. After the @emph{legal expiration} (by default a -decade), contract information is deleted. -@node Transfers,Tipping,Orders and Contracts,Terminology -@anchor{taler-merchant-manual transfers}@anchor{f} +@geindex Template + +Usually, a merchant must use an authenticated endpoint to create an order and +then share the link to the order with a wallet. Templates are a mechanism that +allows wallets to create their own orders directly, using a public endpoint. +The template fixes some properties of the contracts created from it, while +other details may be left for the customer to provide. Templates are useful +in cases where the point-of-sale of a merchant is offline (and thus cannot +setup an order), or even in cases where a simple static QR code is desired to +accept payments or donations. + +When generating a template, the “summary” text of the contract and the +“amount” to be paid by the customer can be fixed or left for the customer to +specify. If the customer is expected to provide either or both of these +values, the template link (or QR code) can specify a default value. For +example, a cafeteria with a fixed price lunch may use a “lunch” template with +both values fixed to the lunch price and the “lunch” product, a bakery might +fix the summary to “baked goods” but allow the customer to enter the amount +based on the total price of the items being bought, and a charity may allow +donating an arbitrary amount and summary message while also suggesting default +values. + +If an offline merchant wants to confirm that a customer did actually pay the +agreed amount using an order derived from a template, they can associate an +OTP device with the template. + +@node OTP Devices,Transfers,Templates,Terminology +@anchor{taler-merchant-manual otp-device}@anchor{12}@anchor{taler-merchant-manual otp-devices}@anchor{13} +@section OTP Devices + + +@geindex OTP + +@geindex TOTP + +A One-Time-Password (OTP) generator is a device or application that generates +a 4 to 8 digit code typically used for authentication. The widely used TOTP +standard is described in RFC 6238@footnote{https://www.rfc-editor.org/rfc/rfc6238}. +For GNU Taler merchant backends, OTP devices are used as a way to assure a +merchant without network connectivity that a customer made a digital +payment. The idea is described in depth in our SUERF Policy Brief@footnote{https://www.suerf.org/suer-policy-brief/69851/practical-offline-payments-using-one-time-passcodes}. +To use this method, a merchant must configure the OTP device’s shared secret +in the merchant backend, and then associate the OTP device with a +@ref{10,,Templates}. Once the customer has paid, they are given a list of OTP +codes which must be shown to the merchant who can check that at least one of +the codes matches their OTP device, proving that the customer made the +payment. + +@node Transfers,Webhooks,OTP Devices,Terminology +@anchor{taler-merchant-manual transfers}@anchor{14} @section Transfers @@ -446,98 +559,208 @@ decade), contract information is deleted. @geindex wire transfer The Taler backend can be used to verify that the exchange correctly wired all -of the funds to the merchant. However, the backend does not have access to the -incoming wire transfers of the merchant’s bank account. Thus, merchants must -manually provide the backend with wire @emph{transfer} data that specifies the wire -transfer subject and the amount that was received. Given this information, the -backend can detect and report any irregularities that might arise. +of the funds to the merchant. However, if no Taler Bank Revenue HTTP API was provided for the respective bank account, +the backend does not have access to the incoming wire transfers of the +merchant’s bank account. In this case, merchants should manually provide the +backend with wire `transfer' data that specifies the `wire transfer subject' +and the amount that was received. Given this information, the backend can +detect and report any irregularities that might arise. + +@node Webhooks,,Transfers,Terminology +@anchor{taler-merchant-manual webhooks}@anchor{15} +@section Webhooks + + +@geindex webhook + +A webhook is a pre-defined HTTP request that the GNU Taler merchant backend +will make upon certain events, such as an order being paid or refunded. When +the configured event happens, the merchant backend will make an HTTP request +to the endpoint configured in the webhook configuration, possibly sending +selected data about the event to the respective Web service. Webhooks can be +used to trigger additional business logic outside of the GNU Taler merchant +backend. + +@node Installation,How to configure the merchant backend,Terminology,Top +@anchor{taler-merchant-manual installation}@anchor{16} +@chapter Installation -@node Tipping,Reserves,Transfers,Terminology -@anchor{taler-merchant-manual tipping}@anchor{10} -@section Tipping +This chapter describes how to install the GNU Taler merchant backend. -@geindex tip +@menu +* Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Installing from source:: -@geindex grant +@end menu -@geindex pick up +@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,,Installation +@anchor{taler-merchant-manual generic-instructions}@anchor{17}@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{18} +@section Installing the GNU Taler binary packages on Debian -Taler does not only allow a Website to be paid, but also to make voluntary, -non-contractual payments to visitors, called @emph{tips}. Such tips could be -granted as a reward for filling in surveys or watching advertisements. For -tips, there is no contract, tips are always voluntary actions by the Web -site that do not arise from a contractual obligation. Before a Web site -can create tips, it must establish a reserve. Once a reserve has been -established, the merchant can @emph{grant} tips, allowing wallets to @emph{pick up} -the tip. -@node Reserves,,Tipping,Terminology -@anchor{taler-merchant-manual reserves}@anchor{11} -@section Reserves +To install the GNU Taler Debian packages, first ensure that you have +the right Debian distribution. At this time, the packages are built for +Debian bookworm. +You need to add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: -@geindex reserve +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main +@end example -@geindex close +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: -A @emph{reserve} is a pool of electronic cash at an exchange under the control of -a private key. Merchants withdraw coins from a reserve when granting -tips. A reserve is established by first generating the required key material -in the merchant backend, and then wiring the desired amount of funds to the -exchange. +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example -An exchange will automatically @emph{close} a reserve after a fixed period of time -(typically about a month), wiring any remaining funds back to the merchant. +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA key out-of-band. +@end quotation +@end cartouche -@node Installation,How to configure the merchant’s backend,Terminology,Top -@anchor{taler-merchant-manual installation}@anchor{12} -@chapter Installation +Now your system is ready to install the official GNU Taler binary packages +using apt. +To install the Taler merchant backend, you can now simply run: -This chapter describes how to install the GNU Taler merchant backend. +@example +# apt install taler-merchant +@end example -@menu -* Generic instructions for installation from source:: -* Installing the GNU Taler binary packages on Debian:: -* Installing the GNU Taler binary packages on Ubuntu:: -* Installing Taler on Debian GNU/Linux from source:: +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 +@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must +furthermore still configure the database and the instances, and may need to +extend the fragment with access control restrictions for non-default +instances. -@end menu +@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the GNU Taler binary packages on Debian,Installation +@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{19} +@section Installing the GNU Taler binary packages on Trisquel -@node Generic instructions for installation from source,Installing the GNU Taler binary packages on Debian,,Installation -@anchor{taler-merchant-manual generic-instructions}@anchor{13}@anchor{taler-merchant-manual generic-instructions-for-installation-from-source}@anchor{14} -@section Generic instructions for installation from source +To install the GNU Taler Trisquel packages, first ensure that you have +the right Trisquel distribution. Packages are currently available for +Trisquel GNU/Linux 10.0. Simply follow the same instructions provided +for Ubuntu. -This section provides generic instructions for the merchant backend -installation independent of any particular operating system. Operating -system specific instructions are provided in the following sections. You -should follow the operating system specific instructions if those are -available, and only consult the generic instructions if no -system-specific instructions are provided for your specific operating -system. +@node Installing the GNU Taler binary packages on Ubuntu,Installing from source,Installing the GNU Taler binary packages on Trisquel,Installation +@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{1a} +@section Installing the GNU Taler binary packages on Ubuntu -@menu -* Installation of dependencies:: -* Installing GNUnet:: -* Installing the GNU Taler exchange:: -* Installing the GNU Taler merchant backend:: -@end menu +To install the GNU Taler Ubuntu packages, first ensure that you have +the right Ubuntu distribution. At this time, the packages are built for +Ubuntu Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. + +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example + +For Ubuntu Mantic use this instead: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic +@end example + +The last line is crucial, as it adds the GNU Taler packages. -@node Installation of dependencies,Installing GNUnet,,Generic instructions for installation from source -@anchor{taler-merchant-manual id3}@anchor{15}@anchor{taler-merchant-manual installation-of-dependencies}@anchor{16} -@subsection Installation of dependencies +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems key out-of-band. +@end quotation +@end cartouche -The following packages need to be installed before we can compile the +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler merchant backend, you can now simply run: + +@example +# apt install taler-merchant +@end example + +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 +@code{/etc/@{apache,nginx@}/conf-available/taler-merchant.conf}. You must +furthermore still configure the database and the instances, and may need to +extend the fragment with access control restrictions for non-default +instances. + +@node Installing from source,,Installing the GNU Taler binary packages on Ubuntu,Installation +@anchor{taler-merchant-manual installing-from-source}@anchor{1b} +@section Installing from source + + +The following instructions will show how to install a GNU Taler +merchant backend from source. + +The package sources can be find in our +download directory@footnote{http://ftpmirror.gnu.org/taler/}. + +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff + +GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format. +The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match. +Exceptions to this general rule are documented in the release notes. +For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x +as the MAJOR version matches. A MAJOR version of 0 indicates experimental +development, and you are expected to always run all of the `latest' releases +together (no compatibility guarantees). + +First, the following packages need to be installed before we can compile the backend: @itemize - @item +“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme} +on Debian-based systems (for GNUnet documentation support, can be +omitted if GNUnet is configured with @code{--disable-documentation}) + +@item libsqlite3 >= 3.16.2 @item @@ -547,10 +770,10 @@ GNU libunistring >= 0.9.3 libcurl >= 7.26 (or libgnurl >= 7.26) @item -libqrencode >= 4.0.0 +libqrencode >= 4.0.0 (Taler merchant only) @item -GNU libgcrypt >= 1.6 +GNU libgcrypt >= 1.6 (1.10 or later highly recommended) @item libsodium >= 1.0 @@ -562,46 +785,48 @@ libargon2 >= 20171227 libjansson >= 2.7 @item -Postgres >= 9.6, including libpq +PostgreSQL >= 15, including libpq @item GNU libmicrohttpd >= 0.9.71 @item -GNUnet >= 0.14.0 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) +GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) @item -GNU Taler exchange (see release announcement@footnote{https://mail.gnu.org/archive/cgi-bin/namazu.cgi?query=taler&idxname=info-gnu&max=20&result=normal&sort=date:late}) +Python3 with @code{jinja2} @end itemize -Except for the last two, these are available in most GNU/Linux distributions -and should just be installed using the respective package manager. Be careful -with GNU libmicrohttpd; here, some distributions only include an older version -that will not work. - -While you are in the GNU Taler exchange -download directory@footnote{http://ftpmirror.gnu.org/taler/}, -you might as well also download the tarball for GNU Taler merchant. - -GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format. -The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match. -Exceptions to this general rule are documented in the release notes. -For example, Taler merchant 0.8.0 is compatible with Taler exchange 0.8.1. - -The following sections will provide detailed instructions for installing -the @code{libgnunetutil} and GNU Taler exchange dependencies. - -@node Installing GNUnet,Installing the GNU Taler exchange,Installation of dependencies,Generic instructions for installation from source -@anchor{taler-merchant-manual installing-gnunet}@anchor{17}@anchor{taler-merchant-manual installing-libgnunetutil}@anchor{18} -@subsection Installing GNUnet - +If you are on Debian stable or later, the following command may help you +install these dependencies: -@geindex GNUnet +@example +# apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 +@end example Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. +On Ubuntu, you also need to install pkg-config, for example: + +@example +$ apt-get install pkg-config +@end example + To install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows: @@ -620,17 +845,17 @@ The @code{ldconfig} command (also run as @code{root}) makes the shared object libraries (@code{.so} files) visible to the various installed programs. +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + There is no need to actually run a GNUnet peer to use the Taler merchant backend – all the merchant needs from GNUnet is a number of headers and libraries! -@node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source -@anchor{taler-merchant-manual id4}@anchor{19}@anchor{taler-merchant-manual installing-the-gnu-taler-exchange}@anchor{1a} -@subsection Installing the GNU Taler exchange - - -@geindex exchange - After installing GNUnet, unpack the GNU Taler exchange tarball, change into the resulting directory, and proceed as follows: @@ -652,21 +877,12 @@ There is no need to actually run a Taler exchange to use the Taler merchant backend – all the merchant needs from the Taler exchange is a few headers and libraries! -@node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source -@anchor{taler-merchant-manual id5}@anchor{1b}@anchor{taler-merchant-manual installing-the-gnu-taler-merchant-backend}@anchor{1c} -@subsection Installing the GNU Taler merchant backend - - -@geindex backend - -GNU Taler merchant has these additional dependencies: +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. - -@itemize - - -@item -libqrencode >= 4.0.0 -@end itemize +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. The following steps assume all dependencies are installed. @@ -699,247 +915,57 @@ run @code{ldconfig}. Without this step, it is possible that the linker may not find the installed libraries and launching the Taler merchant backend would then fail. -@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Ubuntu,Generic instructions for installation from source,Installation -@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{1d} -@section Installing the GNU Taler binary packages on Debian - - -To install the GNU Taler Debian packages, first ensure that you have -the right Debian distribution. At this time, the packages are built for -Sid, which means you should use a system which at least includes -unstable packages in its source list. We recommend using APT pinning -to limit unstable packages to those explicitly requested. To do this, -set your @code{/etc/apt/preferences} as follows: - -@example -Package: * -Pin: release a=stable -Pin-Priority: 700 - -Package: * -Pin: release a=testing -Pin-Priority: 650 - -Package: * -Pin: release a=unstable -Pin-Priority: 600 - -Package: * -Pin: release l=Debian-Security -Pin-Priority: 1000 -@end example - -A typical @code{/etc/apt/sources.list} file for this setup -would look like this: - -@example -deb http://ftp.ch.debian.org/debian/ buster main -deb http://security.debian.org/debian-security buster/updates main -deb http://ftp.ch.debian.org/debian/ testing main -deb http://ftp.ch.debian.org/debian/ unstable main -deb https://deb.taler.net/apt/debian sid main -@end example - -The last line is crucial, as it adds the GNU Taler packages. - -Next, you must import the Taler Systems SA public package signing key -into your keyring and update the package lists: - -@example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - -# apt update -@end example - -@cartouche -@quotation Note -You may want to verify the correctness of the Taler Systems key out-of-band. -@end quotation -@end cartouche +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. -Now your system is ready to install the official GNU Taler binary packages -using apt. +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. -To install the Taler merchant backend, you can now simply run: +@node How to configure the merchant backend,Instance setup,Installation,Top +@anchor{taler-merchant-manual how-to-configure-the-merchant-backend}@anchor{1c} +@chapter How to configure the merchant backend -@example -# apt install taler-merchant -@end example - -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 -@code{/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. - -@node Installing the GNU Taler binary packages on Ubuntu,Installing Taler on Debian GNU/Linux from source,Installing the GNU Taler binary packages on Debian,Installation -@anchor{taler-merchant-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{1e} -@section Installing the GNU Taler binary packages on Ubuntu - - -To install the GNU Taler Ubuntu packages, first ensure that you have -the right Ubuntu distribution. At this time, the packages are built for -Ubuntu 20.04 LTS (Focal Fossa). - -A typical @code{/etc/apt/sources.list} file for this setup -would look like this: - -@example -deb http://ch.archive.ubuntu.com/ubuntu/ focal main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security multiverse restricted - -deb https://deb.taler.net/apt/ubuntu/ focal-fossa main -@end example - -The last line is crucial, as it adds the GNU Taler packages. - -Next, you must import the Taler Systems SA public package signing key -into your keyring and update the package lists: - -@example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-sign add - -# apt update -@end example - -@cartouche -@quotation Note -You may want to verify the correctness of the Taler Systems key out-of-band. -@end quotation -@end cartouche - -Now your system is ready to install the official GNU Taler binary packages -using apt. - -To install the Taler merchant backend, you can now simply run: - -@example -# apt install taler-merchant -@end example - -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 -@code{/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. - -@node Installing Taler on Debian GNU/Linux from source,,Installing the GNU Taler binary packages on Ubuntu,Installation -@anchor{taler-merchant-manual installing-taler-on-debian-gnu-002flinux}@anchor{1f}@anchor{taler-merchant-manual installing-taler-on-debian-gnu-linux-from-source}@anchor{20} -@section Installing Taler on Debian GNU/Linux from source - - -@geindex Wheezy - -@geindex Jessie - -@geindex Stretch - -@geindex Debian - -Debian wheezy is too old and lacks most of the packages required. -Debian jessie is better, but still lacks PostgreSQL 9.6. - -On Debian stretch, only GNU libmicrohttpd needs to be compiled from -source. To install dependencies on Debian stretch, run the following -commands: - -@example -# apt-get install \ - libqrencode-dev \ - libsqlite3-dev \ - libltdl-dev \ - libunistring-dev \ - libsodium-dev \ - libargon2-0-dev \ - libcurl4-gnutls-dev \ - libgcrypt20-dev \ - libjansson-dev \ - libpq-dev \ - postgresql-9.6 -# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz -# wget https://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-latest.tar.gz.sig -# gpg -v libmicrohttpd-latest.tar.gz # Should show signed by 939E6BE1E29FC3CC -# tar xf libmicrohttpd-latest.tar.gz -# cd libmicrohttpd-0* -# ./configure -# make install -@end example - -For more recent versions of Debian, you should instead run: - -@example -# apt-get install \ - libqrencode-dev \ - libsqlite3-dev \ - libltdl-dev \ - libunistring-dev \ - libsodium-dev \ - libargon2-dev \ - libcurl4-gnutls-dev \ - libgcrypt20-dev \ - libjansson-dev \ - libpq-dev \ - postgresql-9.6 \ - libmicrohttpd-dev -@end example - -Note that stretch requires @code{libargon2-0-dev}, -while later versions of Debian require @code{libargon2-dev}. - -For the rest of the installation, follow the generic installation -instructions starting with the installation of libgnunetutil. Note that -if you used the Debian stretch instructions above, you need to pass -@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations. - -@node How to configure the merchant’s backend,Instance setup,Installation,Top -@anchor{taler-merchant-manual how-to-configure-the-merchants-backend}@anchor{21} -@chapter How to configure the merchant’s backend - - -@geindex taler-config @geindex taler.conf The installation already provides reasonable defaults for most of the configuration options. However, some must be provided, in particular the -database account and bank account that the backend should use. By -default, the file @code{$HOME/.config/taler.conf} is where the Web shop -administrator specifies configuration values that augment or override -the defaults. The format of the configuration file is the well-known INI -file format. You can edit the file by hand, or use the @code{taler-config} -commands given as examples. +database that the backend should use. By default, the file +@code{$HOME/.config/taler.conf} is where the Web shop administrator specifies +configuration values that augment or override the defaults. +Note that when using our binary packages, the systemd service files +force the use of @code{/etc/taler/taler.conf} as the main configuration file. @menu * Configuration format:: -* Using taler-config:: * Backend options:: * Sample backend configuration:: * Launching the backend:: @end menu -@node Configuration format,Using taler-config,,How to configure the merchant’s backend -@anchor{taler-merchant-manual configuration-format}@anchor{22} +@node Configuration format,Backend options,,How to configure the merchant backend +@anchor{taler-merchant-manual configuration-format}@anchor{1d} @section Configuration format -In Taler realm, any component obeys to the same pattern to get -configuration values. According to this pattern, once the component has -been installed, the installation deploys default values in -$@{prefix@}/share/taler/config.d/, in .conf files. In order to override -these defaults, the user can write a custom .conf file and either pass -it to the component at execution time, or name it taler.conf and place -it under $HOME/.config/. +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation +prefix. Different components must be installed to the same prefix. + +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the `-c' +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass @code{-c +/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf} +the primary location for the configuration. A config file is a text file containing sections, and each section -contains its values. The right format follows: +contains maps options to their values. Configuration files follow +basically the INI syntax: @example [section1] @@ -951,14 +977,23 @@ value21 = string value22 = /path22 @end example -Throughout any configuration file, it is possible to use @code{$}-prefixed -variables, like @code{$VAR}, especially when they represent filesystem -paths. It is also possible to provide defaults values for those +Comments start with a hash (@code{#}). Throughout the configuration, it is +possible to use @code{$}-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: -@code{$@{VAR:-default@}}. However, there are two ways a user can set -@code{$}-prefixable variables: +@code{$@{VAR:-default@}}. There are two ways a user can set the value +of @code{$}-prefixable variables: + +@quotation -by defining them under a @code{[paths]} section, see example below, + +@enumerate + +@item +by defining them under a @code{[paths]} section: +@end enumerate + +@quotation @example [paths] @@ -967,100 +1002,43 @@ TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data [section-x] path-x = $@{TALER_DEPLOYMENT_SHARED@}/x @end example +@end quotation + +@enumerate 2 + +@item or by setting them in the environment: +@end enumerate + +@quotation @example $ export VAR=/x @end example +@end quotation +@end quotation The configuration loader will give precedence to variables set under -@code{[path]}, though. +@code{[path]} over environment variables. -The utility @code{taler-config}, which gets installed along with the -exchange, serves to get and set configuration values without directly -editing the .conf. The option @code{-f} is particularly useful to resolve +The utility @code{taler-config}, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option @code{-f} is particularly useful to resolve pathnames, when they use several levels of @code{$}-expanded variables. See @code{taler-config --help}. -Note that, in this stage of development, the file -@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the -component. For example, both an exchange and a bank can read values from -it. - -The repository @code{git://taler.net/deployment} contains examples of -configuration file used in our demos. See under @code{deployment/config}. - -@quotation - -@strong{Note} - -Expectably, some components will not work just by using default -values, as their work is often interdependent. For example, a -merchant needs to know an exchange URL, or a database name. -@end quotation - -@node Using taler-config,Backend options,Configuration format,How to configure the merchant’s backend -@anchor{taler-merchant-manual using-taler-config}@anchor{23} -@section Using taler-config - - -The tool @code{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 - -@example -$ taler-config -s $SECTION -@end example - -to list all of the configuration values in section @code{$SECTION}. - -Run - -@example -$ taler-config -s $section -o $option -@end example - -to extract the respective configuration value for option @code{$option} in -section @code{$section}. - -Finally, to change a setting, run - -@example -$ taler-config -s $section -o $option -V $value -@end example - -to set the respective configuration value to @code{$value}. Note that you -have to manually restart the Taler backend after you change the -configuration to make the new configuration go into effect. - -Some default options will use $-variables, such as @code{$DATADIR} within -their value. To expand the @code{$DATADIR} or other $-variables in the -configuration, pass the @code{-f} option to @code{taler-config}. For example, -compare: +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. -@example -$ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE -$ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE -@end example - -While the configuration file is typically located at -@code{$HOME/.config/taler.conf}, an alternative location can be specified -to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} -option. - -@node Backend options,Sample backend configuration,Using taler-config,How to configure the merchant’s backend -@anchor{taler-merchant-manual backend-options}@anchor{24}@anchor{taler-merchant-manual id6}@anchor{25} +@node Backend options,Sample backend configuration,Configuration format,How to configure the merchant backend +@anchor{taler-merchant-manual backend-options}@anchor{1e}@anchor{taler-merchant-manual id3}@anchor{1f} @section Backend options @geindex DBMS -@geindex Postgres +@geindex PostgreSQL @geindex UNIX domain socket @@ -1079,40 +1057,44 @@ option. @geindex wire format The following table describes the options that commonly need to be -modified. Here, the notation @code{[$section]/$option} denotes the option -@code{$option} under the section @code{[$section]} in the configuration file. +modified. Here, the notation @code{[$SECTION]/$OPTION} denotes the option +@code{$OPTION} under the section @code{[$SECTION]} in the configuration file. @menu * Service address:: * Currency:: * Database:: * Exchange:: -* Auditor:: @end menu @node Service address,Currency,,Backend options -@anchor{taler-merchant-manual service-address}@anchor{26} +@anchor{taler-merchant-manual service-address}@anchor{20} @subsection Service address -The following option sets the transport layer address used by the -merchant backend: +The service address specifies where the taler-merchant-httpd should listen for +requests. When using the Debian/Ubuntu packages, these options will already be +configured correctly for the included Nginx and Apache configurations and will +not need any changes. + +The following option sets the transport protocol used by the merchant backend: @example -[MERCHANT]/SERVE = TCP | UNIX +[MERCHANT] +SERVE = unix # or tcp @end example -If given, +If this option is set to @itemize - @item -@code{TCP}, then we need to set the TCP port in @code{[MERCHANT]/PORT} +@code{tcp} then we need to set the TCP port in @code{[MERCHANT]/PORT}; @item -@code{UNIX}, then we need to set the unix domain socket path and mode +@code{unix} then we need to set the unix domain socket path and mode in @code{[MERCHANT]/UNIXPATH} and @code{[MERCHANT]/UNIXPATH_MODE}. The latter takes the usual permission mask given as a number, e.g. 660 for user/group read-write access. @@ -1126,12 +1108,30 @@ the backend to the network. To run the Taler backend on TCP port 8888, use: @example -$ taler-config -s MERCHANT -o SERVE -V TCP -$ taler-config -s MERCHANT -o PORT -V 8888 +[MERCHANT] +SERVE = tcp +PORT = 8888 @end example +@cartouche +@quotation Note +If you need to change where the taler-merchant-httpd listens for requests, +you should edit @code{/etc/taler/merchant-overrides.conf}. By default, the +Taler merchant package will use a UNIX domain socket at +@code{/run/taler/merchant-httpd/merchant-http.sock}. For the best possible +security it is recommended to leave this in place and configure a reverse +proxy (Nginx or Apache) as described below. + +When using the Debian/Ubuntu packages, the use of a UNIX domain socket +is already pre-configured in the @code{/etc/taler/conf.d/merchant.conf} +configuration file. Suitable reverse proxy configuration +file templates (@code{taler-merchant}) are be installed in the +respective @code{sites-available} directories of Apache and Nginx. +@end quotation +@end cartouche + @node Currency,Database,Service address,Backend options -@anchor{taler-merchant-manual currency}@anchor{27} +@anchor{taler-merchant-manual currency}@anchor{21} @subsection Currency @@ -1139,19 +1139,32 @@ Which currency the Web shop deals in, i.e. “EUR” or “USD”, is specified using the option @example -[TALER]/CURRENCY +[TALER] +CURRENCY = EUR # or USD, ... @end example -For testing purposes, the currency MUST match “KUDOS” so that tests -will work with the Taler demonstration exchange at -@indicateurl{https://exchange.demo.taler.net/}: +When testing with the Taler demonstration exchange at +@indicateurl{https://exchange.demo.taler.net/} you must set this +value to @code{KUDOS}: @example -$ taler-config -s TALER -o CURRENCY -V KUDOS +[TALER] +CURRENCY = KUDOS @end example +@cartouche +@quotation Note +When using the Debian/Ubuntu packages, these options should be +configured in the @code{/etc/taler/taler.conf} configuration file +(alternatively, you can also edit @code{/etc/taler/merchant-overrides.conf}). +However, you must edit the @code{taler.conf} file manually and `must not' +use @code{taler-config} to do this, as that would inline the include +directives and destroy the carefully setup path structure. +@end quotation +@end cartouche + @node Database,Exchange,Currency,Backend options -@anchor{taler-merchant-manual database}@anchor{28} +@anchor{taler-merchant-manual database}@anchor{22} @subsection Database @@ -1159,7 +1172,8 @@ In principle it is possible for the backend to support different DBMSs. The option @example -[MERCHANT]/DB +[MERCHANT] +DB = postgres @end example specifies which DBMS is to be used. However, currently only the value @@ -1168,23 +1182,33 @@ specifies which DBMS is to be used. However, currently only the value In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database. -For postgres, you need to provide: +@cartouche +@quotation Note +The `taler-merchant-dbconfig' tool can be used to automate the database +setup. When using the Debian/Ubuntu packages, the user should already have +been created, so you can just run the tool without any arguments and should +have a working database configuration. +@end quotation +@end cartouche + +For the @code{postgres} backend, you need to specify: @example -[MERCHANTDB-postgres]/CONFIG +[merchantdb-postgres] +CONFIG = "postgres:///talermerchant" @end example -This option specifies a postgres access path using the format -@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the -Postgres database you want to use. Suppose @code{$USER} is the name of -the user who will run the backend process. Then, you need to first -run: +This option specifies a PostgreSQL access path, typically using the format +@code{postgres:///$DBNAME}, where @code{$DBNAME} is the name of the PostgreSQL +database you want to use (here, @code{talermerchant} on the local machine). +Suppose @code{$USER} is the name of the user who will run the backend process +(usually @code{taler-merchant-httpd}). Then, you need to first run: @example $ sudo -u postgres createuser -d $USER @end example -as the Postgres database administrator (usually @code{postgres}) to +as the PostgreSQL database administrator (usually @code{postgres}) to grant @code{$USER} the ability to create new databases. Next, you should as @code{$USER} run: @@ -1195,33 +1219,31 @@ $ createdb $DBNAME to create the backend’s database. Here, @code{$DBNAME} must match the database name given in the configuration file. -To configure the Taler backend to use this database, run: - -@example -$ taler-config -s MERCHANTDB-postgres -o CONFIG \ - -V postgres:///$DBNAME -@end example - -Now you should create the tables and indices. To do this, run as @code{$USER}: +Now you should be able to create the tables and indices. To do this, run as +@code{$USER} (usually @code{taler-merchant-httpd}): @example $ taler-merchant-dbinit @end example -You can improve your security posture if you now REVOKE the rights to CREATE, +You may improve your security posture if you now REVOKE the rights to CREATE, DROP or ALTER tables from @code{$USER}. However, if you do so, please be aware that you may have to temporarily GRANT those rights again when you update the merchant backend. For details on how to REVOKE or GRANT these rights, consult -the Postgres documentation. +the PostgreSQL documentation. -Commands, like @code{taler-merchant-dbinit}, that support the @code{-l LOGFILE} -command-line option, send logging output to standard error by default. -See manpages/taler-merchant-dbinit.1 for more information. +@cartouche +@quotation Note +Taler may store sensitive business and customer data in the database. Any +operator SHOULD thus ensure that backup operations are encrypted and +secured from unauthorized access. +@end quotation +@end cartouche @c index: MASTER_KEY -@node Exchange,Auditor,Database,Backend options -@anchor{taler-merchant-manual exchange}@anchor{29} +@node Exchange,,Database,Backend options +@anchor{taler-merchant-manual exchange}@anchor{23} @subsection Exchange @@ -1237,9 +1259,8 @@ The @code{EXCHANGE_BASE_URL} option specifies the exchange’s base URL. For example, to use the Taler demonstrator, specify: @example -$ taler-config -s MERCHANT-EXCHANGE-demo \ - -o EXCHANGE_BASE_URL \ - -V https://exchange.demo.taler.net/ +[merchant-exchange-kudos] +EXCHANGE_BASE_URL = "https://exchange.demo.taler.net/" @end example @item @@ -1247,80 +1268,51 @@ The @code{MASTER_KEY} option specifies the exchange’s master public key in base32 encoding. For the Taler demonstrator, use: @example -$ taler-config -s MERCHANT-EXCHANGE-demo \ - -o MASTER_KEY \ - -V FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0 -@end example - -@item -The @code{CURRENCY} option specifies the exchange’s currency. -For the Taler demonstrator, use: - -@example -$ taler-config -s MERCHANT-EXCHANGE-demo \ - -o CURRENCY \ - -V KUDOS +[merchant-exchange-kudos] +MASTER_KEY = "GNRJCH0HYKN59939JC0CJ2JDC7ZNEBSATJFF00CVS3WPG4TQEA7G" @end example @end itemize -Note that multiple exchanges can be added to the system by using different -tokens in place of @code{demo} in the examples above. Note that all of the -exchanges must use the same currency: If the currency does not match the main -currency from the @code{TALER} section, the exchange is ignored. If you need to -support multiple currencies, you need to configure a backend per currency. - -@node Auditor,,Exchange,Backend options -@anchor{taler-merchant-manual auditor}@anchor{2a} -@subsection Auditor - +@quotation -To add an auditor to the list of trusted auditors (which implies -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: +You can find out this key by running @code{curl https://exchange.demo.taler.net/keys | jq .master_public_key}. +@end quotation @itemize - @item -The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL. -For example, to use the Taler demonstrator’s auditor, specify: - -@example -$ taler-config -s MERCHANT-AUDITOR-demo \ - -o AUDITOR_BASE_URL \ - -V https://exchange.demo.taler.net/ -@end example - -@item -The @code{AUDITOR_KEY} option specifies the auditor’s public key -in base32 encoding. For the Taler demonstrator, use: - -@example -$ taler-config -s MERCHANT-AUDITOR-demo \ - -o AUDITOR_KEY \ - -V DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11 -@end example - -@item -The @code{CURRENCY} option specifies the auditor’s currency. +The @code{CURRENCY} option specifies the exchange’s currency. For the Taler demonstrator, use: @example -$ taler-config -s MERCHANT-AUDITOR-demo \ - -o CURRENCY \ - -V KUDOS +[merchant-exchange-kudos] +CURRENCY = "KUDOS" @end example @end itemize -Note that multiple auditors can be added to the system by using different -tokens in place of @code{demo} in the examples above. Note that all of the -auditors must use the same currency: If the currency does not match the main -currency from the @code{TALER} section, the auditor is ignored. If you need to -support multiple currencies, you need to configure a backend per currency. +Note that multiple exchanges can be added to the system by using different +identifiers in place of @code{KUDOS} in the example above. Note that all of the +exchanges actually used will use the same currency: If the currency does not +match the main @code{CURRENCY} option from the @code{taler} section, the respective +@code{merchant-exchange-} section is automatically ignored. If you need support +for multiple currencies, you need to deploy one backend per currency. + +The merchant already ships with a default configuration that contains the +@code{merchant-exchange-kudos} section from above. -@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant’s backend -@anchor{taler-merchant-manual id7}@anchor{2b}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{2c} +@cartouche +@quotation Note +Manually setting up exchanges is only recommended under special +circumstances. In general, GNU Taler distributions will include trustworthy +exchanges (for each currency) in the default configuration, and there is +rarely a good reason for trusting an exchange that has no relationship +with the GNU Taler development team. +@end quotation +@end cartouche + +@node Sample backend configuration,Launching the backend,Backend options,How to configure the merchant backend +@anchor{taler-merchant-manual id4}@anchor{24}@anchor{taler-merchant-manual sample-backend-configuration}@anchor{25} @section Sample backend configuration @@ -1329,45 +1321,34 @@ support multiple currencies, you need to configure a backend per currency. The following is an example for a complete backend configuration: @example -[TALER] +[taler] CURRENCY = KUDOS -[MERCHANT] +[merchant] SERVE = TCP PORT = 8888 DATABASE = postgres -[MERCHANTDB-postgres] -CONFIG = postgres:///donations +[merchantdb-postgres] +CONFIG = postgres:///taler-merchant -[merchant-exchange-NAME] +[merchant-exchange-kudos] EXCHANGE_BASE_URL = https://exchange.demo.taler.net/ MASTER_KEY = FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0 -# If currency does not match [TALER] section, the exchange -# will be ignored! -CURRENCY = KUDOS - -[merchant-auditor-NAME] -AUDITOR_BASE_URL = https://auditor.demo.taler.net/ -AUDITOR_KEY = DSDASDXAMDAARMNAD53ZA4AFAHA2QADAMAHHASWDAWXN84SDAA11 -# If currency does not match [TALER] section, the auditor +# If currency does not match [taler] section, the exchange # will be ignored! CURRENCY = KUDOS @end example -Given the above configuration, the backend will use a database named -@code{donations} within Postgres. +Given the above configuration, the backend will use a PostgreSQL database +named @code{donations} running on the same host. The backend will deposit the coins it receives to the exchange at @indicateurl{https://exchange.demo.taler.net/}, which has the master key @code{FH1Y8ZMHCTPQ0YFSZECDH8C9407JR3YN0MF1706PTG24Q4NEWGV0}. -Please note that @code{doc/config.sh} will walk you through all -configuration steps, showing how to invoke @code{taler-config} for each of -them. - -@node Launching the backend,,Sample backend configuration,How to configure the merchant’s backend -@anchor{taler-merchant-manual id8}@anchor{2d}@anchor{taler-merchant-manual launching-the-backend}@anchor{2e} +@node Launching the backend,,Sample backend configuration,How to configure the merchant backend +@anchor{taler-merchant-manual id5}@anchor{26}@anchor{taler-merchant-manual launching-the-backend}@anchor{27} @section Launching the backend @@ -1376,122 +1357,172 @@ them. @geindex taler-merchant-httpd Assuming you have configured everything correctly, you can launch the -merchant backend as @code{$USER} using +merchant backend as @code{$USER} using (to provide a trivial example): @example -$ taler-merchant-httpd +$ taler-merchant-httpd & +$ taler-merchant-webhook & +$ taler-merchant-wirewatch & +$ taler-merchant-depositcheck & +$ taler-merchant-exchange & @end example -To ensure the process runs always in the background and also after rebooting, -you should use systemd, cron or some other init system of your operating -system to launch the process. Consult the documentation of your operating -system for how to start and stop daemons. +To ensure these processes run always in the background and also after +rebooting, you should use systemd, cron or some other init system of your +operating system to launch the process. You should also periodically re-start +these services to prevent them from exhausing the memory utilization of the +PostgreSQL database. Consult the documentation of your operating system for +how to start and stop daemons. + +@cartouche +@quotation Note +When using the Debian/Ubuntu packages, the systemd configuration +will already exist. You only need to enable and start the service +using @code{systemctl enable taler-merchant.target} and +@code{systemctl start taler-merchant.target}. Additionally, you should +review the @code{/etc/apache2/sites-available/taler-merchant.conf} +or @code{/etc/nginx/sites-available/taler-merchant} (these files +contain additional instructions to follow), symlink it to +@code{sites-enabled/} and restart your HTTP server. After that, you +should be able to visit the merchant backend at the respective +HTTP(S) endpoint. +@end quotation +@end cartouche If everything worked as expected, the command @example -$ curl http://localhost:8888/ +$ wget -O - http://localhost:8888/config @end example -should return the message +should return some basic configuration status data about the service. -@example -Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. -@end example +Please note that your backend might then be globally reachable without +any access control. You can either: + +@quotation + + +@itemize * + +@item +Use the @code{--auth=$TOKEN} command-line option to `taler-merchant-httpd' to set an access token to be provided in an @code{Authorize: Bearer $TOKEN} HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. + +@item +Set the @code{TALER_MERCHANT_TOKEN} environment variable to @code{$TOKEN} for the same effect. This method has the advantage of @code{$TOKEN} not being visible as a command-line interface to other local users on the same machine. + +@item +Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token! +@end itemize +@end quotation -Please note that your backend is right now likely globally reachable. -Production systems should be configured to bind to a UNIX domain socket +Production systems should additionally be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see @ref{9,,Secure setup}. @geindex instance -@node Instance setup,Secure setup,How to configure the merchant’s backend,Top -@anchor{taler-merchant-manual id9}@anchor{2f}@anchor{taler-merchant-manual instance-setup}@anchor{30} +@node Instance setup,Instance account setup,How to configure the merchant backend,Top +@anchor{taler-merchant-manual id6}@anchor{28}@anchor{taler-merchant-manual instance-setup}@anchor{29} @chapter Instance setup -Before using the backend, you must at least configure the “default” instance. +We recommend the use of the single-page administration application (SPA) that +is served by default at the base URL of the merchant backend. You can use it +to perform all steps described in this section (and more!), using a simple Web +interface. Alternatively, you can also use the @code{wget} commands given below. + +Regardless of which approach you use, the first step for using the backend +involves the creation of a @code{default} instance. The @code{default} instance can +also create, configure or delete other instances, similar to the @code{root} +account on UNIX. When no instance exists and @code{taler-merchant-httpd} was +started without the @code{--auth} option, then the backend is reachable without +any access control (unless you configured some in the reverse proxy). + +The following documentation shows how to handle any instance. Thus, if you +want to have multiple instances, you may need to perform the steps multiple +times, once for each instance. + +@cartouche +@quotation Note +A potential security concern is that normal API usage leaks instance existence. +This means unauthorized users can distinguish between the case where the +instance does not exist (HTTP 404) and the case where access is denied +(HTTP 403). +This is concern can be addressed using a properly configured +@ref{2a,,reverse proxy}. +@end quotation +@end cartouche @menu -* KUDOS Accounts:: -* IBAN Accounts:: -* Setup:: +* Instance setup with the SPA:: +* Instance setup without the Web interface:: @end menu -@node KUDOS Accounts,IBAN Accounts,,Instance setup -@anchor{taler-merchant-manual kudos-accounts}@anchor{31} -@section KUDOS Accounts - +@node Instance setup with the SPA,Instance setup without the Web interface,,Instance setup +@anchor{taler-merchant-manual instance-setup-with-the-spa}@anchor{2b} +@section Instance setup with the SPA -The main configuration data that must be provided for each instance -is the bank account information. -In order to receive payments, the merchant backend needs to -communicate bank account details to the exchange. +In order to setup an instance, you need the merchant backend to already be +running, and you must either have the credentials for the “default” instance, +or no instance must be configured at all yet. -The bank account information is provided in the form of a @code{payto://}-URI. -See RFC 8905@footnote{https://tools.ietf.org/html/rfc8905} -for the format of @code{payto://}-URIs. +To start, point your browser to @code{$PROTO://backend.$DOMAIN_NAME/}, replacing +“$PROTO” with “https” or (rarely) “http” and “$DOMAIN_NAME” with your +organizations DNS domain or subdomain. -For first tests, you should sign up for a KUDOS bank -account at @indicateurl{https://bank.demo.taler.net/}. -In this case, the @code{payto://}-URI will be of the form -@code{payto://x-taler-bank/bank.demo.taler.net/$USERNAME} where @code{$USERNAME} -must be replaced with the name of the account that was established -at @indicateurl{https://bank.demo.taler.net/}. +@cartouche +@quotation Note +The label “backend” here is also just a suggestion, your administrator +can in principle choose any name. +@end quotation +@end cartouche -@node IBAN Accounts,Setup,KUDOS Accounts,Instance setup -@anchor{taler-merchant-manual iban-accounts}@anchor{32} -@section IBAN Accounts +You should be welcomed by the following merchant backoffice page: +@image{taler-merchant-figures/merchant_first_login,,,,png} -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 @code{payto://}-URI of your real bank -account. In Europe, this will involve knowing your IBAN number. If you have an -IBAN, the corresponding @code{payto://}-URI is simply @code{payto://iban/$IBAN} where -@code{$IBAN} must be replaced with the actual IBAN number. +After supplying the required fields, primarily the name of your organization +and the desired access token, click @code{confirm}. You can change the instance +settings later via the @code{Settings} entry in the menu on the left. -@node Setup,,IBAN Accounts,Instance setup -@anchor{taler-merchant-manual setup}@anchor{33} -@section Setup +@node Instance setup without the Web interface,,Instance setup with the SPA,Instance setup +@anchor{taler-merchant-manual instance-setup-without-the-web-interface}@anchor{2c} +@section Instance setup without the Web interface -With the knowledge of the @code{payto://}-URI, instances can be configured by POSTing -a request to @code{POST /private/instances}. To create a first instance, -create a file @code{instance.json} with an InstanceConfigurationMessage +Instances can be created by POSTing a request to @code{/management/instances} +without using the Web interface. This could be useful if you want to create +many instances programmatically. To create an instance without the Web +interface create a file @code{instance.json} with an +InstanceConfigurationMessage: @example @{ - "payto_uris" : [ "$PAYTO_URI" ], "id" : "default", - "name": "example.com", + "name": "Example Inc.", "address": @{ "country" : "zz" @}, "auth": @{ "method" : "external"@} , "jurisdiction": @{ "country" : "zz" @}, - "default_max_wire_fee": "KUDOS:1", - "default_wire_fee_amortization": 100, - "default_max_deposit_fee": "KUDOS:1", + "use_stefan": true, "default_wire_transfer_delay": @{ "d_ms" : 1209600000 @}, "default_pay_delay": @{ "d_ms" : 1209600000 @} @} @end example -In the text above, you must replace @code{$PAYTO_URI} with your actual -@code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the -setup is for an actual bank. The @code{name} field will be shown as the name of -your shop. The @code{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 -account. Those defaults can be modified for individual orders. -For details, see the contract terms specification. +The @code{name} field will be shown as the name of your shop. The +@code{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 account. Those +defaults can be modified for individual orders. For details, see the +contract terms specification. You can then create the instance using: @example -$ wget --post-file=instance.json http://localhost:8888/private/instances +$ wget --post-file=instance.json http://localhost:8888/management/instances @end example The base URL for the instance will then be @@ -1502,8 +1533,135 @@ Endpoints to modify (reconfigure), permanently disable (while keeping the data) or purge (deleting all associated data) instances exist as well and are documented in the Merchant Backend API documentation. -@node Secure setup,Customization,Instance setup,Top -@anchor{taler-merchant-manual id11}@anchor{34}@anchor{taler-merchant-manual secure-setup}@anchor{9} +@node Instance account setup,Manually creating an order using the SPA,Instance setup,Top +@anchor{taler-merchant-manual id7}@anchor{2d}@anchor{taler-merchant-manual instance-account-setup}@anchor{2e} +@chapter Instance account setup + + +Before you can use an instance productively, you need to configure one or more +bank accounts. These bank accounts will be provided to the Taler exchange +operator to tell it where to wire the income from your sales. Every bank +account has an associated `wire method' which determines how an exchange can +transfer the funds. The most commonly supported wire method is `iban', which +implies that bank accounts are identified by IBAN numbers and wire transfers +are to be executed between IBAN accounts. For regional currency setups, the +wire method could also be `x-taler-bank'. + +@cartouche +@quotation Note +When using a regional currency, you need to first create a bank account at +the regional bank. You may need to contact the respective administrator who +can set one up. After being able to login to the new bank account, you can +see your bank account number by clicking on the @code{Welcome, $USERNAME} +message in the profile page. Next to the bank account number, you can find +a convenient button to copy the number to the clipboard. +@end quotation +@end cartouche + +Not every exchange will support every `wire method', and if you do not add a +bank account with a wire method that is supported by a particular exchange, +then you will not be able to receive payments via that exchange even if you +configured the merchant backend to trust that exchange. + +The simplest way to configure an account is to use the Web interface which has +specific forms for different wire methods. First, select @code{Bank account} at +the left of the page. The following page should be shown: + +@image{taler-merchant-figures/no_default_account_yet,,,,png} + +Click on the blue “+” sign on the top right of the page to add a new +bank account. The following page should appear: + +@image{taler-merchant-figures/enter_instance_details,,,,png} + +First, you should select the wire method, after which the dialog will show you +additional fields specific to the wire method. For example, if youchoose +@code{iban} as the account type, the following page should appear: + +@image{taler-merchant-figures/instance_iban_config,,,,png} + +Specifying the revenue gateway with username and password is optional and +discussed in section @ref{2f,,Automatic Settlement Data Import} below. + +After providing the details and confirming, the shop is ready to generate orders +and accept payments. + +@menu +* Detecting Settlement; Manually Adding Transfers: Detecting Settlement Manually Adding Transfers. +* Automatic Settlement Data Import:: + +@end menu + +@node Detecting Settlement Manually Adding Transfers,Automatic Settlement Data Import,,Instance account setup +@anchor{taler-merchant-manual detecting-settlement-manually-adding-transfers}@anchor{30} +@section Detecting Settlement: Manually Adding Transfers + + +The exchange may aggregate many small amounts into one larger wire transfer. +If you want to safely determine for which orders have been settled (final +payment from the exchange has been received), the backend must learn about the +wire transfers made into your bank account. Basically, as a secure system, we +do not simply trust a claim by the exchange that it would transfer the money, +but we allow each merchant to check settlements. + +An easy (but somewhat tedious) way to check settlements is to manually add +every wire transfer that a merchant bank account has received from the +exchange with the total amount and the wire transfer subject. Given this +information, the merchant backend will inquire with the exchange which +individual payments were aggregated, check that the total amount is correct, +and will then flag the respective contracts as wired. + +You can manually enter wire transfers under @code{Transfers}. However, this is +tedious, and so if your banking setup supports it, we highly recommend +using the automatic settlement data import. + +@node Automatic Settlement Data Import,,Detecting Settlement Manually Adding Transfers,Instance account setup +@anchor{taler-merchant-manual automatic-settlement-data-import}@anchor{2f}@anchor{taler-merchant-manual id8}@anchor{31} +@section Automatic Settlement Data Import + + +To automatically import settlement data, you need to provide the merchant +backend with the address and access credentials of a +taler-bank-merchant-http-api for each bank account of an instance. The +revenue API endpoint will allow the merchant backend to obtain a list of all +incoming wire transfers into your bank account and automatically import them +into the list of confirmed wire transfers. + +Note that setting up a revenue API endpoint will usually require you to first +ask your bank for EBICS access and to set up libeufin-nexus to provide +the revenue API endpoint. The libeufin-bank used by regional currency +setups also provides a revenue API endpoint at +@code{$BANK_URL/accounts/$ACCOUNT_NAME/taler-revenue/}. Thus, when using a +regional currency setup, simply use the @code{$BANK_URL} of your bank and specify +your bank login name and password in the @ref{2e,,Instance account setup} dialog. + +@node Manually creating an order using the SPA,Secure setup,Instance account setup,Top +@anchor{taler-merchant-manual manually-creating-an-order-using-the-spa}@anchor{32} +@chapter Manually creating an order using the SPA + + +Click on @code{Orders} at the top left corner of the merchant backoffice page; the +following page should appear + +@image{taler-merchant-figures/create_orders,,,,png} + +After having filled the required fields, the interface should show the +following page with the related links to check the status of the order and let +wallets pay for it. + +@image{taler-merchant-figures/payment_links,,,,png} + +In order to test the setup, it should be now possible to use the command line wallet +to withdraw Taler coins and spend them to pay for the order we just created. + +In practice, you will rarely if ever setup orders manually like this. Instead, +a GNU Taler e-commerce front-end@footnote{https://taler.net/en/docs.html#extensions} or the +taler-merchant-pos-app will do this on-demand. Here, you will only need +to provide the respective front-ends with the URL of your instance +(e.g. @code{https://backend.$DOMAIN/instances/$NAME}) and your access token. + +@node Secure setup,Customization,Manually creating an order using the SPA,Top +@anchor{taler-merchant-manual id9}@anchor{33}@anchor{taler-merchant-manual secure-setup}@anchor{9} @chapter Secure setup @@ -1511,43 +1669,46 @@ in the Merchant Backend API documentation. @geindex TLS -The Taler backend does not include even the most basic forms of -access control or transport layer security. Thus, production -setups @strong{must} deploy the Taler backend behind an HTTP(S) server -that acts as a @emph{reverse proxy}, performs TLS termination and -authentication and then forwards requests to the backend. +The Taler backend is deliberately simple in terms of support for access +control or transport layer security (TLS). Thus, production setups `must' +deploy the Taler backend behind an HTTP(S) server that acts as a `reverse +proxy', performs TLS termination and authentication and then forwards requests +to the backend. @menu * Using UNIX domain sockets:: * Reverse proxy configuration:: * Access control:: +* Status code remapping:: @end menu @node Using UNIX domain sockets,Reverse proxy configuration,,Secure setup -@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{35} +@anchor{taler-merchant-manual using-unix-domain-sockets}@anchor{34} @section Using UNIX domain sockets To ensure that the merchant backend is not exposed directly to the network, -you @emph{should} bind the backend to a UNIX domain socket: +you `should' bind the backend to a UNIX domain socket: @example -$ taler-config -s MERCHANT -o SERVE -V UNIX -$ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock +[MERCHANT] +SERVE = unix +UNIXPATH = "/some/path/here.sock" @end example 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 @emph{may} use a +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 @emph{not recommended}. Relying on NAT or network firewalls for access -control is gross negligence. +but this is `not recommended'. If you do need a TCP socket, you should +instead strongly consider using the “BIND_TO” option to at least bind it only +to “localhost”. @node Reverse proxy configuration,Access control,Using UNIX domain sockets,Secure setup -@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{36} +@anchor{taler-merchant-manual id10}@anchor{35}@anchor{taler-merchant-manual reverse-proxy-configuration}@anchor{2a} @section Reverse proxy configuration @@ -1558,7 +1719,7 @@ control is gross negligence. @end menu @node Nginx,Apache,,Reverse proxy configuration -@anchor{taler-merchant-manual nginx}@anchor{37} +@anchor{taler-merchant-manual nginx}@anchor{36} @subsection Nginx @@ -1578,7 +1739,7 @@ not have HTTPS enabled. Make sure to restart the @code{taler-merchant-httpd} process after changing the @code{SERVE} configuration. @node Apache,,Nginx,Reverse proxy configuration -@anchor{taler-merchant-manual apache}@anchor{38} +@anchor{taler-merchant-manual apache}@anchor{37} @subsection Apache @@ -1605,27 +1766,36 @@ Note that the above again assumes your domain name is @code{example.com} and tha you have TLS configured. Note that you must add the @code{https} header unless your site is not available via TLS. -The above configuration(s) are both incomplete. You must still additionally -setup access control! - -@node Access control,,Reverse proxy configuration,Secure setup -@anchor{taler-merchant-manual access-control}@anchor{39} +@node Access control,Status code remapping,Reverse proxy configuration,Secure setup +@anchor{taler-merchant-manual access-control}@anchor{38} @section Access control -All endpoints with @code{/private/} in the URL must be restricted to authorized users -of the respective instance. Specifically, the HTTP server must be configured -to only allow access to @code{$BASE_URL/private/} to the authorized users of the -default instance, and to @code{$BASE_URL/instances/$ID/private/} to the -authorized users of the instance @code{$ID}. +All endpoints with @code{/private/} in the URL must be restricted to authorized +users of the respective instance. Specifically, the HTTP server must be +configured to only allow access to @code{$BASE_URL/private/} to the authorized +users of the default instance, and to @code{$BASE_URL/instances/$ID/private/} to +the authorized users of the instance @code{$ID}. -How access control is done (TLS client authentication, HTTP basic or digest -authentication, etc.) is completely up to the merchant and does not matter to -the Taler merchant backend. +By default, the GNU Taler merchant backend simply requires the respective +HTTP requests to include an “Authorization” header with a “Bearer” token +set to the respective shared secret which must begin with “secret-token:” +(following RFC 8959). -Note that all of the other endpoints (without @code{/private/}) are expected to be -fully exposed to the Internet, and wallets may have to interact with those -endpoints directly without client authentication. +Note that all of the other endpoints (without @code{/private/}) +are expected to be fully exposed to the Internet, and wallets may have to +interact with those endpoints directly without client authentication. + +@node Status code remapping,,Access control,Secure setup +@anchor{taler-merchant-manual status-code-remapping}@anchor{39} +@section Status code remapping + + +Normal API usage leaks instance existence information. Distinguishing between +404 (Not found) and 403 (Forbidden) is useful for diagnostics. + +For higher security (by leaking less information), you can add the following +fragment, which remaps all 404 response codes to 403. @menu * Nginx: Nginx<2>. @@ -1633,469 +1803,511 @@ endpoints directly without client authentication. @end menu -@node Nginx<2>,Apache<2>,,Access control -@anchor{taler-merchant-manual id12}@anchor{3a} +@node Nginx<2>,Apache<2>,,Status code remapping +@anchor{taler-merchant-manual id11}@anchor{3a} @subsection Nginx -For Nginx, you can implement token-based merchant backend authentication as -follows: - @example -location ~ /private/ @{ - if ($http_authorization !~ "(?i)ApiKey SECURITYTOKEN") @{ - return 401; - @} - proxy_pass ...; // as above -@} +error_page 404 =403 /empty.gif; @end example -Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note -that the @code{~} ensures that the above matches all endpoints that include the -string @code{/private/}. If you only run a single instance, you could simply -specify @code{/private/} without the @code{~} to only configure the access policy for -the default instance. +@node Apache<2>,,Nginx<2>,Status code remapping +@anchor{taler-merchant-manual id12}@anchor{3b} +@subsection Apache -If you are running different instances on the same backend, you -likely will want to specify different access control tokens for -each instance: @example -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 -@} +cond %@{STATUS@} =404 +set-status 403 @end example -@node Apache<2>,,Nginx<2>,Access control -@anchor{taler-merchant-manual id13}@anchor{3b} -@subsection Apache +@node Customization,Upgrade procedure,Secure setup,Top +@anchor{taler-merchant-manual customization}@anchor{3c} +@chapter Customization -For Apache, you should first enable @code{mod_rewrite}: +@menu +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Template Customization:: +* Static files:: +* Internationalization:: +* Limitations:: -@example -$ a2enmod rewrite -@end example +@end menu -Then, you can restrict to an access control token using: +@node Legal conditions for using the service,Terms of Service,,Customization +@anchor{taler-merchant-manual legal-conditions-for-using-the-service}@anchor{3d} +@section Legal conditions for using the service -@example -<Location "/"> -RewriteEngine On -RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=SECURITYTOKEN" -RewriteRule "(.+)/private/" "-" [F] -ProxyPass "unix:/some/path/here.sock|http://example.com/" -</Location> -@end example +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@c terms of the GNU Affero General Public License as published by the Free Software +@c Foundation; either version 2.1, or (at your option) any later version. +@c +@c TALER is distributed in the hope that it will be useful, but WITHOUT ANY +@c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. +@c +@c You should have received a copy of the GNU Affero General Public License along with +@c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> +@c +@c @author Christian Grothoff -Here, @code{SECURITYTOKEN} should be replaced with the actual shared secret. Note -that the @code{(.+)} ensures that the above matches all endpoints that include the -string @code{/private/}. If you only run a single instance, you could simply -specify @code{/private/} without the @code{~} to only configure the access policy for -the default instance. +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. -If you are running different instances on the same backend, you -likely will want to specify different access control tokens for -each instance: +@node Terms of Service,Privacy Policy,Legal conditions for using the service,Customization +@anchor{taler-merchant-manual terms-of-service}@anchor{3e} +@section Terms of Service -@example -<Location "/instances/foo/"> -RewriteEngine On -RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=FOOTOKEN" -RewriteRule "/instances/foo/private/" "-" [F] -ProxyPass ... # as above -</Location> +The service has an endpoint “/terms” to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. -<Location "/instances/bar/"> -RewriteEngine On -RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=BARTOKEN" -RewriteRule "/instances/bar/private/" "-" [F] +To configure the terms of service response, there are two options +in the configuration file for the service: -ProxyPass ... # as above -</Location> -<Location "/"> -RewriteEngine On -RewriteCond "%@{HTTP:AUTHORIZATION@}" "!=MASTERTOKEN" -RewriteRule "/private/" "-" [F] -RewriteRule "(.+)/private/" "-" [F] # reject all others +@itemize - -ProxyPass ... # as above -</Location> -@end example +@item +@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. +This value must be changed whenever the terms of service are +updated. A common value to use would be a version number. +Note that if you change the @code{TERMS_ETAG}, you MUST also provide +the respective files in @code{TERMS_DIR} (see below). + +@item +@code{TERMS_DIR}: The directory that contains the terms of service. +The files in the directory must be readable to the service +process. +@end itemize -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. +@node Privacy Policy,Legal policies directory layout,Terms of Service,Customization +@anchor{taler-merchant-manual privacy-policy}@anchor{3f} +@section Privacy Policy -System administrators are strongly advised to test their access control -setup before going into production! -@node Customization,Upgrade procedure,Secure setup,Top -@anchor{taler-merchant-manual customization}@anchor{3c} -@chapter Customization +The service has an endpoint “/pp” to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy. +This value must be changed whenever the privacy policy is +updated. A common value to use would be a version number. +Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide +the respective files in @code{PRIVACY_DIR} (see below). + +@item +@code{PRIVACY_DIR}: The directory that contains the privacy policy. +The files in the directory must be readable to the service +process. +@end itemize + +@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Customization +@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{40} +@section Legal policies directory layout +The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using two-letter language codes +like “en”, “de”, or “jp”. Each of these directories would then hold +translations of the current terms of service into the respective language. +Empty directories are permitted in case translations are not available. + +Then, inside each language directory, files with the name of the value set as +the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present, +the service may show a warning on startup. + @menu -* Templates:: -* Static files:: -* Internationalization:: -* Limitations:: +* Example:: @end menu -@node Templates,Static files,,Customization -@anchor{taler-merchant-manual templates}@anchor{3d} -@section Templates +@node Example,,,Legal policies directory layout +@anchor{taler-merchant-manual example}@anchor{41} +@subsection Example -The installation process will install various HTML templates to be served -to trigger the wallet interaction. You may change those templates to your -own design. The templating language used is Mustach, and the templates -are in the @code{share/taler/merchant/templates/} directory. +A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be: -@node Static files,Internationalization,Templates,Customization -@anchor{taler-merchant-manual static-files}@anchor{3e} -@section Static files +@itemize - -The merchant backend also has the ability to serve small static files -under the @code{/static/@{FILENAME@}} endpoint. This is used by the templating -logic to load a CSS file, but you can also put other resources such as -images or JavaScript. +@item +TERMS_DIR/en/tos-v0.txt -@node Internationalization,Limitations,Static files,Customization -@anchor{taler-merchant-manual internationalization}@anchor{3f} -@section Internationalization +@item +TERMS_DIR/en/tos-v0.html +@item +TERMS_DIR/en/tos-v0.pdf -Both templates and static files can be internationalized. This is done -by having the language of the resource be a part of the filename. -For templates the format is @code{@{BASENAME@}.@{LANGUAGE@}.must}. The -language is mandatory for templates, the default language is English (en). +@item +TERMS_DIR/en/tos-v0.epub -For static files, the format is @code{@{BASENAME@}.@{LANGUAGE@}.@{EXT@}} for -internationalized files, and @code{@{BASENAME@}.@{EXT@}} for resources that do not -support internationalization. The HTTP client will always request -@code{/static/@{BASENAME@}.@{EXT@}}. If @code{@{BASENAME@}.@{EXT@}} exists, that resource is -returned. Otherwise, an internationalized file based on the language -preferences indicated by the browser is returned. +@item +TERMS_DIR/en/tos-v0.md -@node Limitations,,Internationalization,Customization -@anchor{taler-merchant-manual limitations}@anchor{40} -@section Limitations +@item +TERMS_DIR/de/tos-v0.txt +@item +TERMS_DIR/de/tos-v0.html -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 @code{ulimit} of the @code{taler-merchant-httpd} process if you have -templates for many languages. +@item +TERMS_DIR/de/tos-v0.pdf -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 -formats. +@item +TERMS_DIR/de/tos-v0.epub -The current backend only provides a limited set of variables for the Mustach -template expansion, and does not make use of scopes and other Mustach -features. +@item +TERMS_DIR/de/tos-v0.md +@end itemize -@node Upgrade procedure,Tipping visitors,Customization,Top -@anchor{taler-merchant-manual upgrade-procedure}@anchor{41} -@chapter Upgrade procedure +If the user requests an HTML format with language preferences “fr” followed by +“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +French. +@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Customization +@anchor{taler-merchant-manual generating-the-legal-terms}@anchor{42} +@section Generating the Legal Terms -This is the general upgrade procedure. Please see the release notes -for your specific version to check if a particular release has special -upgrade requirements. -Please note that upgrades are ONLY supported for released version of the -merchant. Attempting to upgrade from or to a version in Git is not supported -and may result in subtle data loss. +The @code{taler-terms-generator} script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in @code{.rst} format and GNU gettext +translations in @code{.po} format. -To safely upgrade the merchant, you should first stop the existing -@code{taler-merchant-httpd} process, backup your merchant database (see Postgres -manual), and then install the latest version of the code. +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective @code{ETAG}. The +resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document. -If you REVOKED database permissions, ensure that the rights to CREATE, -DROP, and ALTER tables are GRANTed to @code{$USER} again. Then, run: +Once you have written the @code{$ETAG.rst} file in English, you can +generate the first set of outputs: @example -$ taler-merchant-dbinit +$ taler-terms-generator -i $ETAG @end example -to upgrade the database to the latest schema. After that, you may again -REVOKE the database permissions. Finally, restart the HTTP service, either via -your systemd or init system, or directly using: +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in @code{$PREFIX/share/terms/}. The generator +has a few options which are documented in its man page. + +@node Adding translations,Updating legal documents,Generating the Legal Terms,Customization +@anchor{taler-merchant-manual adding-translations}@anchor{43} +@section Adding translations + + +Translations must be available in subdirectories +@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}. +To start translating, you first need to add a new +language: + +@example +$ taler-terms-generator -i $ETAG -l $LANGUAGE +@end example + +Here, @code{$LANGUAGE} should be a two-letter language +code like @code{de} or @code{fr}. The command will generate +a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po} +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the @code{.po} +file. Afterwards, simply re-run @example -$ taler-merchant-httpd +$ taler-terms-generator -i $ETAG @end example -@node Tipping visitors,Advanced topics,Upgrade procedure,Top -@anchor{taler-merchant-manual id14}@anchor{42}@anchor{taler-merchant-manual tipping-visitors}@anchor{43} -@chapter Tipping visitors +to make the current translation(s) available to the +service. + +@cartouche +@quotation Note +You must restart the service whenever adding or updating legal documents or their translations. +@end quotation +@end cartouche + +@node Updating legal documents,Template Customization,Adding translations,Customization +@anchor{taler-merchant-manual updating-legal-documents}@anchor{44} +@section Updating legal documents + + +When making minor changes without legal implications, edit the @code{.rst} file, +then re-run the step to add a new language for each existing translation to +produce an updated @code{.po} file. Translate the sentences that have changed and +finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to +create the final files. +When making major changes with legal implications, you should first rename (or +copy) the existing @code{.rst} file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the @code{.po} files, +complete the translations and re-create the final files. Finally, do not +forget to update the @code{ETAG} configuration option to the new name and to +restart the service. -@geindex tipping +@node Template Customization,Static files,Updating legal documents,Customization +@anchor{taler-merchant-manual merchanttemplatecustomization}@anchor{45}@anchor{taler-merchant-manual template-customization}@anchor{46} +@section Template Customization -Taler can also be used to tip Web site visitors. For example, you may be -running an online survey, and you want to reward those people that have -dutifully completed the survey. If they have installed a Taler wallet, -you can provide them with a tip for their deeds. This section describes -how to setup the Taler merchant backend for tipping. -There are three basic steps that must happen to tip a visitor. +The installation process will install various HTML templates to be served to +trigger the wallet interaction. You may change those templates to your own +design. The templating language used is Mustach@footnote{https://gitlab.com/jbol/mustach}, and the templates are in the +@code{share/taler/merchant/templates/} directory. + +The file names must be of the form @code{$NAME.$LANG.must} where @code{$NAME} is the +name of the template and @code{$LANG} is the 2-letter language code of the +template. English templates must exist and will be used as a fallback. If the +browser (user-agent) has provided language preferences in the HTTP header and +the respective language exists, the correct language will be automatically +served. + +The following subsections give details about each of the templates. The +subsection titles are the @code{$NAME} of the respective template. @menu -* Fund the reserve:: -* Authorize a tip:: -* Picking up of the tip:: +* request_payment:: +* offer_refund:: +* show_order_details:: @end menu -@node Fund the reserve,Authorize a tip,,Tipping visitors -@anchor{taler-merchant-manual fund-the-reserve}@anchor{44}@anchor{taler-merchant-manual id15}@anchor{45} -@section Fund the reserve +@node request_payment,offer_refund,,Template Customization +@anchor{taler-merchant-manual request-payment}@anchor{47} +@subsection request_payment -@geindex reserve +Page shown to request the user to make a payment. -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 @code{default} using the demo exchange, use: +This template is instantiated using the following information: -@example -$ taler-merchant-setup-reserve \ - -a KUDOS:10 \ - -e https://exchange.demo.taler.net/ \ - -m http://localhost:8888/instances/default -@end example +@quotation -The above command assumes that the merchant runs on localhost on -port 8888. -For more information, including how to transmit authentication information -to the backend, see manpages/taler-merchant-setup-reserve.1. -The command will output a @code{payto://} URI which specifies where to -wire the funds and which wire transfer subject to use. +@itemize * -FIXME: add full example output. +@item +taler_pay_uri: String; the @code{taler://pay/} URI that must be given +to the wallet to initiate the payment -In our example, the output for the wire transfer subject is: +@item +taler_pay_qrcode_svg: Image; an SVG image of the QR code with the +@code{taler_pay_uri}. -@example -QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG -@end example +@item +order_summary: String; a text summarizing the order -You now need to make a wire transfer to the exchange’s bank account -using the given wire transfer subject. +@item +order_status_url: URL of the merchant backend where the order status +can be found, useful for long-polling to check if the order has been paid +@end itemize +@end quotation -Make your wire transfer and (optionally) check at -“@indicateurl{https://exchange/reserves/QPE24X}…” whether your transfer has arrived at the -exchange. +@node offer_refund,show_order_details,request_payment,Template Customization +@anchor{taler-merchant-manual offer-refund}@anchor{48} +@subsection offer_refund -Once the funds have arrived, you can start to use the reserve for -tipping. -Note that an exchange will typically close a reserve after four weeks, wiring -all remaining funds back to the sender’s account. Thus, you should plan to -wire funds corresponding to a campaign of about two weeks to the exchange -initially. If your campaign runs longer, you should setup another reserve -every other week to ensure one is always ready. +Page shown to offer a customer a refund. -@node Authorize a tip,Picking up of the tip,Fund the reserve,Tipping visitors -@anchor{taler-merchant-manual authorize-a-tip}@anchor{46}@anchor{taler-merchant-manual id16}@anchor{47} -@section Authorize a tip +This template is instantiated using the following information: +@quotation -When your frontend has reached the point where a client is supposed to receive -a tip, it needs to first authorize the tip. For this, the frontend must use -the @code{POST /private/reserves/$RESERVE_PUB/authorize-tip} -API of the backend. To authorize a -tip, the frontend has to provide the following information in the body of the -POST request: +@itemize * -@itemize - +@item +taler_refund_uri: String; the @code{taler://pay/} URI that must be given +to the wallet to initiate the payment @item -The amount of the tip +taler_refund_qrcode_svg: Image; an SVG image of the QR code with the +@code{taler_pay_uri}. @item -The justification (only used internally for the back-office) +refund_amount: Amount; how much did the merchant refund @item -The URL where the wallet should navigate next after the tip was -processed +refund_taken: Amount; how much did the customer already take back in refunds @item -The tip-pickup URL (see next section) +order_summary: String; a text summarizing the order @end itemize +@end quotation -In response to this request, the backend will return a tip token, an -expiration time and the exchange URL. The expiration time will indicate -how long the tip is valid (when the reserve expires). The tip token is -an opaque string that contains all the information needed by the wallet -to process the tip. The frontend must send this tip token to the browser -in a special “402 Payment Required” response inside the @code{X-Taler-Tip} -header. +@node show_order_details,,offer_refund,Template Customization +@anchor{taler-merchant-manual show-order-details}@anchor{49} +@subsection show_order_details -The frontend should handle errors returned by the backend, such as -misconfigured instances or a lack of remaining funds for tipping. -@node Picking up of the tip,,Authorize a tip,Tipping visitors -@anchor{taler-merchant-manual id17}@anchor{48}@anchor{taler-merchant-manual picking-up-of-the-tip}@anchor{49} -@section Picking up of the tip +Page shown to the user when they go back to the payment page but +no payment is required and no refund is present. +This template is instantiated using the following information: -The wallet will POST a JSON object to the shop’s -@code{POST /tips/$TIP_ID/pickup} handler. -The frontend must then forward this request to the backend. The response -generated by the backend can then be forwarded directly to the wallet. +@quotation -@node Advanced topics,Advanced experimental features,Tipping visitors,Top -@anchor{taler-merchant-manual advanced-topics}@anchor{4a} -@chapter Advanced topics +@itemize * -@menu -* Database Scheme:: -* Configuration format: Configuration format<2>. +@item +order_summary: String; a text summarizing the order -@end menu +@item +contract_terms: Object; the full contract terms (shoud probably +not be shown in full!) -@node Database Scheme,Configuration format<2>,,Advanced topics -@anchor{taler-merchant-manual database-scheme}@anchor{4b}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{4c} -@section Database Scheme +@item +refund_amount: Amount; how much did the merchant refund +@item +refund_taken: Amount; how much did the customer already take back in refunds +@end itemize +@end quotation -The merchant database must be initialized using @code{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, -@code{taler-merchant-dbinit} has a function to garbage collect a database, -allowing administrators to purge records that are no longer required. +@node Static files,Internationalization,Template Customization,Customization +@anchor{taler-merchant-manual static-files}@anchor{4a} +@section Static files -The database scheme used by the merchant looks as follows: -@image{taler-merchant-figures/merchant-db,,,,png} +The merchant backend also has the ability to serve small static files +under the @code{/static/@{FILENAME@}} endpoint. This is used by the templating +logic to load a CSS file, but you can also put other resources such as +images or JavaScript. -@node Configuration format<2>,,Database Scheme,Advanced topics -@anchor{taler-merchant-manual id18}@anchor{4d} -@section Configuration format +@node Internationalization,Limitations,Static files,Customization +@anchor{taler-merchant-manual internationalization}@anchor{4b} +@section Internationalization -@geindex configuration +Both templates and static files can be internationalized. This is done +by having the language of the resource be a part of the filename. +For templates the format is @code{@{BASENAME@}.@{LANGUAGE@}.must}. The +language is mandatory for templates, the default language is English (en). -In Taler realm, any component obeys to the same pattern to get -configuration values. According to this pattern, once the component has -been installed, the installation deploys default values in -@code{$@{prefix@}/share/taler/config.d/}, in @code{.conf} files. In order to override -these defaults, the user can write a custom .conf file and either pass -it to the component at execution time, or name it @code{taler.conf} and place -it under @code{$HOME/.config/}. +For static files, the format is @code{@{BASENAME@}.@{LANGUAGE@}.@{EXT@}} for +internationalized files, and @code{@{BASENAME@}.@{EXT@}} for resources that do not +support internationalization. The HTTP client will always request +@code{/static/@{BASENAME@}.@{EXT@}}. If @code{@{BASENAME@}.@{EXT@}} exists, that resource is +returned. Otherwise, an internationalized file based on the language +preferences indicated by the browser is returned. -A config file is a text file containing sections, and each section -contains its values. The right format follows: +@node Limitations,,Internationalization,Customization +@anchor{taler-merchant-manual limitations}@anchor{4c} +@section Limitations -@example -[section1] -value1 = string -value2 = 23 -[section2] -value21 = string -value22 = /path22 -@end example +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 @code{ulimit} of the @code{taler-merchant-httpd} process if you have +many static files. Note that Mustach templates do not increase the number of +open files. -Throughout any configuration file, it is possible to use @code{$}-prefixed -variables, like @code{$VAR}, especially when they represent filesystem -paths. It is also possible to provide defaults values for those -variables that are unset, by using the following syntax: -@code{$@{VAR:-default@}}. However, there are two ways a user can set -@code{$}-prefixable variables: +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 +formats. -by defining them under a @code{[paths]} section, see example below, +The current backend only provides a limited set of variables for the Mustach +template expansion, and does not make use of scopes and other Mustach +features. -@example -[paths] -TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data -... -[section-x] -path-x = $@{TALER_DEPLOYMENT_SHARED@}/x -@end example +@node Upgrade procedure,Advanced topics,Customization,Top +@anchor{taler-merchant-manual upgrade-procedure}@anchor{4d} +@chapter Upgrade procedure -or by setting them in the environment: -@example -$ export VAR=/x -@end example +This section describes the general upgrade procedure. Please see the release +notes for your specific version to check if a particular release has special +upgrade requirements. -The configuration loader will give precedence to variables set under -@code{[path]}, though. +Please note that upgrades are ONLY supported for released version of the +merchant. Attempting to upgrade from or to a version in Git is not supported +and may result in subtle data loss. -The utility @code{taler-config}, which gets installed along with the -exchange, serves to get and set configuration values without directly -editing the @code{.conf}. The option @code{-f} is particularly useful to resolve -pathnames, when they use several levels of @code{$}-expanded variables. See -@code{taler-config --help}. +To safely upgrade the merchant, you should first stop the existing +@code{taler-merchant-httpd} process, backup your merchant database (see +PostgreSQL manual), and then install the latest version of the code. -Note that, in this stage of development, the file -@code{$HOME/.config/taler.conf} can contain sections for @emph{all} the -components. For example, both an exchange and a bank can read values from -it. +If you REVOKED database permissions, ensure that the rights to CREATE, +DROP, and ALTER tables are GRANTed to @code{$USER} again. Then, run: -The deployment repository@footnote{https://git.taler.net/deployment} contains examples of -configuration file used in our demos. See under @code{deployment/config}. +@example +$ taler-merchant-dbinit +@end example -@quotation +to upgrade the database to the latest schema. After that, you may again +REVOKE the database permissions. Finally, restart the merchant services +processes, either via your systemd or init system, or directly. -@strong{Note} +@node Advanced topics,Temporarily Abandoned Features,Upgrade procedure,Top +@anchor{taler-merchant-manual advanced-topics}@anchor{4e} +@chapter Advanced topics -Expectably, some components will not work just by using default -values, as their work is often interdependent. For example, a -merchant needs to know an exchange URL, or a database name. -@end quotation @menu -* Using taler-config: Using taler-config<2>. +* taler-config:: +* Using taler-config:: +* Database Scheme:: +* Benchmarking:: @end menu -@node Using taler-config<2>,,,Configuration format<2> -@anchor{taler-merchant-manual id19}@anchor{4e}@anchor{taler-merchant-manual using-taler-002dconfig}@anchor{4f} -@subsection Using taler-config +@node taler-config,Using taler-config,,Advanced topics +@anchor{taler-merchant-manual taler-config}@anchor{4f} +@section taler-config @geindex taler-config -The tool @code{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. +@node Using taler-config,Database Scheme,taler-config,Advanced topics +@anchor{taler-merchant-manual using-taler-config}@anchor{50} +@section Using taler-config + + +The tool @code{taler-config} can be used to extract or manipulate configuration +values; however, the configuration use the well-known INI file format and is +generally better edited by hand to preserve comments and structure. Thus, @code{taler-config} should primarily be used +to inspect or understand a configuration that is in place, +and not to update it! -Run: +Run @example $ taler-config -s $SECTION @@ -2103,260 +2315,140 @@ $ taler-config -s $SECTION to list all of the configuration values in section @code{$SECTION}. -Run: +Run @example -$ taler-config -s $section -o $option +$ taler-config -s $SECTION -o $OPTION @end example -to extract the respective configuration value for option @code{$option} in -section @code{$section}. +to extract the respective configuration value for option @code{$OPTION} in +section @code{$SECTION}. -Finally, to change a setting, run: +Finally, to change a setting and clobber your entire +configuration file structure, inlining all values and +removing all comments, run @example -$ taler-config -s $section -o $option -V $value +$ taler-config -s $SECTION -o $OPTION -V $VALUE @end example -to set the respective configuration value to @code{$value}. Note that you -have to manually restart the Taler backend after you change the +to set the respective configuration value to @code{$VALUE}. Note that you +have to manually restart affected Taler components after you change the configuration to make the new configuration go into effect. -Some default options will use @code{$}-variables, such as @code{$DATADIR} within -their value. To expand the @code{$DATADIR} or other @code{$}-variables in the +Some default options will use $-variables, such as @code{$DATADIR} within +their value. To expand the @code{$DATADIR} or other $-variables in the configuration, pass the @code{-f} option to @code{taler-config}. For example, compare: @example -$ taler-config -s PATHS \ - -o TALER_DATA_HOME -$ taler-config -f -s PATHS \ - -o TALER_DATA_HOME +$ taler-config --section exchange-offline --option MASTER_PRIV_FILE +$ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE @end example While the configuration file is typically located at -@code{$HOME/.config/taler.conf}, an alternative location can be specified -to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} -option. +@code{$HOME/.config/taler.conf}, an alternative location can be specified to any +GNU Taler component using the @code{-c} option. -@node Advanced experimental features,Temporarily Abandoned Features,Advanced topics,Top -@anchor{taler-merchant-manual advanced-experimental-features}@anchor{50} -@chapter Advanced experimental features +@node Database Scheme,Benchmarking,Using taler-config,Advanced topics +@anchor{taler-merchant-manual database-scheme}@anchor{51}@anchor{taler-merchant-manual merchantdatabasescheme}@anchor{52} +@section Database Scheme -This section describes features that most merchants will not -need, or will not need initially. +The merchant database must be initialized using @code{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, +@code{taler-merchant-dbinit} has a function to garbage collect a database, +allowing administrators to purge records that are no longer required. -@menu -* Benchmarking:: -* Benchmark setup:: -* Running the benchmark command:: +The database scheme used by the merchant looks as follows: -@end menu +@image{taler-merchant-figures/merchant-db,,,,png} -@node Benchmarking,Benchmark setup,,Advanced experimental features -@anchor{taler-merchant-manual benchmarking}@anchor{51}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{52} +@node Benchmarking,,Database Scheme,Advanced topics +@anchor{taler-merchant-manual benchmarking}@anchor{53}@anchor{taler-merchant-manual merchantbenchmarking}@anchor{54} @section Benchmarking -The merchant codebase offers the @code{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 provides them all -the input to accomplish payments. Note that each component will use its -own configuration (as they would do in production). - -The main goal of the benchmarking tool is to serve as a starting point (!) for -merchants that are interested in developing stress tests to see how far their -infrastructure can scale. - -The current tool has already a few options, but we expect that to deliver -@emph{relevant} results it will need to be customized to better reflect the -workload of a particular merchant. This customization would at this point -likely involve writing (C) code. We welcome contributions to make it easier -to customize the benchmark and/or to cover more realistic workloads from the -start. - -@node Benchmark setup,Running the benchmark command,Benchmarking,Advanced experimental features -@anchor{taler-merchant-manual benchmark-setup}@anchor{53} -@section Benchmark setup +The merchant codebase offers the @code{taler-merchant-benchmark} tool to populate +the database with fake payments. The main goal of the benchmarking tool is to +serve as a starting point (!) for merchants that are interested in developing +stress tests to see how far their infrastructure can scale. As is, it +currently is not actually good at stressing the payment system. +The @code{taler-unified-setup.sh} script can be used to launch all required +services and clients. However, the resulting deployment is simplistic +(everything on the local machine, one single-threaded process per service +type) and not optimized for performance at all. However, this can still be +useful to assess the performance impact of changes +to the code or configuration. -The @code{taler-merchant-benchmark} tool will automatically launch and configure the -exchange, (Python) bank and other tools required for the benchmark. However, -the configuration file must be provided and have consistent options set. The -options that require special care include the exchange’s public key (which -must match the private key in the file specified by the configuration), the -currency (which must be consistent across the file), the denomination -structure (which must enable payments in the range of 100ths of the unit -currency (often called cents)). Furthermore, the benchmark will set the -Exchange bank account password to be “x”, so the configuration must also -specify “x” for the passphrase. Finally, the bank must be configured to allow -for substantial debt least the transactions by the benchmark run out of -digital cash. +Various configuration files that can be used in the code snippets in this +section can be found in the @code{src/merchant-tools/} directory of the +merchant. These are generally intended as starting points. Note that the +configuration files ending in @code{.edited} are created by +@code{taler-unified-setup.sh} and contain some options that are determined at +runtime by the setup logic provided by @code{taler-unified-setup.sh}. -A relatively minimal configuration could look like this: +See Taler Exchange Manual for how to use @code{taler-unified-setup.sh} to setup the system and in particular on how to specify the bank to be used. -@example -[PATHS] -# Persistent data storage for the benchmark -TALER_TEST_HOME = benchmark_home/ - -[taler] -# If you change the currency here, you MUST change it -# throughout the file. -CURRENCY = EUR -CURRENCY_ROUND_UNIT = EUR:0.01 - -[merchant] -SERVE = tcp -PORT = 8080 -DB = postgres +@menu +* Running taler-merchant-benchmark:: -[merchantdb-postgres] -CONFIG = postgres:///talercheck +@end menu -[exchange] -DB = postgres -SERVE = tcp -PORT = 8081 -BASE_URL = http://localhost:8081/ -MASTER_PUBLIC_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG +@node Running taler-merchant-benchmark,,,Benchmarking +@anchor{taler-merchant-manual running-taler-merchant-benchmark}@anchor{55} +@subsection Running taler-merchant-benchmark -[exchangedb-postgres] -CONFIG = postgres:///talercheck -[auditor] -DB = postgres -SERVE = tcp -PORT = 8083 -BASE_URL = http://the.auditor/ - -[auditordb-postgres] -CONFIG = postgres:///talercheck - -[bank] -DATABASE = postgres:///talerbank -SERVE = http -HTTP_PORT = 8082 -MAX_DEBT = EUR:5000.0 -MAX_DEBT_BANK = EUR:0.0 - -[merchant-exchange-test] -MASTER_KEY = T1VVFQZZARQ1CMF4BN58EE7SKTW5AV2BS18S87ZEGYS4S29J6DNG -EXCHANGE_BASE_URL = http://localhost:8081/ -CURRENCY = EUR - -[exchange-account-exchange] -# The account name MUST be 'Exchange' -PAYTO_URI = payto://x-taler-bank/localhost/Exchange -WIRE_RESPONSE = $@{TALER_CONFIG_HOME@}/exchange/account.json -WIRE_GATEWAY_URL = http://localhost:8082/taler-wire-gateway/Exchange/ -WIRE_GATEWAY_AUTH_METHOD = basic -USERNAME = Exchange -# The password MUST be 'x' -PASSWORD = x -ENABLE_DEBIT = YES -ENABLE_CREDIT = YES - -[fees-x-taler-bank] -WIRE-FEE-2020 = EUR:0.01 -WIRE-FEE-2021 = EUR:0.01 -WIRE-FEE-2022 = EUR:0.01 -WIRE-FEE-2023 = EUR:0.01 -WIRE-FEE-2024 = EUR:0.01 -WIRE-FEE-2025 = EUR:0.01 -WIRE-FEE-2026 = EUR:0.01 -WIRE-FEE-2027 = EUR:0.01 -CLOSING-FEE-2020 = EUR:0.01 -CLOSING-FEE-2021 = EUR:0.01 -CLOSING-FEE-2022 = EUR:0.01 -CLOSING-FEE-2023 = EUR:0.01 -CLOSING-FEE-2024 = EUR:0.01 -CLOSING-FEE-2025 = EUR:0.01 -CLOSING-FEE-2026 = EUR:0.01 -CLOSING-FEE-2027 = EUR:0.01 - -[coin_eur_ct_1] -value = EUR:0.01 -duration_withdraw = 7 days -duration_spend = 2 years -duration_legal = 3 years -fee_withdraw = EUR:0.00 -fee_deposit = EUR:0.00 -fee_refresh = EUR:0.01 -fee_refund = EUR:0.01 -rsa_keysize = 1024 - -[coin_eur_ct_10] -value = EUR:0.10 -duration_withdraw = 7 days -duration_spend = 2 years -duration_legal = 3 years -fee_withdraw = EUR:0.01 -fee_deposit = EUR:0.01 -fee_refresh = EUR:0.03 -fee_refund = EUR:0.01 -rsa_keysize = 1024 - -[coin_eur_1] -value = EUR:1 -duration_withdraw = 7 days -duration_spend = 2 years -duration_legal = 3 years -fee_withdraw = EUR:0.01 -fee_deposit = EUR:0.01 -fee_refresh = EUR:0.03 -fee_refund = EUR:0.01 -rsa_keysize = 1024 - -[coin_eur_5] -value = EUR:5 -duration_withdraw = 7 days -duration_spend = 2 years -duration_legal = 3 years -fee_withdraw = EUR:0.01 -fee_deposit = EUR:0.01 -fee_refresh = EUR:0.03 -fee_refund = EUR:0.01 -rsa_keysize = 1024 +You can run the tool as follows: +@example +$ CONF=benchmark-rsa.conf +$ taler-unified-setup.sh -emwt -c "$CONF" -f -u exchange-account-1 +$ time taler-merchant-benchmark ordinary -c "$CONF".edited -u exchange-account-1 -f -p 20 @end example -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 set up. -For details, see the Exchange Operator Manual. - -@node Running the benchmark command,,Benchmark setup,Advanced experimental features -@anchor{taler-merchant-manual running-the-benchmark-command}@anchor{54} -@section Running the benchmark command - +The current tool has already a few options, but we expect that to deliver +`relevant' results it will need to be customized to better reflect the +workload of a particular merchant. This customization would at this point +likely involve writing (C) code. We welcome contributions to make it easier +to customize the benchmark and/or to cover more realistic workloads from the +start. The tool takes all of the values it needs from the command line, with -one of them being mandatory: +some of them being common to all subcommands: @itemize - @item -@code{--exchange-account=SECTION} Specifies which configuration +@code{--exchange-account-section=SECTION} Specifies which configuration 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 @code{exchange-account-exchange}. + +@item +@code{--fakebank} Specifies that the benchmark should expect to interact +with a fakebank (instead of libeufin). @end itemize -The tool comes with two operation modes: @emph{ordinary}, and @emph{corner}. +The tool comes with two operation modes: `ordinary', and `corner'. The first just executes normal payments, meaning that it uses the default instance and make sure that all payments get aggregated. The second gives the chance to leave some payments unaggregated, and also to 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 +@cartouche +@quotation Note +The ability to drive the aggregation policy is useful for testing the back-office facility. +@end quotation +@end cartouche Any subcommand is also equipped with the canonical @code{--help} option, so feel free to issue the following command in order to explore all the @@ -2366,43 +2458,34 @@ possibilities. For example: $ taler-merchant-benchmark corner --help @end example -will show all the options offered by the @emph{corner} mode. Among the most +will show all the options offered by the `corner' mode. Among the most interesting, there are: @itemize - @item -@code{--two-coins=TC} This option instructs the tool to perform @emph{TC} +@code{--two-coins=TC} This option instructs the tool to perform `TC' many payments that use two coins, because normally only one coin is spent per payment. @item @code{--unaggregated-number=UN} This option instructs the tool to -perform @emph{UN} (one coin) payments that will be left unaggregated. +perform `UN' (one coin) payments that will be left unaggregated. @end itemize As for the @code{ordinary} subcommand, it is worth explaining the following -options: +option: @itemize - @item -@code{--payments-number=PN} Instructs the tool to perform @emph{PN} payments. - -@item -@code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking -operations. Note that the @strong{total} amount of operations will be two -times @emph{TN}, since “one” tracking operation accounts for -@code{/track/transaction} and @code{/track/transfer}. This command should -only be used to see if the operation ends without problems, as no -actual measurement of performance is provided (despite of the -’benchmark’ word used in the tool’s name). +@code{--payments-number=PN} Instructs the tool to perform `PN' payments. @end itemize -@node Temporarily Abandoned Features,Index,Advanced experimental features,Top -@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{55} +@node Temporarily Abandoned Features,Index,Advanced topics,Top +@anchor{taler-merchant-manual temporarily-abandoned-features}@anchor{56} @chapter Temporarily Abandoned Features @@ -2412,7 +2495,7 @@ actual measurement of performance is provided (despite of the @end menu @node Installing Taler using Docker,,,Temporarily Abandoned Features -@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{56} +@anchor{taler-merchant-manual installing-taler-using-docker}@anchor{57} @section Installing Taler using Docker @@ -2424,7 +2507,7 @@ the @code{docker} command should connect to a @code{docker-machine} instance that uses the VirtualBox driver. Therefore, the needed tools are: “docker“, “docker-machine“, and -“docker-compose“. Please refer to Docker’s official @footnote{@w{(1)} +“docker-compose“. Please refer to Docker’s official @footnote{ @indicateurl{https://docs.docker.com/} } documentation in order to get those components installed, as that is not in this @@ -2465,7 +2548,7 @@ To test if everything worked as expected, it suffices to issue a simple request to the merchant, for example: @example -$ curl http://$(docker-machine ip)/ +$ wget -O - http://$(docker-machine ip)/ # A greeting message should be returned by the merchant. @end example |
