diff options
Diffstat (limited to 'texinfo/taler-exchange.texi')
| -rw-r--r-- | texinfo/taler-exchange.texi | 183 |
1 files changed, 127 insertions, 56 deletions
diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi index 5251f547..ed44281e 100644 --- a/texinfo/taler-exchange.texi +++ b/texinfo/taler-exchange.texi @@ -21,7 +21,7 @@ @copying @quotation -GNU Taler 0.8.0pre0, Jan 21, 2021 +GNU Taler 0.8.0pre0, Jan 27, 2021 GNU Taler team @@ -70,6 +70,7 @@ Copyright @copyright{} 2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) * Installation:: * Configuration: Configuration<2>. * Deployment:: +* Testing a deployment:: * Diagnostics:: * Benchmarking:: * Index:: @@ -97,6 +98,7 @@ Installation * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: Configuration @@ -515,6 +517,7 @@ manager. @menu * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: @end menu @@ -565,7 +568,7 @@ which requires you to run the last step as @code{root}. You have to specify @code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the previous step. -@node Installing the GNU Taler binary packages on Debian,,Installing from source,Installation +@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} @section Installing the GNU Taler binary packages on Debian @@ -612,7 +615,67 @@ 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-sign add - +# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems key out-of-band. +@end quotation +@end cartouche + +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 taler-exchange +@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), 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/}. + +@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} +@section Installing the GNU Taler binary packages on Ubuntu + + +To install the GNU Taler Ubuntu packages, first ensure that you have +the right Ubuntu distribution. At this time, the packages are built for +Ubuntu 20.04 LTS (Focal Fossa). + +A typical @code{/etc/apt/sources.list} file for this setup +would look like this: + +@example +deb http://ch.archive.ubuntu.com/ubuntu/ focal main restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates main restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-security main restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal universe restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates universe restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-security universe restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal multiverse restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates multiverse restricted +deb http://ch.archive.ubuntu.com/ubuntu/ focal-security multiverse restricted + +deb https://deb.taler.net/apt/ubuntu/ focal-fossa main +@end example + +The last line is crucial, as it adds the GNU Taler packages. + +Next, you must import the Taler Systems SA public package signing key +into your keyring and update the package lists: + +@example +# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-sign add - # apt update @end example @@ -641,7 +704,7 @@ Sample configuration files for the HTTP reverse proxy can be found in @code{/etc/taler-exchange/}. @node Configuration<2>,Deployment,Installation,Top -@anchor{taler-exchange-manual id1}@anchor{10} +@anchor{taler-exchange-manual id1}@anchor{11} @chapter Configuration @@ -665,7 +728,7 @@ of some of the options. @end menu @node Configuration format,Using taler-config,,Configuration<2> -@anchor{taler-exchange-manual configuration-format}@anchor{11} +@anchor{taler-exchange-manual configuration-format}@anchor{12} @section Configuration format @@ -740,7 +803,7 @@ merchant needs to know an exchange URL, or a database name. @end quotation @node Using taler-config,Keying,Configuration format,Configuration<2> -@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{12}@anchor{taler-exchange-manual using-taler-config}@anchor{13} +@anchor{taler-exchange-manual using-taler-002dconfig-exchange}@anchor{13}@anchor{taler-exchange-manual using-taler-config}@anchor{14} @section Using taler-config @@ -793,7 +856,7 @@ to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} option. @node Keying,Serving,Using taler-config,Configuration<2> -@anchor{taler-exchange-manual id2}@anchor{14}@anchor{taler-exchange-manual keying}@anchor{15} +@anchor{taler-exchange-manual id2}@anchor{15}@anchor{taler-exchange-manual keying}@anchor{16} @section Keying @@ -805,15 +868,12 @@ The exchange works with four types of keys: @item master key (kept offline) -To create a master public key: +To create a master key, use: @example -$ gnunet-ecc --generate-keys=1 FILENAME -$ gnunet-ecc --print-public-key FILENAME +$ taler-exchange-offline setup @end example -FIXME: Add link to @code{gnunet-ecc} manpage. - @item sign keys (signs normal messages from the exchange) @@ -842,43 +902,43 @@ Key options include: @end itemize @node Serving,Currency,Keying,Configuration<2> -@anchor{taler-exchange-manual id3}@anchor{16}@anchor{taler-exchange-manual serving}@anchor{17} +@anchor{taler-exchange-manual id3}@anchor{17}@anchor{taler-exchange-manual serving}@anchor{18} @section Serving The exchange can serve HTTP over both TCP and UNIX domain socket. -The following values are to be configured in the section [exchange]: +The following options are to be configured in the section @code{[exchange]}: @itemize - @item -serve: must be set to tcp to serve HTTP over TCP, or unix to serve -HTTP over a UNIX domain socket +@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 -port: Set to the TCP port to listen on if serve Is tcp. +@code{PORT}: Set to the TCP port to listen on if @code{SERVE} is @code{tcp}. @item -unixpath: set to the UNIX domain socket path to listen on if serve Is -unix +@code{UNIXPATH}: Set to the UNIX domain socket path to listen on if @code{SERVE} is +@code{unix}. @item -unixpath_mode: number giving the mode with the access permission MASK -for the unixpath (i.e. 660 = rw-rw—-). +@code{UNIXPATH_MODE}: Number giving the mode with the access permission mask +for the @code{UNIXPATH} (i.e. 660 = @code{rw-rw---}). @end itemize @node Currency,Database,Serving,Configuration<2> -@anchor{taler-exchange-manual currency}@anchor{18}@anchor{taler-exchange-manual id4}@anchor{19} +@anchor{taler-exchange-manual currency}@anchor{19}@anchor{taler-exchange-manual id4}@anchor{1a} @section Currency The exchange supports only one currency. This data is set under the -respective option @code{CURRENCY} in section [taler]. +respective option @code{CURRENCY} in section @code{[taler]}. @node Database,Coins denomination keys,Currency,Configuration<2> -@anchor{taler-exchange-manual database}@anchor{1a}@anchor{taler-exchange-manual id5}@anchor{1b} +@anchor{taler-exchange-manual database}@anchor{1b}@anchor{taler-exchange-manual id5}@anchor{1c} @section Database @@ -891,10 +951,10 @@ choosing the backend, it is mandatory to supply the connection string @itemize - @item -via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG. +via an environment variable: @code{TALER_EXCHANGEDB_POSTGRES_CONFIG}. @item -via configuration option CONFIG, under section [exchangedb-BACKEND]. +via configuration option @code{CONFIG}, under section @code{[exchangedb-BACKEND]}. For example, the demo exchange is configured as follows: @end itemize @@ -926,7 +986,7 @@ 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{1c}@anchor{taler-exchange-manual id6}@anchor{1d} +@anchor{taler-exchange-manual coins-denomination-keys}@anchor{1d}@anchor{taler-exchange-manual id6}@anchor{1e} @section Coins (denomination keys) @@ -1013,7 +1073,7 @@ to the same configuration file! @end cartouche @node Sign keys,Terms of Service,Coins denomination keys,Configuration<2> -@anchor{taler-exchange-manual id7}@anchor{1e}@anchor{taler-exchange-manual sign-keys}@anchor{1f} +@anchor{taler-exchange-manual id7}@anchor{1f}@anchor{taler-exchange-manual sign-keys}@anchor{20} @section Sign keys @@ -1051,7 +1111,7 @@ delayed. @end cartouche @node Terms of Service,Bank account,Sign keys,Configuration<2> -@anchor{taler-exchange-manual terms-of-service}@anchor{20} +@anchor{taler-exchange-manual terms-of-service}@anchor{21} @section Terms of Service @@ -1063,33 +1123,33 @@ if none are configured, the exchange 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 [exchange] section: +in the @code{[exchange]} section: @itemize - @item -TERMS_ETAG: The current “Etag” to return for the terms of service. +@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 TERMS_ETAG, you MUST also provide -the respective files in TERMS_DIR (see below). +Note that if you change the @code{TERMS_ETAG}, you MUST also provide +the respective files in @code{TERMS_DIR} (see below). @item -TERMS_DIR: The directory that contains the terms of service. +@code{TERMS_DIR}: The directory that contains the terms of service. The files in the directory must be readable to the exchange process. @end itemize -The TERMS_DIR directory structure must follow a particular layout. -First, inside of TERMS_DIR, there should be sub-directories using +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. Then, inside each language directory, files with the name of the -value set as the TERMS_ETAG must be provided. The extension of +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 @@ -1101,11 +1161,11 @@ present, the exchange may show a warning on startup. @end menu @node Example,,,Terms of Service -@anchor{taler-exchange-manual example}@anchor{21} +@anchor{taler-exchange-manual example}@anchor{22} @subsection Example -A sample file structure for a TERMS_ETAG of “v1” would be: +A sample file structure for a @code{TERMS_ETAG} of “v1” would be: @itemize - @@ -1132,12 +1192,12 @@ TERMS_DIR/de/v1.pdf TERMS_DIR/fr/v1.pdf @end itemize -If the user requests an HTML with language preferences “fr” followed by “en”, -the exchange would return “TERMS_DIR/en/v1.html” lacking an HTML version in +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. @node Bank account,Auditor configuration,Terms of Service,Configuration<2> -@anchor{taler-exchange-manual bank-account}@anchor{22}@anchor{taler-exchange-manual id8}@anchor{23} +@anchor{taler-exchange-manual bank-account}@anchor{23}@anchor{taler-exchange-manual id8}@anchor{24} @section Bank account @@ -1213,7 +1273,7 @@ For details, see manpages/taler-exchange-offline.1. @end menu @node Wire fee structure,,,Bank account -@anchor{taler-exchange-manual id9}@anchor{24}@anchor{taler-exchange-manual wire-fee-structure}@anchor{25} +@anchor{taler-exchange-manual id9}@anchor{25}@anchor{taler-exchange-manual wire-fee-structure}@anchor{26} @subsection Wire fee structure @@ -1250,7 +1310,7 @@ this maintenance activity! @end cartouche @node Auditor configuration,,Bank account,Configuration<2> -@anchor{taler-exchange-manual auditor-configuration}@anchor{26}@anchor{taler-exchange-manual id10}@anchor{27} +@anchor{taler-exchange-manual auditor-configuration}@anchor{27}@anchor{taler-exchange-manual id10}@anchor{28} @section Auditor configuration @@ -1269,8 +1329,8 @@ $ taler-exchange-offline enable-auditor $PUB_KEY $REST_URL "$AUDITOR_NAME" > aud 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. -@node Deployment,Diagnostics,Configuration<2>,Top -@anchor{taler-exchange-manual deployment}@anchor{28}@anchor{taler-exchange-manual id11}@anchor{29} +@node Deployment,Testing a deployment,Configuration<2>,Top +@anchor{taler-exchange-manual deployment}@anchor{29}@anchor{taler-exchange-manual id11}@anchor{2a} @chapter Deployment @@ -1286,7 +1346,7 @@ configured. @end menu @node Launching an exchange,Keys generation,,Deployment -@anchor{taler-exchange-manual launch}@anchor{2a}@anchor{taler-exchange-manual launching-an-exchange}@anchor{2b} +@anchor{taler-exchange-manual launch}@anchor{2b}@anchor{taler-exchange-manual launching-an-exchange}@anchor{2c} @section Launching an exchange @@ -1358,7 +1418,7 @@ attack surface.) @end cartouche @node Keys generation,Private key storage,Launching an exchange,Deployment -@anchor{taler-exchange-manual id12}@anchor{2c}@anchor{taler-exchange-manual keys-generation}@anchor{2d} +@anchor{taler-exchange-manual id12}@anchor{2d}@anchor{taler-exchange-manual keys-generation}@anchor{2e} @section Keys generation @@ -1415,7 +1475,7 @@ $ taler-auditor-offline download sign upload 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{2e} +@anchor{taler-exchange-manual private-key-storage}@anchor{2f} @section Private key storage @@ -1427,7 +1487,7 @@ regenerated. However, we do recommend using RAID (1+1 or 1+1+1) for all disks of the system. @node Database upgrades,,Private key storage,Deployment -@anchor{taler-exchange-manual database-upgrades}@anchor{2f}@anchor{taler-exchange-manual id13}@anchor{30} +@anchor{taler-exchange-manual database-upgrades}@anchor{30}@anchor{taler-exchange-manual id13}@anchor{31} @section Database upgrades @@ -1451,7 +1511,7 @@ not be performed in a production system. @end menu @node Revocations,,,Database upgrades -@anchor{taler-exchange-manual id14}@anchor{31}@anchor{taler-exchange-manual revocations}@anchor{32} +@anchor{taler-exchange-manual id14}@anchor{32}@anchor{taler-exchange-manual revocations}@anchor{33} @subsection Revocations @@ -1483,8 +1543,19 @@ operation. @end quotation @end cartouche -@node Diagnostics,Benchmarking,Deployment,Top -@anchor{taler-exchange-manual diagnostics}@anchor{33}@anchor{taler-exchange-manual id15}@anchor{34} +@node Testing a deployment,Diagnostics,Deployment,Top +@anchor{taler-exchange-manual testing-a-deployment}@anchor{34} +@chapter Testing a deployment + + +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. + +@node Diagnostics,Benchmarking,Testing a deployment,Top +@anchor{taler-exchange-manual diagnostics}@anchor{35}@anchor{taler-exchange-manual id15}@anchor{36} @chapter Diagnostics @@ -1499,7 +1570,7 @@ helpful for diagnostics. @end menu @node Internal audits,Database Scheme,,Diagnostics -@anchor{taler-exchange-manual internal-audit}@anchor{35}@anchor{taler-exchange-manual internal-audits}@anchor{36} +@anchor{taler-exchange-manual internal-audit}@anchor{37}@anchor{taler-exchange-manual internal-audits}@anchor{38} @section Internal audits @@ -1527,7 +1598,7 @@ 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{37}@anchor{taler-exchange-manual id16}@anchor{38} +@anchor{taler-exchange-manual database-scheme}@anchor{39}@anchor{taler-exchange-manual id16}@anchor{3a} @section Database Scheme @@ -1543,7 +1614,7 @@ 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{39}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{3a} +@anchor{taler-exchange-manual benchmarking}@anchor{3b}@anchor{taler-exchange-manual exchangebenchmarking}@anchor{3c} @chapter Benchmarking |