diff options
Diffstat (limited to 'manpages')
45 files changed, 2954 insertions, 1547 deletions
diff --git a/manpages/challenger-admin.1.rst b/manpages/challenger-admin.1.rst new file mode 100644 index 00000000..bdb7687c --- /dev/null +++ b/manpages/challenger-admin.1.rst @@ -0,0 +1,70 @@ +challenger-admin(1) +################### + +.. only:: html + + Name + ==== + + **challenger-admin** - manipulate clients registered in Challenger database + + +Synopsis +======== + +**challenger-admin** +[**-a** *CLIENT_SECRET* | **--add=**\ \ *CLIENT_SECRET*] +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-d** | **--delete**] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-q** | **--quiet**] +[**-v** | **--version**] +CLIENT_URL + + +Description +=========== + +**challenger-admin** is a command-line tool to add or delete clients from the Challenger database. + +Its options are as follows: + +**-a** *SECRET* \| **--add=**\ \ *SECRET* + Add the client with the given *CLIENT_URL setting the client secret to *SECRET*. Prints the CLIENT_ID of the added client. + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the Challenger commands + to operate from *FILENAME*. + +**-d** \| **--delete** + Delete the client with the given *CLIENT_URL*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-q** \| **–-quiet** + Be less verbose in the output. Useful in shell scripts. + +**-v** \| **–-version** + Print version information. + + +See Also +======== + +challenger-config(1), challenger-httpd(1), challenger.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/challenger-config.1.rst b/manpages/challenger-config.1.rst new file mode 100644 index 00000000..16ba7bb7 --- /dev/null +++ b/manpages/challenger-config.1.rst @@ -0,0 +1,101 @@ +challenger-config(1) +#################### + +.. only:: html + + Name + ==== + + **challenger-config** - manipulate Challenger configuration file + +Synopsis +======== + +**challenger-config** +[**-b** *backend* | **--supported-backend=**\ \ *backend*] +[**-c** *filename* | **--config=**\ \ *filename*] +[**-f** | **--filename**] +[**-F** | **--full**] +[**-h** | **--help**] +[**-L** *loglevel* | **--loglevel=**\ \ *loglevel*] +[**-l** *filename* | **--logfile=**\ \ *filename*] +[**-o** *option* | **--option=**\ \ *option*] +[**-r** | **--rewrite**] +[**-S** | **--list-sections**] +[**-s** *section* | **--section=**\ \ *section*] +[**-V** *value* | **--value=**\ \ *value*] +[**-v** | **--version**] + + +Description +=========== + +**challenger-config** can be used to read or modify Challenger configuration files. + +**-b** *BACKEND* \| **--supported-backend=**\ \ *BACKEND* + Tests whether the specified *BACKEND* 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 *BACKEND* 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). + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration file *FILENAME*. + +**-f** \| **--filename** + Try to perform expansions as if the option values represent filenames (will + also be applied even if the option is not really a filename). + +**-F** \| **--full** + Write the full configuration file, not just the differences to the defaults. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Use *LOGLEVEL* for logging. + Valid values are ``DEBUG``, ``INFO``, ``WARNING``, and ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-o** *OPTION* \| **--option=**\ \ *OPTION* + Which configuration option should be accessed or edited. Required to set a + value. If not given, all values of a given section will be printed in the + format "OPTION = VALUE". + +**-r** \| **--rewrite** + Write the configuration file even if nothing changed. Will remove all comments! + +**-S** \| **--list-sections** + List available configuration sections for use with ``--section``. + +**-s** *SECTION* \| **--section=**\ \ *SECTION* + Which configuration section should be accessed or edited. + Required option. + +**-V** *VALUE* \| **--value=**\ \ *VALUE* + Configuration value to store in the given section under the given option. + Must only be given together with ``-s`` and ``-o`` options. + + Note: + Changing the configuration file with ``-V`` will remove comments + and may reorder sections and remove ``@INLINE@`` directives. + +**-v** \| **--version** + Print GNU Taler version number. + + +See Also +======== + +challenger-dbinit(1), challenger-httpd(1), challenger.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/challenger-dbconfig.1.rst b/manpages/challenger-dbconfig.1.rst new file mode 100644 index 00000000..da69eeaf --- /dev/null +++ b/manpages/challenger-dbconfig.1.rst @@ -0,0 +1,61 @@ +challenger-dbconfig(1) +###################### + +.. only:: html + + Name + ==== + + **challenger-dbconfig** - configure challenger database + + +Synopsis +======== + +**challenger-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**challenger-dbconfig** is a simple shell script that configures +a Postgresql database for use by ``challenger-httpd``. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``challenger-dbinit`` manually. + +**-u** *USER* + Specifies the (main) challenger user that will access the database. + +See Also +======== + +challenger-dbinit(1), challenger.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/challenger-dbinit.1.rst b/manpages/challenger-dbinit.1.rst new file mode 100644 index 00000000..5200c661 --- /dev/null +++ b/manpages/challenger-dbinit.1.rst @@ -0,0 +1,65 @@ +challenger-dbinit(1) +#################### + +.. only:: html + + Name + ==== + + **challenger-dbinit** - initialize the Challenger database + + +Synopsis +======== + +**challenger-dbinit** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-g** | **--garbagecollect**] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-r** | **--reset**] +[**-v** | **--version**] + + +Description +=========== + +**challenger-dbinit** is a command-line tool to initialize the Challenger database. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the Challenger commands + to operate from *FILENAME*. + +**-g** \| **--garbagecollect** + Remove state data from database. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-r** \| **--reset** + Reset database. (**DANGEROUS**: All existing data is lost!) + +**-v** \| **–version** + Print version information. + + +See Also +======== + +challenger-config(1), challenger-httpd(1), challenger.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/challenger-httpd.1.rst b/manpages/challenger-httpd.1.rst new file mode 100644 index 00000000..0bc08486 --- /dev/null +++ b/manpages/challenger-httpd.1.rst @@ -0,0 +1,61 @@ +challenger-httpd(1) +################### + +.. only:: html + + Name + ==== + + **challenger-httpd** - provide the Challenger HTTP interface + + +Synopsis +======== + +**challenger-httpd** +[**-C** | **--connection-close**] +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-v** | **--version**] + + +Description +=========== + +**challenger-httpd** is a command-line tool to provide the Challenger HTTP interface. + +Its options are as follows: + +**-C** \| **--connection-close** + Force HTTP connections to be closed after each request. + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the Challenger commands + to operate from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-v** \| **–version** + Print version information. + + +See Also +======== + +challenger-config(1), challenger-dbinit(1), challenger.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/challenger.conf.5.rst b/manpages/challenger.conf.5.rst new file mode 100644 index 00000000..626d11f7 --- /dev/null +++ b/manpages/challenger.conf.5.rst @@ -0,0 +1,88 @@ +challenger.conf(5) +################## + +.. only:: html + + Name + ==== + + **challenger.conf** - Challenger configuration file + + +Description +=========== + +.. include:: ../frags/common-conf-syntax.rst + +Files containing default values for many of the options described below +are installed under ``$PREFIX/share/challenger/config.d/``. +The configuration file given with **-c** to Challenger binaries +overrides these defaults. + +A configuration file may include another, by using the ``@INLINE@`` directive, +for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to +include the entirety of ``sub.conf`` at that point in ``main.conf``. + +Be extra careful when using ``challenger-config -V VALUE`` to change configuration +values: it will destroy all uses of ``@INLINE@`` and furthermore remove all +comments from the configuration file! + + +GLOBAL OPTIONS +-------------- + +The following options are from the “[challenger]” section. +This is normally the only section in a challenger.conf file. + +SERVE + This can either be ``tcp`` or ``unix``. + +PORT + Port on which the HTTP server listens, e.g. 9967. + Only used if ``SERVE`` is ``tcp``. + +BIND_TO + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1`` + for loopback. Can also be given as a hostname. We will bind to + the wildcard (dual-stack) if left empty. + Only used if ``SERVE`` is ``tcp``. + +UNIXPATH + Which unix domain path should we bind to? + Only used if ``SERVE`` is ``unix``. + +UNIXPATH_MODE = 660 + What should be the file access permissions for ``UNIXPATH``? + Only used if ``SERVE`` is ``unix``. + +DB + Plugin to use for the database, e.g. “postgres”. + +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). + +VALIDATION_EXPIRATION + How long is a validation allowed to take (time from + ``/setup`` to ``/token``). 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). + +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. + +ADDRESS_TYPE + Type of the address that is being collected, returned as part of the ``address_type`` in the ``/info`` endpoint. Examples include ``email`` or ``phone``. + +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]+$"}'. + + +SEE ALSO +======== + +challenger-dbinit(1), challenger-httpd(1), challenger-config(1). + + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/libeufin-bank.1.rst b/manpages/libeufin-bank.1.rst new file mode 100644 index 00000000..77bc1104 --- /dev/null +++ b/manpages/libeufin-bank.1.rst @@ -0,0 +1,185 @@ +libeufin-bank(1) +################# + +.. only:: html + + Name + ==== + + **libeufin-bank** - LibEuFin Bank + + +Synopsis +======== + +**libeufin-bank** +[**-h** | **--help**] +[**--version**] +COMMAND [ARGS...] + +Subcommands: **serve**, **dbinit**, **create-account**, **passwd**, **gc**, +**config** + + +Description +=========== + +**libeufin-bank** is a program that implements a simple core banking system with +account and REST APIs, including REST APIs for a Web interface +and REST APIs to interact with GNU Taler components. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. + +**–version** + Print version information. + +The interaction model is as follows: + +- Configure the database with commands ``dbinit``. + +- Set admin account password with commands ``passwd``. + +- Start the HTTP server with command ``serve``. + Let this run in a shell, writing logs to stderr. + +The following sections describe each command in detail. + +dbinit +------ + +This command defines the database schema for LibEuFin Bank. It is mandatory to run this command before invoking the ``serve`` command. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**-r** \| **--reset** + If present, deletes any database table (WARNING: potential data loss) + + +serve +----- + +This command starts the HTTP server. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + +create-account +-------------- + +This command create a bank account and prints its payto://-URI to STDOUT. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**-u** \| **--username** *USERNAME* + Account unique username. +**-p** \| **--password** *PASSWORD* + Account password used for authentication. +**--name** *NAME* + Legal name of the account owner. +**--public** + Make this account visible to anyone. +**--exchange** + Make this account a taler exchange. +**--email** *EMAIL* + E-Mail address used for TAN transmission. +**--phone** *PHONE_NUMBER* + Phone number used for TAN transmission. +**--cashout_payto_uri** *PAYTO_URI* + Payto URI of a fiant account who receive cashout amount. +**--payto_uri** *PAYTO_URI* + Payto URI of this account. +**--debit_threshold** *AMOUNT* + Max debit allowed for this account. + + +edit-account +-------------- + +This command edit an existing account. + +It takes one argument, the account username. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--name** *NAME* + Legal name of the account owner. +**--public** *true|false* + Make this account visible to anyone. +**--email** *EMAIL* + E-Mail address used for TAN transmission. +**--phone** *PHONE_NUMBER* + Phone number used for TAN transmission. +**--cashout_payto_uri** *PAYTO_URI* + Payto URI of this account. +**--debit_threshold** *AMOUNT* + Max debit allowed for this account. + +passwd +------ + +This command change any account password. + +It takes two arguments, the account username and the account new password. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + +gc +-- + +This command performs garbage collection: abort expired operations and clean expired data, etc. + +Its options are as follows: + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + +.. include:: ../frags/libeufin-config-cli.rst + + +SEE ALSO +======== + +libeufin-bank.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>. diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst new file mode 100644 index 00000000..ce00f0fa --- /dev/null +++ b/manpages/libeufin-bank.conf.5.rst @@ -0,0 +1,146 @@ +libeufin-bank.conf(5) +###################### + +.. only:: html + + Name + ==== + + **libeufin-bank.conf** - LibEuFin Bank configuration file + + +Description +=========== + +.. include:: ../frags/common-conf-syntax.rst + +Files containing default values for many of the options described below +are installed under ``$TALER_PREFIX/share/libeufin-bank/config.d/``. +The configuration file given with **-c** to Taler binaries +overrides these defaults. + +A configuration file may include another, by using the ``@INLINE@`` directive, +for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to +include the entirety of ``sub.conf`` at that point in ``main.conf``. + +Be extra careful when using ``taler-config -V VALUE`` to change configuration +values: it will destroy all uses of ``@INLINE@`` and furthermore remove all +comments from the configuration file! + +GLOBAL OPTIONS +-------------- + +The following options are from the “[libeufin-bank]” section. + +CURRENCY + Internal currency of the libeufin-bank, e.g. “EUR” for Euro. + +WIRE_TYPE + Supported payment target type, this can either be ``iban`` or ``x-taler-bank`` + +IBAN_PAYTO_BIC + Bank BIC used in generated iban payto URI. Required if ``WIRE_TYPE``is ``iban`` + +X_TALER_BANK_PAYTO_HOSTNAME + Bank hostname used in generated x-taler-bank payto URI. Required if ``WIRE_TYPE``is ``x-taler-bank`` + +NAME + Bank display name, used in webui and TAN messages. Default to ``Taler Bank`` if not specified. + +BASE_URL + The advertised base URL + +DEFAULT_DEBT_LIMIT + Default debt limit for newly created accounts. Defaults to ``CURRENCY:0`` if not specified. + +REGISTRATION_BONUS + Value of the registration bonus for new users. Defaults to ``CURRENCY:0`` if not specified. + +ALLOW_REGISTRATION + Whether anyone can create a new account or whether this action is reserved for the admin. Defaults to ``NO`` if not specified. + +ALLOW_ACCOUNT_DELETION + Whether anyone can delete its account or whether this action is reserved for the admin. Defaults to ``NO`` if not specified. + +ALLOW_EDIT_NAME + Whether anyone can edit their legal name or whether this action is reserved for the admin. Defaults to ``NO`` if not specified. + +ALLOW_EDIT_CASHOUT_PAYTO_URI + Whether anyone can edit their cashout account or whether this action is reserved for the admin. Defaults to ``NO`` if not specified. + +ALLOW_CONVERSION + Whether regional currency conversion is enabled. Defaults to ``NO`` if not specified. + +FIAT_CURRENCY + External currency used during cashin and cashout. + Only used if ``ALLOW_CONVERSION`` is ``YES``. + +TAN_SMS + Path to TAN challenge transmission script via sms. If not specified, this TAN channel will not be supported. + Only used if ``ALLOW_CONVERSION`` is ``YES``. + +TAN_EMAIL + Path to TAN challenge transmission script via email. If not specified, this TAN channel will not be supported. + Only used if ``ALLOW_CONVERSION`` is ``YES``. + +TAN_SMS_ENV + Environment variables for the sms TAN script. + Only used if ``TAN_SMS`` is set. + +TAN_EMAIL_ENV + Environment variables for the email TAN script. + Only used if ``TAN_EMAIL`` is set. + +SERVE + This can either be ``tcp`` or ``unix``. + +PORT + Port on which the HTTP server listens, e.g. 9967. + Only used if ``SERVE`` is ``tcp``. + +BIND_TO + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1``for loopback. Can also be given as a hostname. + Only used if ``SERVE`` is ``tcp``. + +UNIXPATH + Which unix domain path should we bind to? + Only used if ``SERVE`` is ``unix``. + +UNIXPATH_MODE + What should be the file access permissions for ``UNIXPATH``? + Only used if ``SERVE`` is ``unix``. + +SUGGESTED_WITHDRAWAL_EXCHANGE + Exchange that is suggested to wallets when withdrawing + +GC_ABORT_AFTER + Time after which pending operations are aborted during garbage collection + +GC_CLEAN_AFTER + Time after which aborted operations and expired items are deleted during garbage collection + +GC_DELETE_AFTER + Time after which all bank transactions, operations and deleted accounts are deleted during garbage collection + +DATABASE OPTIONS +---------------- + +Setting the database belongs to the “[libeufin-bankdb-postgres]” section and the +following value. + +CONFIG + PostgreSQL connection string. + +SQL_DIR + Where are the SQL files to setup our tables? + +SEE ALSO +======== + +libeufin-bank(1). + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/libeufin-cli.1.rst b/manpages/libeufin-cli.1.rst deleted file mode 100644 index e48fffd3..00000000 --- a/manpages/libeufin-cli.1.rst +++ /dev/null @@ -1,1006 +0,0 @@ -libeufin-cli(1) -############### - -.. only:: html - - Name - ==== - - **libeufin-cli** - Interact with LibEuFin Sandbox and Nexus - - -Synopsis -======== - -**libeufin-cli** -[**-h** | **--help**] -[**--version**] -COMMAND [ARGS...] - -Commands: accounts, connections, facades, permissions, sandbox, users - - -Description -=========== - -**libeufin-cli** is the user interface program to interact -with **libeufin-sandbox** and **libeufin-nexus** when they are -operating as HTTP servers, listening on localhost ports. -Normally, you invoke them with their respective ``serve`` commands, -and in a separate shell, use **libeufin-cli** to send requests -and receive responses from them. - -The interaction model is as follows: - -- (Optionally) Start the sandbox. - -- Start the nexus. - -- Use **libeufin-cli** to interact with them. - You can manage users and permissions, bank accounts, "facades", - transactions, and connections between the various systems. - -For **libeufin-cli** to be able to communicate with **libeufin-sandbox**, -the following environment variables need to be set: - -``LIBEUFIN_SANDBOX_USERNAME`` - This should normally be ``admin``. - -``LIBEUFIN_SANDBOX_PASSWORD`` - This is the same password chosen when the sandbox was started. - -``LIBEUFIN_SANDBOX_URL`` - This is ``http://localhost:PORT``, where ``PORT`` is the - same port chosen when the sandbox was started. - This URL can also be specified with the ``--sandbox-url URL`` - option to the ``sandbox`` command (see below). - If both are given, the ``--sandbox-url`` option takes precedence. - -For **libeufin-cli** to be able to communicate with **libeufin-nexus**, -the following environment variables need to be set: - -``LIBEUFIN_NEXUS_USERNAME`` - For some operations (such as ``users create``), this must be the - same username chosen by the ``libeufin-nexus superuser`` command. - -``LIBEUFIN_NEXUS_PASSWORD`` - This is the password associated with the username. - -``LIBEUFIN_NEXUS_URL`` - This is ``http://localhost:PORT``, where ``PORT`` is the - same port chosen when the nexus was started. - -Of the six commands, the ``sandbox`` command talks to the sandbox, -while the other five commands talk to the nexus. -The following sections describe each command and their subcommands in detail. - - -sandbox -------- - -The ``libeufin-cli sandbox`` command is for managing the sandbox process -started by ``libeufin-sandbox serve``. -It takes one option, ``--sandbox-url URL``, to be specified before -the subcommands and their arguments. -This URL can also be specified with the ``LIBEUFIN_SANDBOX_URL`` -environment variable (see above). -If both are given, the ``--sandbox-url`` option takes precedence. - -The following subcommands are available: bankaccount, check, demobank, -ebicsbankaccount, ebicshost, ebicssubscriber. - -The first command to use is ``check``, -followed by ``ebicshost``, ``ebicssubscriber``, -and ``ebicsbankaccount``, to configure the basic system. - -You can then use the ``bankaccount`` command to generate (simulated) -transaction traffic. - -After that, the ``demobank`` command and its subcommands -provide the same access to the API that Nexus itself uses. -You normally do not need to use those commands directly. - - -sandbox check -------------- - -The ``check`` command attempts a simple aliveness check by -contacting the sandbox and displaying its returned message. -If all goes well, you should see something like: - -.. code-block:: console - - $ libeufin-cli sandbox check - Hello, this is the Sandbox - - -sandbox ebicshost ------------------ - -The ``ebicshost`` command manages EBICS hosts. -It has two subcommands: create and list. - -sandbox ebicshost create -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicshost create`` command creates a EBICS host. -It takes one option, ``--host-id ID``, where ``ID`` is used to -identify that host for all future commands. - -sandbox ebicshost list -^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicshost list`` command lists the hosts in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicshost create --host-id testhost - $ libeufin-cli sandbox ebicshost list - { - "ebicsHosts" : [ "testhost" ] - } - -Here, the ``ID`` is ``testhost``. - - -sandbox ebicssubscriber ------------------------ - -The ``ebicssubscriber`` command manages EBICS subscribers. -It has two subcommands: create and list. - -sandbox ebicssubscriber create -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -NB: This command is deprecated and will be removed at some point. -See ``sandbox demobank new-ebicssubscriber`` (below) for its replacement. - -The ``ebicssubscriber create`` command creates a EBICS subscriber. -It takes three options, all of which are required: - -:: - - --host-id TEXT Ebics host ID - --partner-id TEXT Ebics partner ID - --user-id TEXT Ebics user ID - -The host ID should be the same one specified in ``ebicshost create`` -(see above). - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicssubscriber create \ - --host-id testhost \ - --partner-id partner01 \ - --user-id user01 - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example (see above). - -sandbox ebicssubscriber list -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicssubscriber list`` command lists the EBICS subscribers -in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicssubscriber list - { - "subscribers" : [ { - "hostID" : "testhost", - "partnerID" : "partner01", - "userID" : "user01", - "systemID" : null, - "demobankAccountLabel" : "not associated yet" - } ] - } - -Note that the output reflects the subscriber created in -the ``ebicssubscriber create`` example (see above). - - -sandbox ebicsbankaccount ------------------------- - -The ``ebicsbankaccount`` command manages EBICS bank accounts. -It has one subcommand: create. -(To list accounts, see ``sandbox bankaccount`` below.) - -sandbox ebicsbankaccount -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``ebicsbankaccount create`` command takes several options, all required: - -:: - - --iban TEXT IBAN - --bic TEXT BIC - --person-name TEXT bank account owner name - --account-name TEXT label of this bank account - --ebics-user-id TEXT user ID of the Ebics subscriber - --ebics-host-id TEXT host ID of the Ebics subscriber - --ebics-partner-id TEXT partner ID of the Ebics subscriber - -At this time, although the ``--person-name`` option is required, -the sandbox does not remember the option value. -(When queried, it displays "Bank account owner's name" instead. -See ``sandbox bankaccount`` below.) -For the sandbox, the important value is the ``--account-name`` option. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox ebicsbankaccount create \ - --iban DE18500105172929531888 \ - --bic INGDDEFFXXX \ - --person-name "Jane Normal" \ - --account-name testacct01 \ - --ebics-host-id testhost \ - --ebics-user-id user01 \ - --ebics-partner-id partner01 - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example, and that ``user01`` and ``partner01`` are the same as in the -``ebicssubscriber create`` example (see above). - - -sandbox bankaccount -------------------- - -The ``bankaccount`` command manages bank accounts. -It has several subcommands: list, generate-transactions, -simulate-incoming-transaction, transactions. - -sandbox bankaccount list -^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount list`` command lists the bank accounts in the system. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount list - [ { - "label" : "bank", - "name" : "Bank account owner's name", - "iban" : "DE370758", - "bic" : "SANDBOXX" - }, { - "label" : "testacct01", - "name" : "Bank account owner's name", - "iban" : "DE18500105172929531888", - "bic" : "INGDDEFFXXX" - } ] - -Note that ``testacct01``, ``DE18500105172929531888``, and ``INGDDEFFXXX`` -are the same as specified in the ``ebicsbankaccount create`` example -(see above). - -sandbox bankaccount generate-transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The remaining ``bankaccount`` commands deal with transactions -to and from the bank accounts. - -The ``bankaccount generate-transactions`` command generates -test transactions. -It takes one arg, the account label. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount generate-transactions testacct01 - -Note that ``testacct01`` is the account label shown in the ``bankaccount -list`` example (see above). - -sandbox bankaccount simulate-incoming-transaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount simulate-incoming-transaction`` books an -incoming payment in the sandbox. -It takes one arg, the account label, and several options. - -:: - - --debtor-iban TEXT IBAN sending the payment - --debtor-bic TEXT BIC sending the payment - --debtor-name TEXT name of the person who is sending the payment - --amount TEXT amount, no currency - --subject TEXT payment subject - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount simulate-incoming-transaction - testacct01 \ - --debtor-iban DE06500105174526623718 \ - --debtor-bic INGDDEFFXXX \ - --debtor-name "Joe Foo" \ - --subject "Hello World" \ - --amount 10.50 - -Note that ``testacct01`` is the same as in previous examples (see above), -and that ``10.50`` is in ``X.Y`` format. - -sandbox bankaccount transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``bankaccount transactions`` command lists transactions. -It takes one arg, the account label. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox bankaccount transactions testacct01 - { - "payments" : [ { - "accountLabel" : "testacct01", - "creditorIban" : "DE18500105172929531888", - "creditorBic" : "INGDDEFFXXX", - "creditorName" : "Creditor Name", - "debtorIban" : "DE64500105178797276788", - "debtorBic" : "DEUTDEBB101", - "debtorName" : "Max Mustermann", - "amount" : "5", - "currency" : "EUR", - "subject" : "sample transaction DILWBJHL", - "date" : "Wed, 26 Jan 2022 09:03:44 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "DILWBJHL", - "paymentInformationId" : null - }, { - "accountLabel" : "testacct01", - "creditorIban" : "DE64500105178797276788", - "creditorBic" : "DEUTDEBB101", - "creditorName" : "Max Mustermann", - "debtorIban" : "DE18500105172929531888", - "debtorBic" : "INGDDEFFXXX", - "debtorName" : "Debitor Name", - "amount" : "12", - "currency" : "EUR", - "subject" : "sample transaction N7JSY17B", - "date" : "Wed, 26 Jan 2022 09:03:44 GMT", - "creditDebitIndicator" : "debit", - "accountServicerReference" : "N7JSY17B", - "paymentInformationId" : null - }, { - "accountLabel" : "testacct01", - "creditorIban" : "DE18500105172929531888", - "creditorBic" : "INGDDEFFXXX", - "creditorName" : "Creditor Name", - "debtorIban" : "DE06500105174526623718", - "debtorBic" : "INGDDEFFXXX", - "debtorName" : "Joe Foo", - "amount" : "10.50", - "currency" : "EUR", - "subject" : "Hello World", - "date" : "Wed, 26 Jan 2022 09:04:31 GMT", - "creditDebitIndicator" : "credit", - "accountServicerReference" : "sandbox-6UI2J3636J9EESXO", - "paymentInformationId" : null - } ] - } - -Note that ``testacct01`` is the same as in previous examples (see above), -and that the generated transactions from previous examples are listed, -as well. - - -sandbox demobank ----------------- - -The ``demobank`` command provides an interface to the Access API, -which includes three commands: register, info, new-transaction. -There is also a fourth ``demobank`` command, new-ebicssubscriber, -that does not use the Access API. - -For all ``demobank`` commands, the sandbox URL *must* specify which -*one* bank the command applies to in the base URL. -Note that this URL cannot be used with other sandbox commands. -In other words: - -``--sandbox-url http://localhost:5016/demobanks/default`` - This base URL can be used for commands: - - - sandbox demobank register - - sandbox demobank info - - sandbox demobank new-ebicssubscriber - - sandbox demobank new-transaction - - It specifies the ``default`` demobank. - -``--sandbox-url http://localhost:5016`` - This base URL can be used for all other sandbox commands. - -In the following examples, the base URL will be explicitly shown with -the ``--sandbox-url`` option for the ``demobank`` commands. - -sandbox demobank register -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank register`` command registers a new bank account. -Note that the username will be both the username to login at -the bank and the bank account label. -It takes the username and password from the -``LIBEUFIN_SANDBOX_USERNAME`` and ``LIBEUFIN_SANDBOX_PASSWORD`` -environment variables. -The username *need not be* ``admin``. - -For example: - -.. code-block:: console - - $ export LIBEUFIN_SANDBOX_USERNAME=jrluser - $ export LIBEUFIN_SANDBOX_PASSWORD=easy - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank register - -sandbox demobank info -^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank info`` command returns basic information on a bank account. -It takes option ``--bank-account NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank info --bank-account jrluser - { - "balance" : { - "amount" : "EUR:100", - "credit_debit_indicator" : "credit" - }, - "paytoUri" : "payto://iban/SANDBOXX/DE948559?receiver-name=admin" - } - -Note that ``jrluser`` is the same username / bank account name -as in the ``register`` example (see above). - -sandbox demobank new-ebicssubscriber -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank new-ebicssubscriber`` command associates a new Ebics -subscriber to an existing bank account. -It takes several options, all required: - -:: - - --host-id TEXT Ebics host ID - --partner-id TEXT Ebics partner ID - --user-id TEXT Ebics user ID - --bank-account TEXT Label of the bank account to associate - with this Ebics subscriber - -For example: - -.. code-block: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank new-ebicssubscriber \ - --host-id testhost \ - --partner-id partner01 \ - --user-id user02 \ - --bank-account jrluser - -Note that ``testhost`` is the same as in the ``ebicshost create`` -example, and that ``partner01`` is the same as in the -``ebicssubscriber create`` example (see above). -The ``user02`` is new. -The ``--bank-account jrluser`` is the same as in the -``info`` example (see above). -You can see the effect of the ``new-ebicssubscriber`` command -with the ``sandbox ebicssubscriber list`` -and ``sandbox bankaccount list`` commands. - -sandbox demobank new-transaction -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``demobank new-transaction`` command initiates a new transaction. -It takes several options, all required: - -:: - - --bank-account TEXT Label of the bank account to be - debited for the transaction - --payto-with-subject TEXT Payto address including the - subject as a query parameter - --amount CUR:X.Y Amount to transfer - -For example: - -.. code-block:: console - - $ libeufin-cli sandbox \ - --sandbox-url http://localhost:5016/demobanks/default \ - demobank new-transaction \ - --bank-account jrluser \ - --payto-with-subject 'payto://FIXME/?message=1kg+coffee' \ - --amount EUR:10.50 - FIXME: Any output? - -Note that ``--bank-account jrluser`` is the same as in the -``info`` and ``new-ebicssubscriber`` command examples (see above). - - -connections ------------ - -The ``connections`` set of commands handle connections between -the bank(s) and Nexus. -It has several subcommands: -new-ebics-connection, -list-connections, -show-connection, -delete-connection, -export-backup, -restore-backup, -get-key-letter, -connect, -list-offered-bank-accounts, -download-bank-accounts, -import-bank-account. - -Generally, you will create a connection, save its critical key information -to a safe location, then use the connection to find and import a bank -account, for further use. - -Several commands take a ``CONNECTION_NAME`` argument. -In the following examples, we use ``conn01`` for that. -Also, for demonstration purposes, we use the sandbox EBICS services, -so the ``EBICS_URL`` follows the previous examples in the ``sandbox`` -command, as the value of environment variable ``LIBEUFIN_SANDBOX_URL`` -suffixed with ``/ebicsweb``, i.e., ``http://localhost:5016/ebicsweb``. - -connections new-ebics-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections new-ebics-connection`` command creates a new connection -between an EBICS service and the Nexus. -It takes one arg, the ``CONNECTION_NAME``, and four required options: - -:: - - --ebics-url TEXT EBICS URL - --host-id TEXT Host ID - --partner-id TEXT Partner ID - --ebics-user-id TEXT Ebics user ID - -For example: - -.. code-block:: console - - $ libeufin-cli connections new-ebics-connection \ - --ebics-url http://localhost:5016/ebicsweb \ - --host-id testhost \ - --partner-id partner01 \ - --ebics-user-id user02 \ - conn01 - -Note that the ``testhost``, ``partner01``, and ``user02`` are the same as -in the ``sandbox demobank new-ebicssubscriber`` command (see above). - -connections list-connections -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections list-connections`` command lists connections in Nexus. -For example: - -.. code-block:: console - - $ libeufin-cli connections list-connections - { - "bankConnections" : [ { - "name" : "conn01", - "type" : "ebics" - } ] - } - -The name of the connection is ``conn01`` as in the -``connections new-ebics-connection`` example (see above). - -connections show-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections show-connection`` command displays information -about a specific connection. -It takes one argument, the ``CONNECTION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections show-connection conn01 - { - "type" : "ebics", - "owner" : "foo", - "ready" : true, - "details" : { - "ebicsUrl" : "http://localhost:5016/ebicsweb", - "ebicsHostId" : "testhost", - "partnerId" : "partner01", - "userId" : "user02" - } - } - -The details are the same as in the ``connections new-ebics-connections`` -example (see above). - -connections delete-connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections delete-connection`` command deletes a bank connection. -It takes one argument, the ``CONNECTION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections delete-connection conn01 - -connections export-backup -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections export-backup`` command writes key and signature -information to a backup file (which you should take care to store -in a secure location). -It takes one argument, the ``CONNECTION_NAME`` and two required options: - -:: - - --passphrase TEXT Passphrase for locking the backup - --output-file TEXT Where to store the backup - -For example: - -.. code-block:: console - - $ libeufin-cli connections export-backup \ - --passphrase secret \ - --output-file sig-and-key-info \ - conn01 - FIXME: Output? - -See: https://bugs.gnunet.org/view.php?id=7180 - -connections restore-backup -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections get-key-letter -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The ``connections get-key-letter`` command creates a PDF file -that contains key information. -It takes two arguments, ``CONNECTION_NAME`` and ``OUTPUT_FILE``. - -For example: - -.. code-block:: console - - $ libeufin-cli connections get-key-letter conn01 key-letter.pdf - -This creates file ``key-letter.pdf`` in the current working directory. - -connections connect -^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections list-offered-bank-accounts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections download-bank-accounts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -connections import-bank-account -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - - -users ------ - -The ``libeufin-cli users`` command manages users authorized to -operate Nexus. -It has several subcommands: self, list, create, change-password. -The ``create`` and ``change-password`` commands can only be issued -by the superuser -(as configured by the ``libeufin-nexus superuser`` command), -while the ``self`` and ``list`` commands can be issued by any user. - -In the following ``users`` examples, we assume that previously -the command ``libeufin-nexus superuser foo`` was issued, and -that the current username and password are for that user -(via environment variables ``LIBEUFIN_NEXUS_USERNAME`` and -``LIBEUFIN_NEXUS_PASSWORD``, see above). - -users self -^^^^^^^^^^ - -The ``users self`` command displays information for the current user. - -For example: - -.. code-block:: console - - $ libeufin-cli users self - { - "username" : "foo", - "superuser" : true - } - -users list -^^^^^^^^^^ - -The ``users list`` command displays information for all the -users authorized to operate Nexus. - -For example: - -.. code-block:: console - - $ libeufin-cli users list - { - "users" : [ { - "username" : "foo", - "superuser" : true - } ] - } - -In this example, there is only one user, the superuser ``foo``. - -users create -^^^^^^^^^^^^ - -The ``users create`` command creates a normal (non-superuser) user. -It takes one argument, the ``USERNAME`` and one option, -``--password TEXT``. -If you omit the option, **libeufin-cli** will prompt you for the password. - -For example: - -.. code-block:: console - - $ libeufin-cli users create --password easy jrluser - { - "message" : "New user 'jrluser' registered" - } - $ libeufin-cli users list - { - "users" : [ { - "username" : "foo", - "superuser" : true - }, { - "username" : "jrluser", - "superuser" : false - } ] - } - -In this example, we create the same user as for the sandbox examples -(see above). -Note that the system now includes two users. - -users change-password -^^^^^^^^^^^^^^^^^^^^^ - -The ``users change-password`` command changes the password for a user. -It takes one argument, the ``USERNAME`` and one option, -``--new-password TEXT``. -If you omit the option, **libeufin-cli** will prompt you for the password. - -For example: - -.. code-block:: console - - $ libeufin-cli users change-password --new-password hard jrluser - { - "message" : "Password successfully changed" - } - - -permissions ------------ - -The ``libeufin-cli permissions`` command manages permissions -for operations on Nexus. -It has three subcommands: list, grant, revoke. -All three commands can only be issued by the superuser. - -permissions list -^^^^^^^^^^^^^^^^ - -The ``permissions list`` command lists the granted permissions. -At the beginning of a session, there are none: - -.. code-block:: console - - $ libeufin-cli permissions list - { - "permissions" : [ ] - } - - -permissions grant -^^^^^^^^^^^^^^^^^ - -The ``permissions grant`` command adds a permission to the list -of granted permissions. -It takes five arguments: ``SUBJECT_TYPE``, ``SUBJECT_ID``, -``RESOURCE_TYPE``, ``RESOURCE_ID``, ``PERMISSION_NAME``. - -FIXME: The subject type and id, resource type and id, are ... - -The ``PERMISSION_NAME`` is one of the following: - -- ``facade.talerwiregateway.history`` -- ``facade.talerwiregateway.transfer`` -- ``facade.anastasis.history`` - -For example: - -.. code-block:: console - - $ libeufin-cli permissions grant \ - some-subject-type some-subject-id \ - some-resource-type some-resource-id \ - facade.anastasis.history - { } - $ libeufin-cli permissions list - { - "permissions" : [ { - "subjectType" : "some-subject-type", - "subjectId" : "some-subject-id", - "resourceType" : "some-resource-type", - "resourceId" : "some-resource-id", - "permissionName" : "facade.anastasis.history" - } ] - } - -permissions revoke -^^^^^^^^^^^^^^^^^^ - -The ``permissions revoke`` command does the opposite of the -``permissions grant`` command. -It takes the same arguments as the ``permissions grant`` command: -``SUBJECT_TYPE``, ``SUBJECT_ID``, ``RESOURCE_TYPE``, ``RESOURCE_ID``, -``PERMISSION_NAME``. - -For example: - -.. code-block:: console - - $ libeufin-cli permissions revoke \ - some-subject-type some-subject-id \ - some-resource-type some-resource-id \ - facade.anastasis.history - { } - $ libeufin-cli permissions list - { - "permissions" : [ ] - } - -This example undoes the effect of the previous (``permissions grant``) example. - - -accounts --------- - -WRITEME - -accounts transactions -^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-status -^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-schedule -^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts task-delete -^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts submit-payment -^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts show-payment -^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts show -^^^^^^^^^^^^^ - -WRITEME - -accounts prepare-payment -^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts list-tasks -^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts list-payments -^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts fetch-transactions -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -accounts delete-payment -^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - - -facades -------- - -WRITEME - -facades new-taler-wire-gateway-facade -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -facades new-anastasis-facade -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WRITEME - -facades list -^^^^^^^^^^^^ - -WRITEME - - -See Also -======== - -.. TODO: libeufin-sandbox(1), libeufin-cli(1). - - -Bugs -==== - -Report bugs by using https://bugs.taler.net or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/libeufin-nexus.1.rst b/manpages/libeufin-nexus.1.rst index d1a0698e..a0ed99ff 100644 --- a/manpages/libeufin-nexus.1.rst +++ b/manpages/libeufin-nexus.1.rst @@ -6,7 +6,7 @@ libeufin-nexus(1) Name ==== - **libeufin-nexus** - Sevice to interface to various bank access APIs + **libeufin-nexus** - EBICS client. Synopsis @@ -17,21 +17,14 @@ Synopsis [**--version**] COMMAND [ARGS...] -Commands: serve, superuser, parse-camt, reset-tables +Subcommands: **dbinit**, **ebics-setup**, **ebics-submit**, **ebics-fetch**, **config** Description =========== **libeufin-nexus** is a program that provides a service to interface to -various bank access APIs, using JSON as the response format. -It maintains state in its own private database. -You interact with it through HTTP -requests either over the network or via a Unix domain socket. -Related program **libeufin-cli** is the preferred front end -for that mode of operation. -There is also a mode where **libeufin-nexus** accepts commands directly, -useful for doing administrative tasks. +various bank access APIs Its options are as follows: @@ -43,108 +36,119 @@ Its options are as follows: The interaction model is as follows: -- Configure the nexus with command ``superuser``. - -- Start the HTTP server with command ``serve``. - Let this run in a shell, writing logs to stderr. - -- Interact with **libeufin-nexus**. - -- When finished, interrupt the ``serve`` process and clean up with command - ``reset-tables``. +In order to operate any EBICS communication with ``libeufin-nexus``, it is necessary to setup EBICS access via the ``ebics-setup`` subcommand. Setting the access means to share the client keys with the bank and downloading the bank keys. After a successful setup, the subcommands ``ebics-submit`` and ``ebics-fetch`` can be run to respectively send payments and download the bank account history. The following sections describe each command in detail. +ebics-setup +----------- -superuser ---------- - -This command adds a superuser, or changes the password. -It takes argument ``USERNAME``. -Option ``--password TEXT`` specifies the password. -If omitted, **libeufin-nexus** will query interactively for it. - -For example: - -.. code-block:: console +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. - $ libeufin-nexus superuser joe +Its options are as follows: -This creates superuser ``joe`` and interactively queries for the password. +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--force-keys-resubmission** + Resubmits the client keys. If no keys were found, it creates and submits them. +**--auto-accept-keys** + Accepts the bank keys without interactively asking the user. +**--generate-registration-pdf** + 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. -parse-camt ----------- +dbinit +------ -This command parses a camt file and displays the result to stdout. -It takes argument ``FILENAME``, which names a file in CAMT format. -Parsing may also display log information to stderr. -The normal log level is ``DEBUG``. -To change it, use ``--log-level LEVEL``, where ``LEVEL`` is one of: -``ERROR``, ``WARN``, ``INFO``, ``DEBUG``, ``TRACE``. +This subcommand defines the database schema for Nexus. It is mandatory to run this command before invoking the ``ebics-submit`` or ``ebics-fetch`` subcommands. -For example: +Its options are as follows: -.. code-block:: console +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**-r** \| **--reset** + If present, deletes any database table (WARNING: potential data loss) - $ libeufin-nexus parse-camt camt53-gls-style-0.xml - { - "transactions" : [ { - "amount" : "EUR:2.35", - "creditDebitIndicator" : "DBIT", - ... - } ] - } +ebics-submit +------------ -serve ------ +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. -This command starts the HTTP server, listening on port 5001. -To use a different port, use option ``--port INT``. -To listen, instead, on a Unix domain socket, -use option ``--with-unix-socket PATH``. -When both ``--port`` and ``--with-unix-socket`` are given, -``--with-unix-socket`` takes precedence. +Its options are as follows: -The process runs in the foreground, writing its logs to standard error. -The normal log level is ``DEBUG``. -To change it, use ``--log-level LEVEL``, where ``LEVEL`` is one of: -``ERROR``, ``WARN``, ``INFO``, ``DEBUG``, ``TRACE``. +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + Uploaded documents will be stored *before* being submitted to the bank. This directory would contain several directories, each named after the ``YYYY-MM-DD/submit`` format. The pain.001 file would then be named in the following schema: ``$microseconds_pain.001.xml``. +**--transient** + This flag, enabled by default, causes the command to check the database and submit only once, and then return. -Before invoking ``serve``, the following environment variable needs to be set: -``LIBEUFIN_NEXUS_DB_CONNECTION`` - This specifies the database **libeufin-nexus** uses to maintain state. - Currently, both Sqlite and PostgreSQL are supported. - (Only one needs to be specified.) - Examples: +ebics-fetch +----------- - - ``jdbc:sqlite:/tmp/libeufin-nexus.db`` - - ``jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret`` +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. -Normally, the ``serve`` command runs until interrupted. -When run in a shell, you can use ``Control-C`` for that. +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: +* ``acknowledgement``: EBICS acknowledgement, retrieves the status of EBICS orders. +* ``status``: Payment status, retrieves status of pending debits. +* ``notification``: Debit & credit notifications, retrieves the history of confirmed debits and credits. -reset-tables ------------- +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--debug-ebics** *SAVEDIR* + Log EBICS content at SAVEDIR. + Downloaded documents will be stored *before* being ingested in the database. This directory would contain several directories, each named after the ``YYYY-MM-DD/fetch`` format. The stored files would then be named after the following schema: ``$microseconds_$filename``. 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: ``$microseconds_HAC_response.pain.002.xml``. +**--transient** + This flag, enabled by default, causes the command to perform one download and return. +**--pinned-start** + Only supported in --transient mode, this option lets specify the earliest timestamp of the downloaded documents. The latest timestamp is always the current time. -This command drops all the tables in the internal database. -(The next time the tables are needed, **libeufin-nexus** creates them -again, automatically.) +initiate-payment +---------------- -It should only be used when the nexus is quiescent. +This subcommand initiates an outgoing payment. The pending payment is stored in the database and will be performed the next time ``ebics-submit`` run. +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. -See Also +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**--amount** *AMOUNT* + The amount to transfer, payto 'amount' parameter takes the precedence +**--subject** *TEXT* + The payment subject, payto 'message' parameter takes the precedence +**--request-uid** *TEXT* + The payment request UID, will be randomly generated if missing. + +.. include:: ../frags/libeufin-config-cli.rst + +SEE ALSO ======== -.. TODO: libeufin-sandbox(1), libeufin-cli(1). - +libeufin-nexus.conf(5) Bugs ==== -Report bugs by using https://bugs.taler.net or by sending electronic -mail to <taler@gnu.org>. +Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>. diff --git a/manpages/libeufin-nexus.conf.5.rst b/manpages/libeufin-nexus.conf.5.rst new file mode 100644 index 00000000..9100f8fe --- /dev/null +++ b/manpages/libeufin-nexus.conf.5.rst @@ -0,0 +1,190 @@ +libeufin-nexus.conf(5) +###################### + +.. only:: html + + Name + ==== + + **libeufin-nexus.conf** - LibEuFin Nexus configuration file + + +Description +=========== + +The configuration file is line-oriented. Blank lines and whitespace at the +beginning and end of a line are ignored. Comments start with ``#`` or ``%`` +in the first column (after any beginning-of-line whitespace) and go to the end +of the line. + +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 ``=`` (equal sign). Section names and options are +*case-insensitive*. + +The values, however, are *case-sensitive*. In particular, boolean values are +one of ``YES`` or ``NO``. Values can include whitespace by surrounding the +entire value with ``"`` (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. + +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 *5m* denotes a duration of *five minutes*. + +Values that represent filenames can begin with a ``/bin/sh``-like variable +reference. This can be simple, such as ``$TMPDIR/foo``, or complex, such as +``${TMPDIR:-${TMP:-/tmp}}/foo``. The variables are expanded either using +key-values from the ``[PATHS]`` section (see below) or from the environment +(``getenv()``). The values from ``[PATHS]`` take precedence over those from +the environment. If the variable name is found in neither ``[PATHS]`` nor the +environment, a warning is printed and the value is left unchanged. Variables (including those from the environment) are expanded recursively, so if ``FOO=$BAR`` and ``BAR=buzz`` then the result is ``FOO=buzz``. Recursion is bounded to at most 128 levels to avoid undefined behavior for mutually recursive expansions like if ``BAR=$FOO`` in the example above. + +The ``[PATHS]`` section is special in that it contains paths that can be +referenced using ``$`` in other configuration values that specify +*filenames*. Note that configuration options that are not specifically +retrieved by the application as *filenames* will not see “$”-expressions +expanded. To expand ``$``-expressions when using ``taler-config``, you must pass +the ``-f`` command-line option. + +The system automatically pre-populates the ``[PATHS]`` 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 `GNU autoconf +<https://www.gnu.org/prep/standards/html_node/Directory-Variables.html>`_. The +values are usually dependent on an ``INSTALL_PREFIX`` which is determined by +the ``--prefix`` option given to configure. The canonical values are: + + * LIBEXECDIR = $INSTALL_PREFIX/taler/libexec/ + * DOCDIR = $INSTALL_PREFIX/share/doc/taler/ + * ICONDIR = $INSTALL_PREFIX/share/icons/ + * LOCALEDIR = $INSTALL_PREFIX/share/locale/ + * PREFIX = $INSTALL_PREFIX/ + * BINDIR = $INSTALL_PREFIX/bin/ + * LIBDIR = $INSTALL_PREFIX/lib/taler/ + * DATADIR = $INSTALL_PREFIX/share/taler/ + +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. + +Files containing default values for many of the options described below +are installed under ``$TALER_PREFIX/share/libeufin-nexus/config.d/``. +The configuration file given with **-c** to Taler binaries +overrides these defaults. + +A configuration file may include another, by using the ``@INLINE@`` directive, +for example, in ``main.conf``, you could write ``@INLINE@ sub.conf`` to +include the entirety of ``sub.conf`` at that point in ``main.conf``. + +Be extra careful when using ``taler-config -V VALUE`` to change configuration +values: it will destroy all uses of ``@INLINE@`` and furthermore remove all +comments from the configuration file! + +GLOBAL OPTIONS +-------------- + +Setting the database belongs to the “[nexus-postgres]” section and the +following value. + +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. + +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: + +LIBEUFIN_HOME + Home directory of the user, usually “${HOME}”. Can be overwritten by + testcases by setting ${LIBEUFIN_TEST_HOME}. + +EBICS SETUP OPTIONS +------------------- + +The following options are from the “[nexus-ebics]” section and used by +the ``libeufin-nexus ebics-setup`` command. + +CURRENCY + Name of the currency, e.g. “EUR” for Euro. + +HOST_BASE_URL + URL of the EBICS server + +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. + +HOST_ID + EBICS specific: name of the EBICS host + +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. + +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. + +BANK_PUBLIC_KEYS_FILE + Filesystem location where Nexus should store the bank public keys. + +CLIENT_PRIVATE_KEYS_FILE + Filesystem location where Nexus should store the subscriber private keys. + +IBAN + IBAN of the bank account that is associated with the EBICS subscriber. + +BIC + BIC of the bank account that is associated with the EBICS subscriber. + +NAME + Legal entity that is associated with the EBICS subscriber. + + +EBICS SUBMIT OPTIONS +-------------------- + +The following configuration value(s) belong to the “[nexus-submit]” section. + +FREQUENCY + Duration value to instruct the ``ebics-submit`` subcommand how much to wait + before checking the database again to find new unsubmitted payments. + +EBICS FETCH OPTIONS +------------------- + +The following configuration value(s) belong to the “[nexus-fetch]” section. + +FREQUENCY + Duration value to instruct the ``ebics-fetch`` subcommand how often it should + download from the bank. + +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. + +DATABASE OPTIONS +---------------- + +Setting the database belongs to the “[libeufin-nexusdb-postgres]” section and the following value. + +CONFIG + PostgreSQL connection string. + +SQL_DIR + Where are the SQL files to setup our tables? + +SEE ALSO +======== + +libeufin-nexus(1) + +BUGS +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/libeufin-sandbox.1.rst b/manpages/libeufin-sandbox.1.rst deleted file mode 100644 index fc1c7f3d..00000000 --- a/manpages/libeufin-sandbox.1.rst +++ /dev/null @@ -1,218 +0,0 @@ -libeufin-sandbox(1) -################### - -.. only:: html - - Name - ==== - - **libeufin-sandbox** - Simulate a banking system core - with EBICS access to bank accounts - - -Synopsis -======== - -**libeufin-sandbox** -[**-h** | **--help**] -[**--version**] -COMMAND [ARGS...] - -Commands: serve, reset-tables, config, make-transaction, camt053tick -default-exchange - - -Description -=========== - -**libeufin-sandbox** is a program to simulate a banking system core -with EBICS access to bank accounts. -It maintains state in its own private database. -You interact with it through HTTP -requests either over the network or via a Unix domain socket. -Related program **libeufin-cli** is the preferred front end -for that mode of operation. -There is also a mode where **libeufin-sandbox** accepts commands directly, -useful for configuring one or more "demobank" (simulated bank) instances. - -Its options are as follows: - -**-h** \| **--help** - Print short help on options. - -**–version** - Print version information. - -The interaction model is as follows: - -.. @MS Is the order of the first two steps correct? - Or are some of the commands to be used AFTER ‘serve’ starts? - Or is it a mix? (I believe it is a mix, but am not sure.) - -- Configure the sandbox with commands ``config``, ``default-exchange``, - ``make-transaction``, and ``camt053tick``. - -- Start the HTTP server with command ``serve``. - Let this run in a shell, writing logs to stderr. - -- Point program **libeufin-nexus** at the sandbox. - -- Interact with **libeufin-nexus**. - -- When finished, interrupt the ``serve`` process and clean up with command - ``reset-tables``. - -The following sections describe each command in detail. - - -config ------- - -This command takes argument ``NAME`` and creates a demobank with that name. - -Option ``--currency CUR`` (default: ``EUR``) specifes another currency. -Option ``--bank-debt-limit N`` (default: 1000000) specifies that -the bank debt limit should be N (units of currency). -Similarly, option ``--users-debt-limit N`` (default: 1000) specifies -that the users debt limit should be N (units of currency). - -For example: - -.. code-block:: console - - $ libeufin-sandbox config default - -This creates the demobank ``default`` with currency ``EUR``, -bank debt limit 1000000, users debt limit 1000, -and allows registrations. - - -default-exchange ----------------- - -This command sets the exchange that a demobank will suggest to wallets. -(Wallets are of course free to disregard the suggestion and choose -another exchange.) -It requires two arguments, ``EXCHANGE-BASEURL`` and ``EXCHANGE-PAYTO``. -The option ``--demobank NAME`` (default: ``default``) specifies -which demobank this setting affects. - -For example: - -.. code-block:: console - - $ libeufin-sandbox default-exchange \ - --demobank bank01 \ - https://exchange.example.com/ \ - payto://iban/CH9300762011623852957 - -This sets the default exchange for demobank ``bank01``. -It is an error if the demobank does not exist. - - -make-transaction ----------------- - -This is a "legacy" command, useful in a previous iteration of LibEuFin -and for internal testing. -It creates and records a wire transfer transaction in the database. - -It takes two arguments and several required options. -The arguments are ``AMOUNT``, in ``CUR:X.Y`` format; -and ``SUBJECT``, a short textual description of the transaction. -The options are: ``--credit-account LABEL`` and ``--debit-account LABEL``, -where each LABEL names a bank account for receiving and issuing, -respectively, the wire transfer. -The option ``--demobank NAME`` (default: ``default``) specifies -in which demobank the wire transfer occurs. - -.. note:: - - If you have not yet called ``config``, this command creates - a demobank named ``default`` on its first use. The currency, - and bank debt limit have the same defaults as for the ``config`` - command. The users debt limit, however, defaults to 10000. - -FIXME: How to achieve the same result with **libeufin-cli**? - - -camt053tick ------------ - -This command advances the internal time step that the demobank -uses to group transactions for reporting. -(Successive transactions will be inserted in a new Camt.053 report.) - -For example: - -.. code-block:: console - - $ libeufin-sandbox camt053tick - -FIXME: How to achieve the same result with **libeufin-cli**? - - -serve ------ - -This command starts the HTTP server, listening on port 5000. -To use a different port, use option ``--port INT``. -To listen, instead, on a Unix domain socket, -use option ``--with-unix-socket PATH``. -When both ``--port`` and ``--with-unix-socket`` are given, -``--with-unix-socket`` takes precedence. - -.. note:: - - If you have not yet called ``config``, this command creates - a demobank named ``default`` on its first use. The currency, - and bank debt limit have the same defaults as for the ``config`` - command. The users debt limit, however, defaults to 10000. - -The process runs in the foreground, writing its logs to standard error. -The normal log level is ``DEBUG``. -To change it, use ``--log-level LEVEL``, where ``LEVEL`` is one of: -``ERROR``, ``WARN``, ``INFO``, ``DEBUG``, ``TRACE``. - -Before invoking ``serve``, the following environment variables need to be set: - -``LIBEUFIN_SANDBOX_ADMIN_PASSWORD`` - The password required for later use by **libeufin-cli**. - For testing purposes, you can use option ``--no-auth`` to disable - this requirement. - (In that case, this environment variable need not be set.) - -``LIBEUFIN_SANDBOX_DB_CONNECTION`` - This specifies the database **libeufin-sandbox** uses to maintain state. - Currently, both Sqlite and PostgreSQL are supported. - (Only one needs to be specified.) - Examples: - - - ``jdbc:sqlite:/tmp/libeufin-sandbox.db`` - - ``jdbc:postgresql://localhost:5432/libeufindb?user=Foo&password=secret`` - -Normally, the ``serve`` command runs until interrupted. -When run in a shell, you can use ``Control-C`` for that. - - -reset-tables ------------- - -This command drops all the tables in the internal database. -(The next time the tables are needed, **libeufin-sandbox** creates them -again, automatically.) - -It should only be used when the sandbox is quiescent. - - -See Also -======== - -.. TODO: libeufin-nexus(1), libeufin-cli(1). - - -Bugs -==== - -Report bugs by using https://bugs.taler.net or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/sync-dbconfig.1.rst b/manpages/sync-dbconfig.1.rst new file mode 100644 index 00000000..bafc5df6 --- /dev/null +++ b/manpages/sync-dbconfig.1.rst @@ -0,0 +1,61 @@ +sync-dbconfig(1) +################ + +.. only:: html + + Name + ==== + + **sync-dbconfig** - configure sync database + + +Synopsis +======== + +**sync-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**sync-dbconfig** is a simple shell script that configures +a Postgresql database for use by ``sync-httpd``. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``sync-dbinit`` manually. + +**-u** *USER* + Specifies the (main) sync user that will access the database. + +See Also +======== + +sync-dbinit(1), sync.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-aggregator-benchmark.1.rst b/manpages/taler-aggregator-benchmark.1.rst new file mode 100644 index 00000000..7047f6f7 --- /dev/null +++ b/manpages/taler-aggregator-benchmark.1.rst @@ -0,0 +1,72 @@ +taler-aggregator-benchmark(1) +############################# + + +.. only:: html + + Name + ==== + + **taler-aggregator-benchmark** - setup database to measure aggregator performance + + +Synopsis +======== + +**taler-aggregator-benchmark** +[**-c** *CONFIG_FILENAME* | **--config=**\ \ *CONFIG_FILENAME*] +[**-d** *DN* | **--deposits=**\ \ *DN*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--log-level=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-m** *DM* | **--merchants=**\ \ *DM*] +[**-r** *RATE* | **--refunds=**\ \ *RATE*] +[**-v** | **--version**] + +Description +=========== + +**taler-aggregator-benchmark** is a command-line tool to fill an exchange +database with records suitable for benchmarking the +**taler-exchange-aggregator**. The **taler-aggregator-benchmark** tool does +not run the actual workload for the benchmark (which usually consists of +starting multiple **taler-exchange-aggregator** processes) and instead only +prepares the database with synthetic work. + +**-c** *CONFIG_FILENAME* \| **--config=**\ \ *CONFIG_FILENAME* + (Mandatory) Use CONFIG_FILENAME as the name for the configuration file. + +**-d** *DN* \| **--deposits=**\ \ *DN* + How many deposits should be instantiated *per merchant*. + Defaults to 1. + +**-h** \| **--help** + Prints a compiled-in help text. + +**-L** *LOGLEVEL* \| **--log-level=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-m** *DM* \| **--merchants=**\ \ *DM* + How many different merchants should we create. Defaults to 1. + +**-r** *RATE* \| **--refunds=**\ \ *RATE* + Probability of a deposit having a refund (as an integer between 0-100). + +**-v** \| **--version** + Print version information. + +See Also +======== + +taler-exchange-dbinit(1), taler-merchant-benchmark(1), +taler-exchange-aggregator(1), taler-unified-setup(1), taler.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-auditor-dbconfig.1.rst b/manpages/taler-auditor-dbconfig.1.rst new file mode 100644 index 00000000..b16fd76d --- /dev/null +++ b/manpages/taler-auditor-dbconfig.1.rst @@ -0,0 +1,61 @@ +taler-auditor-dbconfig(1) +######################### + +.. only:: html + + Name + ==== + + **taler-auditor-dbconfig** - configure Taler auditor database + + +Synopsis +======== + +**taler-auditor-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**taler-auditor-dbconfig** is a simple shell script that configures +a Postgresql database for use by the GNU Taler auditor. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``taler-auditor-dbinit`` manually. + +**-u** *USER* + Specifies the (main) auditor user that will access the database. + +See Also +======== + +taler-auditor-dbinit(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-auditor.1.rst b/manpages/taler-auditor.1.rst index 62cbf69e..9a5fc52b 100644 --- a/manpages/taler-auditor.1.rst +++ b/manpages/taler-auditor.1.rst @@ -15,6 +15,7 @@ Synopsis [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] [**-h** | **--help**] [**-i**_|_**--internal**] +[**-I**_|_**--ignore-not-found**] [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] [**-m** *MASTER_KEY* | **--exchange-key=**\ \ *MASTER_KEY*] @@ -46,6 +47,10 @@ matches the exchange’s database. Its options are as follows. Run additional checks that can only performed on the exchange-internal database and not the "safe" replicated database at the auditor. +**-I** \| **--ignore-not-found** + Do not fail if the bank says that the exchange bank account does not (yet) exist. + Keep trying. + **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``. diff --git a/manpages/taler-bank-benchmark.1.rst b/manpages/taler-bank-benchmark.1.rst index 52078fa9..be7aceb1 100644 --- a/manpages/taler-bank-benchmark.1.rst +++ b/manpages/taler-bank-benchmark.1.rst @@ -13,18 +13,16 @@ Synopsis **taler-bank-benchmark** [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-f** | **--fakebank**] [**-h** | **--help**] -[**-K** | **--linger**] [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] -[**-m** *MODE* | **--mode=**\ \ *MODE*] [**-p** *NPROCS* | **--worker-parallelism=**\ \ *NPROCS*] -[**-P** *NTHREADS* | **--service-parallelism=**\ \ *NTHREADS*] [**-r** *NRESERVES* | **--reserves=**\ \ *NRESERVES*] -[**-s** *HISTSIZE* | **--size=**\ \ *HISTSIZE*] +[**-u** *SECTION* | **--exchange-account-section=**\ \ *SECTION*] [**-V** | **--verbose**] [**-v** | **--version**] -[**-w** | **--wirewatch**] +[**-w**_*NPROC* | **--wirewatch=**\ \ *NPROC*] Description @@ -39,12 +37,12 @@ The options for **taler-bank-benchmark** are: Use the configuration and other resources for the merchant to operate from *FILENAME*. +**-f** \| **--fakebank** + Expect to be run against a fakebank (instead of against libeufin) + **-h** \| **--help** Print short help on options. -**-K** \| **--linger** - Linger around until key press. - **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``. @@ -56,17 +54,14 @@ The options for **taler-bank-benchmark** are: Run as ``bank``, ``client`` or ``both``. If unspecified, *MODE* defaults to ``both``. -**-P** *NTHREADS** \| **--service-parallelism=**\ \ *NTHREADS* - Run with *NTHREADS* service threads. - **-p** *NPROCS* \| **--worker-parallelism=**\ \ *NPROCS* Run with *NPROCS* client processes. **-r** *NRESERVES* \| **--reserves=**\ \ *NRESERVES* Create *NRESERVES* reserves per client. -**-s** *HISTSIZE* \| **--size=**\ \ *HISTSIZE* - Configure the fakebank to keep in memory at most *HISTSIZE* history elements. +**-u** *SECTION* \| **--exchange-account-section=**\ \ *SECTION* + Use *SECTION* as the name of the configuration section which specifies the exchange bank account. **-V** \| **--verbose** Display more output than usual. @@ -74,8 +69,9 @@ The options for **taler-bank-benchmark** are: **-v** \| **--version** Print version information. -**-w** \| **--wirewatch** - Run the ``taler-exchange-wirewatch`` tool. +**-w** *NPROC* \| **--wirewatch=**\ \ *NPROC* + Run *NPROC* processes of the ``taler-exchange-wirewatch`` tool. + See Also ======== diff --git a/manpages/taler-config.1.rst b/manpages/taler-config.1.rst index 14a8959b..abc10dd6 100644 --- a/manpages/taler-config.1.rst +++ b/manpages/taler-config.1.rst @@ -83,6 +83,7 @@ Description Note: Changing the configuration file with ``-V`` will remove comments and may reorder sections and remove ``@INLINE@`` directives. + Using **-V** is thus dangerous! Use with extreme caution! **-v** \| **--version** Print GNU Taler version number. diff --git a/manpages/taler-exchange-benchmark.1.rst b/manpages/taler-exchange-benchmark.1.rst index bcbcb3c1..694a4b2d 100644 --- a/manpages/taler-exchange-benchmark.1.rst +++ b/manpages/taler-exchange-benchmark.1.rst @@ -18,25 +18,21 @@ Synopsis [**-F** | **--reserves-first**] [**-f** | **--fakebank**] [**-h** | **--help**] -[**-K** | **--linger**] [**-L** *LOGLEVEL* | **--log-level=**\ \ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] -[**-m** *MODE* | **--mode=**\ \ *MODE*] [**-n** *HOWMANY_COINS* | **--coins-number=**\ \ *HOWMANY_COINS*] [**-p** *NPROCS* | **--parallelism=**\ \ *NPROCS*] [**-R** *RATE* | **--refresh-rate=**\ \ *RATE*] [**-r** *N* | **--reserves=**\ \ *N*] +[**-u** *SECTION* | **--exchange-account-section=**\ \ *SECTION*] [**-v** | **--version**] Description =========== **taler-exchange-benchmark** 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. **-c** *CONFIG_FILENAME* \| **--config=**\ \ *CONFIG_FILENAME* (Mandatory) Use CONFIG_FILENAME. @@ -45,18 +41,11 @@ that table are always erased during a single benchmark run. Create all reserves first, before starting normal operations. **-f** \| **--fakebank** - 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. **-h** \| **--help** Prints a compiled-in help text. -**-K** \| **--linger** - Linger around until keypress after the benchmark is done. - **-L** *LOGLEVEL* \| **--log-level=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``. @@ -64,9 +53,6 @@ that table are always erased during a single benchmark run. **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* Send logging output to *FILENAME*. -**-m** *MODE* \| **--mode=**\ \ *MODE* - Mode of operation. Accepted values are: ``exchange``, ``clients``, ``both``. - **-n** *HOWMANY_COINS* \| **--coins-number=**\ \ *HOWMANY_COINS* Defaults to 1. Specifies how many coins this benchmark should withdraw and spend. After being spent, each coin will be refreshed @@ -81,6 +67,10 @@ that table are always erased during a single benchmark run. **-r** *N* \| **--reserves=**\ \ *N* Create *N* reserves per client. +**-u** *SECTION* \| **--exchange-account-section=**\ \ *SECTION* + Which configuration section should be used for the bank account + of the exchange. + **-v** \| **--version** Print version information. @@ -88,7 +78,7 @@ See Also ======== 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) Bugs ==== diff --git a/manpages/taler-exchange-dbconfig.1.rst b/manpages/taler-exchange-dbconfig.1.rst new file mode 100644 index 00000000..38cb1cba --- /dev/null +++ b/manpages/taler-exchange-dbconfig.1.rst @@ -0,0 +1,61 @@ +taler-exchange-dbconfig(1) +########################## + +.. only:: html + + Name + ==== + + **taler-exchange-dbconfig** - configure Taler exchange database + + +Synopsis +======== + +**taler-exchange-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**taler-exchange-dbconfig** is a simple shell script that configures +a Postgresql database for use by the GNU Taler exchange. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``taler-exchange-dbinit`` manually. + +**-u** *USER* + Specifies the (main) exchange user that will access the database. + +See Also +======== + +taler-exchange-dbinit(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst index 0ee83543..cbbc494c 100644 --- a/manpages/taler-exchange-dbinit.1.rst +++ b/manpages/taler-exchange-dbinit.1.rst @@ -13,6 +13,7 @@ Synopsis ======== **taler-exchange-dbinit** +[**-a** | **--inject-auditor**] [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] [**-g** | **--gc**] [**-h** | **--help**] @@ -31,6 +32,9 @@ Taler exchange to operate. Its options are as follows: +**-a** \| **--inject-auditor** + Installs triggers to notify real-time auditors of relevant changes to the database state. + **-c** *FILENAME* \| **--config=**\ \ *FILENAME* Use the configuration and other resources for the exchange to operate from *FILENAME*. diff --git a/manpages/taler-exchange-drain.1.rst b/manpages/taler-exchange-drain.1.rst new file mode 100644 index 00000000..ade7c00e --- /dev/null +++ b/manpages/taler-exchange-drain.1.rst @@ -0,0 +1,56 @@ +taler-exchange-drain(1) +######################### + +.. only:: html + + Name + ==== + + **taler-exchange-drain** - drain profits from exchange escrow account + +Synopsis +======== + +**taler-exchange-drain** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-v** | **--version**] + +Description +=========== + +**taler-exchange-drain** 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. + +To use it, you must first create an upload a 'drain' command using **taler-exchange-offline**. Afterwards this command should be run to actually queue the drain. The actual drain will then be executed by **taler-exchange-transfer**. + + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the exchange to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-v** \| **--version** + Print version information. + +See Also +======== + +taler-exchange-transfer(1), taler-exchange-offline(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-expire.1.rst b/manpages/taler-exchange-expire.1.rst new file mode 100644 index 00000000..24540ec4 --- /dev/null +++ b/manpages/taler-exchange-expire.1.rst @@ -0,0 +1,66 @@ +taler-exchange-expire(1) +######################### + +.. only:: html + + Name + ==== + + **taler-exchange-expire** - refund expired purses + +Synopsis +======== + +**taler-exchange-expire** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-exchange-expire** 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. + + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the exchange to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode and exit when idle. + +**-v** \| **--version** + Print version information. + +See Also +======== + +taler-exchange-router(1), taler-exchange-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-kyc-aml-pep-trigger.1.rst b/manpages/taler-exchange-kyc-aml-pep-trigger.1.rst new file mode 100644 index 00000000..566fdcab --- /dev/null +++ b/manpages/taler-exchange-kyc-aml-pep-trigger.1.rst @@ -0,0 +1,35 @@ +taler-exchange-kyc-aml-pep-trigger(1) +##################################### + +.. only:: html + + Name + ==== + + **taler-exchange-kyc-aml-pep-trigger** - helper script to trigger AML if KYC attributes indicate a politically exposed person + +Synopsis +======== + +**taler-exchange-kyc-aml-pep-trigger** + + +Description +=========== + +**taler-exchange-kyc-aml-pep-trigger** 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. + +The script is mostly an example (or starting point) for +writing programs for the KYC_AML_TRIGGER option of the +exchange. + +See Also +======== + +taler.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-kyc-tester.1.rst b/manpages/taler-exchange-kyc-tester.1.rst new file mode 100644 index 00000000..6bfad3b2 --- /dev/null +++ b/manpages/taler-exchange-kyc-tester.1.rst @@ -0,0 +1,93 @@ +taler-exchange-kyc-tester(1) +############################ + +.. only:: html + + Name + ==== + + **taler-exchange-kyc-tester** - tool to test interaction with KYC provider + +Synopsis +======== + +**taler-exchange-kyc-tester** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-i** *SECTION_NAME* | **--initiate=**\ \ *SECTION_NAME*] +[**-u** *ID* | **--user=**\ \ *ID*] +[**-U** *ID* | **--legitimization=**\ \ *ID*] +[**-P** | **--print-payto-hash**] +[**-p** *HASH* | **--payto-hash=**\ \ *HASH*] +[**-r** *NUMBER* | **--rowid=**\ \ *NUMBER*] +[**-v** | **--version**] +[**-w** | **--run-webservice**] + + +Description +=========== + +**taler-exchange-kyc-tester** 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 *not* required at all during production. + +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. + +Begin with a first invocation of taler-exchange-kyc-tester using the options **-i** for an individual or business and use **-R** to specify a list of checks required from the process. The output will be an URL to visit with the browser, as well as **-p**, **-u**, **-U** options to use in future invocations of the tool. + +Next, run taler-exchange-kyc-tester again, but this time using **-w** (to run the Webserver) and using the **-u** and **-U** options output by the previous call, as well as the **-p** 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. + + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the exchange to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-i** *USERTYPE* \| **--initiate=**\ \ *USERTYPE* + Specifies the type of user for which we are starting a fresh KYC process. USERTYPE must be either "individual" or "business". + +**-u** *ID* \| **--user=**\ \ *ID* + Run the process with ID for the user identifier at the KYC provider. Not useful in conjunction with **-i** and **-R** as that option will override whatever value is provided here. + +**-U** *ID* \| **--legitimization=**\ \ *ID* + Run the process with ID for the legitimization process identifier at the KYC provider. Not useful in conjunction with **-R** / **-i** as that option will override whatever value is provided here. + +**-p** *HASH* \| **--payto-hash=**\ \ *HASH* + 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. + +**-P** \| **--print-payto-hash** + 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 **-p**. + +**-r** *NUMBER* \| **--rowid=**\ \ *NUMBER* + Run the process with NUMBER as the database row for the legitimization operation. Rarely useful, except maybe for debugging. Defaults to 42. + +**-R** *CHECKS* \| **--requirements=**\ \ *CHECKS* + 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 *PROVIDED_CHECKS* 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 **-P** option to also obtain the Payto-Hash for use with **p** later. + + +**-v** \| **--version** + Print version information. + +**-w** \| **--run-webservice** + Run a simulated Taler exchange HTTP service on the configured port with the ``/kyc-proof/`` and ``/kyc-webhook/`` endpoints. + + +See Also +======== + +taler-exchange-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst index 265324e4..bd8cd793 100644 --- a/manpages/taler-exchange-offline.1.rst +++ b/manpages/taler-exchange-offline.1.rst @@ -142,6 +142,47 @@ It outputs the signatures over *all* denomination and signing keys present in the input, in a format suitable for the ``upload`` subcommand. +extensions +---------- + +This subcommand is responsible for the management of available extensions in +the exchange. + +It consumes the output of the ``download`` subcommand, either from ``stdin`` or +directly. + +It provides the sub-subcommand ``extensions show`` to show the configuration +for extensions and the ``extensions sign`` command to sign the current +configuration of extensions, in a format suitable for the ``upload`` +subcommand. + +Note that an extension on the exchange will only become activated at runtime +*after* the extension's configurations has been signed by the offline tool with +the signing key and the signed configuration been uploaded to the exchange. + +drain +----- + +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. + +Arguments to the ``drain`` 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. + +Note that to actually wire the funds, the exchange administrator must run +**taler-exchange-drain** manually and confirm the operation after the +``upload`` was completed. + + revoke-denomination ------------------- @@ -217,31 +258,73 @@ in a format suitable for the ``upload`` subcommand. enable-account -------------- -This subcommand -informs an exchange that it should advertise a bank account as belonging to -the exchange on its ``/wire`` endpoint. Note that this does *not* ensure that -the exchange will use this bank account for incoming or outgoing wire -transfers! For this, the **taler-exchange-transfer** and +This subcommand informs an exchange that it should advertise a bank account as +belonging to the exchange on its ``/keys`` endpoint. Note that this does +*not* ensure that the exchange will use this bank account for incoming or +outgoing wire transfers! For this, the **taler-exchange-transfer** and **taler-exchange-wirewatch** 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. The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given as the first argument to the subcommand. +Afterwards, optional arguments can be given: + + * ``conversion-url`` $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. + + * ``display-hint`` $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. + + * ``credit-restriction`` $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. + + * ``debit-restriction`` $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. + +The following types of credit- and debit-restrictions are supported: + + * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used + for the given operation. ``deny`` takes no further arguments. + + * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's + bank account ``payto``-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 + `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ + 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. + The subcommand takes no inputs from ``stdin`` or other subcommands. It outputs the signature affirming the addition of the wire account, in a format suitable for the ``upload`` subcommand. - disable-account --------------- This subcommand informs an exchange that it should stop advertising a bank account as -belonging to the exchange on its ``/wire`` endpoint. +belonging to the exchange on its ``/keys`` endpoint. The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be given as the first argument to the subcommand. @@ -255,13 +338,13 @@ format suitable for the ``upload`` subcommand. wire-fee -------- -This subcommand informs an exchange about the desired wire fee structure (that is, wire, closing and wad fees) +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. The subcommand takes the year, wire-method (see RFC 8905, examples include -``x-taler-bank`` or ``iban``), wire fee, closing fee and wad fee as arguments. +``x-taler-bank`` or ``iban``), wire fee, and closing fee as arguments. Instead of a year, the string ``now`` 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 @@ -281,8 +364,8 @@ 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. -The subcommand takes the year, history fee, kyc fee, account fee, purse fee, -purse timeout, kyc timeout, history expiration and the (free) purse (per) +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 ``now`` 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 ``CURRENCY:NUMBER.FRACTION``. @@ -324,6 +407,45 @@ The arguments provided must include: (9) History fee charged when inquiring about non-recent account history. +aml-enable +---------- + +Enable AML officer's account, granting them access to AML data and, +if 'rw' is given, the power to make AML decisions. + +The arguments provided must include: + + (1) AML staff member public key (in base32 encoding) + (2) AML staff member legal name + (3) 'ro' or 'rw' to set access to read-only or read-write + + +aml-disable +----------- + +Disable AML officer's account. Also updates the legal name. + +The arguments provided must include: + + (1) AML staff member public key (in base32 encoding) + (2) AML staff member legal name + + +add-partner +----------- + +Add partner exchange for wad transfers. Enables P2P payments +between users of these exchanges. + +The arguments provided must include: + + (1) Master public key of the partner exchange. + (2) Base URL of the partner exchange API. + (3) Wad fee to charge. + (4) Wad transfer frequency. + (5) Year for which the above options are to be configured, 'now' for the current year. + + upload ------ @@ -376,25 +498,58 @@ Upload signatures about future public keys (online) Download, sign and upload, all in one (online) ---------------------------------------------- -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! .. code-block:: console - $ taler-exchange-offline download sign upload + $ taler-exchange-offline \ + download \ + sign \ + upload Here is a variant that shows the output of ``download``, but does not consume it, so that ``sign`` can see it as input, as in the variant without ``show``. .. code-block:: console - $ taler-exchange-offline download show - sign upload + $ taler-exchange-offline \ + download \ + show - \ + sign \ + upload + Create signature to enable bank account (offline) ------------------------------------------------- +The following command sets up an unrestricted simple exchange bank account +without conversion: + .. code-block:: console - $ taler-exchange-offline enable-account payto://iban/DE24242 > account.json + $ taler-exchange-offline \ + enable-account payto://iban/DE24242?receiver-name=operator > account.json + +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: + +.. code-block:: shell-session + + $ taler-exchange-offline \ + enable-account payto://x-taler-bank/example.com/?receiver-name=name \ + conversion-url http://conversion.exchange.com/ \ + debit-restriction \ + deny \ + credit-restriction \ + regex \ + 'payto://iban/.*/CH.*?receiver-name=.*' \ + 'Swiss only' \ + '{ "de" : "nur Schweiz", \ + "fr" : "Suisse uniquement" }' + Upload bank account signature (online) -------------------------------------- @@ -407,9 +562,19 @@ Upload bank account signature (online) Combine signing keys and enabling bank account (offline) -------------------------------------------------------- +You can chain multiple commands into one invocation: + .. code-block:: console - $ taler-exchange-offline sign enable-account payto://iban/DE24242 < keys.json > combo.json + $ taler-exchange-offline \ + sign \ + enable-account \ + payto://iban/DE24242 < keys.json > combo.json + +Note that ``sign`` must be first as it consumes the ``keys.json`` +input. The resulting output combines the outputs of the ``sign`` +and ``enable-account`` subcommands. + Upload various signatures (online) ---------------------------------- @@ -421,11 +586,20 @@ Upload various signatures (online) Create multiple revocation messages in one pass (offline) --------------------------------------------------------- +You can freely combine almost all commands, including those for +key revocation: + .. code-block:: console - $ 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 \ + 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 The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload`` subcommand to the exchange to actually revoke the keys. diff --git a/manpages/taler-exchange-router.1.rst b/manpages/taler-exchange-router.1.rst new file mode 100644 index 00000000..e24d2d45 --- /dev/null +++ b/manpages/taler-exchange-router.1.rst @@ -0,0 +1,67 @@ +taler-exchange-router(1) +######################### + +.. only:: html + + Name + ==== + + **taler-exchange-router** - route purse payments to partner exchanges + +Synopsis +======== + +**taler-exchange-router** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-exchange-router** 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. + + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the exchange to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode and exit when idle. + +**-v** \| **--version** + Print version information. + +See Also +======== + +taler-exchange-expire(1), taler-exchange-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-exchange-wire-gateway-client.1.rst b/manpages/taler-exchange-wire-gateway-client.1.rst index 0533c35b..878ce39b 100644 --- a/manpages/taler-exchange-wire-gateway-client.1.rst +++ b/manpages/taler-exchange-wire-gateway-client.1.rst @@ -109,7 +109,7 @@ Options See Also ======== -taler-bank-manage(1), taler.conf(5), https://docs.taler.net/core/api-wire.html#wire-transfer-test-apis +taler.conf(5), https://docs.taler.net/core/api-wire.html#wire-transfer-test-apis Bugs ==== diff --git a/manpages/taler-exchange-wirewatch.1.rst b/manpages/taler-exchange-wirewatch.1.rst index 08bb6014..dbd0f2bc 100644 --- a/manpages/taler-exchange-wirewatch.1.rst +++ b/manpages/taler-exchange-wirewatch.1.rst @@ -14,6 +14,7 @@ Synopsis **taler-exchange-wirewatch** [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] [**-h** | **--help**] +[**-I**_|_**--ignore-not-found**] [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] [**-r** | **--reset**] @@ -33,9 +34,16 @@ Its options are as follows: Use the configuration and other resources for the exchange to operate from *FILENAME*. +**-f** *DELAY*\| **--longpoll-timeout=**\ \ *DELAY* + 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. + **-h** \| **--help** Print short help on options. +**-I** \| **--ignore-not-found** + Do not fail if the bank says that the exchange bank account does not (yet) exist. + Keep trying. + **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``. diff --git a/manpages/taler-fakebank-run.1.rst b/manpages/taler-fakebank-run.1.rst index 590b4b6f..1a23cf24 100644 --- a/manpages/taler-fakebank-run.1.rst +++ b/manpages/taler-fakebank-run.1.rst @@ -17,6 +17,7 @@ Synopsis [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] [**-n** *N* | **--num-threads=**\ \ *N*] +[**-s** *AMOUNT* | **--signup-bonus=**\ \ *AMOUNT*] [**-v** | **--version**] Description @@ -49,6 +50,9 @@ Its options are as follows: **-n** *N* \| **--num-threads=**\ \ *N* Use *N* threads in the thread pool. +**-s** *AMOUNT* \| **--signup-bonus=**\ \ *AMOUNT* + Credit newly registered accounts with a balance of *AMOUNT*. Unlike other banks, this initial balance will be created out of thin air and not via a wire transfer from some bank-internal account. + **-v** \| **--version** Print version information. diff --git a/manpages/taler-helper-auditor-purses.1.rst b/manpages/taler-helper-auditor-purses.1.rst new file mode 100644 index 00000000..09d23676 --- /dev/null +++ b/manpages/taler-helper-auditor-purses.1.rst @@ -0,0 +1,75 @@ +taler-helper-auditor-purses(1) +############################## + +.. only:: html + + Name + ==== + + **taler-helper-auditor-purses** - Audit Taler exchange purse handling + + +Synopsis +======== + +**taler-helper-auditor-purses** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**i** | **--internal**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-m** *KEY* | **--exchange-key=**\ \ *KEY*] +[**-T** *USEC* | **--timetravel=**\ \ *USEC*] +[**-v** | **--version**] + + +Description +=========== + +**taler-helper-auditor-purses** is a command-line tool to +audit Taler exchange purse handling. + +FIXME: More detail. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the auditor to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-i** \| **--internal** + Perform checks only applicable for exchange-internal audits. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-m** *KEY* \| **--exchange-key=**\ \ *KEY* + Use *KEY* (Crockford base32 encoded) as the public key of the exchange. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-v** \| **--version** + Print version information. + + +See Also +======== + +taler-auditor(1), taler.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-mdb.1.rst b/manpages/taler-mdb.1.rst new file mode 100644 index 00000000..5e6f86d2 --- /dev/null +++ b/manpages/taler-mdb.1.rst @@ -0,0 +1,73 @@ +taler-mdb(1) +############ + +.. only:: html + + Name + ==== + + **taler-mdb** - Taler multi-drop bus vending machine integration + + +Synopsis +======== + +**taler-mdb** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-d** | **--disable-mdb**] +[**-h** | **--help**] +[**-i** | **--backlight-invert**] +[**-L** _*LOGLEVEL* | **--log=**\ \ *LOGLEVEL*] +[**-l** _*FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-s** | **--enable-soldout**] +[**-t** | **--disable-tty**] +[**-v** | **--version**] + + +Description +=========== + +**taler-mdb** is a command-line tool to operate a vending machine using GNU Taler for payments. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the Sync commands + to operate from *FILENAME*. + +**-d** \| **--disable-mdb** + Disable interaction with the MDB bus (for testing). + +**-h** \| **--help** + Print short help on options. + +**-i** \| **--backlight-invert** + Invert the bit for turning on/off the backlight. + +**-L** *LOGLEVEL* \| **--log=**\ \ *LOGLEVEL* + Configure logging to use *LOGLEVEL*. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Configure logging to write logs to *FILENAME*. + +**-s** \| **--enable-soldout** + When the machine fails to dispense a product, internally set the product to "sold out" and refuse future orders until restarted. + +**-t** \| **--disable-tty** + Disable interactive command-line use. + +**-v** \| **–version** + Print version information. + + +See Also +======== + +taler-merchant-httpd(1), taler.conf(5). + + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-benchmark.1.rst b/manpages/taler-merchant-benchmark.1.rst index 2f91634a..7016c9d4 100644 --- a/manpages/taler-merchant-benchmark.1.rst +++ b/manpages/taler-merchant-benchmark.1.rst @@ -29,20 +29,16 @@ Subcommands ordinary Generate normal payments: all the payments are performed (by the default instance) and aggregated by the exchange. Takes the following - options. + option: **-p** *PN* \| **--payments-number=**\ \ *PN* Perform PN many payments, defaults to 1. - **-t** *TN* \| **--tracks-number=**\ \ *TN* - Perform TN many tracking operations, defaults to 1. - - 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: **-t** *TC* \| **--two-coins=**\ \ *TC* @@ -67,8 +63,7 @@ Common Options Use the configuration and other resources for the merchant to operate from FILENAME. -**-e** *SECTION* \| **--exchange-account=**\ \ *SECTION* - Mandatory. +**-u** *SECTION* \| **--exchange-account-section=**\ \ *SECTION* Configuration *SECTION* specifying the exchange account to use. **-h** \| **--help** @@ -88,7 +83,7 @@ Common Options See Also ======== -taler-merchant-dbinit(1), taler-merchant-tip-enable(1), taler.conf(5) +taler-merchant-dbinit(1), taler.conf(5) Bugs diff --git a/manpages/taler-merchant-dbconfig.1.rst b/manpages/taler-merchant-dbconfig.1.rst new file mode 100644 index 00000000..f2055710 --- /dev/null +++ b/manpages/taler-merchant-dbconfig.1.rst @@ -0,0 +1,61 @@ +taler-merchant-dbconfig(1) +########################## + +.. only:: html + + Name + ==== + + **taler-merchant-dbconfig** - configure Taler merchant database + + +Synopsis +======== + +**taler-merchant-dbconfig** +[**-c** *FILENAME*] +[**-h**] +[**-n** *NAME*] +[**-r**] +[**-s**] +[**-u** *USER*] + +Description +=========== + +**taler-merchant-dbconfig** is a simple shell script that configures +a Postgresql database for use by the GNU Taler merchant. + +Its options are as follows: + +**-c** *FILENAME* + Write the database configuration to FILENAME. The tool + will append the required ``CONFIG`` option for the + Postgresql access to the respective file. + +**-h** + Print short help on options. + +**-n** *DBNAME* + Use DBNAME for the name of the created database. + +**-r** + Reset any existing database. Looses all existing data. DANGEROUS. + +**-s** + Skip database initialization. Useful if you want to run + ``taler-merchant-dbinit`` manually. + +**-u** *USER* + Specifies the (main) merchant user that will access the database. + +See Also +======== + +taler-merchant-dbinit(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-depositcheck.1.rst b/manpages/taler-merchant-depositcheck.1.rst new file mode 100644 index 00000000..e243f0d2 --- /dev/null +++ b/manpages/taler-merchant-depositcheck.1.rst @@ -0,0 +1,78 @@ +taler-merchant-depositcheck(1) +############################## + +.. only:: html + + Name + ==== + + **taler-merchant-depositcheck** - check if deposits are associated with wire transfers + + +Synopsis +======== + +**taler-merchant-depositcheck** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-e** *BASE_URL* | **--exchange=**\ \ *BASE_URL*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-merchant-depositcheck** 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. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-e** *BASE_URL* \| **--exchange=**\ \ *BASE_URL* + 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). + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-s** *SECTION* \| **--section=**\ \ *SECTION* + 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). + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode. Only runs until the current list of bank + transactions are all imported. + +**-v** \| **–version** + Print version information. + +See Also +======== + +taler-merchant-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-exchange.1.rst b/manpages/taler-merchant-exchange.1.rst new file mode 100644 index 00000000..de2b571f --- /dev/null +++ b/manpages/taler-merchant-exchange.1.rst @@ -0,0 +1,73 @@ +taler-merchant-exchange(1) +########################## + +.. only:: html + + Name + ==== + + **taler-merchant-exchange** - reconcile bank transfers with Taler exchange + + +Synopsis +======== + +**taler-merchant-exchange** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-merchant-exchange** 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. + +The tool is part of a set of processes that allow a merchant backend to +validate that the exchange paid the merchant correctly. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode. Only runs until the current list of bank + transactions have all been checked. + +**-v** \| **–version** + Print version information. + +See Also +======== + +taler-merchant-depositcheck(1), taler-merchant-wirewatch(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-httpd.1.rst b/manpages/taler-merchant-httpd.1.rst index 5ea47c12..3df4f4ac 100644 --- a/manpages/taler-merchant-httpd.1.rst +++ b/manpages/taler-merchant-httpd.1.rst @@ -13,6 +13,7 @@ Synopsis ======== **taler-merchant-httpd** +[**-a**_|_**--auth**] [**-C** | **--connection-close**] [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] [**-h** | **--help**] @@ -33,9 +34,9 @@ Options ======= **-a** *TOKEN* \| **--auth=**\ \ *TOKEN* - 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 @@ -92,7 +93,7 @@ TALER_MERCHANT_TOKEN See Also ======== -taler-merchant-dbinit(1), taler-merchant-tip-enable(1), taler.conf(5) +taler-merchant-dbinit(1), taler-merchant-setup-reserve(1), taler.conf(5) Bugs diff --git a/manpages/taler-merchant-passwd.1.rst b/manpages/taler-merchant-passwd.1.rst new file mode 100644 index 00000000..6cb102b2 --- /dev/null +++ b/manpages/taler-merchant-passwd.1.rst @@ -0,0 +1,64 @@ +taler-merchant-passwd(1) +######################## + +.. only:: html + + Name + ==== + + **taler-merchant-passwd** - reset password of existing instance + + +Synopsis +======== + +**taler-merchant-passwd** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-i**_*NAME* | **--instance**\ \ *NAME*] +[**-v** | **--version**] +[PASSWORD] + +Description +=========== + +**taler-merchant-passwd** 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. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-i** *NAME* \| **--instance**\ \ *NAME* + Specifies the name of the instance for which the password should be + updated. If not given, the "default" instance is modified. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-v** \| **–version** + Print version information. + +See Also +======== + +taler-merchant-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-setup-reserve.1.rst b/manpages/taler-merchant-setup-reserve.1.rst deleted file mode 100644 index 25d5b102..00000000 --- a/manpages/taler-merchant-setup-reserve.1.rst +++ /dev/null @@ -1,119 +0,0 @@ -taler-merchant-setup-reserve(1) -############################### - - -.. only:: html - - Name - ==== - - **taler-merchant-setup-reserve** - setup reserve for tipping - - -Synopsis -======== - -**taler-merchant-setup-reserve** -[**-A** *USERNAME:PASSWORD* | **--auth=**\ \ *USERNAME:PASSWORD*] -[**-a** *VALUE* | **--amount=**\ \ *VALUE*] -[**-C** *CERTFILE* | **--cert=**\ \ *CERTFILE*] -[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] -[**-e** *URL* | **--exchange-url=**\ \ *URL*] -[**-h** | **--help**] -[**-k** *KEYFILE* | **--key=**\ \ *KEYFILE*] -[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] -[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] -[**-m** *URL* | **--merchant-url=**\ \ *URL*] -[**-p** *KEYFILEPASSPHRASE* | **--pass=**\ \ *KEYFILEPASSPHRASE*] -[**-t** *CERTTYPE* | **--type=**\ \ *CERTTYPE*] -[**-w** *METHOD* | **--wire-method=**\ \ *METHOD*] -[**-v** | **--version**] - - -Description -=========== - -**taler-merchant-setup-reserve** 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. - - -Options -======= - -**-A** *USERNAME:PASSWORD* \| **--auth=**\ \ *USERNAME:PASSWORD* - Use ``USERNAME`` and ``PASSWORD`` 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 ``-C``, ``-k`` and ``-p`` options. - The ``PASSWORD`` given to this option is given to the server! - -**-a** *VALUE* \| **--amount=**\ \ *VALUE* - Mandatory. - Amount to be transferred to the reserve. - -**-C** *CERTFILE* \| **--cert=**\ \ *CERTFILE* - The specified ``CERTFILE`` contains a TLS client certificate to be used to - authenticate the client. See also ``-t``. - -**-c** *FILENAME* \| **--config=**\ \ *FILENAME* - Use the configuration and other resources for the merchant to - operate from ``FILENAME``. - -**-e** *URL* \| **--exchange-url=**\ \ *URL* - Mandatory. - Use ``URL`` 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. - -**-h** \| **--help** - Print short help on options. - -**-k** *KEYFILE* \| **--key=**\ \ *KEYFILE* - The specified ``KEYFILE`` contains a TLS client private key to be used to - authenticate the client. See also ``-p`` and ``-C``. - -**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* - Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, - ``WARNING``, ``ERROR``. - -**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* - Send logging output to *FILENAME*. - -**-m** *URL* \| **--merchant-url=**\ \ *URL* - Mandatory. - Use ``URL`` as the merchant base URL. - Should include the path to the instance if the reserve is to be - created for a non-default instance. - -**-p** *KEYFILEPASSPHRASE* \| **--pass=**\ \ *KEYFILEPASSPHRASE* - The specified ``KEYFILEPASSPHRASE`` is to be used to decrypt the KEYFILE. - See also ``-k``. Not to be confused with ``-A``. - The ``KEYFILEPASSPHRASE`` given here is only used locally to decrypt the KEYFILE. - -**-t** *CERTTYPE* \| **--type=**\ \ *CERTTYPE* - The specified CERTFILE contains a TLS client certificate of ``CERTTYPE``. - Default is ``PEM``. See also ``-C``. - -**-w** *METHOD* \| **--wire-method=**\ \ *METHOD* - 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 ``iban`` or ``x-taler-bank``. - -**-v** \| **--version** - Print version information. - - -See Also -======== - -taler-merchant-dbinit(1), taler.conf(5) - - -Bugs -==== - -Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-webhook.1.rst b/manpages/taler-merchant-webhook.1.rst new file mode 100644 index 00000000..c3a71509 --- /dev/null +++ b/manpages/taler-merchant-webhook.1.rst @@ -0,0 +1,68 @@ +taler-merchant-webhook(1) +######################### + +.. only:: html + + Name + ==== + + **taler-merchant-webhook** - run webhooks of Taler merchant backend + + +Synopsis +======== + +**taler-merchant-webhook** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-merchant-webhook** 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. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode. Only runs until there are no more webhooks + to be executed. + +**-v** \| **–version** + Print version information. + +See Also +======== + +taler-merchant-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-merchant-wirewatch.1.rst b/manpages/taler-merchant-wirewatch.1.rst new file mode 100644 index 00000000..e2f9d1df --- /dev/null +++ b/manpages/taler-merchant-wirewatch.1.rst @@ -0,0 +1,78 @@ +taler-merchant-wirewatch(1) +########################### + +.. only:: html + + Name + ==== + + **taler-merchant-wirewatch** - import bank transfers into Taler merchant backend + + +Synopsis +======== + +**taler-merchant-wirewatch** +[**-c** *FILENAME* | **--config=**\ \ *FILENAME*] +[**-h** | **--help**] +[**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] +[**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] +[**-p** | **--persist**] +[**-T** *USEC* | **--timetravel**\ \ *USEC*] +[**-t** | **--test**] +[**-v** | **--version**] + +Description +=========== + +**taler-merchant-wirewatch** 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. + +Its options are as follows: + +**-c** *FILENAME* \| **--config=**\ \ *FILENAME* + Use the configuration and other resources for the merchant to operate + from *FILENAME*. + +**-h** \| **--help** + Print short help on options. + +**-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* + Send logging output to *FILENAME*. + +**-p** \| **--persist** + Run in persist mode. Does not exit when the account configuration changes. Useful when not running under systemd. + +**-s** *SECTION* \| **--section=**\ \ *SECTION* + 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). + +**-T** *USEC* \| **--timetravel=**\ \ *USEC* + Modify the system time by *USEC* microseconds. + *USEC* may be prefixed with ``+`` or ``-`` (e.g. ``-T +300``). + This option is intended for debugging/testing only. + +**-t** \| **--test** + Run in test mode. Only runs until the current list of bank + transactions are all imported. + +**-v** \| **–version** + Print version information. + +See Also +======== + +taler-merchant-httpd(1), taler.conf(5). + +Bugs +==== + +Report bugs by using https://bugs.taler.net or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-terms-generator.1.rst b/manpages/taler-terms-generator.1.rst new file mode 100644 index 00000000..d6c22411 --- /dev/null +++ b/manpages/taler-terms-generator.1.rst @@ -0,0 +1,72 @@ +taler-terms-generator(1) +######################## + + +.. only:: html + + Name + ==== + + **taler-terms-generator** - generate legal terms for GNU Taler services + + +Synopsis +======== + +**taler-terms-generator** +[**-a** *AUTHOR*] +[**-C** *COPYRIGHT*] +[**-h**] +[**-i** *INPUT*] +[**-l** *LANGUAGE*] +[**-o** *OUTPUT*] +[**-p** *PAPER*] +[**-t** *TITLE*] + + +Description +=========== + +**taler-terms-generator** 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 ``/terms`` and ``/pp`` endpoints. + +**-a** *AUTHOR* + set the author information to the given AUTHOR in the meta-data of various generated outputs. + +**-C** *COPYRIGHT* + set the copyright information to the given COPYRIGHT in the meta-data of various generated outputs. + +**-h** \| **--help** + Prints a compiled-in help text. + +**-i** *INPUT* + Name of the input (.rst) file with the terms of service or privacy policy to convert. + +**-l** *LANGUAGE* + Add the given *LANGUAGE* to the list of translations for the current *INPUT*. *LANGUAGE* must be a two-letter language code (like "de" or "it"). This will generate or update the respective ".po" files to translate the *INPUT* terms to this *LANGUAGE*. + +**-L** *LOCALE_DIR* + 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. + +**-o** *OUTPUT* + 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. + +**-p** *PAPER* + Specifies the paper format for generated PDF documents. Can be "a4" or "letter". + +**-t** *TITLE* + Overrides the document title. By default, the title will be set to the contents of the first line of the *INPUT* ".rst" file. + + +See Also +======== + +taler-config(1), taler.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-unified-setup.1.rst b/manpages/taler-unified-setup.1.rst new file mode 100644 index 00000000..fe60d1e5 --- /dev/null +++ b/manpages/taler-unified-setup.1.rst @@ -0,0 +1,110 @@ +taler-unified-setup.sh(1) +######################### + + +.. only:: html + + Name + ==== + + **taler-unified-setup.sh** - conveniently launch GNU Taler services + + +Synopsis +======== + +**taler-unified-setup** +[**-a**] +[**-b**] +[**-c** *CONFIG_FILENAME*] +[**-d** *METHOD*] +[**-e**] +[**-f**] +[**-h**] +[**-k**] +[**-l** *FILENAME*] +[**-m**] +[**-n**] +[**-r** *MEX*] +[**-s**] +[**-t**] +[**-u** *SECTION*] +[**-v**] +[**-w**] + + +Description +=========== + +**taler-unified-setup** 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. + +**-a** + Start auditor + +**-b** + Start backup/sync service + +**-c** *CONFIG_FILENAME* + (Mandatory) Use CONFIG_FILENAME. + +**-d** *METHOD* + use the given wire method. Default is 'x-taler-bank'. + +**-e** + Start exchange + +**-f** + Start fakebank + +**-g** + Start aggregator + +**-h** \| **--help** + Prints a compiled-in help text. + +**-k** + Start challenger (KYC service) + +**-L** *LOGLEVEL* + Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, + ``WARNING``, ``ERROR``. + +**-m** + Start merchant + +**-n** + Start libeufin nexus + +**-r** *MEX* + Which exchange to use at the merchant + +**-s** + Start libeufin sandbox + +**-t** + Start taler-exchange-transfer + +**-u** *SECTION* + Specifies configuration section with the exchange account to use + +**-v** + Use valgrind + +**-w** + Start taler-exchange-wirewatch + + +See Also +======== + +taler-exchange-dbinit(1), taler-exchange-offline(1), taler-merchant-benchmark(1), +taler-exchange-httpd(1), taler.conf(5) + +Bugs +==== + +Report bugs by using https://bugs.taler.net/ or by sending electronic +mail to <taler@gnu.org>. diff --git a/manpages/taler-wallet-cli.1.rst b/manpages/taler-wallet-cli.1.rst index bac9ea9f..dad790f5 100644 --- a/manpages/taler-wallet-cli.1.rst +++ b/manpages/taler-wallet-cli.1.rst @@ -46,8 +46,6 @@ for testing. **withdraw-uri** URI -**tip-uri** URI - **refund-uri** URI **pay-uri** [**-y** | **--yes**] URI diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 76b1c6b8..3074f68b 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -1,4 +1,4 @@ -it putaler.conf(5) +taler.conf(5) ############# .. only:: html @@ -32,11 +32,19 @@ GLOBAL OPTIONS -------------- 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. + CURRENCY Name of the currency, e.g. “EUR” for Euro. +CURRENCY_ROUND_UNIT + Smallest amount in this currency that can be transferred using the + underlying RTGS. For example: "EUR:0.01" or "JPY:1". + + + 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: @@ -61,6 +69,62 @@ TALER_RUNTIME_DIR Where should Taler store system runtime data (like UNIX domain sockets). Usually “${TMP}/taler-system-runtime”. + +CURRENCY SPECIFICATIONS +----------------------- + +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: + +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. + +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. + +NAME + Long human-readable name for the currency. No restrictions, + but should match the official name in English. + +FRACTIONAL_INPUT_DIGITS + Number of fractional digits that users are allowed to enter + manually in the user interface. + +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). + +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. + +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). + + EXCHANGE OPTIONS ---------------- @@ -70,22 +134,60 @@ exchange tools. DB Plugin to use for the database, e.g. “postgres”. +SERVE + Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")? + +UNIXPATH + Path to listen on if we "SERVE" is set to "unix". + +UNIXPATH_MODE + Access permission mask to use for the "UNIXPATH". + PORT Port on which the HTTP server listens, e.g. 8080. +BIND_TO + Hostname to which the exchange HTTP server should be bound to, e.g. "localhost". + 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 **auditor** to determine the public key of the + exchange which it is auditing. -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). +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". + +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. + +STEFAN_ABS + Absolute amount to add as an offset in the STEFAN fee approximation + curve (see DD47). Defaults to CURRENCY:0 if not specified. + +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. + +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. 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. +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". + AGGREGATOR_IDLE_SLEEP_INTERVAL For how long should the taler-exchange-aggregator sleep when it is idle before trying to look for more work? Default is 60 seconds. @@ -148,52 +250,159 @@ PRIVACY_DIR PRIVACY_ETAG Works the same as ``TERMS_ETAG``, just for the privacy policy. -KYC_MODE - Set to "NONE" to disable KYC for this exchange (but check with your lawyer first). - Set to "OAUTH2" to use OAuth2 for KYC. -KYC_WITHDRAW_LIMIT - Maximum amount that can be withdrawn in - KYC_WITHDRAW_PERIOD without needing KYC. - Only used if KYC_MODE is not "NONE". +EXCHANGE KYC PROVIDER OPTIONS +----------------------------- + +The following options must be in the section "[kyc-provider-XXX]" sections. -KYC_WITHDRAW_PERIOD - The time period over which transactions - are considered for the KYC_WITHDRAW_LIMIT. - Only used if KYC_MODE is not "NONE". +COST + Relative cost of the KYC provider, non-negative number. -KYC_WALLET_BALANCE_LIMIT - Maximum amount that a wallet is allowed to hold without - having to undergo the KYC process of the issuing - exchange. Optional option, if not given there - is no limit. +LOGIC + API type of the KYC provider. + +USER_TYPE + Type of user this provider is for, either INDIVIDUAL or BUSINESS. + +PROVIDED_CHECKS + List of checks performed by this provider. Space-separated names of checks, must match check names in legitimization rules. EXCHANGE KYC OAUTH2 OPTIONS ---------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The following options must be in the section "[exchange-kyc-oauth2]". +The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2". -KYC_OAUTH2_AUTH_URL - URL of the OAuth2 endpoint to be used for KYC checks. Requires KYC_ENABLED to be "OAUTH2". Example: "http://localhost:8888/oauth/v2/login" (or "/token") +KYC_OAUTH2_VALIDITY + Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". -KYC_OAUTH2_LOGIN_URL - URL of the OAuth2 endpoint to be used for KYC checks. Requires KYC_ENABLED to be "OAUTH2". Example: "http://localhost:8888/oauth/v2/login" +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: "http://localhost:8888/oauth/v2/authorize". To use the plugin in combination with the Challenger service's ``/setup`` step, append "#setup", thus "https://challenger.example.com/authorize#setup". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the ``/setup/$CLIENT_ID`` handler. -KYC_INFO_URL - URL of the endpoint where the OAuth 2.0 token can be used to download the user's details. Requires KYC_ENABLED to be "OAUTH2". Example: "http://localhost:8888/api/user/me" +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: "http://localhost:8888/oauth/v2/token" (or just "/token") + +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: "http://localhost:8888/api/user/me" or "http://localhost:8888/oauth/v2/info" KYC_OAUTH2_CLIENT_ID - Client ID of the exchange when it talks to the KYC OAuth2 endpoint. Requires KYC_ENABLED to be "OAUTH2". + Client ID of the exchange when it talks to the KYC OAuth2 endpoint. KYC_OAUTH2_CLIENT_SECRET - Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. Requires KYC_ENABLED to be "OAUTH2". + Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. KYC_OAUTH2_POST_URL + URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. Example: "http://example.com/thank-you" + +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. + +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. + + +EXCHANGE KYC KYCAID OPTIONS +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid". + + +KYC_KYCAID_VALIDITY + Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". + +KYC_KYCAID_AUTH_TOKEN + Authentication token to access the KYC service. + +KYC_KYCAID_FORM_ID + ID that specifies the form to use for the KYC process. + +KYC_KYCAID_POST_URL URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. +EXCHANGE KYC PERSONA OPTIONS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona". + + +KYC_PERSONA_VALIDITY + Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". + +KYC_PERSONA_AUTH_TOKEN + Authentication token to access the KYC service. + +KYC_PERSONA_SALT + Salt value to use for request idempotency. Optional, generated at random per process if not given. + +KYC_PERSONA_SUBDOMAIN + Subdomain to use under Persona. + +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". + +KYC_PERSONA_POST_URL + URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. + +KYC_PERSONA_TEMPLATE_ID + ID of the Persona template to use. + +EXCHANGE KYC PERSONA GLOBAL OPTIONS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following option must be in the section "[kyclogic-persona]". + + +WEBHOOK_AUTH_TOKEN + Authentication token Persona must supply to our webhook. This is an optional setting. + + +EXCHANGE EXTENSIONS OPTIONS +--------------------------- + +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 ``$LIBDIR``, starting with prefix ``libtaler_extension_``. Each +extension can be enabled by adding a dedicated section +"[exchange-extension-<extensionname>]" and the following option: + +ENABLED + If set to ``YES`` the extension ``<extensionsname>`` is enabled. Extension-specific + options might be set in the same section. + + +EXCHANGE EXTENSION FOR AGE RESTRICTION +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The extension for age restriction support can be enabled by adding a section +"[exchange-extension-age_restriction]" with the following options: + +ENABLE + Must be set to ``YES`` in order to activate the extension. + +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: + + 1. Group 0: ages 0 through 9 (including) + 2. Group 1: ages 10 through 17 (including) + 3. Group 2: ages 18 and above + + If not provided, the default value is "8:10:12:14:16:18:21". + +**Note**: Age restriction is bound to specific denominations and must be +enabled for each selected denomination in the corresponding section by adding +the option ``AGE_RESTRICTED = YES``, see `EXCHANGE COIN OPTIONS`_. However, the +age groups are defined globally for all denominations. + + EXCHANGE OFFLINE SIGNING OPTIONS -------------------------------- @@ -201,7 +410,8 @@ EXCHANGE OFFLINE SIGNING OPTIONS The following options must be in the section "[exchange-offline]". 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. SECM_TOFU_FILE @@ -323,6 +533,10 @@ AGGREGATOR_SHIFT Delay between a deposit being eligible for aggregation and the aggregator actually triggering. +DEFAULT_PURSE_LIMIT + Number of concurrent purses that a reserve may have active + if it is paid to be opened for a year. + EXCHANGE POSTGRES BACKEND DATABASE OPTIONS ------------------------------------------ @@ -433,6 +647,11 @@ CIPHER RSA_KEYSIZE What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA". +AGE_RESTRICTED + Setting this option to ``YES`` marks the denomination as age restricted + (default is ``NO``). For this option to be accepted the extension for age + restriction MUST be enabled (see `EXCHANGE EXTENSION FOR AGE RESTRICTION`_). + MERCHANT OPTIONS ---------------- @@ -443,9 +662,24 @@ merchant backend. DB Plugin to use for the database, e.g._“postgres”. +SERVE + Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")? + +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. + +UNIXPATH + Path to listen on if we "SERVE" is set to "unix". + +UNIXPATH_MODE + Access permission mask to use for the "UNIXPATH". + PORT Port on which the HTTP server listens, e.g. 8080. +BIND_TO + Hostname to which the merchant HTTP server should be bound to, e.g. "localhost". + LEGAL_PRESERVATION How long do we keep data in the database for tax audits after the transaction has completed? Default is 10 years. @@ -494,25 +728,8 @@ CURRENCY The entire section is ignored if the currency does not match the currency we use, which must be given in the ``[taler]`` section. -KNOWN AUDITORS (for merchants) ------------------------------- - -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 -``$NAME`` is a merchant-given name for the auditor. The following options -must be given in each “[merchant-auditor-$NAME]” section. - -AUDITOR_BASE_URL - Base URL of the auditor, e.g. “https://auditor.demo.taler.net/” - -AUDITOR_KEY - Crockford Base32 encoded auditor public key. - -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 ``[taler]`` section. +DISABLED + Set to YES to disable this exchange. Optional option, defaults to NO. AUDITOR OPTIONS @@ -534,6 +751,23 @@ PUBLIC_KEY BASE_URL Base URL of the auditor, e.g. “https://auditor.demo.taler.net/” +SERVE + Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")? + +UNIXPATH + Path to listen on if we "SERVE" is set to "unix". + +UNIXPATH_MODE + Access permission mask to use for the "UNIXPATH". + +PORT + Port on which the HTTP server listens, e.g. 8080. + +BIND_TO + Hostname to which the merchant HTTP server should be bound to, e.g. "localhost". + + + AUDITOR POSTGRES BACKEND DATABASE OPTIONS ----------------------------------------- @@ -557,6 +791,51 @@ 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. +Taler-mdb Options +----------------- + +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. + +ADVERTISEMENT_COMMAND + Program to run while not vending, possibly useful to show advertisements on the screen (optional). +ESSID + ESSID to advertise to wallets for use as an open WiFi to make payments (optional). +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. +BACKEND_BASE_URL + Base URL (possibly including instance) for the Taler merchant backend used to process payments. +BACKEND_AUTHORIZATION + Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Mandatory. +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. +FRAMEBUFFER_DEVICE + Name of the framebuffer device to use. Defaults to "/dev/fb1" if not given. +UART_DEVICE + Name of the UART device to use. Defaults to "/dev/ttyAMA0" if not given. +FAIL_COMMAND + Command to run to display a failure to the user. If not given, errors will not be properly shown. + +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: + +NUMBER + Number identifying the slot in the vending machine that corresponds to this product. +INSTANCE + Instance to use for the payment. Optional. If not given, the BACKEND_BASE_URL from "[taler-mdb]" will be used. +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. +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). +PRICE + Actual price of the product, as a Taler amount ("$CURRENCY:$VALUE.$FRACTION"). +KEY + Key used to select the product from the console during testing. Optional. +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. + SEE ALSO ======== |