Merge pull request #4 from broedli/master

Added chapters, reworked some others.

docs/bl_wl.md

@@ -1,3 +1,5 @@
-Edit a domain as (domain) administrator to add an item to the filter table.
+To add or edit an entry to your **domain wide** filter table, login to your *mailcow UI* as (domain) administrator.
+
+![Black- and Whitelist configuration](images/bl_wl.png)
 
 Beware that a mailbox user can login to mailcow and override a domain policy filter item.

docs/debug.md

@@ -1,3 +1,5 @@
+## Logs
+
 You can use `docker-compose logs $service-name` for all containers.
 
 Run `docker-compose logs` for all logs at once.
@@ -5,3 +7,28 @@ Run `docker-compose logs` for all logs at once.
 Follow the log output by running docker-compose with `logs -f`.
 
 Limit the output by calling logs with `--tail=300` like `docker-compose logs --tail=300 mysql-mailcow`.
+
+## Reset admin password
+Reset mailcow admin to `admin:moohoo`:
+
+```
+cd mailcow_path
+bash mailcow-reset-admin.sh
+```
+
+## What container does what
+
+Here is a brief overview of what container does what:
+
+| Container Name  | Service Descriptions                                                      |
+| --------------- | ------------------------------------------------------------------------- |
+| bind9-mailcow   | Local (DNSSEC) DNS Resolver                                               |
+| mysql-mailcow   | Stores most of mailcow's settings                                         |
+| postfix-mailcow | Receives and sends mails                                                  |
+| dovecot-mailcow | User logins and sieve filter                                              |
+| redis-mailcow   | Storage backend for DKIM keys, Rmilter and Rspamd                         |
+| rspamd-mailcow  | Mail filtering system. Used for av handling, dkim signing, spam handling  |
+| rmilter-mailcow | Integrates Rspamd into postfix                                            |
+| clamd-mailcow   | Scans attachments for viruses                                             |
+| sogo-mailcow    | Webmail client that handles Microsoft ActiveSync and Cal- / CardDav       |
+| nginx-mailcow   | Nginx remote proxy that handles all mailcow related HTTP / HTTPS requests |

docs/dns.md

