nickslowinski/mailcow-dockerized-docs
1
0
Fork 0
Code Issues Pull-Requests Projekte Releases Pakete Wiki Aktivität

Merge pull request #4 from broedli/master

Quellcode durchsuchen 
Added chapters, reworked some others.
Dieser Commit ist enthalten in:
André Peters 2017-05-06 08:48:23 +02:00 committet von GitHub
Commit e8bfc26ea4
13 geänderte Dateien mit 315 neuen und 41 gelöschten Zeilen
Statistiken anzeigen Patch-Datei herunterladen Diff-Datei herunterladen Alle Dateien ausklappen Alle Dateien einklappen

4
docs/bl_wl.md
Datei anzeigen

@ -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.

27
docs/debug.md
Datei anzeigen

@ -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 |

78
docs/dns.md Normale Datei
Datei anzeigen

@ -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=..."
```

BIN
docs/images/bl_wl.png Normale Datei
Datei anzeigen

Binäre Datei nicht angezeigt.
Nebeneinander

Nachher

Breite:  |  Höhe:  |  Größe: 12 KiB

BIN
docs/images/tagging.png Normale Datei
Datei anzeigen

Binäre Datei nicht angezeigt.
Nebeneinander

Nachher

Breite:  |  Höhe:  |  Größe: 24 KiB

5
docs/install.md
Datei anzeigen

@ -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
```

100
docs/mc14_import.md Normale Datei
Datei anzeigen

@ -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
```

8
docs/redis.md
Datei anzeigen

@ -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
```

75
docs/requirements.md Normale Datei
Datei anzeigen

@ -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
```

4
docs/ssl.md
Datei anzeigen

@ -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}

4
docs/tagging.md
Datei anzeigen

@ -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)

17
docs/tfa.md
Datei anzeigen

@ -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).
<!-- @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.
- 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.

34
mkdocs.yml
Datei anzeigen

@ -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'