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