@@ -0,0 +1,78 @@
+Below you can find a list of **recommended DNS records**. While some are mandatory for a mail server (A, MX), others are recommended to build a good reputation score (TXT/SPF) or used for auto-configuration of mail clients (SRV).
+
+## References
+
+- A good article covering all relevant topics:
+  ["3 DNS Records Every Email Marketer Must Know"](https://www.rackaid.com/blog/email-dns-records)      
+- Another great one, but Zimbra as an example platform:
+  ["Best Practices on Email Protection: SPF, DKIM and DMARC"](https://wiki.zimbra.com/wiki/Best_Practices_on_Email_Protection:_SPF,_DKIM_and_DMARC)       
+- An in-depth discussion of SPF, DKIM and DMARC:
+  ["How to eliminate spam and protect your name with DMARC"](https://www.skelleton.net/2015/03/21/how-to-eliminate-spam-and-protect-your-name-with-dmarc/)
+
+## Reverse DNS of your IP
+
+Make sure that the PTR record of your IP matches the FQDN hostname of your mailcow host: `mail.domain.tld`. This record is usually set at the provider you leased the IP (server) from.
+
+## The minimal DNS configuration
+
+This example shows you a set of records for one domain managed by mailcow. Each domain that is added to mailcow needs at least this set or records to function correctly.
+
+```
+# Name              Type       Value
+mail                IN A       1.2.3.4
+autodiscover        IN A       1.2.3.4
+autoconfig          IN A       1.2.3.4
+
+@                   IN MX 10   mail
+```
+
+## DKIM, SPF and DMARC
+
+In the example DNS zone file snippet below, a simple **SPF** TXT record is used to only allow THIS server (the MX) to send mail for your domain. Every other server is disallowed but able to ("`~all`"). Please refer to [SPF Project](http://www.openspf.org).
+
+```
+@                   IN TXT     "v=spf1 mx ~all"
+```
+
+It is highly recommended to create a **DKIM** TXT record in your mailcow UI and set the corresponding TXT record in your DNS records. Please refer to [OpenDKIM](http://www.opendkim.org).
+
+```
+default._domainkey  IN TXT     "v=DKIM1; k=rsa; t=s; s=email; p=..."
+```
+
+The last step in protecting yourself and others is the implementation of a **DMARC** TXT record, for example by using the [DMARC Assistant](http://www.kitterman.com/dmarc/assistant.html) ([check](https://dmarcian.com/dmarc-inspector/google.com)).
+
+```
+_dmarc              IN TXT     "v=DMARC1; p=reject; rua=mailto:mailauth-reports@example.org"
+```
+
+## The advanced DNS configuration
+
+**SRV** records specify the server(s) for a specific protocol on your domain. If you want to explicitly announce a service as not provided, give "." as the target address (instead of "mail.example.tld."). Please refer to [RFC 2782](https://tools.ietf.org/html/rfc2782).
+
+```
+_imap._tcp          IN SRV     0 1 143 mail.example.org.
+_imaps._tcp         IN SRV     0 1 993 mail.example.org.
+_pop3._tcp          IN SRV     0 1 110 mail.example.org.
+_pop3s._tcp         IN SRV     0 1 995 mail.example.org.
+_submission._tcp    IN SRV     0 1 587 mail.example.org.
+_autoconfig._tcp    IN SRV     0 1 443 autoconfig.example.org.
+_autodiscover._tcp  IN SRV     0 1 443 autodiscover.example.org.
+```
+
+## Testing
+
+Here are some tools you can use to verify your DNS configuration:
+
+- [MX Toolbox](https://mxtoolbox.com/SuperTool.aspx) (DNS, SMTP, RBL)
+- [port25.com](https://www.port25.com/dkim-wizard/) (DKIM, SPF)
+- [HAD Pilot](https://www.had-pilot.com/testdetails.html) (DKIM, DMARC, SPF)
+- [DMARC Analyzer](https://www.dmarcanalyzer.com/spf-record-check/) (DMARC, SPF)
+
+## Misc
+
+If you are interested in statistics, you can additionally register with the [Postmaster Tool](https://gmail.com/postmaster)  by Google and supply a **google-site-verification** TXT record, which will give you details about spam-classified mails by your domain. This is clearly optional.
+
+```
+@                   IN TXT     "google-site-verification=..."
+```

docs/install.md

@@ -1,6 +1,3 @@
-!!! warning
-    Please use Ubuntu 16.04 instead of Debian 8 or [switch to the kernel 4.9 from jessie backports](https://packages.debian.org/jessie-backports/linux-image-amd64) because there is a bug (kernel panic) with the kernel 3.16 when running docker containers with healthchecks! Full details here: [github.com/docker/docker/issues/30402](https://github.com/docker/docker/issues/30402) and [forum.mailcow.email/t/solved-mailcow-docker-causes-kernel-panic-edit/448](https://forum.mailcow.email/t/solved-mailcow-docker-causes-kernel-panic-edit/448)
-
 You need Docker and Docker Compose.
 
 1\. Learn how to install [Docker](https://docs.docker.com/engine/installation/linux/) and [Docker Compose](https://docs.docker.com/compose/install/).
@@ -10,7 +7,7 @@ Quick installation for most operation systems:
 - Docker
 ```
 curl -sSL https://get.docker.com/ | sh
-``` 
+```
 
 - Docker-Compose
 ```

docs/mc14_import.md

@@ -0,0 +1,100 @@
+**WARNING** Please be adviced that this guide is a first draft. Mailcow: dockerized changed quite a lot on its DB configuration. It now uses the InnoDB file format `Barracuda` and the `utf8mb4` character set. There is also some change to the DB / TABLE structure.
+
+Also note that this guide doesn't touch on the users settings like *Spamlevels*, *TLS Settings*, etc. nor the export / import of your roundcube or SOGo settings.
+
+Lastly please check the section on how to [import / restore](backup_maildir/#restore) your maildir backup to get an idea how to migrate your mails.
+
+## Create mailcow db backups
+
+First you need to modify the table `mailcow`. Mailcow-dockerized adds three and moves two existing columns in the table `mailbox`. The columns `tls_enforce_in` and `tls_enforce_out` get moved two rows up (behind `domain`). The columns `key`, `multiple_bookings` and `wants_tagged_subject` need to be added after `tls_enforce_out`.
+
+It should look like this:
+
+```
+MariaDB [mailcow]> desc mailbox;
++----------------------+--------------+------+-----+-------------------+-----------------------------+
+| Field                | Type         | Null | Key | Default           | Extra                       |
++----------------------+--------------+------+-----+-------------------+-----------------------------+
+| username             | varchar(255) | NO   | PRI | NULL              |                             |
+| password             | varchar(255) | NO   |     | NULL              |                             |
+| name                 | varchar(255) | YES  |     | NULL              |                             |
+| maildir              | varchar(255) | NO   |     | NULL              |                             |
+| quota                | bigint(20)   | NO   |     | 0                 |                             |
+| local_part           | varchar(255) | NO   |     | NULL              |                             |
+| domain               | varchar(255) | NO   | MUL | NULL              |                             |
+| tls_enforce_in       | tinyint(1)   | NO   |     | 0                 |                             |
+| tls_enforce_out      | tinyint(1)   | NO   |     | 0                 |                             |
+| kind                 | varchar(100) | NO   |     |                   |                             |
+| multiple_bookings    | tinyint(1)   | NO   |     | 0                 |                             |
+| wants_tagged_subject | tinyint(1)   | NO   |     | 0                 |                             |
+| created              | datetime     | NO   |     | CURRENT_TIMESTAMP |                             |
+| modified             | datetime     | YES  |     | NULL              | on update CURRENT_TIMESTAMP |
+| active               | tinyint(1)   | NO   |     | 1                 |                             |
++----------------------+--------------+------+-----+-------------------+-----------------------------+
+```
+
+You can do this with a UI like [Adminer](https://www.adminer.org/#download) or use the MySQL CLI like :
+
+```
+MariaDB [mailcow]> ALTER TABLE mailbox MODIFY COLUMN tls_enforce_in TINYINT(1) NOT NULL DEFAULT '0' AFTER domain,
+MODIFY COLUMN tls_enforce_out TINYINT(1) NOT NULL DEFAULT '0' AFTER tls_enforce_in;
+MariaDB [mailcow]> ALTER TABLE mailbox ADD COLUMN `kind` VARCHAR(255) NOT NULL AFTER `tls_enforce_out`,
+ADD COLUMN `multiple_bookings` TINYINT(1) NOT NULL DEFAULT '0' AFTER `kind`,
+ADD COLUMN `wants_tagged_subject` TINYINT(1) NOT NULL DEFAULT '0' AFTER `multiple_bookings`;
+MariaDB [mailcow]> DESC mailbox;
+```
+
+When this is done we can backup the tables:
+
+```bash
+# Load your mysql variables into environment
+DBHOST=$(grep database_host /var/www/mail/inc/vars.inc.php | cut -d'"' -f2)
+DBNAME=$(grep database_name /var/www/mail/inc/vars.inc.php | cut -d'"' -f2)
+DBUSER=$(grep database_user /var/www/mail/inc/vars.inc.php | cut -d'"' -f2)
+DBPASS=$(grep database_pass /var/www/mail/inc/vars.inc.php | cut -d'"' -f2)
+
+# Backup your tables
+mysqldump --replace --no-create-info --default-character-set=utf8mb4 \
+    --host &{DBHOST}-u${DBUSER} -p${DBPASS} ${DBNAME} \
+    alias alias_domain domain domain_admins mailbox quota2 sender_acl > backup_mailcow.sql
+```
+
+- **--replace**: Write `REPLACE` statements rather than `INSERT` statements
+- **--no-create-info**: Don't write `CREATE TABLE` statements.
+- **--default-character-set** make sure our exported default charset is *utf8mb4*.
+
+
+## Prepare mailcow: dockerized
+
+To initiate your fresh installed database, visit **https://${MAILCOW_HOSTNAME}** with a browser of your choice. Check if the DB is initiated correctly afterwards:
+
+```
+# source mailcow.conf
+# docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME}
+MariaDB [mailcow]> show tables;
++-------------------------------+
+| Tables_in_mailcow             |
++-------------------------------+
+| admin                         |
+| alias                         |
+[...]
+```
+
+## Import your backups:
+
+  ```
+  # source mailcow.conf
+  # docker exec -i $(docker-compose ps -q mysql-mailcow) mysql -u${DBUSER} -p${DBPASS} ${DBNAME} < backup_mailcow.sql
+  ```
+
+  Recalculate used quota with `doveadm`:
+
+  ```
+  # docker-compose exec dovecot-mailcow doveadm quota recalc -A
+  ```
+
+  Restart services:
+
+  ```
+  # docker-compose restart
+  ```

docs/redis.md

@@ -13,11 +13,3 @@ docker-compose exec redis-mailcow redis-cli
 - Remove volume `rspamd-vol-1` to remove all Rspamd data.
 
 Running `docker-compose down -v` will **destroy all mailcow: dockerized volumes** and delete any related containers.
-
-## Reset admin password
-Reset mailcow admin to `admin:moohoo`:
-
-```
-cd mailcow_path
-bash mailcow-reset-admin.sh
-```

docs/requirements.md

@@ -0,0 +1,75 @@
+Before you run **mailcow: dockerized**, there are a few requirements that you should check:
+
+- **WARNING**: When you want to run the dockerized version on your Debian 8 (Jessie) box you should [switch to the kernel 4.9 from jessie backports](https://packages.debian.org/jessie-backports/linux-image-amd64) because there is a bug (kernel panic) with the kernel 3.16 when running docker containers with *healthchecks*! For more details read: [github.com/docker/docker/issues/30402](https://github.com/docker/docker/issues/30402) and [forum.mailcow.email/t/solved-mailcow-docker-causes-kernel-panic-edit/448](https://forum.mailcow.email/t/solved-mailcow-docker-causes-kernel-panic-edit/448)
+- Mailcow: dockerized requires [some ports](#default-ports) to be open for incomming connections, so make sure that your firewall is not bloking these. Also make sure that no other application is interferring with mailcow's configuration.
+- A correct DNS setup is crucial to every good mailserver setup, so please make sure you got at least the [basics](dns/#the-minimal-dns-configuration) covered bevore you begin!
+- Make sure that your system has a correct date and [time setup](#date-and-time). This is crucial for stuff like two factor TOTP authentication.
+
+## Minimum System Resources
+
+Please make sure that your system has at least the following resources:
+
+| Resource                | mailcow: dockerized |
+| ----------------------- | ------------------- |
+| CPU                     | 1 GHz               |
+| RAM                     | 1 GiB               |
+| Disk                    | 5 GiB               |
+| System Type             | x86_64              |
+
+## Firewall & Ports
+
+Please check if any of mailcow's standard ports are open and not blocked by other applications:
+
+```
+# netstat -tulpn | grep -E -w '25|80|110|143|443|465|587|993|995'
+```
+
+If this command returns any results please remove or stop the application running on that port. You may also adjust mailcows ports via the `mailcow.conf` configuration file.
+
+### Default Ports
+
+If you have a firewall already up and running please make sure that these ports are open for incomming connections:
+
+| Service             | Protocol | Port   | Container       | Variable                       |
+| --------------------|:--------:|:-------|:----------------|--------------------------------|
+| Postfix SMTP        | TCP      | 25     | postfix-mailcow | `${SMTP_PORT}`                 |
+| Postfix SMTPS       | TCP      | 465    | postfix-mailcow | `${SMTPS_PORT}`                |
+| Postfix Submission  | TCP      | 587    | postfix-mailcow | `${SUBMISSION_PORT}`           |
+| Dovecot IMAP        | TCP      | 143    | dovecot-mailcow | `${IMAP_PORT}`                 |
+| Dovecot IMAPS       | TCP      | 993    | dovecot-mailcow | `${IMAPS_PORT}`                |
+| Dovecot POP3        | TCP      | 110    | dovecot-mailcow | `${POP_PORT}`                  |
+| Dovecot POP3S       | TCP      | 995    | dovecot-mailcow | `${POPS_PORT}`                 |
+| Dovecot ManageSieve | TCP      | 4190   | dovecot-mailcow | `${SIEVE_PORT}`                |
+| HTTP(S)             | TCP      | 80/443 | nginx-mailcow   | `${HTTP_PORT}` / `${HTTPS_PORT}` |
+
+## Date and Time
+
+To ensure that you have the correct date and time setup on your system, please check the output of `timedatectl status`:
+
+```
+$ timedatectl status
+      Local time: Sat 2017-05-06 02:12:33 CEST
+  Universal time: Sat 2017-05-06 00:12:33 UTC
+        RTC time: Sat 2017-05-06 00:12:32
+       Time zone: Europe/Berlin (CEST, +0200)
+     NTP enabled: yes
+NTP synchronized: yes
+ RTC in local TZ: no
+      DST active: yes
+ Last DST change: DST began at
+                  Sun 2017-03-26 01:59:59 CET
+                  Sun 2017-03-26 03:00:00 CEST
+ Next DST change: DST ends (the clock jumps one hour backwards) at
+                  Sun 2017-10-29 02:59:59 CEST
+                  Sun 2017-10-29 02:00:00 CET
+```
+
+The lines `NTP enabled: yes` and `NTP synchronized: yes` indicate wether you have NTP enabled and if it's syncronized.
+
+To enable NTP you need to run the command `timedatectl set-ntp true`. You also need to edit your `/etc/systemd/timesyncd.conf`:
+
+```
+# vim /etc/systemd/timesyncd.conf
+[Time]
+Servers=0.pool.ntp.org 1.pool.ntp.org 2.pool.ntp.org 3.pool.ntp.org
+```

docs/ssl.md

@@ -1,6 +1,6 @@
 mailcow dockerized comes with a snakeoil CA "mailcow" and a server certificate in `data/assets/ssl`. Please use your own trusted certificates.
 
-mailcow uses 3 domain names that should be covered by your new certificate:
+mailcow uses **at least** 3 domain names that should be covered by your new certificate:
 
 - ${MAILCOW_HOSTNAME}
 - autodiscover.**example.org**
@@ -35,7 +35,7 @@ certbot certonly \
 ```
 
 **Remember to replace the example.org domain with your own domain, this command will not work if you dont.**
-    
+
 4\. Create hard links to the full path of the new certificates. Assuming you are still in the mailcow root folder:
 ``` bash
 mv data/assets/ssl/cert.{pem,pem.backup}

docs/tagging.md

@@ -1,4 +1,6 @@
-Mailbox users can tag their mail address like in `me+facebook@example.org` and choose between to setups to handle this tag:
+Mailbox users can tag their mail address like in `me+facebook@example.org`. They can control the taghandling in the users **mailcow UI** panel.
+
+![mailcow mail tagging settings](images/tagging.png)
 
 1\. Move this message to a subfolder "facebook" (will be created lower case if not existing)
 

docs/tfa.md

@@ -1,14 +1,11 @@
-So far three methods for TFA are implemented.
+So far three methods for *Two-Factor Authentication* are implemented: U2F, Yubi OTP, and TOTP
 
-FOr U2F to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
+- For U2F to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
-
+- Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
-Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
+<!-- @andryyy, ich bin mir nicht sicher, was du mit diesem Absatz sagen möchtest, Yubi OTP oder U2F? -->
-
+- While Yubi OTP needs an active internet connection and an API ID + key, U2F will work with any FIDO U2F USB key out of the box, but can only be used when mailcow is accessed over HTTPS.
-While Yubi OTP needs an active internet connection and an API ID + key, U2F will work with any FIDO U2F USB key out of the box, but can only be used when mailcow is accessed over HTTPS.
+- U2F and Yubi OTP support multiple keys per user.
-
+- As the third TFA method mailcow uses TOTP: time-based one-time passwords. Those psaswords can be generated with apps like "Google Authenticator" after initially scanning a QR code or entering the given secret manually.
-U2F and Yubi OTP support multiple keys per user.
-
-As the third TFA method mailcow uses TOTP: time-based one-time passwords. Those psaswords can be generated with apps like "Google Authenticator" after initially scanning a QR code or entering the given secret manually.
 
 As administrator you are able to temporary disable a domain administrators TFA login until they successfully logged in.
 

mkdocs.yml

@@ -11,8 +11,12 @@ markdown_extensions:
   - pymdownx.mark
   - pymdownx.tilde
 pages:
-- 'Information and support': 'index.md'
+- 'Information & Support': 'index.md'
-- 'Installation & update':
+- 'Prerequisites':
+  - 'Prepare Your System': 'requirements.md'
+  - 'DNS Setup': 'dns.md'
+- 'Migrating from mailcow 0.14': 'mc14_import.md'
+- 'Installation & Update':
   - 'Installation': 'install.md'
   - 'Update': 'update.md'
 - 'First Steps (optional)': 
@@ -24,23 +28,23 @@ pages:
   - 'Local MTA on Docker host': 'local_mta.md'
   - 'Sender and receiver model': 'sender_rcv.md'
 - 'Usage & Examples':
-  - 'mailcow UI configuration': 'mailcow_ui.md'
+  - 'Debugging & Troubleshooting': 'debug.md'
-  - 'Redirect HTTP to HTTPS': '80_to_443.md'
+  - 'mailcow UI Configuration': 'mailcow_ui.md'
-  - 'Anonymize headers': 'anonym_headers.md'
-  - 'Adjust service configurations': 'change_config.md'
-  - 'Docker Compose Bash completion': 'dc_bash_compl.md'
-  - 'Two-factor authentication': 'tfa.md'
-  - 'Blacklist / Whitelist': 'bl_wl.md'
-  - 'Backup Maildir': 'backup_maildir.md'
-  - 'Customize Dockerfiles': 'cust_dockerfiles.md'
-  - 'Disable sender addresses verification': 'disable_sender_verification.md'
-  - 'Debug': 'debug.md'
-  - 'Autodiscover / Autoconfig': 'autodiscover_config.md'
   - 'Redis': 'redis.md'
   - 'MySQL': 'mysql.md'
   - 'Rspamd': 'rspamd.md'
-  - 'Tagging': 'tagging.md'
   - 'Why bind9?': 'why_bind9.md'
+  - 'Adjust Service Configurations': 'change_config.md'
+  - 'Customize Dockerfiles': 'cust_dockerfiles.md'
+  - 'Docker Compose Bash Completion': 'dc_bash_compl.md'
+  - 'Backup Maildir': 'backup_maildir.md'
+  - 'Two-Factor Authentication': 'tfa.md'
+  - 'Redirect HTTP to HTTPS': '80_to_443.md'
+  - 'Anonymize Headers': 'anonym_headers.md'
+  - 'Tagging': 'tagging.md'
+  - 'Blacklist / Whitelist': 'bl_wl.md'
+  - 'Autodiscover / Autoconfig': 'autodiscover_config.md'
+  - 'Disable Sender Addresses Verification': 'disable_sender_verification.md'
 - 'Third party apps':
   - 'Roundcube': 'roundcube.md'
   - 'Portainer': 'portainer.md'