65d32bc823e1a2c402da4c182627aecee399ee96
[cacert-infradocs.git] / docs / systems / email.rst
1 .. index::
2 single: Systems; Email
3
4 =====
5 Email
6 =====
7
8 Purpose
9 =======
10
11 This system handles email for @cacert.org addresses. It also provides users of
12 @cacert.org with IMAPs and POP3s access to their accounts.
13
14 The database on this container is used by :doc:`webmail` too.
15
16 Administration
17 ==============
18
19 System Administration
20 ---------------------
21
22 * Primary: :ref:`people_jselzer`
23 * Secondary: :ref:`people_jandd`
24
25 Contact
26 -------
27
28 * email-admin@cacert.org
29
30 Additional People
31 -----------------
32
33 :ref:`people_mario` has :program:`sudo` access on that machine too.
34
35 Basics
36 ======
37
38 Physical Location
39 -----------------
40
41 This system is located in an :term:`LXC` container on physical machine
42 :doc:`infra02`.
43
44 Logical Location
45 ----------------
46
47 :IP Internet: :ip:v4:`213.154.225.228`
48 :IP Intranet: :ip:v4:`172.16.2.19`
49 :IP Internal: :ip:v4:`10.0.0.19`
50 :IPv6: :ip:v6:`2001:7b8:616:162:2::19`
51 :MAC address: :mac:`00:ff:8f:e0:4a:90` (eth0)
52
53 .. seealso::
54
55 See :doc:`../network`
56
57 Monitoring
58 ----------
59
60 :internal checks: :monitor:`email.infra.cacert.org`
61
62 DNS
63 ---
64
65 .. index::
66 single: DNS records; Email
67
68 ======================= ======== ============================================
69 Name Type Content
70 ======================= ======== ============================================
71 email.cacert.org. IN A 213.154.225.228
72 email.cacert.org. IN SSHFP 1 1 BF391FD72656A275524D1D25A624C6045B44AE90
73 email.cacert.org. IN SSHFP 2 1 73B0D8ACB492A7187016DD3C5FC1519B309A550F
74 email.intra.cacert.org. IN A 172.16.2.19
75 ======================= ======== ============================================
76
77 A DKIM record for cacert.org ist setup but no DKIM signing is active currently.
78
79 .. todo:: setup DKIM properly, see :bug:`696` for an older discussion
80
81 .. todo:: setup SPF records when the system is ready, see :bug:`492` for an
82 older discussion
83
84 .. seealso::
85
86 See :wiki:`SystemAdministration/Procedures/DNSChanges`
87
88 Operating System
89 ----------------
90
91 .. index::
92 single: Debian GNU/Linux; Lenny
93 single: Debian GNU/Linux; 5.0.10
94
95 * Debian GNU/Linux 5.0.10
96
97 Applicable Documentation
98 ------------------------
99
100 This is it :-)
101
102 Services
103 ========
104
105 Listening services
106 ------------------
107
108 +----------+---------+----------------+----------------------------------------+
109 | Port | Service | Origin | Purpose |
110 +==========+=========+================+========================================+
111 | 22/tcp | ssh | ANY | admin console access |
112 +----------+---------+----------------+----------------------------------------+
113 | 25/tcp | smtp | ANY | mail receiver for cacert.org |
114 +----------+---------+----------------+----------------------------------------+
115 | 110/tcp | pop3 | ANY | POP3 access for cacert.org mail |
116 | | | | addresses |
117 +----------+---------+----------------+----------------------------------------+
118 | 143/tcp | imap | ANY | IMAP access for cacert.org mail |
119 | | | | addresses |
120 +----------+---------+----------------+----------------------------------------+
121 | 465/tcp | smtps | ANY | SMTPS for cacert.org mail addresses |
122 +----------+---------+----------------+----------------------------------------+
123 | 587/tcp | smtp | ANY | mail submission for cacert.org mail |
124 | | | | addresses |
125 +----------+---------+----------------+----------------------------------------+
126 | 993/tcp | imaps | ANY | IMAPS access for cacert.org mail |
127 | | | | addresses |
128 +----------+---------+----------------+----------------------------------------+
129 | 995/tcp | pop3s | ANY | POP3S access for cacert.org mail |
130 | | | | addresses |
131 +----------+---------+----------------+----------------------------------------+
132 | 2000/tcp | sieve | ANY | Manage sieve access for cacert.org |
133 | | | | mail addresses |
134 +----------+---------+----------------+----------------------------------------+
135 | 2001/tcp | sieve | :doc:`webmail` | Manage sieve access for cacert.org |
136 | | | | mail addresses without TLS, accessible |
137 | | | | from ``172.16.2.20`` only |
138 +----------+---------+----------------+----------------------------------------+
139 | 3306/tcp | mysql | local | MySQL database server |
140 +----------+---------+----------------+----------------------------------------+
141 | 4433/tcp | http | local | Apache httpd with phpmyadmin |
142 +----------+---------+----------------+----------------------------------------+
143 | 5666/tcp | nrpe | monitor | remote monitoring service |
144 +----------+---------+----------------+----------------------------------------+
145
146 .. topic:: PHPMyAdmin access
147
148 Administrators can use ssh to forward the Apache httpd HTTPS port to their
149 own machine:
150
151 .. code-block:: bash
152
153 ssh -L 4433:localhost:4433 -l username email.cacert.org
154
155 and access PHPMyAdmin at https://localhost:4433/
156
157 Running services
158 ----------------
159
160 .. index::
161 single: apache httpd
162 single: cron
163 single: dovecot
164 single: mysql
165 single: nrpe
166 single: openssh
167 single: postfix
168 single: pysieved
169 single: rsyslog
170 single: xinetd
171
172 +--------------------+---------------------+----------------------------------------+
173 | Service | Usage | Start mechanism |
174 +====================+=====================+========================================+
175 | Apache httpd | Webserver for | init script |
176 | | phpmyadmin | :file:`/etc/init.d/apache2` |
177 +--------------------+---------------------+----------------------------------------+
178 | cron | job scheduler | init script :file:`/etc/init.d/cron` |
179 +--------------------+---------------------+----------------------------------------+
180 | dovecot | IMAP(s) and POP3(s) | init script |
181 | | daemon | :file:`/etc/init.d/dovecot` |
182 +--------------------+---------------------+----------------------------------------+
183 | MySQL | MySQL database | init script |
184 | | server for email | :file:`/etc/init.d/mysql` |
185 | | services | |
186 +--------------------+---------------------+----------------------------------------+
187 | Nagios NRPE server | remote monitoring | init script |
188 | | service queried by | :file:`/etc/init.d/nagios-nrpe-server` |
189 | | :doc:`monitor` | |
190 +--------------------+---------------------+----------------------------------------+
191 | openssh server | ssh daemon for | init script :file:`/etc/init.d/ssh` |
192 | | remote | |
193 | | administration | |
194 +--------------------+---------------------+----------------------------------------+
195 | Postfix | SMTP server for | init script |
196 | | cacert.org | :file:`/etc/init.d/postfix` |
197 +--------------------+---------------------+----------------------------------------+
198 | rsyslog | syslog daemon | init script |
199 | | | :file:`/etc/init.d/syslog` |
200 +--------------------+---------------------+----------------------------------------+
201 | xinetd | socket listener | init script |
202 | | for pysieved | :file:`/etc/init.d/xinetd` |
203 +--------------------+---------------------+----------------------------------------+
204
205 Databases
206 ---------
207
208 +-------+----------------+----------------------------------+
209 | RDBMS | Name | Used for |
210 +=======+================+==================================+
211 | MySQL | cacertusers | database for dovecot and postfix |
212 +-------+----------------+----------------------------------+
213 | MySQL | postfixpolicyd | empty database |
214 +-------+----------------+----------------------------------+
215 | MySQL | roundcubemail | roundcube on :doc:`webmail` |
216 +-------+----------------+----------------------------------+
217
218 .. todo:: check whether the empty postfixpolicyd database is required
219
220 Connected Systems
221 -----------------
222
223 * :doc:`monitor`
224 * :doc:`webmail`
225 * all @cacert.org address owners have access to POP3 (STARTTLS and POP3S), IMAP
226 (STARTTLS and IMAPS), SMTPS, SMTP submission (STARTTLS) and manage sieve
227
228 Outbound network connections
229 ----------------------------
230
231 * DNS (53) resolving nameservers 172.16.2.2 and 172.16.2.3
232 * :doc:`proxyout` as HTTP proxy for APT
233 * :doc:`issue` for OTRS mail
234 * :doc:`lists` for mailing lists
235 * arbitrary Internet SMTP servers for outgoing mail
236
237 Security
238 ========
239
240 .. sshkeys::
241 :RSA: SHA256:yLaPPrmoOQI5G3hoa0iFoxf6wPdLBJCnizLsu+6SHfE MD5:a1:d2:17:53:6b:0f:b6:a4:14:13:46:f7:04:ef:4a:23
242 :DSA: SHA256:zY4YEmiCYrbDXK1FHum9Qw8cKAInnizrbODF8o2ofEU MD5:f4:eb:0a:36:40:1c:55:6b:75:a2:26:34:ea:18:7e:91
243
244 .. warning::
245
246 The system is too old to support ECDSA or ED25519 keys.
247
248 Non-distribution packages and modifications
249 -------------------------------------------
250
251 Tlslite in :file:`/usr/local/lib/tlslite-0.3.8/` has been patched to handle
252 GeneratorExit exceptions. The original tlslite 0.3.8 is stored in
253 :file:`/usr/local/lib/tlslite-0.3.8-orig/`.
254
255 Pysieved in :file:`/usr/local/lib/pysieved.neale/` seems to be a git clone from
256 2009 originating from http://woozle.org/~neale/repos/pysieved at commit
257 ``d9b67036387a9a7aca954a17ff6fec44a8d309e0`` with no local modifications.
258
259 :file:`/usr/local/lib/pysieved` is a symbolic link to
260 :file:`/usr/local/lib/pysieved.neale/`.
261
262 .. todo:: use pysieved, python-tlslite and dovecot-sieve from distribution
263 packages after OS upgrade
264
265
266 Risk assessments on critical packages
267 -------------------------------------
268
269 The whole system is outdated, it needs to be replaced as soon as possible.
270
271 Critical Configuration items
272 ============================
273
274 Keys and X.509 certificates
275 ---------------------------
276
277 Server certificate for SMTP communication from the Internet and PHPMyAdmin.
278
279 .. sslcert:: email.cacert.org
280 :altnames: DNS:email.cacert.org
281 :certfile: /etc/ssl/certs/ssl-cert-email-cacert.pem
282 :keyfile: /etc/ssl/private/ssl-cert-email-cacert.key
283 :serial: 1381FA
284 :expiration: Mar 16 11:23:55 2020 GMT
285 :sha1fp: 3A:EC:11:D0:78:6C:99:34:F2:45:A5:DF:08:90:94:1F:67:2C:6F:47
286 :issuer: CA Cert Signing Authority
287
288 Server certificate for community email services (SMTPS, SMTP submission in
289 Postfix and IMAP with STARTTLS, IMAPS, POP3 with STARTTLS, POP3S and pysieved)
290
291 .. sslcert:: community.cacert.org
292 :certfile: /etc/ssl/certs/ssl-cert-community-cacert.pem
293 :keyfile: /etc/ssl/private/ssl-cert-community-cacert.key
294 :serial: 1381F8
295 :secondary:
296
297 * :file:`/etc/postfix/dh_1024.pem` and :file:`/etc/postfix/dh_512.pem`
298 Diffie-Hellman parameter files for Postfix
299
300 .. note::
301
302 Postfix uses the email.cacert.org certificate for client authentication if
303 requested by a target server.
304
305 .. todo::
306 check whether it makes sense to use a separate certificate for that
307 purpose
308
309 .. seealso::
310
311 * :wiki:`SystemAdministration/CertificateList`
312
313 .. index::
314 pair: Apache httpd; configuration
315
316 Apache httpd configuration
317 --------------------------
318
319 :file:`/etc/apache2/sites-available/adminssl` configures a VirtualHost that
320 allows dedicated users to access a PHPMyAdmin instance. The allowed users are
321 authenticated by client certificates and are authorized by an entry in
322 :file:`/etc/apache2/phpmyadmin.passwd`.
323
324 .. note::
325
326 to authorize a user you need the subject distinguished name of the user's
327 client certificate which can be extracted with::
328
329 openssl x509 -noout -subject -in certificate.crt
330
331 A line with the subject distinguished name and the fake password
332 ``xxj31ZMTZzkVA`` separated by colon have to be added to
333 :file:`/etc/apache2/phpmyadmin.passwd`::
334
335 /CN=Example User/emailAddress=example@cacert.org:xxj31ZMTZzkVA
336
337 .. seealso::
338
339 FakeBasicAuth option of the `SSLOptions
340 <https://httpd.apache.org/docs/2.2/mod/mod_ssl.html#ssloptions>`_
341 directive in the mod_ssl reference documentation.
342
343 .. index::
344 pair: MySQL; configuration
345
346 MySQL configuration
347 -------------------
348
349 MySQL configuration is stored in the :file:`/etc/mysql/` directory.
350
351 .. index::
352 pair: MySQL; NSS
353 single: libnss-mysql
354
355 .. _nss:
356
357 NSS configuration
358 -----------------
359
360 The libc name service switch is configured to use MySQL lookups for passwd,
361 group and shadow via :file:`/etc/nsswitch.conf`. The queries are configured in
362 :file:`/etc/libnss-mysql.cfg` and the root user for reading shadow information
363 is configured in :file:`/etc/libnss-mysql-root.cfg`.
364
365 .. index::
366 pair: PHPMyAdmin; configuration
367
368 PHPMyAdmin configuration
369 ------------------------
370
371 PHPMyAdmin configuration is stored in the :file:`/etc/phpmyadmin/` directory.
372
373 .. index::
374 pair: dovecot; configuration
375
376 Dovecot configuration
377 ---------------------
378
379 Dovecot configuration is stored in the :file:`/etc/dovecot/` directory. The
380 database settings are stored in
381 :file:`dovecot-sql-masterpassword-webmail.conf`.
382
383 .. index::
384 pair: dovecot; authentication
385
386 .. topic:: Dovecot authentication
387
388 :file:`/etc/dovecot/dovecot.conf` refers to PAM mail. PAM mail is defined
389 :file:`/etc/pam.d/mail`. System users are defined by NSS which is a
390 combination of :file:`/etc/passwd` (for root and non-imap/pop users) and
391 :file:`/etc/libnss-mysql*` (see `nss`_).
392
393 There is a special master password so that webmail can do the authentication
394 for dovecot using certificates. This is defined in
395 :file:`/etc/dovecot/dovecot-sql-masterpassword-webmail.conf`. This special
396 password is restricted to the IP address of Community.
397
398 .. index::
399 pair: Postfix; configuration
400
401 Postfix configuration
402 ---------------------
403
404 Postfix configuration is stored in the :file:`/etc/postfix/` directory. The
405 following files are special for this setup:
406
407 +----------------+-------------------------------------------------------------+
408 | File | Used for |
409 +================+=============================================================+
410 | arbitration | rewrite recipients matching specific regular expressions to |
411 | | support+deletedaccounts@cacert.org and |
412 | | support@issue.cacert.org |
413 +----------------+-------------------------------------------------------------+
414 | cacert-inc-bcc | used as recipient_bcc_maps for specific functional mail |
415 | | addresses |
416 +----------------+-------------------------------------------------------------+
417 | main.cf | the main configuration file |
418 +----------------+-------------------------------------------------------------+
419 | master.cf | adds configuration for the community SMTPS and SMTP |
420 | | submission transports |
421 +----------------+-------------------------------------------------------------+
422 | mysql-\*.cf | configuration of several MySQL queries for alias mapping, |
423 | | Postfix operates on views for the user table |
424 +----------------+-------------------------------------------------------------+
425 | transport | forward email for lists.cacert.org to :doc:`lists` and for |
426 | | issue.cacert.org to :doc:`issue` |
427 +----------------+-------------------------------------------------------------+
428
429 .. todo:: consider to send all outgoing mail via :doc:`emailout`
430
431 .. todo:: remove unused transports from :file:`master.cf`
432
433 .. index::
434 pair: pysieved; configuration
435
436 PySieved configuration
437 ----------------------
438
439 :file:`/usr/local/etc/pysieved.ini` for regular manage sieve access and
440 :file:`/usr/local/etc/pysieved-notls.ini` for use with Roundcube webmail.
441 Pysieved uses dovecot for authentication.
442
443 .. index::
444 pair: rsyslog; configuration
445
446 Rsyslog configuration
447 ---------------------
448
449 Rsyslog is configured in :file:`/etc/rsyslog.conf` which includes files in
450 :file:`/etc/rsyslog.d/`. Consumption of kernel log messages and network input
451 is disabled. :file:`/etc/rsyslog.d/postfix.conf` configures a separate unix
452 socket to receive log messages from postfix and
453 :file:`/etc/rsyslog.d/remotelog.conf` contains commented settings for a
454 non-existant remote syslog server.
455
456 .. todo:: setup remote logging when a central logging container is available
457
458 .. index::
459 pair: xinetd; configuration
460
461 Xinetd configuration
462 --------------------
463
464 Xinetd listens on tcp ports 2000 and 2001 and spawn pysieved. Configuration for
465 these listeners is stored in :file:`/etc/xinetd.d/pysieved` and
466 :file:`/etc/xinetd.d/pysieved-notls`.
467
468 Email storage
469 -------------
470
471 Mail for :samp:`{user}` is stored in :samp:`/home/{user}/Maildir`.
472
473 .. todo::
474 move mail storage to a separate data volume to allow easier backup and OS
475 upgrades
476
477 Tasks
478 =====
479
480 .. index::
481 single: add email users
482
483 Adding email users
484 ------------------
485
486 1. create user in the database table ``cacertusers.user``:
487
488 .. code-block:: bash
489
490 mysql -p cacertusers
491
492 .. code-block:: sql
493
494 INSERT INTO user (username, fullnamealias, realname, password)
495 VALUES ('user', 'user.name', 'User Name', '$1$salt$passwordhash')
496
497 2. create the user's home directory and Maildir:
498
499 :samp:`install -o {user} -g {user} -m 0755 -d /home/{user}/Maildir`
500
501 .. note::
502
503 * a valid password hash for the password ``secret`` is
504 ``$1$caea3837$gPafod/Do/8Jj5M9HehhM.``
505 * users can reset their password via
506 https://community.cacert.org/password.php on :doc:`webmail`
507 * use the :download:`mail template
508 <../downloads/template_new_community_mailaddress.rfc822>` to send out to a
509 user's non-cacert.org mail account and make sure to encrypt the mail to a
510 known public key of that user
511
512 .. todo::
513 implement tooling to automate password salt generation and user creation
514
515 Setting up mail aliases
516 -----------------------
517
518 There are two types of aliases.
519
520 1. The first type are those that are never sent from. e.g.
521 postmaster@cacert.org. All these aliases are defined in
522 :file:`/etc/aliases`. Don't forget to run
523
524 .. code-block:: bash
525
526 postalias /etc/aliases
527
528 after any changes. Aliases for issue tracking are installed here as
529 :samp:`{issuetrackingaddress} : {issuetrackingaddress}@issue.cacert.org`.
530
531 2. The second type are those aliases that are used to send email too, e.g
532 pr@cacert.org. These aliases are recorded in the aliases table on the
533 cacertusers database. The reason for this implementation is to only allow
534 the designated person to send email from this email address.
535
536 Planned
537 -------
538
539 .. todo:: switch to Puppet management
540 .. todo:: replace nrpe with icinga2 agent
541 .. todo:: update to Debian 6/7/8/9/10
542 .. todo:: implement CRL checking
543 .. todo:: setup IPv6
544
545 .. todo::
546 throttle brute force attack attempts using fail2ban or similar mechanism
547
548 .. todo::
549 consider to use LDAP to consolidate user, password and email information
550
551 * there were plans for X.509 certificate authentication for mail services, but
552 there is no progress so far
553
554 Changes
555 =======
556
557 System Future
558 -------------
559
560 .. todo::
561 The system has to be replaced with a new system using a current operating
562 system version
563
564 Additional documentation
565 ========================
566
567 .. seealso::
568
569 * :wiki:`PostfixConfiguration`
570 * :wiki:`SystemAdministration/Systems/Email` for some discussion on legal
571 implications related to mail archiving
572
573 References
574 ----------
575
576 Postfix documentation
577 http://www.postfix.org/documentation.html
578 Postfix Debian wiki page
579 https://wiki.debian.org/Postfix
580 Dovecot 1.x wiki
581 http://wiki1.dovecot.org/FrontPage