commit ff48b9daafd1a6fc27756d6db06a2915ea95c950
parent 763e3f5469c77e0b21401590143192e2963fb41e
Author: Antoine A <>
Date: Fri, 6 Nov 2026 12:28:25 +0100
taler-rust: fix documentation
Diffstat:
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
------------------