diff options
98 files changed, 13083 insertions, 3821 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 bb34c9f3..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-dbinit \- setup auditor database . .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-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 @@ -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 c3923c05..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor-exchange \- add or remove exchange from auditor’s list . .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-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 @@ -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 e9c955ad..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" "Aug 08, 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,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-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 @@ -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 eff88afc..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" "Aug 08, 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,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-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 @@ -42,7 +42,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .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. @@ -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 63d5853b..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-auditor \- audit exchange . .nr rst2man-indent-level 0 . @@ -30,12 +27,16 @@ 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\-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] @@ -65,6 +66,10 @@ Print short help on options. Run additional checks that can only performed on the exchange\-internal 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 Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. @@ -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 index a98c9817..37ee9fd8 100644 --- a/man/taler-config.1 +++ b/man/taler-config.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-CONFIG" "1" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-config \- Taler configuration inspection and editing . .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-CONFIG" "1" "Apr 12, 2024" "0.9" "GNU Taler" +.SH NAME +taler-config \- Taler configuration inspection and editing .SH SYNOPSIS .sp \fBtaler\-config\fP @@ -54,7 +54,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] \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 Postgres database backend of the “NAMESTORE” service. If \fIBACKEND\fP is +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 @@ -103,6 +103,7 @@ Must only be given together with \fB\-s\fP and \fB\-o\fP options. .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 @@ -118,6 +119,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-aggregator.1 b/man/taler-exchange-aggregator.1 index 5417b93b..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-aggregator \- aggregate deposits into wire transfers . .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-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 @@ -40,11 +40,16 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] [\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 @@ -71,6 +76,9 @@ Run in test mode and exit when idle. .TP \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 55dc9586..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-benchmark \- measure exchange performance . .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-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 @@ -37,23 +37,19 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] [\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\-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 @@ -63,18 +59,11 @@ that table are always erased during a single benchmark run. 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. +Expect to interact with a fakebank instead of libeufin. .TP \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 Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\fP, \fBWARNING\fP, \fBERROR\fP\&. @@ -82,9 +71,6 @@ Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\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 Defaults to 1. Specifies how many coins this benchmark should withdraw and spend. After being spent, each coin will be refreshed @@ -99,13 +85,17 @@ Defaults to 10. Probability of refresh per coin (0\-100). \fB\-r\fP \fIN\fP | \fB–reserves=\fP\fIN\fP Create \fIN\fP reserves per client. .TP +\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 bac9e75e..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-closer \- close idle reserves . .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-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 @@ -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 55b53573..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-dbinit \- initialize Taler exchange database . .nr rst2man-indent-level 0 . @@ -30,15 +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-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\-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 @@ -49,6 +51,9 @@ Taler exchange to operate. Its options are as follows: .INDENT 0.0 .TP +\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\&. @@ -71,6 +76,9 @@ Send logging output to \fIFILENAME\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 6f6a9722..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-httpd \- run Taler exchange (with RESTful API) . .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-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 @@ -41,6 +41,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] [\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] @@ -98,8 +99,10 @@ Specifies the log level to use. Accepted values are: \fBDEBUG\fP, \fBINFO\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 Modify the system time by \fIUSEC\fP microseconds. @@ -139,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 db10b00e..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" "Aug 08, 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,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-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 @@ -150,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. @@ -211,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 advertize 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 advertized could theoretically differ from that which +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’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, @@ -232,7 +323,7 @@ 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’s (former) bank account must be given as the first argument to the subcommand. @@ -243,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 @@ -259,6 +350,23 @@ 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 @@ -308,6 +416,61 @@ 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) @@ -366,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 @@ -385,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 enable\-account payto://iban/DE24242 > account.json +$ 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 \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 @@ -413,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 @@ -435,14 +644,23 @@ $ 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 @@ -482,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 fb91fde3..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" "Aug 08, 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,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-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 @@ -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 c88af796..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" "Aug 08, 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,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-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 @@ -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 f3c8194c..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-transfer \- execute wire transfers . .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-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 @@ -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-wire-gateway-client.1 b/man/taler-exchange-wire-gateway-client.1 index f03772c5..25d09723 100644 --- a/man/taler-exchange-wire-gateway-client.1 +++ b/man/taler-exchange-wire-gateway-client.1 @@ -1,8 +1,5 @@ .\" Man page generated from reStructuredText. . -.TH "TALER-EXCHANGE-WIRE-GATEWAY-CLIENT" "1" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-wire-gateway-client \- trigger a transfer at the bank . .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-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\-exchange\-wire\-gateway\-client\fP @@ -133,7 +133,7 @@ Specifies a \fIROW\fP from which the history should be obtained. If not given, t .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 35403ed3..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-exchange-wirewatch \- watch for incoming wire transfers . .nr rst2man-indent-level 0 . @@ -30,11 +27,15 @@ 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\-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] @@ -53,9 +54,16 @@ Its options are as follows: Use the configuration and other resources for the exchange to operate from \fIFILENAME\fP\&. .TP +\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\-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\&. @@ -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 6a9007da..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-aggregation \- audit Taler exchange aggregation activity . .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-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 @@ -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 db339baa..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-coins \- audit Taler coin processing . .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-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 @@ -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 44a66bba..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" "Aug 08, 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,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-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 @@ -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 7955b41c..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-helper-auditor-reserves \- audit Taler exchange reserve handling . .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-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 @@ -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 633ef08e..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" "Aug 08, 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,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-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 @@ -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 d3b215f7..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" "Aug 08, 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,20 +43,17 @@ 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 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 @@ -79,8 +76,7 @@ HTTP ‘Authorization’ header to send to the merchant. 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 @@ -98,7 +94,7 @@ 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 05e2ed8b..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-dbinit \- initialize Taler merchant database . .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-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 @@ -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 8060ed7a..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" "Aug 08, 2021" "0.8" "GNU Taler" -.SH NAME -taler-merchant-httpd \- run Taler merchant backend (with RESTful API) . .nr rst2man-indent-level 0 . @@ -30,9 +27,13 @@ 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\-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] @@ -49,9 +50,9 @@ before running this command. .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 +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: Bearer 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 @@ -104,7 +105,7 @@ 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 e038442b..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" "Aug 08, 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 e23421ff..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" "Aug 08, 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,31 +221,88 @@ 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’s 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, @@ -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]”. .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 @@ -236,6 +548,33 @@ 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]”. @@ -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 @@ -334,7 +681,7 @@ Password for \fBbasic\fP authentication with the wire gateway. .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 @@ -372,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 @@ -384,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. @@ -432,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 @@ -471,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 @@ -482,6 +852,78 @@ The following options must be in section “[auditordb\-postgres]” if the 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 taler\-exchange\-dbinit(1), taler\-exchange\-httpd(1), @@ -493,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/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 fb41a174..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.2, Aug 08, 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 @@ -99,12 +97,22 @@ System setup Configuration * Configuration format:: -* Using taler-config:: * Initial configuration:: * Keys:: * 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 @@ -145,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 @@ -165,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 @@ -203,7 +226,7 @@ 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 @@ -276,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. @@ -286,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 @@ -358,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 @@ -367,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 @@ -382,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/}, @@ -406,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: @@ -441,6 +509,13 @@ 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. +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 @@ -448,60 +523,28 @@ previous step. 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 +Debian bookworm. -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 -which combines Debian stable with more recent packages -from testing and unstable 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 -@end example - -Naturally, you may want to use different mirrors depending on your region. -Additionally, you must add a file to import the GNU Taler packages. Typically, +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 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 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/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 @@ -527,13 +570,21 @@ Sample configuration files for the HTTP reverse proxy can be found in 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.d/taler.list} file for this setup -would look like this: +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 https://deb.taler.net/apt/ubuntu/ focal-fossa 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. @@ -542,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/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 @@ -609,7 +661,7 @@ auditor-ingres — imports database from exchange production system auditor-wire — imports wire transfer data from bank production system @item -offline — manages the offline key, on a separate @emph{offline} machine +offline — manages the offline key, on a separate `offline' machine @end itemize @end quotation @@ -632,7 +684,7 @@ distribution would typically create for you): www-data — runs the HTTPS frontend (usually nginx or Apache) @item -postgres — runs the Postgres database +postgres — runs the PostgreSQL database @end itemize @end quotation @@ -662,7 +714,7 @@ libeufin — local state of the auditor-wire tool for the bank transfer data imp @end itemize @end quotation -As the @emph{postgres} user, you can create these databases using: +As the `postgres' user, you can create these databases using: @example # As the 'postgres' user: @@ -696,30 +748,42 @@ This section discusses configuration options related to the auditor. @menu * Configuration format:: -* Using taler-config:: * Initial configuration:: * Keys:: * 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 +@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] @@ -731,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 + + +@enumerate + +@item +by defining them under a @code{[paths]} section: +@end enumerate -by defining them under a @code{[paths]} section, see example below, +@quotation @example [paths] @@ -747,94 +820,37 @@ 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,Initial configuration,Configuration format,Configuration -@anchor{taler-auditor-manual using-taler-config}@anchor{10} -@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. +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. -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: - -@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 Initial configuration,Keys,Using taler-config,Configuration -@anchor{taler-auditor-manual initial-configuration}@anchor{11}@anchor{taler-auditor-manual setupbaseurl}@anchor{12} +@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 @@ -843,7 +859,8 @@ REST API of the auditor will be available to the public: @example # Both for the 'offline' *and* the 'auditor' user: -$ taler-config -s auditor -o BASE_URL -V https://auditor.example.com/ +[auditor] +BASE_URL = https://auditor.example.com/ @end example The @code{helper} user that is used to download information from the exchange @@ -855,18 +872,19 @@ and configure these: @example # As the 'helper' and 'offline' users: -$ taler-config -s exchange -o BASE_URL -V https://exchange.example.com/ -$ taler-config -s exchange -o MASTER_PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE +[exchange] +BASE_URL = https://exchange.example.com/ +MASTER_PUBLIC_KEY = $SOMELONGBASE32VALUEHERE @end example @node Keys,Configuring the auditor’s REST endpoint,Initial configuration,Configuration -@anchor{taler-auditor-manual auditorkeys}@anchor{13}@anchor{taler-auditor-manual keys}@anchor{14} +@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 +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. @@ -904,11 +922,12 @@ You can set this configuration value using: @example # As the 'auditor' and 'helper' users: -$ taler-config -s auditor -o PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE +[auditor] +PUBLIC_KEY = $SOMELONGBASE32VALUEHERE @end example @node Configuring the auditor’s REST endpoint,Bank account,Keys,Configuration -@anchor{taler-auditor-manual auditorserving}@anchor{15}@anchor{taler-auditor-manual configuring-the-auditor-s-rest-endpoint}@anchor{16} +@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 @@ -936,7 +955,7 @@ for @code{unixpath} (i.e. 660 = @code{rw-rw----}). @end itemize @node Bank account,Database,Configuring the auditor’s REST endpoint,Configuration -@anchor{taler-auditor-manual auditorbank-account}@anchor{17}@anchor{taler-auditor-manual bank-account}@anchor{18} +@anchor{taler-auditor-manual auditorbank-account}@anchor{16}@anchor{taler-auditor-manual bank-account}@anchor{17} @section Bank account @@ -944,8 +963,8 @@ 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{19}@anchor{taler-auditor-manual database}@anchor{1a} +@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 @@ -1000,11 +1019,250 @@ 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{1b}@anchor{taler-auditor-manual deployment}@anchor{1c} +@anchor{taler-auditor-manual auditordeployment}@anchor{22}@anchor{taler-auditor-manual deployment}@anchor{23} @chapter Deployment -@anchor{taler-auditor-manual wallets}@anchor{1d} +@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 @@ -1024,7 +1282,7 @@ FIXME-DOLD: explain how that Web page works, once it works… @end menu @node Exchange,Signing Denominations,,Deployment -@anchor{taler-auditor-manual auditorexchange}@anchor{1e}@anchor{taler-auditor-manual exchange}@anchor{1f} +@anchor{taler-auditor-manual auditorexchange}@anchor{25}@anchor{taler-auditor-manual exchange}@anchor{26} @section Exchange @@ -1049,13 +1307,13 @@ 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{20}@anchor{taler-auditor-manual signingdenominations}@anchor{21} +@anchor{taler-auditor-manual signing-denominations}@anchor{27}@anchor{taler-auditor-manual signingdenominations}@anchor{28} @section Signing Denominations @geindex maintenance -These steps must be performed @emph{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: @@ -1112,17 +1370,17 @@ 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{22}@anchor{taler-auditor-manual id1}@anchor{23} +@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 +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 @@ -1132,7 +1390,7 @@ 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 +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. @@ -1143,7 +1401,7 @@ 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{24} +@anchor{taler-auditor-manual ingres-replication-of-the-exchange-production-database}@anchor{2b} @subsection Ingres replication of the exchange production database @@ -1151,7 +1409,7 @@ 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 Postgres. It is +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 @@ -1160,7 +1418,7 @@ 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 @@ -1177,14 +1435,14 @@ $ 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 buisness unit name. A secure tunnel +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} Postgres configuaration (the port +the following lines are in the @code{main.cf} PostgreSQL configuration (the port may differ) to enable replication over the network: @example @@ -1194,7 +1452,7 @@ wal_level= logical @end example Equally, the auditor must configure logical replication in the @code{main.cf} -Postgres configuaration: +PostgreSQL configuration: @example wal_level= logical @@ -1204,9 +1462,15 @@ Next, the @code{postgres} user of the auditor’s system must first initialize t 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-config -s exchange -o DB -V "postgres" -$ taler-config -s exchangedb-postgres -o CONFIG -V "postgres:///taler-ingress" $ taler-exchange-dbinit @end example @@ -1220,7 +1484,7 @@ $ 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 Postgres manual. +For details, we refer to the PostgreSQL manual. @cartouche @quotation Note @@ -1229,15 +1493,15 @@ 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 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{25} +@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 @@ -1254,7 +1518,7 @@ 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 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 +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. @@ -1270,9 +1534,15 @@ To run @code{taler-auditor-sync}, you must first configure two configuration files that identify the source and destination databases: @example -# As the 'sync' user: -$ taler-config -c src.conf -s exchangedb -o CONFIG -V "postgres:///auditor-ingres/" -$ taler-config -c dst.conf -s exchangedb -o CONFIG -V "postgres:///auditor/" +# 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 @@ -1295,7 +1565,7 @@ 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{26}@anchor{taler-auditor-manual operation}@anchor{27} +@anchor{taler-auditor-manual id2}@anchor{2d}@anchor{taler-auditor-manual operation}@anchor{2e} @chapter Operation @@ -1311,7 +1581,7 @@ at the same time when the exchange runs its garbage collection. @end menu @node Web service,Audit,,Operation -@anchor{taler-auditor-manual id3}@anchor{28}@anchor{taler-auditor-manual web-service}@anchor{29} +@anchor{taler-auditor-manual id3}@anchor{2f}@anchor{taler-auditor-manual web-service}@anchor{30} @section Web service @@ -1328,7 +1598,7 @@ 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{2a}@anchor{taler-auditor-manual id4}@anchor{2b} +@anchor{taler-auditor-manual audit}@anchor{31}@anchor{taler-auditor-manual id4}@anchor{32} @section Audit @@ -1363,7 +1633,7 @@ 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{2c} +@anchor{taler-auditor-manual reading-the-report}@anchor{33} @section Reading the report @@ -1399,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{2d}@anchor{taler-auditor-manual database-upgrades}@anchor{2e} +@anchor{taler-auditor-manual auditordatabaseupgrades}@anchor{34}@anchor{taler-auditor-manual database-upgrades}@anchor{35} @section Database upgrades @@ -1425,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 @@ -1454,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{2f} +@anchor{taler-auditor-manual database-reset}@anchor{36} @section Database reset @@ -1465,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{30}@anchor{taler-auditor-manual revocations}@anchor{31} +@anchor{taler-auditor-manual auditorrevocations}@anchor{37}@anchor{taler-auditor-manual revocations}@anchor{38} @section Revocations @@ -1490,7 +1760,7 @@ 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{32} +@anchor{taler-auditor-manual failures}@anchor{39} @section Failures @@ -1502,12 +1772,12 @@ 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 @@ -1516,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{33} +@anchor{taler-auditor-manual auditor-implementation-guide}@anchor{3a} @chapter Auditor implementation guide @@ -1555,7 +1825,7 @@ JSON reports into LaTeX and then into PDF. @end menu @node The auditor’s database,Invariants checked by the auditor,,Auditor implementation guide -@anchor{taler-auditor-manual the-auditor-s-database}@anchor{34} +@anchor{taler-auditor-manual the-auditor-s-database}@anchor{3b} @section The auditor’s database @@ -1564,7 +1834,7 @@ 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{35} +@anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{3c} @section Invariants checked by the auditor @@ -1584,7 +1854,7 @@ 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{36} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-aggregation}@anchor{3d} @subsection Invariants checked by the taler-helper-auditor-aggregation @@ -1696,7 +1966,7 @@ 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{37} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-coins}@anchor{3e} @subsection Invariants checked by the taler-helper-auditor-coins @@ -1792,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{38} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-deposits}@anchor{3f} @subsection Invariants checked by the taler-helper-auditor-deposits @@ -1802,7 +2072,7 @@ 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{39} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-reserves}@anchor{40} @subsection Invariants checked by the taler-helper-auditor-reserves @@ -1863,12 +2133,12 @@ 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{3a} +@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 +`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. @@ -1928,7 +2198,7 @@ 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{3b} +@anchor{taler-auditor-manual testing-the-auditor}@anchor{42} @section Testing the auditor 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 ef7e1d05..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 1a90b590..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.2, Aug 08, 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{taler-bank-manual tsref-type-BankRegistrationRequest}@w{ } -@anchor{8}@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.texi b/texinfo/taler-developer-manual.texi index 4896a6ff..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.2, Aug 08, 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,7 +48,7 @@ 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 Affero General Public License as published by the Free Software @@ -65,17 +63,26 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @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’ - -@item -[ ] make dist, make check on result of ‘make dist’. - -@item -[ ] Change version number in configure.ac. +There are other important repositories without code, including: -@item -[ ] make dist for release. +@quotation -@item -[ ] tag repo. -@item -[ ] Upload triplet to ftp-upload.gnu.org/incoming/ftp or /incoming/alpha +@itemize * @item -[ ] Update bug tracker (mark release, resolved -> closed) +gana: Hosted on git.gnunet.org, this repository defines various +constants used in the GNU Taler project. @item -[ ] Send announcement to @email{taler@@gnu.org} +docs: documentation, including this very document. @item -[ ] Send announcement to @email{info-gnu@@gnu.org} (major releases only) +marketing: various presentations, papers and other resources for +outreach. @item -[ ] Send announcement to @email{coordinator@@translationproject.org} -@end itemize - -For bank: - - -@itemize - +large-media: very large data objects, such as videos. @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. -Post-upgrade checks: +@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 -@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 +This is because, at the moment, there is no support for +doing these steps automatically in the @code{make check} flow. -Donation demo: +(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,7 +346,7 @@ 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 @@ -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 + +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 + +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 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. - -Before deploying on @code{demo}, the same version of all components @strong{must} -be deployed @emph{and} tested on @code{int}. - -Please use the @ref{4,,demo upgrade checklist} to make +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:: + +@end menu + +@node Domains,Post-upgrade checks,,GNU Taler Demo Upgrade Checklist +@anchor{taler-developer-manual domains}@anchor{18} +@subsection Domains -@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 -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. +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. -@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 +@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{$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). -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 @@ -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,51 +1282,8 @@ $ 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 - - -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. - -@example -# Log-in as the 'demo-checker' user - -$ cd $HOME -$ git clone git://git.taler.net/deployment -$ ./deployment/bootstrap-demochecker - -# If the previous step worked, the setup is -# complete and the Buildbot worker can be started. - -$ 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 - - -Both ‘test’ and ‘demo’ setups get their tip reserve topped up -by a Buildbot worker. The following steps get the reserve topper -prepared. - -@example -# Log-in as <env>-topper, with <env> being either 'test' or 'demo' - -$ git clone git://git.taler.net/deployment -$ ./deployment/prepare-reservetopper <env> - -# If the previous steps worked, then it should suffice to start -# the worker, with: - -$ 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} +@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 @@ -901,7 +1295,7 @@ prepared. # Log-in as <env>-auditor, with <env> being either 'test' or 'demo' $ git clone git://git.taler.net/deployment -$ ./deployment/prepare-auditorreporter <env> +$ ./deployment/buildbot/bootstrap-scripts/prepare-auditorreporter <env> # If the previous steps worked, then it should suffice to start # the worker, with: @@ -910,12 +1304,12 @@ $ buildbot-worker start worker/ @end example @node Database schema versioning,,Producing auditor reports,Environments and Builders on taler net -@anchor{taler-developer-manual database-schema-versioning}@anchor{1f} +@anchor{taler-developer-manual database-schema-versioning}@anchor{2a}@anchor{taler-developer-manual databaseversioning}@anchor{5} @section Database schema versioning -The Postgres databases of the exchange and the auditor are versioned. -See the 0000.sql file in the respective directory for documentation. +The PostgreSQL databases of the exchange and the auditor are versioned. +See the @code{versioning.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 @@ -923,15 +1317,523 @@ any release (or version being deployed to a production or staging environment), existing scripts MUST be immutable. Developers and operators MUST NOT make changes to database schema -outside of this versioning. +outside of this versioning. All tables of a GNU Taler component should live in their own schema. + +@node QA Plans,Releases,Environments and Builders on taler net,Top +@anchor{taler-developer-manual qa-plans}@anchor{2b} +@chapter QA Plans + + +@menu +* Taler 0.9.4 QA Plan: Taler 0 9 4 QA Plan. + +@end menu + +@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 + + +@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:: + +@end menu -@node Releases,Continuous integration,Environments and Builders on taler net,Top -@anchor{taler-developer-manual releases}@anchor{20} +@node Wallet Platforms,Running Deployments,,Taler 0 9 4 QA Plan +@anchor{taler-developer-manual wallet-platforms}@anchor{2d} +@subsection Wallet Platforms + + +Platforms listed here are the officially supported platforms for this release. + + +@itemize * + +@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 + +@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 + + +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 -Please use the @ref{1,,release checklist} 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 +taler-mdb (taler-mdb.git) @item -talerblog (blog.git) +libeufin (libeufin.git) @item -taler-bank (bank.git) +challenger (challenger.git) @item -taler-wallet-webex (wallet-webex.git) +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,25 +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 -The Taler merchant backend stores private keys and other sensitive -business and customer data in the database. The backend operator -SHOULD ensure that backup operations are encrypted and secured from -unauthorized access. +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 @@ -1065,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 @@ -1079,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 @@ -1091,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 @@ -1113,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 @@ -1148,8 +2432,8 @@ for that. There is also the possibility to trigger builds manually, but this is 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 @@ -1170,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 @@ -1187,84 +2471,84 @@ 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 Affero 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. @@ -1273,18 +2557,18 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}: 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 @@ -1292,8 +2576,72 @@ weblate.taler.net signs GPG commits with the GPG key CD33CE35801462FA5EB0B695F26 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 Android Apps,Code Coverage,Internationalization,Top -@anchor{taler-developer-manual android-apps}@anchor{32} +@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,iOS Apps,Top +@anchor{taler-developer-manual android-apps}@anchor{50} @chapter Android Apps @@ -1306,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 @@ -1351,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 @@ -1443,7 +2791,7 @@ 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 @@ -1477,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 @@ -1508,7 +2856,7 @@ $ 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 @@ -1532,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 @@ -1554,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 @@ -1564,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 @@ -1599,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 @@ -1760,7 +3110,7 @@ must be called “perf_module-under-test_case-description.c” @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 @@ -1787,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 @@ -1807,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 @@ -1824,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 @@ -1845,8 +3195,22 @@ are useful: 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 @@ -1854,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. @@ -1872,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. @@ -1911,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. @@ -1919,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 @@ -1933,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 @@ -1945,27 +3309,34 @@ 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. @@ -1975,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 @@ -1993,7 +3364,7 @@ See Payment Replay. Too ambiguous in the wallet. -@strong{Use instead}: Purchase +`Use instead': Purchase @item Fulfillment URL @@ -2002,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 @@ -2054,7 +3425,7 @@ 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 @@ -2063,171 +3434,137 @@ 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 - -@itemx refresh commitment +@item coin -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} +@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 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 @@ -2238,385 +3575,346 @@ 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 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 @@ -2624,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 8872a3c0..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.2, Aug 08, 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,7 +48,7 @@ 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 Affero General Public License as published by the Free Software @@ -64,15 +62,25 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @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,70 +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 -The Taler merchant backend stores private keys and other sensitive -business and customer data in the database. The backend operator -SHOULD ensure that backup operations are encrypted and secured from -unauthorized access. +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: @@ -264,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 @@ -272,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 @@ -289,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 @@ -308,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. @@ -318,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 @@ -361,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 @@ -382,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 @@ -411,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 @@ -425,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. @@ -442,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: + + +@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). -Please install the following packages before proceeding with the -exchange compilation. +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 @@ -491,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 @@ -506,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. +If you are on Debian stable or later, the following command may help you +install these dependencies: -@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 - - -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: @@ -560,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: @@ -577,67 +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 -which combines Debian stable with more recent packages -from testing and unstable 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 -@end example - -Naturally, you may want to use different mirrors depending on your region. -Additionally, you must add a file to import the GNU Taler packages. Typically, +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 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 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/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 @@ -647,7 +867,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install -t sid taler-exchange +[root@@exchange-online]# apt install taler-exchange @end example Note that the package does not perform any configuration work except for @@ -656,23 +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 Ubuntu,,Installing the GNU Taler binary packages on Debian,Installation -@anchor{taler-exchange-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{10} +@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 + + +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.d/taler.list} file for this setup -would look like this: +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 https://deb.taler.net/apt/ubuntu/ focal-fossa 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. @@ -681,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/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 @@ -697,7 +939,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install -t focal-fossa taler-exchange +[root@@exchange-online]# apt install taler-exchange @end example Note that the package does not perform any configuration work except for @@ -706,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 -@itemize - + +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 * @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 + +@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 +[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 -Given this database configuration, the database can be initialized using: +Finally we need to grant the other accounts limited access: @example -$ taler-exchange-dbinit +[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 -Commands, like @code{taler-exchange-dbinit}, that support the @code{-l LOGFILE} -command-line option, send logging output to standard error by default. -@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} +@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 + +@menu +* Coins (denomination keys): Coins denomination keys. +* Sign keys:: +* Setting up the offline signing key:: + +@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_} @@ -1009,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? @@ -1040,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: @@ -1085,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 @@ -1123,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:: + +@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 -@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 +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: @@ -1227,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} @@ -1238,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 @@ -1259,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. -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: +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 * + +@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 + +@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} + +@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 -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 + + +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,Testing a deployment,Configuration<2>,Top -@anchor{taler-exchange-manual deployment}@anchor{29}@anchor{taler-exchange-manual id11}@anchor{2a} +@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 @@ -1372,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 @@ -1390,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 @@ -1430,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 + +@cartouche +@quotation Note +At this point, the exchange service is not yet fully operational. +@end quotation +@end cartouche + +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. -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). +@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 -Next, the @emph{future} key material should be downloaded using: +@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: @@ -1458,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. +@geindex wire fee + +@geindex fee -The exchange database can be re-initialized using: +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 @@ -1544,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}. @@ -1556,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. -@node Diagnostics,Benchmarking,Testing a deployment,Top -@anchor{taler-exchange-manual diagnostics}@anchor{35}@anchor{taler-exchange-manual id15}@anchor{36} -@chapter Diagnostics +@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. -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. +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. + +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 + +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 @@ -1600,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. @@ -1610,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 @@ -1626,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.texi b/texinfo/taler-merchant-api-tutorial.texi index a0b32006..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.2, Aug 08, 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,7 +47,7 @@ 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 Affero General Public License as published by the Free Software @@ -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 @@ -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,7 +540,7 @@ 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). @@ -552,7 +548,7 @@ 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 +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 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_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 5c5f9e5b..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.2, Aug 08, 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 +* Installing from source:: -* Installation of dependencies:: -* Installing GNUnet:: -* Installing the GNU Taler exchange:: -* Installing the GNU Taler merchant backend:: - -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,12 +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/} 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 to production. +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} @@ -316,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'). + +@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 -@node Accounts,Inventory,Instances,Terminology -@anchor{taler-merchant-manual accounts}@anchor{c} -@section Accounts +@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 account +@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. -@node Inventory,Orders and Contracts,Accounts,Terminology -@anchor{taler-merchant-manual inventory}@anchor{d} +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,Instance Bank Accounts,Terminology +@anchor{taler-merchant-manual inventory}@anchor{e} @section Inventory @@ -366,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 @@ -399,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 @@ -410,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 @@ -445,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 + + +This chapter describes how to install the GNU Taler merchant backend. + +@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:: + +@end menu + +@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 + + +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: -@node Tipping,Reserves,Transfers,Terminology -@anchor{taler-merchant-manual tipping}@anchor{10} -@section Tipping +@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: -@geindex tip +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example -@geindex grant +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA key out-of-band. +@end quotation +@end cartouche -@geindex pick up +Now your system is ready to install the official GNU Taler binary packages +using apt. -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 advertizements. 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. +To install the Taler merchant backend, you can now simply run: -@node Reserves,,Tipping,Terminology -@anchor{taler-merchant-manual reserves}@anchor{11} -@section Reserves +@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. -@geindex reserve +@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 -@geindex close -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. +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. -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. +@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 -@node Installation,How to configure the merchant’s backend,Terminology,Top -@anchor{taler-merchant-manual installation}@anchor{12} -@chapter Installation +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}. -This chapter describes how to install the GNU Taler merchant backend. +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: -@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:: +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example -@end menu +For Ubuntu Mantic use this instead: -@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 +@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. -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. +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: -@menu -* Installation of dependencies:: -* Installing GNUnet:: -* Installing the GNU Taler exchange:: -* Installing the GNU Taler merchant backend:: +@example +# wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example -@end menu +@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 -@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 +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). -The following packages need to be installed before we can compile the +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 @@ -546,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 @@ -561,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. +If you are on Debian stable or later, the following command may help you +install these dependencies: -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 - - -@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: @@ -619,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: @@ -651,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: - - -@itemize - +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. -@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. @@ -698,244 +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 +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. -Package: * -Pin: release l=Debian-Security -Pin-Priority: 1000 -@end example - -A typical @code{/etc/apt/sources.list} file for this setup -which combines Debian stable with more recent packages -from testing and unstable 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 -@end example - -Naturally, you may want to use different mirrors depending on your region. -Additionally, you must 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 https://deb.taler.net/apt/debian sid main -@end example - -Next, you must import the Taler Systems SA public package signing key -into your keyring and update the package lists: +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. -@example -# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add - -# apt update -@end example +@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 -@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 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.d/taler.list} file for this setup -would look like this: - -@example -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/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 - -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] @@ -947,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 + + +@enumerate + +@item +by defining them under a @code{[paths]} section: +@end enumerate -by defining them under a @code{[paths]} section, see example below, +@quotation @example [paths] @@ -963,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. +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. -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 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 @@ -1075,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. @@ -1122,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 @@ -1135,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 @@ -1155,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 @@ -1164,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: @@ -1191,42 +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. - -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. +the PostgreSQL documentation. @cartouche @quotation Note -The Taler merchant backend stores private keys and other sensitive -business and customer data in the database. The backend operator -SHOULD ensure that backup operations are encrypted and secured from -unauthorized access. +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 @@ -1242,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 @@ -1252,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 @@ -1334,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 @@ -1381,26 +1357,48 @@ 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/config +$ wget -O - http://localhost:8888/config @end example should return some basic configuration status data about the service. -Please note that your backend is right now likely globally reachable. You can either: +Please note that your backend might then be globally reachable without +any access control. You can either: @quotation @@ -1408,7 +1406,7 @@ Please note that your backend is right now likely globally reachable. You can e @itemize * @item -Use the @code{--auth=$TOKEN} command-line option 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. +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. @@ -1423,88 +1421,103 @@ 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{/management/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: @@ -1520,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 @@ -1529,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 @@ -1576,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 @@ -1596,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 @@ -1623,511 +1766,548 @@ 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/} and -@code{$BASE_URL/management/} 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}. +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/} or @code{/management/}) +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>. * Apache: Apache<2>. @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 -@} -location /management/ @{ - 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 /management/ @{ - 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] -RewriteRule "/management/" "-" [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 "/management/" "-" [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). -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. +@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 -System administrators are strongly advised to test their access control -setup before going into production! +@node Privacy Policy,Legal policies directory layout,Terms of Service,Customization +@anchor{taler-merchant-manual privacy-policy}@anchor{3f} +@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,Customization +@anchor{taler-merchant-manual legal-policies-directory-layout}@anchor{40} +@section Legal policies directory layout -@node Customization,Upgrade procedure,Secure setup,Top -@anchor{taler-merchant-manual customization}@anchor{3c} -@chapter Customization +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. +@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 -@geindex tipping -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. +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. -There are three basic steps that must happen to tip a visitor. +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 -a POST to @code{/private/reserves/$RESERVE_PUB/authorize-tip}. 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{/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 @@ -2135,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-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. +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. -A relatively minimal configuration could look like this: +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}. -@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 +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. -[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 @@ -2398,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 @@ -2444,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 @@ -2456,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 @@ -2497,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 |
