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