taler-directory-manual.rst (7910B)
1 .. 2 This file is part of GNU TALER. 3 4 Copyright (C) 2025 Taler Systems SA 5 6 TALER is free software; you can redistribute it and/or modify it under the 7 terms of the GNU Affero General Public License as published by the Free Software 8 Foundation; either version 2.1, or (at your option) any later version. 9 10 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 11 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 12 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 13 14 You should have received a copy of the GNU Affero General Public License along with 15 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 16 17 @author Martin Schanzenbach 18 19 Directory Operator Manual 20 ######################### 21 22 .. contents:: Table of Contents 23 :depth: 2 24 :local: 25 26 27 Introduction 28 ============ 29 30 About Taler Directory 31 --------------------- 32 33 The Taler Directory (TalDir) alias lookup service allows Taler wallets to 34 securely associate an inbox service (URL and public key) with the address of a 35 messaging service used by the wallet's user. Wallets can also lookup the 36 inbox of other users. This will enable wallets to make wallet-to-wallet 37 payments to distant wallets where the target user is only identified by their 38 address in a messaging service. Examples for messaging services include E-mail 39 and SMS. 40 The service in principle allows registration of any valid URI as inbox 41 service. 42 For Taler, the URI is a link a :ref:`mailbox <api-mailbox>`. 43 44 45 About this manual 46 ----------------- 47 48 This manual targets system administrators who want to install, 49 operate or integrate a directory service. To report issues 50 or learn about known limitations, please check our 51 `bug tracker <https://bugs.taler.net>`__. 52 53 54 Architecture overview 55 --------------------- 56 57 .. include:: frags/taldir-maildir-architecture.rst 58 59 .. _TaldirInstallation: 60 61 Installation 62 ============ 63 64 In this guide's shell-session fragments, the command prompt shows two pieces 65 of information: 66 67 * Who is performing the command 68 (``$user`` vs ``root``, and ending character ``$`` vs ``#``). 69 70 71 Installing from source 72 ---------------------- 73 74 The following instructions will show how to install libgnunetutil and 75 the core GNU Taler libraries from source. 76 77 The package sources can be find in our 78 `download directory <http://ftpmirror.gnu.org/taler/>`__. 79 80 GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. 81 The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match. 82 Exceptions to this general rule are documented in the release notes. 83 For example, taler-directory 1.3.0 should be compatible with Taler exchange 1.4.x 84 as the MAJOR version matches. A MAJOR version of 0 indicates experimental 85 development, and you are expected to always run all of the *latest* releases 86 together (no compatibility guarantees). 87 88 First, the following packages need to be installed before we can compile the 89 backend: 90 91 - Golang >= 1.19 92 93 - taler-merchant >= 1.0 94 95 For the GNS disseminator, a running GNUnet installation is also required: 96 97 .. include:: frags/installing-gnunet.rst 98 99 .. include:: frags/installing-taler-merchant.rst 100 101 .. include:: frags/installing-taldir.rst 102 103 .. include:: frags/install-before-check.rst 104 105 106 107 Installing the directory binary packages on Debian 108 -------------------------------------------------- 109 110 .. include:: frags/installing-debian.rst 111 112 To install taler-directory you can now simply run: 113 114 .. code-block:: shell-session 115 116 # apt install taler-directory 117 118 Note that the package does not perform any configuration work except for 119 setting up the various users and the systemd service scripts. You still must 120 configure at least the database, HTTP reverse proxy (typically with TLS 121 certificates) and the terms of service. 122 123 Installing the GNU Taler binary packages on Trisquel 124 ---------------------------------------------------- 125 126 .. include:: frags/installing-trisquel.rst 127 128 Installing the GNU Taler binary packages on Ubuntu 129 -------------------------------------------------- 130 131 .. include:: frags/installing-ubuntu.rst 132 133 To install the Taler exchange, you can now simply run: 134 135 .. code-block:: shell-session 136 137 # apt install taler-directory 138 139 Note that the package does not perform any configuration work except for 140 setting up the various users and the systemd service scripts. You still must 141 configure at least the database, HTTP reverse proxy (typically with TLS 142 certificates), and the terms of service. 143 144 145 Services, users, groups and file system hierarchy 146 ------------------------------------------------- 147 148 The *taler-directory* package will use several system users 149 to compartmentalize different parts of the system: 150 151 * ``taldir-httpd``: runs the HTTP daemon with the core business logic. 152 * ``postgres``: runs the PostgreSQL database (from *postgresql* package). 153 * ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package). 154 155 The package will deploy a systemd service files in 156 ``/usr/lib/systemd/system/`` for taler-directory: 157 158 * ``taler-directory.service``: the business logic with the public REST API. 159 160 161 Configuration Fundamentals 162 ========================== 163 164 This chapter provides fundamental details about the exchange configuration. 165 166 The configuration for all Taler components uses a single configuration file 167 as entry point: ``/etc/taldir/taldir.conf``. 168 169 System defaults are automatically loaded from files in 170 ``/usr/share/taldir/config.d``. These default files should never be modified. 171 172 The default configuration ``taldir.conf`` configuration file also includes all 173 configuration files in ``/etc/taldir/conf.d``. 174 175 To view the entire configuration annotated with the source of each configuration option, you 176 can use the ``taldir-config`` helper: 177 178 179 .. code-block:: shell-session 180 181 [root@exchange-online]# taler-directory-config --help 182 183 .. include:: frags/configuration-format.rst 184 185 186 Fundamental Setup: Address validation 187 ------------------------------------- 188 189 The service is designed to validate aliases. Possible 190 alias types include: 191 192 * phone numbers (via SMS) 193 * e-mail addresses (via SMTP) 194 195 In principle, additional types of addresses can easily be added by extending 196 the respective HTML and programs to send challenges to the new address type. 197 198 To make different types of address validations possible, the Challenger 199 configuration contains two configuration options. 200 201 (1) The ``ADDRESS_TYPE`` configuration option informs Challenger about the 202 type of address it is expected to validate. It is returned as part of 203 the OAuth 2.0 ``/info`` endpoint to the client, and is typically also 204 used when deciding how to render the HTML form for address entry that is 205 shown to the user. 206 207 (2) The ``AUTH_COMMAND`` configuration option specifies which command 208 Challenger should run to send a challenge to an address. The actual 209 address is given to this subcommand as the first argument (``$1``), 210 while the text with the challenge is passed to standard input. 211 The subcommand should terminate with a status code of 0 on success. 212 213 .. code-block:: ini 214 :caption: /etc/taldir/taldir.conf 215 216 [challenger] 217 ADDRESS_TYPE = email 218 AUTH_COMMAND = challenger-send-email.sh 219 # ... rest of file ... 220 221 Challenger comes with ``AUTH_COMMAND`` shell scripts for sending e-mail, SMS 222 and postal mail. Note that for SMS and postal mail the Challenger scripts uses 223 third party services to actually send the SMS or print and mail the postal 224 mail. These third parties naturally charge money for their services, and thus 225 the Challenger administrator will need to add the respective credentials to 226 the SMS and postal mail scripts before they can function. In any case, these 227 scripts should be primarily seen as *examples* on how to write authentication 228 commands. 229 230 .. note:: 231 232 We strongly welcome contributions for additional scripts with alternative 233 providers or for new types of addresses.