taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

commit ff48b9daafd1a6fc27756d6db06a2915ea95c950
parent 763e3f5469c77e0b21401590143192e2963fb41e
Author: Antoine A <>
Date:   Fri,  6 Nov 2026 12:28:25 +0100

taler-rust: fix documentation

Diffstat:
Mmanpages/frags/common-serve-options.rst | 2+-
Mmanpages/taler-apns-relay.1.rst | 2+-
Mmanpages/taler-apns-relay.conf.5.rst | 3+++
Mmanpages/taler-cyclos.1.rst | 2+-
Mmanpages/taler-magnet-bank.conf.5.rst | 8+++++++-
Mmanpages/taler-wise.1.rst | 19+++++++++++++------
Mmanpages/taler-wise.conf.5.rst | 26+++++++++++++++++---------
Mtaler-apns-relay-manual.rst | 23+++++++++++------------
Mtaler-cyclos-manual.rst | 21++++++++++-----------
Mtaler-magnet-bank-manual.rst | 25++++++++++++-------------
Mtaler-wise-manual.rst | 37++++++++++++++++++++-----------------
11 files changed, 96 insertions(+), 72 deletions(-)

diff --git a/manpages/frags/common-serve-options.rst b/manpages/frags/common-serve-options.rst @@ -6,7 +6,7 @@ PORT 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. + Which IP address should we bind to? E.g. ``127.0.0.1`` or ``::1`` for loopback. Only used if ``SERVE`` is ``tcp``. UNIXPATH diff --git a/manpages/taler-apns-relay.1.rst b/manpages/taler-apns-relay.1.rst @@ -75,7 +75,7 @@ Its options are as follows: **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. **-r** \| **--reset** - Reset connection info and overwrite keys file + Delete all registered devices after the APNs configuration check succeeds. **-h** \| **--help** Print short help on options. diff --git a/manpages/taler-apns-relay.conf.5.rst b/manpages/taler-apns-relay.conf.5.rst @@ -28,6 +28,9 @@ WORKER OPTIONS The following options are from the “[apns-relay-worker]” section. +SERVER + APNs environment: ``production`` or ``sandbox`` + KEY_FILE Path to the Apple Push Notification private key diff --git a/manpages/taler-cyclos.1.rst b/manpages/taler-cyclos.1.rst @@ -77,7 +77,7 @@ Its options are as follows: **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. **-r** \| **--reset** - Reset connection info and overwrite keys file + Accepted for compatibility, has no effect. **-h** \| **--help** Print short help on options. diff --git a/manpages/taler-magnet-bank.conf.5.rst b/manpages/taler-magnet-bank.conf.5.rst @@ -58,6 +58,12 @@ KEYS_FILE ACCOUNT_TYPE Specify the account type and therefore the indexing behavior. This can either can be ``normal`` or ``exchange``. Exchange accounts bounce invalid incoming Taler transactions. +IGNORE_TRANSACTIONS_BEFORE + Ignore incoming transactions before this value date (``YYYY-MM-DD``). + +IGNORE_BOUNCES_BEFORE + Do not bounce malformed incoming transactions before this value date (``YYYY-MM-DD``). + HTTP SERVER OPTIONS ------------------- @@ -98,7 +104,7 @@ ENABLED DATABASE OPTIONS ---------------- -Setting the database belongs to the “[magnet-bankddb-postgres]” section and the following value. +Setting the database belongs to the “[magnet-bankdb-postgres]” section and the following value. .. include:: frags/common-db-options.rst diff --git a/manpages/taler-wise.1.rst b/manpages/taler-wise.1.rst @@ -40,7 +40,8 @@ The interaction model is as follows: - Check API access with commands ``setup``. -- After a successful setup, the subcommands ``worker`` can be run to both send payments and sync the bank account history. +- After a successful setup, the subcommand ``worker`` can be run to sync the balance histories. + The adapter is read-only: it cannot send payments or bounce malformed transfers. - Start the HTTP server with command ``serve``. Let this run in a shell, writing logs to stderr. @@ -66,7 +67,9 @@ Its options are as follows: setup ----- -This command establishes a working API connection. It verifies that the current configuration is valid and that the bank account has sufficient rights to function as an exchange. +This command checks API access and the configured profile and balances, then +initializes synchronization state from each balance's creation time. Existing +synchronization state is preserved unless ``--reset`` is supplied. It is mandatory to run this command before invoking the ``worker`` command. @@ -76,15 +79,17 @@ Its options are as follows: Specifies the configuration file. **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. -**-r** \| **--reset** - Reset connection info and overwrite keys file +**--reset** + Reset all synchronization cursors and schedules to rescan from balance creation. + Credentials and recorded transactions are preserved. **-h** \| **--help** Print short help on options. worker ------ -This subcommand initiate transaction throught the Wise API and sync the balances account history. +This subcommand synchronizes balance histories through the Wise API. It does not +initiate transfers. Its options are as follows: @@ -109,7 +114,9 @@ Its options are as follows: **-L** \| **--log** *LOGLEVEL* Configure logging to use LOGLEVEL. **--check** - Check whether an API is in use (if it's useful to start the HTTP server). Exit with 0 if at least one API is enabled, otherwise 1. + Validate the server configuration without starting the HTTP server. Exit with 0 + if it is valid, including when all optional APIs are disabled: the server also + provides the Wise webhook endpoint. **-h** \| **--help** Print short help on options. diff --git a/manpages/taler-wise.conf.5.rst b/manpages/taler-wise.conf.5.rst @@ -30,7 +30,13 @@ ADAPTER OPTIONS The following options are from the “[wise]” section. NAME - Legal entity that is associated with the Cyclos account. + Legal entity that is associated with the Wise account. + +PROFILE_ID + Adapter Wise profile ID + +API_ENV + API environment: ``production`` or ``sandbox`` WORKER OPTIONS -------------- @@ -38,18 +44,15 @@ WORKER OPTIONS The following options are from the “[wise-worker]” section. FREQUENCY - How often should worker run when no notification is received + How often should worker scan recent history TOKEN Account token -ACCOUNT_TYPE - Specify the account type and therefore the indexing behavior. This can either can be ``normal`` or ``exchange``. Exchange accounts bounce invalid incoming Taler transactions. - BALANCE OPTIONS --------------- -The following options are from the “[wise-balance*]” section. +The following options are from the ``[wise-balance-*]`` sections. ID Balance Wise ID @@ -58,7 +61,7 @@ CURRENCY Balance currency PAYTO_TYPE - Balance account type, this can only be ``iban`` + Balance account type, this can be ``iban`` or ``ach`` IBAN Balance IBAN, for ``iban`` payto type @@ -66,6 +69,12 @@ IBAN BIC Balance BIC, for ``iban`` payto type +ROUTING_NUMBER + Balance routing number, for ``ach`` payto type + +ACCOUNT_NUMBER + Balance account number, for ``ach`` payto type + HTTP SERVER OPTIONS ------------------- @@ -121,4 +130,4 @@ BUGS ==== Report bugs by using https://bugs.taler.net/ or by sending electronic -mail to <taler@gnu.org>. -\ No newline at end of file +mail to <taler@gnu.org>. diff --git a/taler-apns-relay-manual.rst b/taler-apns-relay-manual.rst @@ -66,12 +66,16 @@ APNs Relay belongs to the Taler Rust project, and can be downloaded via Git: $ git clone git://git.taler.net/taler-rust $ cd taler-rust -You will need the latest version of the rust stable toolchain and a C toolchain: +Building Debian/Ubuntu packages requires the distribution packages ``cargo`` +and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: .. code-block:: console - $ sudo apt install rustup build-essential - $ rustup toolchain install stable + $ sudo apt install cargo rustc build-essential python3 git debhelper + +If your distribution provides an older ``rustc``, install newer distribution +packages before continuing. A toolchain installed only through ``rustup`` does +not satisfy the Debian package build dependencies. Then from top-level run: @@ -83,7 +87,6 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup .. code-block:: console - $ sudo apt install debhelper $ make deb $ sudo dpkg -i ../taler-apns-relay*.deb @@ -144,7 +147,7 @@ can use the ``taler-apns-relay config`` helper: .. code-block:: shell-session - # taler-apns-relay config dump --diagnostics + # taler-apns-relay -c /etc/taler-apns-relay/taler-apns-relay.conf config dump --diagnostics Basic Setup =========== @@ -161,12 +164,8 @@ is: [apns-relaydb-postgres] config = postgres:///taler-apns-relay -If the database is run on a different host, please follow the instructions -from the PostgreSQL manual for configuring remote access. - -Assuming the configuration is correct, the following -command initializes (or upgrades) the database schema using: -You can then use a script to automate a secure database setup: +For a local PostgreSQL installation, the following helper creates the database +and roles, initializes (or upgrades) the schema, and grants service access: .. code-block:: console @@ -179,7 +178,7 @@ You will need an `Apple private key <https://developer.apple.com/help/account/ma Update the configuration files: .. code-block:: ini - :caption: /etc/taler-apns-relay/secret/apns-relay-worker.secret.conf + :caption: /etc/taler-apns-relay/secrets/apns-relay-worker.secret.conf [apns-relay-worker] KEY_ID = 555CFX5XXX diff --git a/taler-cyclos-manual.rst b/taler-cyclos-manual.rst @@ -91,12 +91,16 @@ Cyclos Adapter belongs to the Taler Rust project, and can be downloaded via Git: $ git clone git://git.taler.net/taler-rust $ cd taler-rust -You will need the latest version of the rust stable toolchain and a C toolchain: +Building Debian/Ubuntu packages requires the distribution packages ``cargo`` +and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: .. code-block:: console - $ sudo apt install rustup build-essential - $ rustup toolchain install stable + $ sudo apt install cargo rustc build-essential python3 git debhelper + +If your distribution provides an older ``rustc``, install newer distribution +packages before continuing. A toolchain installed only through ``rustup`` does +not satisfy the Debian package build dependencies. Then from top-level run: @@ -108,7 +112,6 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup .. code-block:: console - $ sudo apt install debhelper $ make deb $ sudo dpkg -i ../taler-cyclos*.deb @@ -170,7 +173,7 @@ can use the ``taler-cyclos config`` helper: .. code-block:: shell-session - # taler-cyclos config dump --diagnostics + # taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf config dump --diagnostics Basic Setup =========== @@ -187,12 +190,8 @@ is: [cyclosdb-postgres] config = postgres:///taler-cyclos -If the database is run on a different host, please follow the instructions -from the PostgreSQL manual for configuring remote access. - -Assuming the configuration is correct, the following -command initializes (or upgrades) the database schema using: -You can then use a script to automate a secure database setup: +For a local PostgreSQL installation, the following helper creates the database +and roles, initializes (or upgrades) the schema, and grants service access: .. code-block:: console diff --git a/taler-magnet-bank-manual.rst b/taler-magnet-bank-manual.rst @@ -59,12 +59,16 @@ Magnet Bank Adapter belongs to the Taler Rust project, and can be downloaded via $ git clone git://git.taler.net/taler-rust $ cd taler-rust -You will need the latest version of the rust stable toolchain and a C toolchain: +Building Debian/Ubuntu packages requires the distribution packages ``cargo`` +and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: .. code-block:: console - $ sudo apt install rustup build-essential - $ rustup toolchain install stable + $ sudo apt install cargo rustc build-essential python3 git debhelper + +If your distribution provides an older ``rustc``, install newer distribution +packages before continuing. A toolchain installed only through ``rustup`` does +not satisfy the Debian package build dependencies. Then from top-level run: @@ -76,7 +80,6 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup .. code-block:: console - $ sudo apt install debhelper $ make deb $ sudo dpkg -i ../taler-magnet-bank*.deb @@ -139,7 +142,7 @@ can use the ``taler-magnet-bank config`` helper: .. code-block:: shell-session - # taler-magnet-bank config dump --diagnostics + # taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf config dump --diagnostics Basic Setup =========== @@ -156,12 +159,8 @@ is: [magnet-bankdb-postgres] config = postgres:///taler-magnet-bank -If the database is run on a different host, please follow the instructions -from the PostgreSQL manual for configuring remote access. - -Assuming the configuration is correct, the following -command initializes (or upgrades) the database schema using: -You can then use a script to automate a secure database setup: +For a local PostgreSQL installation, the following helper creates the database +and roles, initializes (or upgrades) the schema, and grants service access: .. code-block:: console @@ -177,7 +176,7 @@ Update the configuration files: :caption: /etc/taler-magnet-bank/taler-magnet-bank.conf [magnet-bank] - IBAN = HU59131000073585363679133532 + IBAN = HU30162000031000163100000000 NAME = John Smith S.A. .. code-block:: ini @@ -265,4 +264,4 @@ Launching the adapter .. code-block:: console - $ sudo systemctl start taler-magnet-bank.target + $ sudo systemctl enable --now taler-magnet-bank.target diff --git a/taler-wise-manual.rst b/taler-wise-manual.rst @@ -78,19 +78,23 @@ To install the adapter, you can now simply run: Building from source -------------------- -Cyclos Adapter belongs to the Taler Rust project, and can be downloaded via Git: +Wise Adapter belongs to the Taler Rust project, and can be downloaded via Git: .. code-block:: console $ git clone git://git.taler.net/taler-rust $ cd taler-rust -You will need the latest version of the rust stable toolchain and a C toolchain: +Building Debian/Ubuntu packages requires the distribution packages ``cargo`` +and ``rustc`` (version 1.95 or newer), as well as a C toolchain, Python and Git: .. code-block:: console - $ sudo apt install rustup build-essential - $ rustup toolchain install stable + $ sudo apt install cargo rustc build-essential python3 git debhelper + +If your distribution provides an older ``rustc``, install newer distribution +packages before continuing. A toolchain installed only through ``rustup`` does +not satisfy the Debian package build dependencies. Then from top-level run: @@ -102,7 +106,6 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup .. code-block:: console - $ sudo apt install debhelper $ make deb $ sudo dpkg -i ../taler-wise*.deb @@ -141,7 +144,7 @@ Configuration Fundamentals This chapter provides fundamental details about the adapter configuration. The configuration for all adapter components uses a single configuration file -as entry point: ``/etc/taler-cyclos/taler-wise.conf``. +as entry point: ``/etc/taler-wise/taler-wise.conf``. System defaults are automatically loaded from files in ``/usr/share/taler-wise/config.d``. @@ -164,7 +167,7 @@ can use the ``taler-wise config`` helper: .. code-block:: shell-session - # taler-wise config dump --diagnostics + # taler-wise -c /etc/taler-wise/taler-wise.conf config dump --diagnostics Basic Setup =========== @@ -181,12 +184,8 @@ is: [wisedb-postgres] config = postgres:///taler-wise -If the database is run on a different host, please follow the instructions -from the PostgreSQL manual for configuring remote access. - -Assuming the configuration is correct, the following -command initializes (or upgrades) the database schema using: -You can then use a script to automate a secure database setup: +For a local PostgreSQL installation, the following helper creates the database +and roles, initializes (or upgrades) the schema, and grants service access: .. code-block:: console @@ -219,12 +218,13 @@ The setup process should fail and provide you with the information needed to fil NAME = John Smith S.A. .. code-block:: ini - :caption: /etc/taler-wise/conf.d/wise-worker.conf + :caption: /etc/taler-wise/conf.d/wise-system.conf - [wise-worker] + [wise] PROFILE_ID = 77620708 -The setup process should fail and provide you with the information needed to fill the Wise balances information: +Run the setup command again. It should now report the available balances and +ask you to configure at least one. Use the IDs and account details it reports: .. code-block:: ini :caption: /etc/taler-wise/conf.d/wise-worker.conf @@ -242,7 +242,10 @@ And finally run the setup process again: $ sudo -u taler-wise-worker taler-wise -c /etc/taler-wise/taler-wise.conf setup -This time, you should not see any errors; if you do, you should modify the configuration until it works. +On success, setup initializes synchronization state from each balance's creation +time. If it reports errors, correct the configuration and run it again. +``setup --reset`` resets all synchronization cursors and schedules to rescan +from balance creation; it does not reset credentials. Wire Gateway setup ------------------