diff --git a/docs/bl_wl.md b/docs/bl_wl.md index 31561e858..08b925537 100644 --- a/docs/bl_wl.md +++ b/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. diff --git a/docs/debug.md b/docs/debug.md index 4e4c69412..4155d03bc 100644 --- a/docs/debug.md +++ b/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 | diff --git a/docs/dns.md b/docs/dns.md new file mode 100644 index 000000000..1030f117c --- /dev/null +++ b/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=..." +``` diff --git a/docs/images/bl_wl.png b/docs/images/bl_wl.png new file mode 100644 index 000000000..3619868f5 Binary files /dev/null and b/docs/images/bl_wl.png differ diff --git a/docs/images/tagging.png b/docs/images/tagging.png new file mode 100644 index 000000000..20591d514 Binary files /dev/null and b/docs/images/tagging.png differ diff --git a/docs/install.md b/docs/install.md index bdb2b381d..dc5bcbd4d 100644 --- a/docs/install.md +++ b/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 ``` diff --git a/docs/mc14_import.md b/docs/mc14_import.md new file mode 100644 index 000000000..7d044663d --- /dev/null +++ b/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 + ``` diff --git a/docs/redis.md b/docs/redis.md index 996a4723a..61ded2cc5 100644 --- a/docs/redis.md +++ b/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 -``` diff --git a/docs/requirements.md b/docs/requirements.md new file mode 100644 index 000000000..479790960 --- /dev/null +++ b/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 +``` diff --git a/docs/ssl.md b/docs/ssl.md index aa672f37c..9ebccb7a9 100644 --- a/docs/ssl.md +++ b/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} diff --git a/docs/tagging.md b/docs/tagging.md index 36101d5e7..6cf9c352d 100644 --- a/docs/tagging.md +++ b/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) diff --git a/docs/tfa.md b/docs/tfa.md index 60ad71df0..8eaa827b7 100644 --- a/docs/tfa.md +++ b/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. - -Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com). - -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. +- 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). + +- 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. As administrator you are able to temporary disable a domain administrators TFA login until they successfully logged in. diff --git a/mkdocs.yml b/mkdocs.yml index a1d8a167f..23a814e43 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,8 +11,12 @@ markdown_extensions: - pymdownx.mark - pymdownx.tilde pages: -- 'Information and support': 'index.md' -- 'Installation & update': +- 'Information & Support': 'index.md' +- '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' - - 'Redirect HTTP to HTTPS': '80_to_443.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' + - 'Debugging & Troubleshooting': 'debug.md' + - 'mailcow UI Configuration': 'mailcow_ui.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'