commit 24206706cfbbeb93a321e1f7501a0cc3b4d2ff39
parent f8022fd19fa7508287bb1ad4480f4ab4479172ad
Author: Martin Schanzenbach <schanzen@gnunet.org>
Date: Thu, 18 Sep 2025 13:29:39 +0200
forgot to add file
Diffstat:
1 file changed, 254 insertions(+), 0 deletions(-)
diff --git a/taler-directory-manual.rst b/taler-directory-manual.rst
@@ -0,0 +1,254 @@
+..
+ 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 Martin Schanzenbach
+
+Directory Operator Manual
+#########################
+
+.. contents:: Table of Contents
+ :depth: 2
+ :local:
+
+
+Introduction
+============
+
+About Taler Directory
+---------------------
+
+The Taler Directory (TalDir) alias lookup service allows Taler wallets to
+securely associate an inbox service (URL and public key) with the address of a
+messaging service used by the wallet's user. Wallets can also lookup the
+inbox of other users. This will enable wallets to make wallet-to-wallet
+payments to distant wallets where the target user is only identified by their
+address in a messaging service. Examples for messaging services include E-mail
+and SMS.
+The service in principle allows registration of any valid URI as inbox
+service.
+For Taler, the URI is a link a :ref:`mailbox <api-mailbox>`.
+
+
+About this manual
+-----------------
+
+This manual targets system administrators who want to install,
+operate or integrate a directory service. To report issues
+or learn about known limitations, please check our
+`bug tracker <https://bugs.taler.net>`__.
+
+
+Architecture overview
+---------------------
+
+The following illustrations gives an overview of the
+architecture and the main interactions:
+
+.. image:: images/taldir-mailbox-registration.png
+
+.. image:: images/taldir-mailbox-lookup.png
+
+The user, in this case Alice, first requires a mailbox URI.
+In the case of GNU Taler Mailboxes offered through the mailbox
+service, mailbox URIs can be generated from wallet addresses.
+
+The mailbox URI can then be associated with one or more aliases
+by Alice with the directory service.
+To do so, Alice must prove that she is actually behind a respective
+alias.
+For example, a validation link is sent to Alices email address if she
+wants to associate her email alias with the mailbox URI.
+The validation process differs depending on the alias used.
+
+Other users, in this case Bob, may then resolve the mailbox URI using
+one of Alice's aliases in order to request a payment, or use Alice's
+wallet address to send money.
+
+.. _TaldirInstallation:
+
+Installation
+============
+
+In this guide's shell-session fragments, the command prompt shows two pieces
+of information:
+
+* Who is performing the command
+ (``$user`` vs ``root``, and ending character ``$`` vs ``#``).
+
+
+Installing from source
+----------------------
+
+The following instructions will show how to install libgnunetutil and
+the core GNU Taler libraries from source.
+
+The package sources can be find in our
+`download directory <http://ftpmirror.gnu.org/taler/>`__.
+
+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-directory 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).
+
+First, the following packages need to be installed before we can compile the
+backend:
+
+- Golang >= 1.19
+
+- taler-merchant >= 1.0
+
+For the GNS disseminator, a running GNUnet installation is also required:
+
+.. include:: frags/installing-gnunet.rst
+
+.. include:: frags/installing-taler-merchant.rst
+
+.. include:: frags/installing-taldir.rst
+
+.. include:: frags/install-before-check.rst
+
+
+
+Installing the directory binary packages on Debian
+--------------------------------------------------
+
+.. include:: frags/installing-debian.rst
+
+To install taler-directory you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-directory
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure at least the database, HTTP reverse proxy (typically with TLS
+certificates) and the terms of service.
+
+Installing the GNU Taler binary packages on Trisquel
+----------------------------------------------------
+
+.. include:: frags/installing-trisquel.rst
+
+Installing the GNU Taler binary packages on Ubuntu
+--------------------------------------------------
+
+.. include:: frags/installing-ubuntu.rst
+
+To install the Taler exchange, you can now simply run:
+
+.. code-block:: shell-session
+
+ # apt install taler-directory
+
+Note that the package does not perform any configuration work except for
+setting up the various users and the systemd service scripts. You still must
+configure at least the database, HTTP reverse proxy (typically with TLS
+certificates), and the terms of service.
+
+
+Services, users, groups and file system hierarchy
+-------------------------------------------------
+
+The *taler-directory* package will use several system users
+to compartmentalize different parts of the system:
+
+* ``taldir-httpd``: runs the HTTP daemon with the core business logic.
+* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
+* ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package).
+
+The package will deploy a systemd service files in
+``/usr/lib/systemd/system/`` for taler-directory:
+
+* ``taler-directory.service``: the business logic with the public REST API.
+
+
+Configuration Fundamentals
+==========================
+
+This chapter provides fundamental details about the exchange configuration.
+
+The configuration for all Taler components uses a single configuration file
+as entry point: ``/etc/taldir/taldir.conf``.
+
+System defaults are automatically loaded from files in
+``/usr/share/taldir/config.d``. These default files should never be modified.
+
+The default configuration ``taldir.conf`` configuration file also includes all
+configuration files in ``/etc/taldir/conf.d``.
+
+To view the entire configuration annotated with the source of each configuration option, you
+can use the ``taldir-config`` helper:
+
+
+.. code-block:: shell-session
+
+ [root@exchange-online]# taler-directory-config --help
+
+.. include:: frags/configuration-format.rst
+
+
+Fundamental Setup: Address validation
+-------------------------------------
+
+The service is designed to validate aliases. Possible
+alias types include:
+
+* phone numbers (via SMS)
+* e-mail addresses (via SMTP)
+
+In principle, additional types of addresses can easily be added by extending
+the respective HTML and programs to send challenges to the new address type.
+
+To make different types of address validations possible, the Challenger
+configuration contains two configuration options.
+
+(1) The ``ADDRESS_TYPE`` configuration option informs Challenger about the
+ type of address it is expected to validate. It is returned as part of
+ the OAuth 2.0 ``/info`` endpoint to the client, and is typically also
+ used when deciding how to render the HTML form for address entry that is
+ shown to the user.
+
+(2) The ``AUTH_COMMAND`` configuration option specifies which command
+ Challenger should run to send a challenge to an address. The actual
+ address is given to this subcommand as the first argument (``$1``),
+ while the text with the challenge is passed to standard input.
+ The subcommand should terminate with a status code of 0 on success.
+
+.. code-block:: ini
+ :caption: /etc/taldir/taldir.conf
+
+ [challenger]
+ ADDRESS_TYPE = email
+ AUTH_COMMAND = challenger-send-email.sh
+ # ... rest of file ...
+
+Challenger comes with ``AUTH_COMMAND`` shell scripts for sending e-mail, SMS
+and postal mail. Note that for SMS and postal mail the Challenger scripts uses
+third party services to actually send the SMS or print and mail the postal
+mail. These third parties naturally charge money for their services, and thus
+the Challenger administrator will need to add the respective credentials to
+the SMS and postal mail scripts before they can function. In any case, these
+scripts should be primarily seen as *examples* on how to write authentication
+commands.
+
+.. note::
+
+ We strongly welcome contributions for additional scripts with alternative
+ providers or for new types of addresses.
