diff options
Diffstat (limited to 'doc/manual.texi')
| -rw-r--r-- | doc/manual.texi | 1296 |
1 files changed, 0 insertions, 1296 deletions
diff --git a/doc/manual.texi b/doc/manual.texi deleted file mode 100644 index b37ad613..00000000 --- a/doc/manual.texi +++ /dev/null @@ -1,1296 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@c Too generic, should be renamed to avoid system conflicts. -@c probably: manual.info -> taler-merchant.info -@setfilename manual.info -@include version-manual.texi -@settitle The GNU Taler merchant backend operator tutorial @value{VERSION} - -@include syntax.texi - -@c Define a new index for options. -@defcodeindex op -@c Combine everything into one index (arbitrarily chosen to be the -@c concept index). -@syncodeindex op cp -@c %**end of header - -@copying -This manual is for the GNU Taler merchant backend (version @value{VERSION}, @value{UPDATED}), - -Copyright @copyright{} 2016, 2017, 2019 Taler Systems SA - -@quotation -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover Texts, and with no Back-Cover -Texts. A copy of the license is included in the section entitled -``GNU Free Documentation License''. -@end quotation -@end copying -@c If your manual is published on paper by the FSF, it should include -@c The standard FSF Front-Cover and Back-Cover Texts, as given in -@c maintain.texi. -@c -@c Titlepage -@c -@titlepage -@title The GNU Taler merchant backend operator tutorial -@subtitle Version @value{VERSION} -@subtitle @value{UPDATED} -@author Marcello Stanisci (@email{marcello.stanisci@@inria.fr}) -@author Christian Grothoff (@email{christian.grothoff@@inria.fr}) -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@summarycontents -@contents - -@ifnottex -@node Top -@top The GNU Taler manual for Web shops -@insertcopying -@end ifnottex - -@menu -* Introduction:: Whom this manual is addressed to -* Installation:: Installing the Merchant backend -* Configuration:: How to set up the Merchant backend -* Testing:: How to test the installed Merchant backend -* Advanced topics:: Detailed solutions to specific issues - - -Appendices - -* GNU-LGPL:: The GNU Lesser General Public License says how you - can use the code of libtalermerchant.so in your own projects. -* GNU Affero GPL:: The Affero GNU General Public License says how you - can copy and share the Taler merchant backend. -* GNU-FDL:: The GNU Free Documentation License says how you - can copy and share the documentation of GNU Taler. - -Indices - -* Concept Index:: Index of concepts and programs. - -@detailmenu - --- The Detailed Node Listing --- - -Introduction - -* About GNU Taler:: -* About this manual:: -* Architecture overview:: - -Installation - -* Installing Taler using Docker:: -* Generic instructions:: -* Installing Taler on Debian GNU/Linux:: - -Configuration - -* Backend options:: -* Sample backend configuration:: -* Launching the backend:: - -Testing - -Advanced topics - -* Configuration format:: -* Using taler-config:: -* Merchant key management:: -* SEPA configuration:: -* Tipping visitors:: -* Generate payments:: - -@end detailmenu -@end menu - - -@node Introduction -@chapter Introduction - -@menu -* About GNU Taler:: -* About this manual:: -* Architecture overview:: -@end menu - -@node About GNU Taler -@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). - -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 -@section About this manual - -This tutorial targets system administrators who want to -install a GNU Taler merchant @emph{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 tutorial 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. - -@c The fouth chapter will explain how to test that the setup worked correctly. - -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 -@section Architecture overview - -@cindex crypto-currency -@cindex 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. - -The Taler software stack for a merchant consists of four main components: - -@itemize -@cindex frontend -@item 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 assumed to exist at the merchant. This manual - describes how to integrate Taler with Web shop frontends. -@cindex back office -@item 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 - again not included with Taler, but rather assumed to exist at the - merchant. This manual will describe how to integrate such a component - to handle payments managed by Taler. -@cindex backend -@item A Taler-specific payment backend which makes it easy for the - frontend to process financial transactions with Taler. The - next two chapters will describe how to install and configure - this backend. -@cindex DBMS -@cindex Postgres -@item A DBMS which stores the transaction history for the Taler backend. - For now, the GNU Taler reference implemenation only supports Postgres, - but the code could be easily extended to support another DBMS. -@end itemize - -The following image illustrates the various interactions of these -key components: - -@center @image{arch, 3in} - -@cindex RESTful -Basically, the backend provides the cryptographic protocol support, -stores Taler-specific financial information in a DBMS and communicates -with the GNU 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 is encapsulated within the Taler backend. - - -@node Installation -@chapter Installation - -@menu -* Installing Taler using Docker:: -* Generic instructions:: -* Installing Taler on Debian GNU/Linux:: -@c * Installing Taler with GNU Guix:: Installing Taler with GNU Guix -@c * Installing Taler on Arch Linux:: Installing Taler on Arch Linux -@c * Installing Taler on Windows:: Installing Taler on Windows -@c * Installing Taler on OS X:: Installing Taler on OS X -@end menu - -This chapter describes how to install the GNU Taler merchant backend. - -@node Installing Taler using Docker -@section Installing Taler using Docker - -This section provides instructions for the merchant backend -installation using `Docker`. - -For security reasons, we run Docker against a VirtualBox instance, -so 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{https://docs.docker.com/}documentation in order -to get those components installed, as that is not in this manual's scope. - -Before starting to build the merchant's image, make sure a -``docker-machine`` instance is up and running. - -Because all of the Docker source file are kept in our ``deployment`` -repository, we start by checking out the -@code{git://taler.net/deployment} codebase: - -@smallexample -$ git clone git://taler.net/deployment -@end smallexample - -Now we actually build the merchant's image. From the same -directory as above: - -@smallexample -$ cd deployment/docker/merchant/ -$ docker-compose build -@end smallexample - -If everything worked as expected, the merchant is ready to be -launched. From the same directory as the previous step: - -@smallexample -# Recall: the docker-machine should be up and running. -$ docker-compose up -@end smallexample - -You should see some live logging from all the involved containers. -At this stage of development, you should also ignore some (harmless) -error message from postresql about already existing roles and databases. - -To test if everything worked as expected, it suffices to issue a -simple request to the merchant, as: - -@smallexample -$ curl http://$(docker-machine ip)/ -# A greeting message should be returned by the merchant. -@end smallexample - - -@node Generic instructions -@section Generic instructions - -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. - -@menu -* Installation of dependencies:: -* Installing libgnunetutil:: -* Installing the GNU Taler exchange:: -* Installing the GNU Taler merchant backend:: -@end menu - -@node Installation of dependencies -@subsection Installation of dependencies - -The following packages need to be installed before we can compile the -backend: - -@itemize -@item autoconf >= 2.69 -@item automake >= 1.14 -@item libtool >= 2.4 -@item autopoint >= 0.19 -@item libltdl >= 2.4 -@item libunistring >= 0.9.3 -@item libcurl >= 7.26 (or libgnurl >= 7.26) -@item GNU libmicrohttpd >= 0.9.39 -@item GNU libgcrypt >= 1.6 -@item libjansson >= 2.7 -@item Postgres >= 9.4, including libpq -@item libgnunetutil (from Git) -@item GNU Taler exchange (from Git) -@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. - -The following sections will provide detailed instructions for -installing the libgnunetutil and GNU Taler exchange dependencies. - -@node Installing libgnunetutil -@subsection Installing libgnunetutil - -@cindex GNUnet -Before you install libgnunetutil, you must download and install the -dependencies mentioned in the previous section, otherwise the build -may succeed but fail to export some of the tooling required by Taler. - -To download and install libgnunetutil, proceed as follows: - -@example -$ git clone https://gnunet.org/git/gnunet/ -$ cd gnunet/ -$ ./bootstrap -$ ./configure [--prefix=GNUNETPFX] -$ # Each dependency can be fetched from non standard locations via -$ # the '--with-<LIBNAME>' option. See './configure --help'. -$ make -# make install -@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}. - -@node Installing the GNU Taler exchange -@subsection Installing the GNU Taler exchange - -@cindex exchange -After installing GNUnet, you can download and install -the exchange as follows: - -@example -$ git clone git://taler.net/exchange -$ cd exchange -$ ./bootstrap -$ ./configure [--prefix=EXCHANGEPFX] \ - [--with-gnunet=GNUNETPFX] -$ # Each dependency can be fetched from non standard locations via -$ # the '--with-<LIBNAME>' option. See './configure --help'. -$ make -# make install -@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}. Note that 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 merchant backend -@subsection Installing the GNU Taler merchant backend - -@cindex backend -The following steps assume all dependencies are installed. - -Use the following commands to download and install the -merchant backend: - -@example -$ git clone git://taler.net/merchant -$ cd merchant -$ ./bootstrap -$ ./configure [--prefix=PFX] \ - [--with-gnunet=GNUNETPFX] \ - [--with-exchange=EXCHANGEPFX] -$ # Each dependency can be fetched from non standard locations via -$ # the '--with-<LIBNAME>' option. See './configure --help'. -$ make -$ make install -@end example - -Note that you have to specify @code{--with-exchange=/usr/local} and/or -@code{--with-exchange=/usr/local} if you installed the exchange and/or -GNUnet to @code{/usr/local} in the previous steps. - -@c @node Installing Taler with GNU Guix -@c @section Installing Taler with GNU Guix - -@c This section has not yet been written. - - - - -@node Installing Taler on Debian GNU/Linux -@section Installing Taler on Debian GNU/Linux - -@cindex Wheezy -@cindex Debian -Debian wheezy is too old and lacks most of the packages required. - -On Debian jessie, only GNU libmicrohttpd needs to be compiled from -source. To install dependencies on Debian jesse, run the following -commands: - -@example -# apt-get install \ - autoconf \ - automake \ - autopoint \ - libtool \ - libltdl-dev \ - libunistring-dev \ - libcurl4-gnutls-dev \ - libgcrypt20-dev \ - libjansson-dev \ - libpq-dev \ - postgresql-9.4 -# 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 \ - autoconf \ - automake \ - autopoint \ - libtool \ - libltdl-dev \ - libunistring-dev \ - libcurl4-gnutls-dev \ - libgcrypt20-dev \ - libjansson-dev \ - libpq-dev \ - postgresql-9.5 \ - libmicrohttpd-dev -@end example - -For the rest of the installation, follow the -generic installation instructions starting with the installation of -libgnunetutil. Note that if you used the Debian wheezy instructions -above, you need to pass -@code{--with-microhttpd=/usr/local/} to all @code{configure} invocations. - - - -@c @node Installing Taler on Arch Linux -@c @section Installing Taler on Arch Linux - -@c This section has not yet been written. - - -@c @node Installing Taler on Windows -@c @section Installing Taler on Windows - -@c This section has not yet been written. - - -@c @node Installing Taler on OS X -@c @section Installing Taler on OS X - -@c This section has not yet been written. - - -@node Configuration -@chapter How to configure the merchant's backend - -@cindex taler-config -@cindex 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. -For more information on @code{taler-config}, @pxref{Using taler-config}. - -@menu -* Backend options:: -* Sample backend configuration:: -* Launching the backend:: -@end menu - -@node Backend options -@section Backend options - -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. - - -@table @asis - -@item Service address -The following option sets the transport layer address used by the merchant backend: - -@cindex UNIX domain socket -@cindex TCP -@example -[MERCHANT]/SERVE = TCP | UNIX -@end example - -If given, -@itemize -@item @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 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. -@end itemize - -The frontend can then connect to the backend over HTTP using the specified address. -If frontend and backend run within the same operating system, the use of -a UNIX domain socket is recommended to avoid accidentally exposing the backend -to the network. - -@c FIXME: we should offer an option to bind the TCP socket to a particular IP address (#4752) - -@cindex port -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 -@end example - - -@item Currency -Which currency the Web shop deals in, i.e. ``EUR'' or ``USD'', is specified using the option - -@cindex currency -@cindex KUDOS -@example -[TALER]/CURRENCY -@end example - -For testing purposes, the currency MUST match ``KUDOS'' so that tests will work -with the Taler demonstration exchange at @url{https://exchange.demo.taler.net/}: - -@example -$ taler-config -s TALER -o CURRENCY -V KUDOS -@end example - - -@item Database -@cindex DBMS -In principle is possible for the backend to support different DBMSs. -The option - -@example -[MERCHANT]/DB -@end example - -specifies which DBMS is to be used. However, currently only the value "postgres" is supported. This is also -the default. - -In addition to selecting the DBMS software, the backend requires DBMS-specific options to access the database. - -For postgres, you need to provide: - -@example -[merchantdb-postgres]/config -@end example -@cindex Postgres - -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 - -@example -$ sudu -u postgres createuser -d $USER -@end example - -as the Postgres database administrator (usually @code{postgres}) to -grant @code{$USER} the ability to create new databases. Next, you -should as @code{$USER} run: - -@example -$ createdb $DBNAME -@end example - -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 - - -@item Exchange -@cindex exchange -To add an exchange to the list of trusted payment service providers, -you create a section with a name that starts with ``exchange-''. -In that section, the following options need to be configured: - -@itemize - -@item -The ``url'' option specifies the exchange's base URL. For example, -to use the Taler demonstrator use: - -@example -$ taler-config -s EXCHANGE-demo -o URL \ - -V https://exchange.demo.taler.net/ -@end example - -@item -@cindex master key -The ``master_key'' option specifies the exchange's master public key in base32 encoding. -For the Taler demonstrator, use: - -@example -$ taler-config -s EXCHANGE-demo -o master_key \ - -V CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 -@end example - -Note that multiple exchanges can be added to the system by using different -tokens in place of @code{demo} in the example above. Note that all -of the exchanges must use the same currency. If you need to support -multiple currencies, you need to configure a backend per currency. - -@end itemize - -@c FIXME: In the future, we need to describe specifying auditors here. -@c @item Auditors - - -@item Instances -@cindex instance -The backend allows the user to run multiple instances of shops with -distinct business entities against a single backend. Each instance -uses its own bank accounts and key for signing contracts. It is -mandatory to configure a "default" instance. - -@itemize - -@item -The ``KEYFILE'' option specifies the file containing the instance's -private signing key. For example, use: - -@example -$ taler-config -s INSTANCE-default -o KEYFILE \ - -V '$@{TALER_CONFIG_HOME@}/merchant/instace/default.key' -@end example - -@item -The ``NAME'' option specifies a human-readable name for the instance. -For example, use: - -@example -$ taler-config -s INSTANCE-default -o NAME \ - -V 'Kudos Inc.' -@end example - - -@item -The optional ``TIP_EXCHANGE'' and ``TIP_EXCHANGE_PRIV_FILENAME'' -options are discussed in @cite{Tipping visitors} -@end itemize - - - -@item Accounts -@cindex wire format -In order to receive payments, the merchant backend needs to communicate bank -account details to the exchange. For this, the configuration must -include one or more sections named ``ACCOUNT-name'' where @code{name} can be -replaced by some human-readable word identifying the account. For -each section, the following options should be provided: - - -@itemize -@item -The ``URL'' option specifies a @code{payto://}-URL for the account of -the merchant. For example, use: - -@example -$ taler-config -s ACCOUNT-bank -o NAME \ - -V 'payto://x-taler-bank/bank.demo.taler.net/4' -@end example - -@item -The ``WIRE_RESPONSE'' option specifies where Taler should store the -(salted) JSON encoding of the wire account. The file given will be -created if it does not exist. For example, use: - -@example -$ taler-config -s ACCOUNT-bank -o WIRE_RESPONSE \ - -V '@{$TALER_CONFIG_HOME@}/merchant/bank.json' -@end example - - -@item -The ``PLUGIN'' option specifies which wire plugin should be used for -this account. The plugin must support the wire method used by the -URL. For example, use: - -@example -$ taler-config -s ACCOUNT-bank -o PLUGIN \ - -V taler_bank -@end example - -@item -For each @code{instance} that should use this account, you should set -@code{HONOR_instance} and @code{ACTIVE_instance} to YES. The first -option will cause the instance to accept payments to the account (for -existing contracts), while the second will cause the backend to -include the account as a possible option for new contracts. - -For example, use: - -@example -$ taler-config -s ACCOUNT-bank -o HONOR_default \ - -V YES -$ taler-config -s ACCOUNT-bank -o ACTIVE_default \ - -V YES -@end example - -to use ``account-bank'' for the ``default'' instance. - -@end itemize - -Depending on which PLUGIN you configured, you may additionally specfiy -authentication options to enable the plugin to use the account. - -For example, with @code{taler_bank} plugin, use: - -@example -$ taler-config -s ACCOUNT-bank -o TALER_BANK_AUTH_METHOD \ - -V basic -$ taler-config -s ACCOUNT-bank -o USERNAME \ - -V user42 -$ taler-config -s ACCOUNT-bank -o PASSWORD \ - -V pass42 -@end example - - - -@c Document EBICS here once supported. - -Note that additional instances can be specified using different tokens -in the section name instead of @code{default}. - -@end table - -@node Sample backend configuration -@section Sample backend configuration - -@cindex configuration -The following is an example for a complete backend configuration: - -@smallexample -[TALER] -CURRENCY = KUDOS - -[MERCHANT] -SERVE = TCP -PORT = 8888 -DATABASE = postgres - -[MERCHANTDB-postgres] -CONFIG = postgres:///donations - -[INSTANCE-default] -KEYFILE = $DATADIR/key.priv -NAME = "Kudos Inc." - -[ACCOUNT-bank] -URL = payto://x-taler-bank/bank.demo.taler.net/4 -WIRE_RESPONSE = $DATADIR/bank.json -PLUGIN = taler_bank -HONOR_default = YES -ACTIVE_default = YES -TALER_BANK_AUTH_METHOD = basic -USERNAME = my_user -PASSWORD = 1234pass - -[EXCHANGE-trusted] -URL = https://exchange.demo.taler.net/ -MASTER_KEY = CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00 -CURRENCY = KUDOS - -@end smallexample - - -Given the above configuration, the backend will use a database named -@code{donations} within Postgres. - -The backend will deposit the coins it receives to the exchange at -@url{https://exchange.demo.taler.net/}, which has the master key @* -"CQQZ9DY3MZ1ARMN5K1VKDETS04Y2QCKMMCFHZSWJWWVN82BTTH00". - -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 -@section Launching the backend - -@cindex backend -@cindex taler-merchant-httpd -Assuming you have configured everything correctly, you can launch the -merchant backend using: - -@example -$ taler-merchant-httpd -@end example - -When launched for the first time, this command will print a message -about generating your private key. If everything worked as expected, -the command - -@example -$ curl http://localhost:8888/ -@end example - -should return the message - -@smallexample -Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. -@end smallexample - -Please note that your backend is right now likely globally -reachable. Production systems should be configured to bind -to a UNIX domain socket or properly restrict access to the -port. - - -@node Testing -@chapter Testing - -The tool @code{taler-merchant-generate-payments} can be used to test -the merchant backend installation. It implements all the payment's steps -in a programmatically way, relying on the backend you give it as input. -Note that this tool gets installed along all the -merchant backend's binaries. - -This tool gets configured by a config file, that must have the following -layout: - -@example -[PAYMENTS-GENERATOR] - -# The exchange used during the test: make sure the merchant backend -# being tested accpets this exchange. -# If the sysadmin wants, she can also install a local exchange -# and test against it. -EXCHANGE = https://exchange.demo.taler.net/ - -# This value must indicate some URL where the backend -# to be tested is listening; it doesn't have to be the -# "official" one, though. -MERCHANT = http://localbackend/ - -# This value is used when the tool tries to withdraw coins, -# and must match the bank used by the exchange. If the test is -# done against the exchange at https://exchange.demo.taler.net/, -# then this value can be "https://bank.demo.taler.net/". -BANK = https://bank.demo.taler.net/ - -# The merchant instance in charge of serving the payment. -# Make sure this instance has a bank account at the same bank -# indicated by the 'bank' option above. -INSTANCE = default - -# The currency used during the test. Must match the one used -# by merchant backend and exchange. -CURRENCY = KUDOS -@end example -@c FIXME: the last option should be removed and [taler]/CURRENCY used instead! - -Run the test in the following way: - -@example -$ taler-merchant-generate-payments [-c config] [-e EURL] [-m MURL] -@end example - -The argument @code{config} given to @code{-c} points to the configuration -file and is optional -- @code{~/.config/taler.conf} will be checked by -default. -By default, the tool forks two processes: one for the merchant backend, -and one for the exchange. -The option @code{-e} (@code{-m}) avoids any exchange (merchant backend) -fork, and just runs the generator against the exchange (merchant backend) -running at @code{EURL} (@code{MURL}). - -Please NOTE that the generator contains @emph{hardcoded} values, as for -deposit fees of the coins it uses. -In order to work against the used exchange, those values MUST match the -ones used by the exchange. - -The following example shows how the generator "sets" a deposit fee -of EUR:0.01 for the 5 EURO coin. - -@example -// from <merchant_repository>/src/sample/generate_payments.c -@{ .oc = OC_PAY, - .label = "deposit-simple", - .expected_response_code = MHD_HTTP_OK, - .details.pay.contract_ref = "create-proposal-1", - .details.pay.coin_ref = "withdraw-coin-1", - .details.pay.amount_with_fee = concat_amount (currency, "5"), - .details.pay.amount_without_fee = concat_amount (currency, "4.99") @}, -@end example - -The logic calculates the deposit fee according to the subtraction: -@code{amount_with_fee - amount_without_fee}. - -The following example shows a 5 EURO coin configuration - needed by the -used exchange - which is compatible with the hardcoded example above. - -@example -[COIN_eur_5] -value = EUR:5 -duration_overlap = 5 minutes -duration_withdraw = 7 days -duration_spend = 2 years -duration_legal = 3 years -fee_withdraw = EUR:0.00 -fee_deposit = EUR:0.01 # important bit -fee_refresh = EUR:0.00 -fee_refund = EUR:0.00 -rsa_keysize = 1024 -@end example - -If the command terminates with no errors, then the merchant backend -is correctly installed. - -After this operation is done, the merchant database will have some dummy -data in it, so it may be convenient to clean all the tables; to this -purpose, issue the following command: - -@example -$ taler-merchant-dbinit -r -@end example - - -@node Advanced topics -@chapter Advanced topics - -@menu -* Configuration format:: Configuration file format -* Using taler-config:: Introduction to the taler-config tool -* Merchant key management:: Managing the merchant's cryptographic keys -* SEPA configuration:: Configuring a SEPA bank account -* Tipping visitors:: Giving money to Web site visitors with Taler -* Generate payments:: Generate fake payments for testing purposes -@end menu - -@include configuration-format.texi -@include taler-config.texi - - -@node Merchant key management -@section Merchant key management -@cindex merchant key -@cindex KEYFILE - -The option ``KEYFILE'' in the section ``INSTANCE-default'' -specifies the path to the instance's private key. You do not need to -create a key manually, the backend will generate it automatically if -it is missing. While generally unnecessary, it is possible to display -the corresponding public key using the @code{gnunet-ecc} command-line -tool: - -@example -$ gnunet-ecc -p \ - $(taler-config -f -s INSTANCE-default \ - -o KEYFILE) -@end example - -@c Add more on how to add that key to X.509 CSRs once we can do that. - -@node SEPA configuration -@section Using the SEPA wire transfer method -@cindex SEPA -@cindex EBICS - -The following is a sample configuration for the SEPA wire transfer -method:@footnote{Supporting SEPA is still -work in progress; the backend will accept this configuration, but the -exchange will not work with SEPA today.}. - -Then, to configure the EBICS backend for SEPA payments in EUR, -the following configuration -options need to be set: - -@example -$ taler-config -s TALER -o CURRENCY -V EUR -$ taler-config -s ACCOUNT-e -o PLUGIN -V ebics -$ taler-config -s ACCOUNT-e -o URL \ - -V payto://sepa/XY00111122223333444455556666 -$ taler-config -s ACCOUNT-e -o WIRE_RESPONSE - -V '$@{DATADIR@}/b.json' -@end example - -Please note that you will also have to configure an exchange and/or -auditors that support SEPA. However, we cannot explain how to do this -yet as such entities do not yet exist. Once such entities do exist, -we expect future versions of the Taler backend to ship with -pre-configured exchanges and auditors for common denominations. - - -@node Tipping visitors -@section Tipping visitors -@cindex 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. - -There are four basic steps that must happen to tip a visitor. - -@menu -* Configure a reserve and exchange for tipping:: -* Fund the reserve:: -* Authorize a tip:: -* Picking up of the tip:: -@end menu - -@node Configure a reserve and exchange for tipping -@subsection Configure a reserve and exchange for tipping -@cindex gnunet-ecc -@cindex reserve key - -@c TODO: We should probably create a tool that automates the -@c configuration process and simply outputs the wire transfer -@c subject of the reserve. - -To tip users, you first need to create a reserve. A reserve is a pool -of money held in escrow at the Taler exchange. This is the source of -the funds for the tips. Tipping will fail (resulting in disappointed -visitors) if you do not have enough funds in your reserve! - -First, we configure the backend. You need to enable tipping for each -instance separately, or you can use an instance only for tipping. To -configure the ``default'' instance for tipping, use the following -configuration: - -@example -[INSTANCE-default] -# this is NOT the tip.priv -KEYFILE = signing_key.priv -# replace the URL with the URL of the exchange you will use -TIP_EXCHANGE = https://exchange:443/ -# here put the path to the file created with "gnunet-ecc -g1 tip.priv" -TIP_RESERVE_PRIV_FILENAME = tip.priv -@end example - -Note that the KEYFILE option should have already been present for -the instance. It has nothing to do with the ``tip.priv'' file we -created above, and you should probably use a different file here. - -Instead of manually editing the configuration, you could also run: - -@example -$ taler-config -s INSTANCE-default \ - -o TIP_RESERVE_PRIV_FILENAME \ - -V tip.priv -$ taler-config -s INSTANCE-default \ - -o TIP_EXCHANGE \ - -V https://exchange:443/ -@end example - - -Next, to create the @code{TIP_RESERVE_PRIV_FILENAME} file, use: - -@example -$ gnunet-ecc -g 1 \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) -@end example - -This will create a file with the private key that will be used to -identify the reserve. You need to do this once for each instance that -is configured to tip. - - -Now you can (re)start the backend with the new configuration. - -@node Fund the reserve -@subsection Fund the reserve -@cindex reserve -@cindex close - -To fund the reserve, you must first extract the public key -from ``tip.priv'': - -@example -$ gnunet-ecc --print-public-key \ - $(taler-config -f -s INSTANCE-default \ - -o TIP-RESERVE_PRIV_FILENAME) -@end example - -In our example, the output for the public key is: - -@example -QPE24X8PBX3BZ6E7GQ5VAVHV32FWTTCADR0TRQ183MSSJD2CHNEG -@end example - -You now need to make a wire transfer to the exchange's bank account -using the public key as the wire transfer subject. The exchange's -bank account details can be found in JSON format at -``https://exchange:443//wire/METHOD'' where METHOD is the respective -wire method (i.e. ``sepa''). Depending on the exchange's operator, -you may also be able to find the bank details in a human-readable -format on the main page of the exchange. - -Make your wire transfer and (optionally) check at -``https://exchange:443/reserve/status/reserve_pub=QPE24X...'' -whether your transfer has arrived at the exchange. -@c FIXME: we should create a nicer tool to do this check! - -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 wire further funds to the reserve every other week to prevent -it from expiring. - -@node Authorize a tip -@subsection Authorize a tip - -When your frontend has reached the point where a client is supposed -to receive a tip, it needs to first authorize the tip. For this, -the frontend must use the ``/tip-authorize'' API of the backend. -To authorize a tip, the frontend has to provide the following information -in the body of the POST request: - -@itemize @bullet -@item The amount of the tip - -@item The justification (only used internally for the back-office) - -@item The URL where the wallet should navigate next after the tip was processed - -@item The tip-pickup URL (see next section) -@end itemize - -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. - -The frontend should handle errors returned by the backend, such -as missconfigured instances or a lack of remaining funds for tipping. - -@node Picking up of the tip -@subsection Picking up of the tip - -The wallet will POST a JSON object to the shop's ``/tip-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. - -@node Generate payments -@section Generate payments -@cindex testing database - -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 provide them all -the input to accomplish payments. Note that each component will use its -own configuration (as they would do in production). - -The tool takes all of the values it needs from the command line, with -some of them being mandatory. Among those, we have: - -@itemize -@item @code{--currency=K} Use currency @emph{K}, for example to craft coins to withdraw. -@item @code{--bank-url=URL} Assume that the bank is serving under the base URL @emph{URL}. -This option is only actually used by the tool to check if the bank was well launched. -@item @code{--merchant-url=URL} Reach the merchant through @emph{URL}, for downloading -contracts and sending payments. -@end itemize - -The tool then comes with two operation modes: @emph{ordinary}, -and @emph{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 abilty of driving the aggregation policy is useful -for testing the backoffice facility. - -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 possibilities. For example: - -@smallexample -$ taler-merchant-benchmark corner --help -@end smallexample - -will show all the options offered by the @emph{corner} mode. -Among the most interesting, there are: - -@itemize -@item @code{--two-coins=TC} This option instructs the tool to perform @emph{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. -@item @code{--alt-instance=AI} This option instructs the tool to perform payments -using the merchant instance @emph{AI} (instead of the @emph{default} instance) -@end itemize - -As for the @code{ordinary} subcommand, it is worth explaining the -following options: - -@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 @b{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' work used -in the tool's name). -@end itemize - -@c ********************************************************** -@c ******************* Appendices ************************* -@c ********************************************************** - -@node GNU-LGPL -@unnumbered GNU-LGPL -@cindex license -@cindex LGPL -@include lgpl.texi - -@node GNU Affero GPL -@unnumbered GNU Affero GPL -@cindex license -@cindex Affero GPL -@include agpl.texi - -@node GNU-FDL -@unnumbered GNU-FDL -@cindex license -@cindex GNU Free Documentation License -@include fdl-1.3.texi - -@node Concept Index -@unnumbered Concept Index - -@printindex cp - -@bye |