commit 468eb743aec2b7838857d6c60f80a3530cb1b250
parent 730a10804d3dd23aa3f5d74ae0520fb732f493d2
Author: Antoine A <>
Date: Tue, 23 Dec 2025 13:50:51 +0100
taler-rust: add cyclos man pages & manual and simplify magnet bank
manual
Diffstat:
6 files changed, 530 insertions(+), 107 deletions(-)
diff --git a/manpages/frags/common-serve-options.rst b/manpages/frags/common-serve-options.rst
@@ -1,5 +1,5 @@
SERVE
- This can either be ``tcp`` or ``unix``.
+ Should the HTTP server listen on a UNIX domain socket (set option to ``unix``), or on a TCP socket (set option to ``tcp``), or be activated via systemd (set option to ``systemd``).
PORT
Port on which the HTTP server listens, e.g. 9967.
diff --git a/manpages/taler-cyclos.1.rst b/manpages/taler-cyclos.1.rst
@@ -0,0 +1,162 @@
+taler-cyclos(1)
+###############
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-cyclos** - Cyclos Taler adapter.
+
+
+Synopsis
+========
+
+**taler-cyclos**
+[**-h** | **--help**]
+[**--version**]
+COMMAND [ARGS...]
+
+Subcommands: **dbinit**, **setup**,
+**serve**, **worker**, **taler-deployment**, **config**
+
+
+Description
+===========
+
+**taler-cyclos** is a Taler adapter for the Cyclos API.
+
+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``.
+
+- 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.
+
+- 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 taler-cyclos. It is mandatory to run this command before invoking the ``setup`` or ``serve`` commands.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-r** \| **--reset**
+ Reset database (DANGEROUS: All existing data is lost)
+**-h** \| **--help**
+ Print short help on options.
+
+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.
+
+It is mandatory to run this command before invoking the ``worker`` command.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-r** \| **--reset**
+ Reset connection info and overwrite keys file
+**-h** \| **--help**
+ Print short help on options.
+
+worker
+------
+
+This subcommand initiate transaction throught the Cyclos API and sync the the bank account history.
+
+If ACCOUNT_TYPE is ``exchange``, incoming payments with an invalid Taler subject are bounced.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**--transient**
+ Execute once and return.
+**-h** \| **--help**
+ Print short help on options.
+
+serve
+-----
+
+This command starts the HTTP server.
+
+Its options are as follows:
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-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.
+**-h** \| **--help**
+ Print short help on options.
+
+taler-deployment
+----------------
+
+Helpers to integrate taler-cyclos with taler-exchange.
+
+**-h** \| **--help**
+ Print short help on options.
+
+Subcommands: **exchange-payto**, **wire-gateway-credentials**
+
+taler-deployment exchange-payto
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Output the exchange payto.
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-h** \| **--help**
+ Print short help on options
+
+taler-deployment wire-gateway-credentials
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Output the wire gateway credentials configuration.
+
+**-c** \| **--config** *config_file*
+ Specifies the configuration file.
+**-L** \| **--log** *LOGLEVEL*
+ Configure logging to use LOGLEVEL.
+**-h** \| **--help**
+ Print short help on options
+
+.. include:: ../frags/common-config-cli.rst
+
+SEE ALSO
+========
+
+taler-cyclos.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-cyclos.conf.5.rst b/manpages/taler-cyclos.conf.5.rst
@@ -0,0 +1,102 @@
+taler-cyclos.conf(5)
+####################
+
+.. only:: html
+
+ Name
+ ====
+
+ **taler-cyclos.conf** - Cyclos Taler adapter configuration file
+
+
+Description
+===========
+
+.. include:: ../frags/common-conf-syntax.rst
+
+Files containing default values for many of the options described below
+are installed under ``$TALER_CYCLOS_PREFIX/share/taler-cyclos/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``.
+
+
+ADAPTER OPTIONS
+---------------
+
+The following options are from the “[cyclos]” section.
+
+CURRENCY
+ Adapter currency
+
+ACCOUNT_ID
+ ID of the Cyclos account to sync.
+
+NAME
+ Legal entity that is associated with the Cyclos account.
+
+WORKER OPTIONS
+--------------
+
+The following options are from the “[cyclos-worker]” section.
+
+API_URL
+ Base URL of the Cyclos API server.
+
+USERNAME
+ Account username.
+
+PASSWORD
+ Account password
+
+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.
+
+HTTP SERVER OPTIONS
+-------------------
+
+The following configuration value(s) belong to the “[cyclos-httpd]” section.
+
+.. include:: frags/common-serve-options.rst
+
+HTTP WIRE GATEWAY API OPTIONS
+-----------------------------
+
+The following configuration value(s) belong to the “[cyclos-httpd-wire-gateway-api]” section.
+
+ENABLED
+ Whether to serve the Wire Gateway API.
+
+.. include:: frags/common-api-options.rst
+
+HTTP REVENUE API OPTIONS
+------------------------
+
+The following configuration value(s) belong to the “[cyclo-httpd-revenue-api]” section.
+
+ENABLED
+ Whether to serve the Revenue API.
+
+.. include:: frags/common-api-options.rst
+
+DATABASE OPTIONS
+----------------
+
+Setting the database belongs to the “[cyclosdb-postgres]” section and the following value.
+
+.. include:: frags/common-db-options.rst
+
+
+SEE ALSO
+========
+
+taler-cyclos(1)
+
+BUGS
+====
+
+Report bugs by using https://bugs.taler.net/ or by sending electronic
+mail to <taler@gnu.org>.
+\ No newline at end of file
diff --git a/manpages/taler-magnet-bank.conf.5.rst b/manpages/taler-magnet-bank.conf.5.rst
@@ -41,7 +41,7 @@ WORKER OPTIONS
The following options are from the “[magnet-bank-worker]” section.
API_URL
- URL of the Magnet Bank API server.
+ Base URL of the Magnet Bank API server.
CONSUMER_KEY
Your Magnet Bank API unique identifier.
diff --git a/taler-cyclos-manual.rst b/taler-cyclos-manual.rst
@@ -0,0 +1,259 @@
+..
+ This file is part of GNU TALER.
+ Copyright (C) 2025 Taler Systems SA
+
+ TALER is free software; you can redistribute it and/or modify it under the
+ terms of the GNU Affero General Public License as published by the Free Software
+ Foundation; either version 2.1, or (at your option) any later version.
+
+ TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+ WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+ A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License along with
+ TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/>
+
+ @author Antoine d'Aligny
+
+
+Cyclos Adapter Setup Manual
+###########################
+
+taler-cyclos is a Cyclos Taler adapter.
+
+This manual targets system administrators who want to install and
+operate a Cyclos GNU Taler adapter
+
+.. contents:: Table of Contents
+ :depth: 1
+ :local:
+
+Installation
+============
+
+Installing on Debian
+--------------------
+
+.. include:: frags/installing-debian.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-cyclos
+
+Installing on Ubuntu
+--------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the adapter, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-cyclos
+
+Building from source
+--------------------
+
+Cyclos 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:
+
+.. code-block:: console
+
+ $ sudo apt install rustup build-essential
+ $ rustup toolchain install stable
+
+Then from top-level run:
+
+.. code-block:: console
+
+ $ ./bootstrap
+
+To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
+
+.. code-block:: console
+
+ $ sudo apt install debhelper
+ $ make deb
+ $ sudo dpkg -i ../taler-cyclos*.deb
+
+If the previous steps succeeded, the ``taler-cyclos`` command should be found in the $PATH.
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-cyclos* package will create several system users
+to compartmentalize different parts of the system:
+
+* ``taler-cyclos-httpd``: runs the HTTP daemon with the API logic.
+* ``taler-cyclos-worker``: runs the worker daemon interacting with the Cyclos API.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+
+The adapter setup uses the following system groups:
+
+* ``taler-cyclos-db``: group for all adapter users with direct database access, specifically taler-cyclos-httpd and taler-cyclos-worker.
+
+The package will deploy systemd service files in
+``/usr/lib/systemd/system/`` for the various components:
+
+* ``taler-cyclos-httpd.service``: adapter REST API.
+* ``taler-cyclos-httpd.socket``: systemd socket activation for the HTTP daemon.
+* ``taler-cyclos-worker.service``: worker deamon interacting with the Cyclos API.
+* ``taler-cyclos.target``: main target for the adapter to be operational.
+
+The deployment creates the following key locations in the system:
+
+* ``/etc/taler-cyclos/``: configuration files.
+* ``/run/taler-cyclos/``: contains the UNIX domain sockets for inter-process communication (IPC).
+
+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-cyclos.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taler-cyclos/config.d``.
+These default files should never be modified.
+
+The default configuration ``taler-cyclos.conf`` configuration file
+also includes all configuration files in ``/etc/taler-cyclos/conf.d``.
+The settings from files in
+``conf.d`` are only relevant to particular components of an adapter, while
+``taler-cyclos.conf`` contains settings that affect all adapter components.
+
+
+The directory ``/etc/taler-cyclos/secrets`` contains configuration file snippets with
+values that should only be readable to certain users. They are included with the ``@inline-secret@``
+directive and should end with ``.secret.conf``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taler-cyclos config`` helper:
+
+
+.. code-block:: shell-session
+
+ # taler-cyclos config dump --diagnostics
+
+.. include:: frags/configuration-format.rst
+
+Basic Setup
+===========
+
+Database setup
+--------------
+
+The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
+is:
+
+.. code-block:: ini
+ :caption: /etc/taler-cyclos/secrets/cyclos-db.secret.conf
+
+ [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:
+
+.. code-block:: console
+
+ $ sudo taler-cyclos-dbconfig
+
+Worker setup
+------------
+
+You will need a Cyclos account to sync.
+Update the configuration files:
+
+.. code-block:: ini
+ :caption: /etc/taler-cyclos/taler-cyclos.conf
+
+ [cyclos]
+ CURRENCY = KUDOS
+ ACCOUNT_ID = 7762070814178012479
+ NAME = John Smith S.A.
+
+.. code-block:: ini
+ :caption: /etc/taler-cyclos/secrets/cyclos-worker.secret.conf
+
+ [cyclos-worker]
+ API_URL = https://demo.cyclos.org/api/
+ USERNAME = admin
+ PASSWORD = password
+
+And finaly run the setup process:
+
+.. code-block:: console
+
+ $ sudo -u taler-cyclos-worker taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf setup
+
+Wire Gateway setup
+------------------
+
+Update the configuration files:
+
+.. code-block:: ini
+ :caption: /etc/taler-cyclos/conf.d/cyclos-httpd.conf
+
+ [cyclos-httpd-wire-gateway-api]
+ ENABLED = YES
+
+.. code-block:: ini
+ :caption: /etc/taler-cyclos/secrets/cyclos-httpd.secret.conf
+
+ [cyclos-httpd-wire-gateway-api
+ AUTH_METHOD = bearer
+ TOKEN = $SECRET_TOKEN
+
+Check the server is correctly configured:
+
+.. code-block:: console
+
+ $ sudo -u taler-cyclos-httpd taler-cyclos -c /etc/taler-cyclos/taler-cyclos.conf serve --check
+
+Deployment
+==========
+
+This chapter describes how to deploy the adapter once the basic installation
+and configuration are completed.
+
+Reverse Proxy Setup
+-------------------
+
+By default, the ``taler-cyclos-httpd`` service listens for HTTP connections
+on a UNIX domain socket. To make the service publicly available, a reverse
+proxy such as nginx should be used. We strongly recommend to configure nginx
+to use TLS.
+
+The ``taler-cyclos`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+ # vim /etc/nginx/sites-available/taler-cyclos
+ < ... customize configuration ... >
+ # ln -s /etc/nginx/sites-available/taler-cyclos /etc/nginx/sites-enabled/taler-cyclos
+ # systemctl reload nginx
+
+With this last step, we are finally ready to launch the
+main adapter process.
+
+Launching the adapter
+---------------------
+
+.. code-block:: console
+
+ $ sudo systemctl start taler-cyclos.target
+\ No newline at end of file
diff --git a/taler-magnet-bank-manual.rst b/taler-magnet-bank-manual.rst
@@ -76,9 +76,6 @@ Then from top-level run:
$ ./bootstrap
-Install deb package
-~~~~~~~~~~~~~~~~~~~
-
To install the adapter as a Debian/Ubuntu package with an automated secure setup and systemd services:
.. code-block:: console
@@ -89,18 +86,6 @@ To install the adapter as a Debian/Ubuntu package with an automated secure setup
If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH.
-Install binaries
-~~~~~~~~~~~~~~~~
-
-To install the adapter binaries and default configuration localy run:
-
-.. code-block:: console
-
- $ ./configure --prefix=$PREFIX
- $ make install
-
-If the previous steps succeeded, the ``taler-magnet-bank`` command should be found in the $PATH.
-
Services, users, groups and file system hierarchy
-------------------------------------------------
@@ -165,11 +150,8 @@ can use the ``taler-magnet-bank config`` helper:
Basic Setup
===========
-Using package script
---------------------
-
Database setup
-~~~~~~~~~~~~~~
+--------------
The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
is:
@@ -192,7 +174,7 @@ You can then use a script to automate a secure database setup:
$ sudo taler-magnet-bank-dbconfig
Worker setup
-~~~~~~~~~~~~
+------------
You will need a Magnet Bank account to sync.
Update the configuration files:
@@ -218,7 +200,7 @@ And finaly run the setup process:
$ sudo -u taler-magnet-bank-worker taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf setup
Wire Gateway setup
-~~~~~~~~~~~~~~~~~~
+------------------
Update the configuration files:
@@ -240,69 +222,6 @@ Check the server is correctly configured:
.. code-block:: console
$ sudo -u taler-magnet-bank-httpd taler-magnet-bank -c /etc/taler-magnet-bank/taler-magnet-bank.conf serve --check
-
-Manual setup
-------------
-
-Database setup
-~~~~~~~~~~~~~~
-
-The configuration file must include a connection string that tells the adapter how it should connect to the database. The default
-is:
-
-.. code-block:: ini
- :caption: $CONFIG_FILE
-
- [magnet-bankdb-postgres]
- config = postgres:///taler-magnet-bank
-
-You must make sure that this database exists and is accessible to the user
-running the adapter before continuing. If the database is run on a different host, please follow the instructions from the PostgreSQL manual for configuring remote access.
-
-Assuming that the configuration file exists at ``$CONFIG_FILE``, the following
-command initializes (or upgrades) the database schema:
-
-.. code-block:: console
-
- $ taler-magnet-bank -c "$CONFIG_FILE" dbinit
-
-Update the configuration files:
-
-.. code-block:: ini
- :caption: $CONFIG_FILE
-
- [magnet-bank]
- IBAN = HU59131000073585363679133532
- NAME = John Smith S.A.
-
- [magnet-bank-worker]
- CONSUMER_KEY = $CONSUMER_KEY
- CONSUMER_SECRET = $CONSUMER_SECRET
-
-And finaly run the setup process:
-
-.. code-block:: console
-
- $ taler-magnet-bank -c "$CONFIG_FILE" setup
-
-Wire Gateway setup
-~~~~~~~~~~~~~~~~~~
-
-Update the configuration files:
-
-.. code-block:: ini
- :caption: $CONF_FILE
-
- [magnet-bank-httpd-wire-gateway-api]
- ENABLED = YES
- AUTH_METHOD = bearer
- TOKEN = $SECRET_TOKEN
-
-Check the server is correctly configured:
-
-.. code-block:: console
-
- $ taler-magnet-bank -c "$CONF_FILE" serve --check
Deployment
==========
@@ -310,27 +229,6 @@ Deployment
This chapter describes how to deploy the adapter once the basic installation
and configuration are completed.
-Serving
--------
-
-The adapter can serve HTTP over both TCP and UNIX domain socket.
-
-The following options are to be configured in the section ``[magnet-bank-httpd]``:
-
-- ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve
- HTTP over a UNIX domain socket.
-
-- ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``.
-
-- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is
- ``unix``.
-
-- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask
- for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such
- a way that your adapter has permissions to access the UNIX domain
- socket. The default (660) assumes that the reverse proxy is a member of
- the group under which the adapter HTTP server is running.
-
Reverse Proxy Setup
-------------------
