2 title: Documentation for server-admins
5 {% include docs-head.md version=4.0 %}
12 You can install schleuder either from Linux distribution packages or rubygems. Currently there are supported distribution packages for Debian ("buster" and above), CentOS 7 and Archlinux (via AUR). If you use one of the directly supported platforms, you should choose the packages over the gems.
15 Don't use the packages provided by Ubuntu in all releases up to and including 17.10, they are severely outdated. On Ubuntu 18.04 only use the package if it has at least version 3.2.2.
17 Besides schleuder you should also install at least one of [schleuder-cli](https://0xacab.org/schleuder/schleuder-cli) (the command line tool to manage Schleuder lists), and [schleuder-web](https://0xacab.org/schleuder/schleuder-web) (the web interface to manage and maintain Schleuder lists).
19 Additionally we recommend running an entropy source such as `haveged`. This ensures Schleuder won't be blocked by lacking entropy, which otherwise might happen e.g. during key generation.
24 The step needs root privileges
26 We maintain schleuder and schleuder-cli in "buster" and above. (For production usage we recommend Debian "buster".)
27 To install the packages
29 apt-get install schleuder schleuder-cli
31 Running `schleuder install` afterwards isn't necessary, the package takes care of it.
35 For CentOS 7 there is a maintained [copr-repository](https://copr.fedorainfracloud.org/coprs/schleuder/schleuder/) using [Software Collections](https://www.softwarecollections.org/en/).
38 All steps need root privileges
40 Install the repository & the SCL repository
42 yum install centos-release-scl
43 curl -o /etc/yum.repos.d/schleuder-schleuder-epel-7.repo https://copr.fedorainfracloud.org/coprs/schleuder/schleuder/repo/epel-7/schleuder-schleuder-epel-7.repo
45 Now you are ready to install schleuder and schleuder-cli
47 yum install schleuder schleuder-cli
49 Afterwards run `schleuder install` to finalize the setup of Schleuder. This creates necessary directories, copies example configs, etc. If you see errors about missing write permissions please follow the advice given.
52 The copr-repository also provides you with a package for [schleuder-web](https://0xacab.org/schleuder/schleuder-web/). Please read the documentation of schleuder-web on how to get it up and running.
56 For archlinux there are the [AUR](https://wiki.archlinux.org/title/Arch_User_Repository) packages for [schleuder](https://aur.archlinux.org/packages/schleuder/) and [schleuder-cli](https://aur.archlinux.org/packages/schleuder-cli/).
58 See the [official AUR documentation](https://wiki.archlinux.org/title/Arch_User_Repository#Installing_and_upgrading_packages) on how to install AUR packages or use one of the many available [AUR helpers](https://wiki.archlinux.org/title/AUR_helpers) to manage AUR dependencies.
60 Once you have installed the `schleuder` package you need to run `schleuder install` as the created schleuder system user. See also the [schleuder wiki page](https://wiki.archlinux.org/title/Schleuder) for information about installation and configuration.
64 For instructions on how to install from rubygems please see the [README](https://0xacab.org/schleuder/schleuder/blob/main/README.md#installing-schleuder) of Schleuder.
69 To ease the installation and configuration of schleuder, schleuder-cli and schleuder-web, and to help with the creation and deletion of lists, you can rely either on...
71 * an [ansible role](https://github.com/systemli/ansible-role-schleuder), which works for Debian, or
73 * a [puppet module](https://0xacab.org/schleuder/puppet-schleuder). Currently it works for CentOS 7, but we would like to make it work for Debian as well - help would be highly appreciated.
78 Schleuder reads its **basic settings** from a file that it by default expects at `/etc/schleuder/schleuder.yml`. To make Schleuder read a different file set the environment variable `SCHLEUDER_CONFIG` to the path to your file when running schleuder. E.g.:
80 SCHLEUDER_CONFIG=/usr/local/etc/schleuder.yml /path/to/bin/schleuder ...
82 For explanations of the possible settings read the default config file (also [available in the repository](https://0xacab.org/schleuder/schleuder/blob/main/etc/schleuder.yml)).
84 The **default settings for new lists** are read from another config file. By default Schleuder looks at `/etc/schleuder/list-defaults.yml`. To make Schleuder read a different file set the environment variable `SCHLEUDER_LIST_DEFAULTS` analogous to above. The possible settings are explained in the default config file, which is [also available in the repository](https://0xacab.org/schleuder/schleuder/blob/main/etc/list-defaults.yml).
86 Once a list is created, it is not affected by these configuration files any more. Existing lists have their configuration stored in the database. The settings in the database can be shown and set via the schleuder API, available through schleuder-web or schleuder-cli. Run `schleuder-cli lists help` and `schleuder-cli lists list-options` for more information on the latter.
88 ### Hook into Mail Transport Agent
90 In "work"-mode, Schleuder expects the list's email-address as second argument (first one is "work") and the incoming email on standard-input.
92 To enable Schleuder to receive emails, your Mail Transport Agent must be configured accordingly. How to do this with Postfix is documented in detail below.
97 This section describes only those parts of a Postfix-setup that are relevant to Schleuder. We assume that you have a sensible and tested Postfix-setup already.
99 Firstly, to hook Schleuder into Postfix adapt these lines (path and maybe user) and add them to `master.cf`:
101 schleuder unix - n n - - pipe
102 flags=DRhu user=schleuder argv=/path/to/bin/schleuder work ${recipient}
104 Then you have to chose how postfix should decide if a message should be delivered to Schleuder. There are two options:
106 1. Configure it for each list individually. That's the way to go if you don't run many lists, or use the respective domain also for a varying number of email accounts or aliases.
107 2. Dedicate a whole domain to Schleuder. That's the way to go if you run more lists than email accounts or aliases on that domain.
110 **To configure each list individually,** add these lines to `main.cf`:
112 schleuder_destination_recipient_limit = 1
113 transport_maps = hash:/etc/postfix/transport_schleuder
115 Now adapt the following lines for each list and add them to `/etc/postfix/transport_schleuder`:
117 foo@example.org schleuder:
118 foo-request@example.org schleuder:
119 foo-owner@example.org schleuder:
120 foo-bounce@example.org schleuder:
121 foo-sendkey@example.org schleuder:
123 Afterwards run `postmap /etc/postfix/transport_schleuder` and restart postfix. Remember to repeat this also for newly created lists later.
126 Another way to tell postfix which domain and list can be piped to schleuder is to get that information out of the sqlite database. A requirement for that is the postfix-sqlite package, which isn't in the standard repositories of CentOS, but Debian.
128 **To dedicate a whole domain to Schleuder,** add these lines to `main.cf`:
130 schleuder_destination_recipient_limit = 1
131 virtual_mailbox_domains = sqlite:/etc/postfix/schleuder_domain_sqlite.cf
132 virtual_transport = schleuder
133 virtual_alias_maps = hash:/etc/postfix/virtual_aliases
134 virtual_mailbox_maps = sqlite:/etc/postfix/schleuder_list_sqlite.cf
136 Then adapt and add at least the following exceptions from the All-to-Schleuder-rule to `/etc/postfix/virtual_aliases`:
138 postmaster@lists.example.org root@anotherdomain
139 abuse@lists.example.org root@anotherdomain
140 MAILER-DAEMON@lists.example.org root@anotherdomain
141 root@lists.example.org root@anotherdomain
143 Afterwards run `postmap /etc/postfix/virtual_aliases`.
145 The file `schleuder_domain_sqlite.cf` can ask the schleuder sqlite database (this will delegate the whole domain to schleuder):
147 dbpath = /var/lib/schleuder/db.sqlite
148 query = select distinct substr(email, instr(email, '@') + 1) from lists
149 where email like '%%%s'
151 And the file `schleuder_list_sqlite.cf` can also get the information from the schleuder sqlite database:
153 dbpath = /var/lib/schleuder/db.sqlite
154 query = select 'present' from lists
156 or email = replace('%s', '-bounce@', '@')
157 or email = replace('%s', '-owner@', '@')
158 or email = replace('%s', '-request@', '@')
159 or email = replace('%s', '-sendkey@', '@')
161 From now on each Schleuder-list will instantly be reachable by email once it was created.
166 This section describes only those parts of a Exim-setup that are relevant to Schleuder. We assume that you have a sensible and tested Exim-setup already.
168 As with any exim email routing, we need to configure essentially a router that accepts and directs a mail to a transport, which knows how to hand-over an email to schleuder.
170 Within the `begin routers` section of your `exim.conf` you can add the following router:
174 address_data = ${lookup sqlite,file=/var/lib/schleuder/db.sqlite {select email from lists where email = '${quote_sqlite:${local_part}@${domain}}'} {$value} fail}
175 local_part_suffix_optional
176 local_part_suffix = +* : -bounce : -sendkey : -request : -owner
177 transport = mlschleuder_transport_local
179 This router will look directly in schleuder’s sqlite file to check if the given recipient is a legitimate list’s email address. For this to work, exim needs to be able to read that file. One approach to achieve this is to add the user exim is running as to the group the file belongs to and make the file group-readable. For Debian the following commands will achieve that:
181 adduser Debian-exim schleuder
182 chmod g+r /var/lib/schleuder/db.sqlite
184 If that is not possible, you can instead add the following router:
188 require_files = /etc/exim/schleuder-lists
189 address_data = ${lookup {$local_part@$domain} lsearch,ret=key {/etc/exim/schleuder-lists} {$value} fail}
190 local_part_suffix_optional
191 local_part_suffix = +* : -bounce : -sendkey : -request : -owner
192 transport = mlschleuder_transport_local
194 `/etc/exim/schleuder-lists` is a simple textfile containing one list-address per line. You can for example create it by executing `schleuder-cli lists list > /etc/exim/schleuder-lists` after creating or deleting any lists.
196 In more advanced setups you might have different conditions depending on how you manage the inventory of your schleuder lists and decide to accept a mail for a list.
198 Within the `begin transports` section of your `exim.conf` you then configure the transport:
200 mlschleuder_transport_local:
204 # schleuders generates nice log messages for some of the problems
205 return_fail_output = true
206 home_directory = /var/lib/schleuder/lists/${domain:$address_data}/${local_part:$address_data}
207 command = "/usr/bin/schleuder work ${local_part:$address_data}${local_part_suffix}@${domain:$address_data}"
208 message_size_limit = 10M
210 Please note that we keep the `$local_part_suffix` when handing the mail over to schleuder, so schleuder can e.g. detect bounces or sendkey emails properly.
212 Restart exim and you have your working schleuder+exim setup.
214 Remember to repeat dumping the list of schleuder-lists to `/etc/exim/schleuder-lists` also for newly created lists later.
218 The Schleuder API is provided by `schleuder-api-daemon`. Configuration clients (schleuder-web, schleuder-cli) use it to access information about lists, subscriptions, and keys. As you probably want to at least use schleuder-cli from localhost, setting up schleuder-api-daemon is useful even without remote clients.
221 Schleuder does **not** use schleuder-api-daemon to process emails. You can stop schleuder-api-daemon at any time without breaking the email flow.
223 To run `schleuder-api-daemon`, depending on the type of operating system and the setup you are using, you can either start the systemd-unit-file:
225 systemctl start schleuder-api-daemon
227 Or you can run it manually in a shell:
232 Please take care to run `schleuder-api-daemon` as the user that owns the directory of schleuder lists (by default `/var/lib/schleuder/lists`) to avoid running into file permission problems!
234 #### Transport encryption
236 schleuder-api-daemon uses transport encryption (TLS) for all connections. The required TLS-certifcates should have been generated during the setup (`schleuder install`). You can generate new ones at any time by executing:
238 schleuder cert generate
240 If the file systems permissions allow it, Schleuder will write the certificate and the key directly into the correct files (paths are read from the configuration file). Otherwise you might have to move them. Please read the output of the above command for possible instructions.
242 In case you already have a suitable certificate you can use that, too. Its hostnames do not matter. Just copy it to the paths specified in the configuration file, or change those paths.
244 In order to verify the connection, each client needs to know the fingerprint of the API-certificate. The fingerprint will be shown when generating the certificates. Later you can always have it show again by executing this:
246 schleuder cert fingerprint
249 Use secure channels to transport this information!
253 The Schleuder API uses API-keys to authenticate clients.
255 You can generate new API-keys by executing:
257 schleuder new_api_key
259 To enable the client to connect, their API-key must be added to the section `valid_api_keys` in Schleuder's configuration file.
262 Provide each client with their own API-key, and use secure channels to transport this information!
265 There is **no authorization of clients,** yet. Each client is allowed every action. So be wary who to give an API-key to. schleuder-web does its own authorization, but schleuder-cli does not!
269 To create and manage lists you have two options: schleuder-web and schleuder-cli.
271 Both require a running `schleuder-api-daemon`. Please see [the previous section](#schleuder-api) on how to set that up.
276 To create lists with schleuder-web log in as `root@localhost`. Managing lists is allowed to each list-admin.
280 To use schleuder-cli please see the output of
287 Please take care to have the following commands run by the user that owns the directory of schleuder lists (by default `/var/lib/schleuder/lists`) to avoid running into file permission problems!
290 Schleuder can **check all keys** that are present in the list's keyrings for (upcoming) expiration dates, revocation, or other reasons for not being usable.
292 Call this command weekly from cron to automate the check and have the results sent to the respective list-admins:
297 Schleuder can also **refresh all keys** in the same manner. Each key of each list will be refreshed from a keyserver one by one. If you're using gpg 2.1, it's possible to configure a TOR onion service to be used as keyserver! See [the config](https://0xacab.org/schleuder/schleuder/blob/main/etc/schleuder.yml) for an example.
300 Call this command weekly from cron to automate the check and have the results sent to the respective list-admins:
302 schleuder refresh_keys
304 The available packages for Debian and CentOS both install a weekly cron job that check and refresh keys. Listadmins will be notified about issues with or changes to their keyring.
306 An additional maintenance command is available that allows you to pin subscriptions to their best matching key. If there is no key assigned, schleuder will try to select a key from the list's keyring that distinctly matches the subscription's email address.
308 This feature should be used with care. It's easy for a malicious (or inexperienced) person to inject additional user-IDs into the list's keyring. This can lead to situations in which people suddenly receive emails that are encrypted to a key they don't own.
310 You should better not run this command automatedly, and you should always examine the output closely to check for unintended consequences.
315 {% include participate.md %}