diff options
Diffstat (limited to 'frags')
25 files changed, 815 insertions, 80 deletions
diff --git a/frags/about-taler.rst b/frags/about-taler.rst new file mode 100644 index 00000000..7838cde7 --- /dev/null +++ b/frags/about-taler.rst @@ -0,0 +1,26 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2014-2023 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/> + + +GNU Taler is an open protocol for an electronic payment system with a +free software reference implementation. GNU Taler offers secure, fast +and easy payment processing using well understood cryptographic +techniques. GNU Taler allows customers to remain anonymous, while +ensuring that merchants can be held accountable by governments. Hence, +GNU Taler is compatible with anti-money-laundering (AML) and +know-your-customer (KYC) regulation, as well as data protection +regulation (such as GDPR). + diff --git a/frags/apt-install-libeufin-bank.rst b/frags/apt-install-libeufin-bank.rst new file mode 100644 index 00000000..97b1bd71 --- /dev/null +++ b/frags/apt-install-libeufin-bank.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-bank diff --git a/frags/apt-install-libeufin-nexus.rst b/frags/apt-install-libeufin-nexus.rst new file mode 100644 index 00000000..25ff8070 --- /dev/null +++ b/frags/apt-install-libeufin-nexus.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-nexus diff --git a/frags/apt-install-taler-merchant.rst b/frags/apt-install-taler-merchant.rst index d9605f79..1593dcfd 100644 --- a/frags/apt-install-taler-merchant.rst +++ b/frags/apt-install-taler-merchant.rst @@ -9,5 +9,6 @@ Note that the package does not complete the integration of the backend with the HTTP reverse proxy (typically with TLS certificates). A configuration fragment for Nginx or Apache will be placed in ``/etc/{apache,nginx}/conf-available/taler-merchant.conf``. You must -furthermore still configure the instances, and may need to extend the fragment -with access control restrictions for non-default instances. +furthermore still configure the database and the instances, and may need to +extend the fragment with access control restrictions for non-default +instances. diff --git a/frags/common-conf-syntax.rst b/frags/common-conf-syntax.rst new file mode 100644 index 00000000..2ca15058 --- /dev/null +++ b/frags/common-conf-syntax.rst @@ -0,0 +1,61 @@ +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. + +Values that represent a time duration are represented as a series +of one or more ``NUMBER UNIT`` pairs, e.g. ``60 s``, ``4 weeks 1 day``, +``5 years 2 minutes``. + +Values that represent an amount are in the usual amount syntax: +``CURRENCY:VALUE.FRACTION``, e.g. ``EUR:1.50``. +The ``FRACTION`` portion may extend up to 8 places. + +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. diff --git a/frags/configuration-format.rst b/frags/configuration-format.rst index f9b28e19..5a74c775 100644 --- a/frags/configuration-format.rst +++ b/frags/configuration-format.rst @@ -1,16 +1,22 @@ Configuration format -------------------- -In Taler realm, any component obeys to the same pattern to get -configuration values. According to this pattern, once the component has -been installed, the installation deploys default values in -${prefix}/share/taler/config.d/, in .conf files. In order to override -these defaults, the user can write a custom .conf file and either pass -it to the component at execution time, or name it taler.conf and place -it under $HOME/.config/. +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at ${prefix}/share/taler/config.d/ where ${prefix} is the installation +prefix. Different components must be installed to the same prefix. + +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the *-c* +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass ``-c +/etc/taler/taler.conf``, thus making ``/etc/taler/taler.conf`` +the primary location for the configuration. A config file is a text file containing sections, and each section -contains its values. The right format follows: +contains maps options to their values. Configuration files follow +basically the INI syntax: .. code-block:: ini @@ -22,48 +28,37 @@ contains its values. The right format follows: value21 = string value22 = /path22 -Throughout any configuration file, it is possible to use ``$``-prefixed -variables, like ``$VAR``, especially when they represent filesystem -paths. It is also possible to provide defaults values for those +Comments start with a hash (``#``). Throughout the configuration, it is +possible to use ``$``-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those variables that are unset, by using the following syntax: -``${VAR:-default}``. However, there are two ways a user can set -``$``-prefixable variables: +``${VAR:-default}``. There are two ways a user can set the value +of ``$``-prefixable variables: -by defining them under a ``[paths]`` section, see example below, +(1) by defining them under a ``[paths]`` section: -.. code-block:: ini + .. code-block:: ini - [paths] - TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data - .. - [section-x] - path-x = ${TALER_DEPLOYMENT_SHARED}/x + [paths] + TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data + .. + [section-x] + path-x = ${TALER_DEPLOYMENT_SHARED}/x -or by setting them in the environment: +(2) or by setting them in the environment: -.. code-block:: console + .. code-block:: console - $ export VAR=/x + $ export VAR=/x The configuration loader will give precedence to variables set under -``[path]``, though. +``[path]`` over environment variables. -The utility ``taler-config``, which gets installed along with the -exchange, serves to get and set configuration values without directly -editing the .conf. The option ``-f`` is particularly useful to resolve +The utility ``taler-config``, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option ``-f`` is particularly useful to resolve pathnames, when they use several levels of ``$``-expanded variables. See ``taler-config --help``. -Note that, in this stage of development, the file -``$HOME/.config/taler.conf`` can contain sections for *all* the -component. For example, both an exchange and a bank can read values from -it. - -The repository ``git://taler.net/deployment`` contains examples of -configuration file used in our demos. See under ``deployment/config``. - - **Note** - - Expectably, some components will not work just by using default - values, as their work is often interdependent. For example, a - merchant needs to know an exchange URL, or a database name. +The repository ``git://git.taler.net/deployment`` contains example code +for generating configuration files under ``deployment/netzbon/``. diff --git a/frags/db-stores-sensitive-data.rst b/frags/db-stores-sensitive-data.rst index 514db015..0e3dab86 100644 --- a/frags/db-stores-sensitive-data.rst +++ b/frags/db-stores-sensitive-data.rst @@ -1,6 +1,5 @@ .. note:: - The Taler merchant backend stores private keys and other sensitive - business and customer data in the database. The backend operator - SHOULD ensure that backup operations are encrypted and secured from - unauthorized access. + Taler may store sensitive business and customer data in the database. Any + operator SHOULD thus ensure that backup operations are encrypted and + secured from unauthorized access. diff --git a/frags/deploying-tos.rst b/frags/deploying-tos.rst new file mode 100644 index 00000000..5b389f44 --- /dev/null +++ b/frags/deploying-tos.rst @@ -0,0 +1,45 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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/> + + +Configuring exchange terms +========================== + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/frags/ebics-setup.rst diff --git a/frags/install-before-check.rst b/frags/install-before-check.rst new file mode 100644 index 00000000..9cde7481 --- /dev/null +++ b/frags/install-before-check.rst @@ -0,0 +1,6 @@ +Please note that unlike most packages, if you want to run the ``make check`` +command, you should run it only *after* having done ``make install``. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if ``make check`` fails, please consider filing a +bug report with the Taler `bug tracker <https://bugs.taler.net>`__. diff --git a/frags/installing-challenger.rst b/frags/installing-challenger.rst new file mode 100644 index 00000000..2e7526e4 --- /dev/null +++ b/frags/installing-challenger.rst @@ -0,0 +1 @@ +TBD. diff --git a/frags/installing-debian.rst b/frags/installing-debian.rst index 0110b243..0032e65e 100644 --- a/frags/installing-debian.rst +++ b/frags/installing-debian.rst @@ -1,6 +1,6 @@ To install the GNU Taler Debian packages, first ensure that you have the right Debian distribution. At this time, the packages are built for -Bullseye. +Debian bookworm. You need to add a file to import the GNU Taler packages. Typically, this is done by adding a file ``/etc/apt/sources.list.d/taler.list`` that @@ -8,19 +8,20 @@ looks like this: .. code-block:: - deb https://deb.taler.net/apt/debian bullseye main + deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm main Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: .. code-block:: console - # wget -O - https://taler.net/taler-systems.gpg.key | apt-key add - + # wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg # apt update .. note:: - You may want to verify the correctness of the Taler Systems key out-of-band. + You may want to verify the correctness of the Taler Systems SA key out-of-band. Now your system is ready to install the official GNU Taler binary packages using apt. diff --git a/frags/installing-gnunet.rst b/frags/installing-gnunet.rst index 99ff472d..a39358d0 100644 --- a/frags/installing-gnunet.rst +++ b/frags/installing-gnunet.rst @@ -2,6 +2,13 @@ Before you install GNUnet, you must download and install the dependencies mentioned in the previous section, otherwise the build may succeed, but could fail to export some of the tooling required by GNU Taler. +On Ubuntu, you also need to install pkg-config, for example: + +.. code-block:: console + + $ apt-get install pkg-config + + To install GNUnet, unpack the tarball and change into the resulting directory, then proceed as follows: diff --git a/frags/installing-taler-merchant.rst b/frags/installing-taler-merchant.rst index 249d5d77..f83e4aca 100644 --- a/frags/installing-taler-merchant.rst +++ b/frags/installing-taler-merchant.rst @@ -1,7 +1,3 @@ -GNU Taler merchant has these additional dependencies: - -- libqrencode >= 4.0.0 - The following steps assume all dependencies are installed. First, unpack the GNU Taler merchant tarball and change into diff --git a/frags/installing-trisquel.rst b/frags/installing-trisquel.rst index 4ca8bcc5..f431b120 100644 --- a/frags/installing-trisquel.rst +++ b/frags/installing-trisquel.rst @@ -1,4 +1,4 @@ To install the GNU Taler Trisquel packages, first ensure that you have the right Trisquel distribution. Packages are currently available for Trisquel GNU/Linux 10.0. Simply follow the same instructions provided -for Ubuntu 20.04 LTS (Focal Fossa). +for Ubuntu. diff --git a/frags/installing-ubuntu.rst b/frags/installing-ubuntu.rst index 12831043..f31b4ec6 100644 --- a/frags/installing-ubuntu.rst +++ b/frags/installing-ubuntu.rst @@ -1,13 +1,21 @@ To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for -Ubuntu 20.04 LTS (Focal Fossa). +Ubuntu Lunar and Ubuntu Jammy. Make sure to have ``universe`` in your +``/etc/apt/sources.list`` (after ``main``) as we depend on some packages +from Ubuntu ``universe``. A typical ``/etc/apt/sources.list.d/taler.list`` file for this setup -would look like this: +would look like this for Ubuntu Lunar: .. code-block:: - deb https://deb.taler.net/apt/ubuntu/ focal-fossa main + deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar + +For Ubuntu Mantic use this instead: + +.. code-block:: + + deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic The last line is crucial, as it adds the GNU Taler packages. @@ -16,7 +24,8 @@ into your keyring and update the package lists: .. code-block:: console - # wget -O - https://taler.net/taler-systems.gpg.key | apt-key add - + # wget -O /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg # apt update .. note:: diff --git a/frags/legal.rst b/frags/legal.rst new file mode 100644 index 00000000..be9b7f91 --- /dev/null +++ b/frags/legal.rst @@ -0,0 +1,183 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2014-2023 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 Christian Grothoff + + +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. + + +Terms of Service +---------------- + +The service has an endpoint "/terms" to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. + +To configure the terms of service response, there are two options +in the configuration file for the service: + +- ``TERMS_ETAG``: The current "Etag" to return for the terms of service. + This value must be changed whenever the terms of service are + updated. A common value to use would be a version number. + Note that if you change the ``TERMS_ETAG``, you MUST also provide + the respective files in ``TERMS_DIR`` (see below). +- ``TERMS_DIR``: The directory that contains the terms of service. + The files in the directory must be readable to the service + process. + + +Privacy Policy +-------------- + +The service has an endpoint "/pp" to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + +- ``PRIVACY_ETAG``: The current "Etag" to return for the privacy policy. + This value must be changed whenever the privacy policy is + updated. A common value to use would be a version number. + Note that if you change the ``PRIVACY_ETAG``, you MUST also provide + the respective files in ``PRIVACY_DIR`` (see below). +- ``PRIVACY_DIR``: The directory that contains the privacy policy. + The files in the directory must be readable to the service + process. + + +Legal policies directory layout +------------------------------- + +The ``TERMS_DIR`` and ``PRIVACY_DIR`` directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using two-letter language codes +like "en", "de", or "jp". Each of these directories would then hold +translations of the current terms of service into the respective language. +Empty directories are permitted in case translations are not available. + +Then, inside each language directory, files with the name of the value set as +the ``TERMS_ETAG`` or ``PRIVACY_ETAG`` must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +".epub", ".html", ".md", ".pdf" and ".txt" files. If other files are present, +the service may show a warning on startup. + +Example +^^^^^^^ + +A sample file structure for a ``TERMS_ETAG`` of "tos-v0" would be: + +- TERMS_DIR/en/tos-v0.txt +- TERMS_DIR/en/tos-v0.html +- TERMS_DIR/en/tos-v0.pdf +- TERMS_DIR/en/tos-v0.epub +- TERMS_DIR/en/tos-v0.md +- TERMS_DIR/de/tos-v0.txt +- TERMS_DIR/de/tos-v0.html +- TERMS_DIR/de/tos-v0.pdf +- TERMS_DIR/de/tos-v0.epub +- TERMS_DIR/de/tos-v0.md + +If the user requests an HTML format with language preferences "fr" followed by +"en", the service would return ``TERMS_DIR/en/tos-v0.html`` lacking a version in +French. + + +Generating the Legal Terms +-------------------------- + +The ``taler-terms-generator`` script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in ``.rst`` format and GNU gettext +translations in ``.po`` format. + +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +``$PREFIX/share/terms/*.rst`` where ``$PREFIX`` is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective ``ETAG``. The +resulting file must be called ``$ETAG.rst`` and the first line of the file should be the title of the document. + +Once you have written the ``$ETAG.rst`` file in English, you can +generate the first set of outputs: + +.. code-block:: shell-session + + $ taler-terms-generator -i $ETAG + +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in ``$PREFIX/share/terms/``. The generator +has a few options which are documented in its man page. + + +Adding translations +------------------- + +Translations must be available in subdirectories +``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po``. +To start translating, you first need to add a new +language: + +.. code-block:: shell-session + + $ taler-terms-generator -i $ETAG -l $LANGUAGE + +Here, ``$LANGUAGE`` should be a two-letter language +code like ``de`` or ``fr``. The command will generate +a file ``locale/$LANGUAGE/LC_MESSAGES/$ETAG.po`` +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the ``.po`` +file. Afterwards, simply re-run + +.. code-block:: shell-session + + $ taler-terms-generator -i $ETAG + +to make the current translation(s) available to the +service. + +.. note:: + + You must restart the service whenever adding or updating legal documents or their translations. + + +Updating legal documents +------------------------ + +When making minor changes without legal implications, edit the ``.rst`` file, +then re-run the step to add a new language for each existing translation to +produce an updated ``.po`` file. Translate the sentences that have changed and +finally run the generator (without ``-l``) on the ETAG (``-i $ETAG``) to +create the final files. + +When making major changes with legal implications, you should first rename (or +copy) the existing ``.rst`` file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the ``.po`` files, +complete the translations and re-create the final files. Finally, do not +forget to update the ``ETAG`` configuration option to the new name and to +restart the service. diff --git a/frags/libeufin-config-cli.rst b/frags/libeufin-config-cli.rst new file mode 100644 index 00000000..5475324e --- /dev/null +++ b/frags/libeufin-config-cli.rst @@ -0,0 +1,51 @@ +config +------ + +This command inspect or change the configuration. + +**-h** \| **--help** + Print short help on options. + +Subcommands: **get**, **dump**, **pathsub** + +config get +----------- + +This command lookup config value. + +It takes two arguments, the section name and the option name + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. +**-f** \| **--filename** + Interpret value as path with dollar-expansion. + +config dump +----------- + +This command dump the configuration. + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. + +config pathsub +-------------- + +This command substitute variables in a path. + +It takes one argument, a path expression. + +**-h** \| **--help** + Print short help on options. +**-c** \| **--config** *FILENAME* + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. diff --git a/frags/list-of-dependencies.rst b/frags/list-of-dependencies.rst index f0a183f2..5c36b086 100644 --- a/frags/list-of-dependencies.rst +++ b/frags/list-of-dependencies.rst @@ -1,12 +1,16 @@ +- "Sphinx RTD Theme" Python package aka ``python3-sphinx-rtd-theme`` + on Debian-based systems (for GNUnet documentation support, can be + omitted if GNUnet is configured with ``--disable-documentation``) + - libsqlite3 >= 3.16.2 - GNU libunistring >= 0.9.3 - libcurl >= 7.26 (or libgnurl >= 7.26) -- libqrencode >= 4.0.0 +- libqrencode >= 4.0.0 (Taler merchant only) -- GNU libgcrypt >= 1.6 +- GNU libgcrypt >= 1.6 (1.10 or later highly recommended) - libsodium >= 1.0 @@ -14,8 +18,31 @@ - libjansson >= 2.7 -- Postgres >= 9.6, including libpq +- PostgreSQL >= 15, including libpq - GNU libmicrohttpd >= 0.9.71 -- GNUnet >= 0.14.0 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__) +- GNUnet >= 0.20 (from `source tarball <http://ftpmirror.gnu.org/gnunet/>`__) + +- Python3 with ``jinja2`` + + +If you are on Debian stable or later, the following command may help you +install these dependencies: + +.. code-block:: console + + # apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst new file mode 100644 index 00000000..76f51bfe --- /dev/null +++ b/frags/nexus-ebics-setup.rst @@ -0,0 +1,87 @@ + +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the +name of the *fiat* currency. + +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + CURRENCY = CHF + + # Bank + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 + + # Account information + IBAN = CH7789144474425692816 + BIC = POFICHBEXXX + NAME = John Smith S.A. + +.. note:: + Refer to the manpage ``libeufin-nexus.conf(5)`` + for the full array of configuration values. + +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + +Reuse existing client keys +-------------------------- + +If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config). + +Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json + +Create new client keys +---------------------- + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command should start the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document you can continue. + +Get bank keys +------------- + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command will finish the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +The EBICS setup is finished once the bank keys have been accepted. + +Make sure this bank keys are accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/bank-ebics-keys.json diff --git a/frags/regional-manual-architecture.rst b/frags/regional-manual-architecture.rst new file mode 100644 index 00000000..ec8c9907 --- /dev/null +++ b/frags/regional-manual-architecture.rst @@ -0,0 +1,48 @@ +Architecture +============ + +There are several key components needed to operate a regional currency based +on GNU Taler and LibEuFin technology: + +- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn + about incoming payments and to send fiat cash-out payments +- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, + account management, cash-out's +- Taler exchange: server side of Taler operations. +- Taler wallet: client side of Taler operations. +- Taler merchant backend: abstracts Taler details to the shops. + +.. image:: ../images/regional-currency-architecture-diagram.png + +In this model, the regional currency is backed by the fiat currency and users +are offered two operations: *cash-in* to create regional currency starting +from fiat money, and *cash-out* to convert regional currency into fiat +currency. + +The design assumes that one single unit of regional currency is always backed +by one single unit of fiat currency. + + +Cash-in ++++++++ + +One fundamental entity to create the regional currency is the *master bank account*. +The master bank account is hosted at one fiat bank and whenever it receives a *valid* +fiat payment of N units, it triggers the creation of N units of regional currency. +Such trigger causes the *admin bank account* at the regional bank to wire the N units of +regional currency to the Taler exchange (regional) bank account. At this point, the +Taler exchange is ready to issue the regional coins to the Taler wallet that proves +to own them. + +.. note:: + + *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. + + +Cash-out +++++++++ + +Once a regional bank user confirms a cash-out operation of N units, the system sends +a regional payment of N units to the *admin bank account*. This latter triggers then +a fiat payment of N units to the fiat bank account owned by the user who initiated the +cash-out. diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst new file mode 100644 index 00000000..7566d622 --- /dev/null +++ b/frags/regional-manual-use.rst @@ -0,0 +1,110 @@ +.. _regional-use: + +Using the Regional Currency +=========================== + +The very first step you should check after the installation process has been +completed successfully, is to make sure all three URLs (bank, backend and exchange), +are available (this means to see a Website, and not any NGINX error). + + +Bank backend walkthrough ++++++++++++++++++++++++++ + +- As stated above, please visit before "https://bank.$DOMAIN_NAME", to make sure it is available. + +- Now login with the username "admin" and the password you have choosen during the installation process, or use the one which might + have been generated automatically (and shown on your terminal screen), during the installation process. + Once inside the Bank Administrator area, please create the "very first" customer account. + +- Transfer some funds from the "admin" bank account to this new customer account. + +- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make sure the funds you have transfered from admin, have arrived correctly. + +- Now, please choose the option "Send Money to a Taler Wallet", and try to send for example 100 units of your regional currency to the + wallet installed on your browser or mobile phone. + +- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital currency you have choosen, during your installation process, let's say Netzbon. + +- Lastly, you can also try to transfer funds to another "bank account",for that you will need to know the recipient's username or the bank account ID. + +If you have successfully accomplished all the previous steps, for the bank administrator +backend and your installed Wallet, you can move now to test other components such +as the Merchant backend (https://backend.$DOMAIN_NAME). + +Wallet Setup +++++++++++++ + +This section describes the interaction between the Taler graphical wallet (Android, +iOS, WebExtensions) and the regional currency system. + +You need to add your regional currency exchange to the wallet. This can +be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN_NAME/$MASTER_PUBLIC_KEY`` +URL or by manually entering the URL into the respective ``Add exchange`` +dialogue. + +.. _regional-use-cashin: + +Cash-In ++++++++ + +Next, start the withdraw process in the Taler wallet for the respective +currency and specify the desired amount. The wallet will then show you the +details of the fiat wire transfer that must be made for the cash-in to be +completed. Once the money has arrived at the fiat bank account, Nexus will +obtain the transaction data and the regional currency bank will create the +corresponding amount in regional currency, crediting the GNU Taler exchange +account. In turn, the exchange will issue the respective amount to your +wallet. + +.. note:: + + Cash-in operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + +.. warning:: + + Cash-in operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed. + +Making payments ++++++++++++++++ + +For testing, you should be able to *deposit* regional currency directly into +your regional currency libeufin-bank account directly from the Taler wallet. +For this, you primarily need to know your bank account details (which should +be accessible by clicking on your name in the bank Web site after logging in). + +.. note:: + + There may be a short delay between the wallet making the deposit and + the exchange crediting your bank account. This is because the wallet + uses a small wire transfer delay by default when initiating a deposit + into a bank account. + +For production, it is more common for a shop to configure a :ref:`Taler +merchant backend <taler-merchant-backend-operator-manual>` or at least use an +instance within such a setup. To configure an instance, you primarily need +again the bank account details to :ref:`setup instance bank accounts +<instance-bank-account>`. + +.. _regional-use-cashout: + +Cash-Out +++++++++ + +Regional currency accounts that have a positive balance could be eligible for +cash-out. Cash-out operations may again be restricted by the regional +currency operator and will *only* be made to the respective pre-configured +fiat currency bank account. To cash-out, simply log into your regional +currency account, select cash-out, specify the desired amount and pass the +second-factor authorization challenge by entering the TAN you receive at the +registered e-mail address or mobile phone number. + +.. note:: + + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + +.. warning:: + + Cash-out operations can take a long time, hours at the best of times, and even days on weekends or holidays when the bank is closed. diff --git a/frags/regional-system-on.rst b/frags/regional-system-on.rst new file mode 100644 index 00000000..1a2898e0 --- /dev/null +++ b/frags/regional-system-on.rst @@ -0,0 +1,44 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2014-2024 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/> + + +System ON! +========== + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions <receive-transaction-data>` (cash in) and to :ref:`trigger +outgoing bank transactions <sending-payments>` (cash out). + +First, check that libeufin-nexus is correctly configured by running the following commands: + +.. code-block:: console + + # sudo -u libeufin-nexus libeufin-nexus ebics-setup + # sudo -u libeufin-nexus libeufin-nexus ebics-fetch --transient + # sudo -u libeufin-nexus libeufin-nexus ebics-submit --transient + +If you have old transactions after the date YYYY-MM-DD that you wish to import into the database, run the following command: + +.. code-block:: console + + # sudo -u libeufin-nexus libeufin-nexus ebics-fetch --transientt --pinned-start YYYY-MM-DD + +None of those commands should fail. If they all work, you can enable the services: + +.. code-block:: console + + # systemctl enable --now libeufin-nexus.target + +Now that we know that libeufin-nexus is working correctly, we still need to check that communication with your bank is working properly. We will test this later, at :ref:`the end of the manual <regional-use>`. The system should only be considered functional after a successful :ref:`cash in <regional-use-cashin>` and :ref:`cash out <regional-use-cashout>`.
\ No newline at end of file diff --git a/frags/semver.rst b/frags/semver.rst new file mode 100644 index 00000000..8e655315 --- /dev/null +++ b/frags/semver.rst @@ -0,0 +1,25 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2014-2023 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 Christian Grothoff + +GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. +The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match. +Exceptions to this general rule are documented in the release notes. +For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x +as the MAJOR version matches. A MAJOR version of 0 indicates experimental +development, and you are expected to always run all of the *latest* releases +together (no compatibility guarantees). diff --git a/frags/using-taler-config.rst b/frags/using-taler-config.rst index c15df84b..ba4febb4 100644 --- a/frags/using-taler-config.rst +++ b/frags/using-taler-config.rst @@ -1,9 +1,11 @@ Using taler-config ------------------ -The tool ``taler-config`` can be used to extract or manipulate -configuration values; however, the configuration use the well-known INI -file format and can also be edited by hand. +The tool ``taler-config`` can be used to extract or manipulate configuration +values; however, the configuration use the well-known INI file format and is +generally better edited by hand to preserve comments and structure. Thus, ``taler-config`` should primarily be used +to inspect or understand a configuration that is in place, +and not to update it! Run @@ -17,19 +19,21 @@ Run .. code-block:: console - $ taler-config -s $section -o $option + $ taler-config -s $SECTION -o $OPTION -to extract the respective configuration value for option ``$option`` in -section ``$section``. +to extract the respective configuration value for option ``$OPTION`` in +section ``$SECTION``. -Finally, to change a setting, run +Finally, to change a setting and clobber your entire +configuration file structure, inlining all values and +removing all comments, run .. code-block:: console - $ taler-config -s $section -o $option -V $value + $ taler-config -s $SECTION -o $OPTION -V $VALUE -to set the respective configuration value to ``$value``. Note that you -have to manually restart the Taler backend after you change the +to set the respective configuration value to ``$VALUE``. Note that you +have to manually restart affected Taler components after you change the configuration to make the new configuration go into effect. Some default options will use $-variables, such as ``$DATADIR`` within @@ -39,12 +43,9 @@ compare: .. code-block:: console - $ taler-config -s ACCOUNT-bank \ - -o WIRE_RESPONSE - $ taler-config -f -s ACCOUNT-bank \ - -o WIRE_RESPONSE + $ taler-config --section exchange-offline --option MASTER_PRIV_FILE + $ taler-config -f --section exchange-offline --option MASTER_PRIV_FILE While the configuration file is typically located at -``$HOME/.config/taler.conf``, an alternative location can be specified -to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c`` -option. +``$HOME/.config/taler.conf``, an alternative location can be specified to any +GNU Taler component using the ``-c`` option. |