From 01b4fc908623bb0ee79ceaf1b5845f0820996047 Mon Sep 17 00:00:00 2001 From: andryyy Date: Sat, 6 May 2017 00:22:26 +0200 Subject: [PATCH] Rearrange format, still a wip --- docs/80_to_443.md | 25 +++ docs/anonym_headers.md | 16 ++ docs/autodiscover_config.md | 5 + docs/backup_maildir.md | 20 ++ docs/bl_wl.md | 3 + docs/change_config.md | 70 ++++++ docs/cust_dockerfiles.md | 11 + docs/dc_bash_compl.md | 3 + docs/debug.md | 7 + docs/disable_sender_verification.md | 19 ++ docs/first_steps.md | 321 ---------------------------- docs/gogs.md | 64 ++++++ docs/index.md | 52 +++-- docs/install.md | 76 ------- docs/local_mta.md | 7 + docs/mailcow_ui.md | 14 ++ docs/mysql.md | 68 ++++++ docs/portainer.md | 53 +++++ docs/redis.md | 23 ++ docs/relayhost.md | 34 +++ docs/roundcube.md | 83 +++++++ docs/rp.md | 80 +++++++ docs/rspamd.md | 36 ++++ docs/rspamd_ui.md | 20 ++ docs/sender_rcv.md | 33 +++ docs/ssl.md | 52 +++++ docs/syslog.md | 76 +++++++ docs/tagging.md | 5 + docs/tfa.md | 31 +++ docs/update.md | 71 ++++++ docs/why_bind9.md | 6 + mkdocs.yml | 55 +++-- 32 files changed, 1008 insertions(+), 431 deletions(-) create mode 100644 docs/80_to_443.md create mode 100644 docs/anonym_headers.md create mode 100644 docs/autodiscover_config.md create mode 100644 docs/backup_maildir.md create mode 100644 docs/bl_wl.md create mode 100644 docs/change_config.md create mode 100644 docs/cust_dockerfiles.md create mode 100644 docs/dc_bash_compl.md create mode 100644 docs/debug.md create mode 100644 docs/disable_sender_verification.md delete mode 100644 docs/first_steps.md create mode 100644 docs/gogs.md create mode 100644 docs/local_mta.md create mode 100644 docs/mailcow_ui.md create mode 100644 docs/mysql.md create mode 100644 docs/portainer.md create mode 100644 docs/redis.md create mode 100644 docs/relayhost.md create mode 100644 docs/roundcube.md create mode 100644 docs/rp.md create mode 100644 docs/rspamd.md create mode 100644 docs/rspamd_ui.md create mode 100644 docs/sender_rcv.md create mode 100644 docs/ssl.md create mode 100644 docs/syslog.md create mode 100644 docs/tagging.md create mode 100644 docs/tfa.md create mode 100644 docs/update.md create mode 100644 docs/why_bind9.md diff --git a/docs/80_to_443.md b/docs/80_to_443.md new file mode 100644 index 000000000..b2b66108f --- /dev/null +++ b/docs/80_to_443.md @@ -0,0 +1,25 @@ +Since February the 28th 2017 mailcow does come with port 80 and 443 enabled. + +Open `mailcow.conf` and set `HTTP_BIND=0.0.0.0` - if not already set. + +Open `data/conf/nginx/site.conf` and add a new site at the top of that file: + +``` +server { + listen 80 default_server; + include /etc/nginx/conf.d/server_name.active; + return 301 https://$host$request_uri; +} +``` + +In case you changed the HTTP_BIND parameter, recreate the container: + +``` +docker-compose up -d +``` + +Otherwise restart Nginx: + +``` +docker-compose restart nginx-mailcow +``` diff --git a/docs/anonym_headers.md b/docs/anonym_headers.md new file mode 100644 index 000000000..edd6283c1 --- /dev/null +++ b/docs/anonym_headers.md @@ -0,0 +1,16 @@ +Save as `data/conf/postfix/mailcow_anonymize_headers.pcre`: + +``` +/^\s*Received:[^\)]+\)\s+\(Authenticated sender:(.+)/ + REPLACE Received: from localhost (localhost [127.0.0.1]) (Authenticated sender:$1 +/^\s*User-Agent/ IGNORE +/^\s*X-Enigmail/ IGNORE +/^\s*X-Mailer/ IGNORE +/^\s*X-Originating-IP/ IGNORE +/^\s*X-Forward/ IGNORE +``` + +Add this to `data/conf/postfix/main.cf`: +``` +smtp_header_checks = pcre:/opt/postfix/conf/mailcow_anonymize_headers.pcre +``` diff --git a/docs/autodiscover_config.md b/docs/autodiscover_config.md new file mode 100644 index 000000000..a832b74a8 --- /dev/null +++ b/docs/autodiscover_config.md @@ -0,0 +1,5 @@ +This disables ActiveSync in the autodiscover service for Outlook and configures it with IMAP and SMTP instead: + +Open `data/web/autodiscover.php` and set `'useEASforOutlook' => 'yes'` to `'useEASforOutlook' => 'no'`. + +To always use IMAP and SMTP instead of EAS, set `'autodiscoverType' => 'imap'`. diff --git a/docs/backup_maildir.md b/docs/backup_maildir.md new file mode 100644 index 000000000..5ab6cc2cf --- /dev/null +++ b/docs/backup_maildir.md @@ -0,0 +1,20 @@ +### Backup + +This line backups the vmail directory to a file backup_vmail.tar.gz in the mailcow root directory: +``` +cd /path/to/mailcow-dockerized +source mailcow.conf +DATE=$(date +"%Y%m%d_%H%M%S") +docker run --rm -it -v $(docker inspect --format '{{ range .Mounts }}\{{ if eq .Destination "/var/vmail" }}{{ .Name }}{{ end }}{{ end }}' $(docker-compose ps -q dovecot-mailcow)):/vmail -v ${PWD}:/backup debian:jessie tar cvfz /backup/backup_vmail.tar.gz /vmail +``` + +You can change the path by adjusting ${PWD} (which equals to the current directory) to any path you have write-access to. +Set the filename `backup_vmail.tar.gz` to any custom name, but leave the path as it is. Example: `[...] tar cvfz /backup/my_own_filename_.tar.gz` + +### Restore +``` +cd /path/to/mailcow-dockerized +source mailcow.conf +DATE=$(date +"%Y%m%d_%H%M%S") +{% raw %}docker run --rm -it -v $(docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/var/vmail" }}{{ .Name }}{{ end }}{{ end }}' $(docker-compose ps -q dovecot-mailcow)):/vmail -v ${PWD}:/backup debian:jessie tar xvfz /backup/backup_vmail.tar.gz{% endraw %} +``` diff --git a/docs/bl_wl.md b/docs/bl_wl.md new file mode 100644 index 000000000..31561e858 --- /dev/null +++ b/docs/bl_wl.md @@ -0,0 +1,3 @@ +Edit a domain as (domain) administrator to add an item to the filter table. + +Beware that a mailbox user can login to mailcow and override a domain policy filter item. diff --git a/docs/change_config.md b/docs/change_config.md new file mode 100644 index 000000000..4a178b098 --- /dev/null +++ b/docs/change_config.md @@ -0,0 +1,70 @@ +The most important configuration files are mounted from the host into the related containers: + +``` +data/conf +├── bind9 +│   └── named.conf +├── dovecot +│   ├── dovecot.conf +│   ├── dovecot-master.passwd +│   ├── sieve_after +│   └── sql +│   ├── dovecot-dict-sql.conf +│   └── dovecot-mysql.conf +├── mysql +│   └── my.cnf +├── nginx +│   ├── dynmaps.conf +│   ├── site.conf +│   └── templates +│   ├── listen_plain.template +│   ├── listen_ssl.template +│   └── server_name.template +├── postfix +│   ├── main.cf +│   ├── master.cf +│   ├── postscreen_access.cidr +│   ├── smtp_dsn_filter +│   └── sql +│   ├── mysql_relay_recipient_maps.cf +│   ├── mysql_tls_enforce_in_policy.cf +│   ├── mysql_tls_enforce_out_policy.cf +│   ├── mysql_virtual_alias_domain_catchall_maps.cf +│   ├── mysql_virtual_alias_domain_maps.cf +│   ├── mysql_virtual_alias_maps.cf +│   ├── mysql_virtual_domains_maps.cf +│   ├── mysql_virtual_mailbox_maps.cf +│   ├── mysql_virtual_relay_domain_maps.cf +│   ├── mysql_virtual_sender_acl.cf +│   └── mysql_virtual_spamalias_maps.cf +├── rmilter +│   └── rmilter.conf +├── rspamd +│   ├── dynmaps +│   │   ├── authoritative.php +│   │   ├── settings.php +│   │   ├── tags.php +│   │   └── vars.inc.php -> ../../../web/inc/vars.inc.php +│   ├── local.d +│   │   ├── dkim.conf +│   │   ├── metrics.conf +│   │   ├── options.inc +│   │   ├── redis.conf +│   │   ├── rspamd.conf.local +│   │   └── statistic.conf +│   ├── lua +│   │   └── rspamd.local.lua +│   └── override.d +│   ├── logging.inc +│   ├── worker-controller.inc +│   └── worker-normal.inc +└── sogo + ├── sieve.creds + └── sogo.conf + +``` + +Just change the according configuration file on the host and restart the related service: +``` +docker-compose restart service-mailcow +``` diff --git a/docs/cust_dockerfiles.md b/docs/cust_dockerfiles.md new file mode 100644 index 000000000..cf06aee6b --- /dev/null +++ b/docs/cust_dockerfiles.md @@ -0,0 +1,11 @@ +Make your changes in `data/Dockerfiles/$service` and build the image locally: + +``` +docker build data/Dockerfiles/service -t mailcow/$service +``` + +Now auto-recreate modified containers: + +``` +docker-compose up -d +``` diff --git a/docs/dc_bash_compl.md b/docs/dc_bash_compl.md new file mode 100644 index 000000000..3b82321dc --- /dev/null +++ b/docs/dc_bash_compl.md @@ -0,0 +1,3 @@ +``` +curl -L https://raw.githubusercontent.com/docker/compose/$(docker-compose version --short)/contrib/completion/bash/docker-compose -o /etc/bash_completion.d/docker-compose +``` diff --git a/docs/debug.md b/docs/debug.md new file mode 100644 index 000000000..4e4c69412 --- /dev/null +++ b/docs/debug.md @@ -0,0 +1,7 @@ +You can use `docker-compose logs $service-name` for all containers. + +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`. diff --git a/docs/disable_sender_verification.md b/docs/disable_sender_verification.md new file mode 100644 index 000000000..4d2546096 --- /dev/null +++ b/docs/disable_sender_verification.md @@ -0,0 +1,19 @@ +This option is not best-practice and should only be implemented when there is no other option available to archive whatever you are trying to do. + +Simply create a file `data/conf/postfix/check_sasl_access` and enter the following content. This user must exist in your installation and needs to authenticate before sending mail. +``` +user-to-allow-everything@example.com OK +``` + +Open `data/conf/postfix/main.cf` and find `smtpd_sender_restrictions`. Prepend `check_sasl_access hash:/opt/postfix/conf/check_sasl_access` like this: +``` +smtpd_sender_restrictions = check_sasl_access hash:/opt/postfix/conf/check_sasl_access reject_authenticated_sender_login_mismatch [...] +``` + +Run postmap on check_sasl_access: + +``` +docker-compose exec postfix-mailcow postmap /opt/postfix/conf/check_sasl_access +``` + +Restart the Postfix container. diff --git a/docs/first_steps.md b/docs/first_steps.md deleted file mode 100644 index b75075959..000000000 --- a/docs/first_steps.md +++ /dev/null @@ -1,321 +0,0 @@ -## SSL (and: How to use Let's Encrypt) - -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_HOSTNAME} -- autodiscover.**example.org** -- autoconfig.**example.org** - -### Obtain multi-SAN certificate by Let's Encrypt - -This is just an example of how to obtain certificates with certbot. There are several methods! - -1\. Get the certbot client: -``` bash -wget https://dl.eff.org/certbot-auto -O /usr/local/sbin/certbot && chmod +x /usr/local/sbin/certbot -``` - -2\. Make sure you set `HTTP_BIND=0.0.0.0` and `HTTP_PORT=80` in `mailcow.conf` or setup a reverse proxy to enable connections to port 80. If you changed HTTP_BIND, then rebuild Nginx: -``` bash -docker-compose up -d -``` - -3\. Request the certificate with the webroot method: -``` bash -cd /path/to/git/clone/mailcow-dockerized -source mailcow.conf -certbot certonly \ - --webroot \ - -w ${PWD}/data/web \ - -d ${MAILCOW_HOSTNAME} \ - -d autodiscover.example.org \ - -d autoconfig.example.org \ - --email you@example.org \ - --agree-tos -``` - -**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} -mv data/assets/ssl/key.{pem,pem.backup} -ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/fullchain.pem) data/assets/ssl/cert.pem -ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/privkey.pem) data/assets/ssl/key.pem -``` - -5\. Restart affected containers: -``` -docker-compose restart postfix-mailcow dovecot-mailcow nginx-mailcow -``` - -When renewing certificates, run the last two steps (link + restart) as post-hook in a script. - -## Rspamd Web UI -At first you may want to setup Rspamds web interface which provides some useful features and information. - -1\. Generate a Rspamd controller password hash: -``` -docker-compose exec rspamd-mailcow rspamadm pw -``` - -2\. Replace the default hash in `data/conf/rspamd/override.d/worker-controller.inc` by your newly generated: -``` -enable_password = "myhash"; -``` - -You can use `password = "myhash";` instead of `enable_password` to disable write-access in the web UI. - -3\. Restart rspamd: -``` -docker-compose restart rspamd-mailcow -``` - -Open https://${MAILCOW_HOSTNAME}/rspamd in a browser and login! - -## Optional: Reverse proxy - -You don't need to change the Nginx site that comes with mailcow: dockerized. -mailcow: dockerized trusts the default gateway IP 172.22.1.1 as proxy. This is very important to control access to Rspamd's web UI. - -1\. Make sure you change HTTP_BIND and HTTPS_BIND in `mailcow.conf` to a local address and set the ports accordingly, for example: -``` bash -HTTP_BIND=127.0.0.1 -HTTP_PORT=8080 -HTTPS_PORT=127.0.0.1 -HTTPS_PORT=8443 -``` -** IMPORTANT: Do not use port 8081 ** - -Recreate affected containers by running `docker-compose up -d`. - -2\. Configure your local webserver as reverse proxy: - -### Apache 2.4 -``` apache - - ServerName mail.example.org - ServerAlias autodiscover.example.org - ServerAlias autoconfig.example.org - - [...] - # You should proxy to a plain HTTP session to offload SSL processing - ProxyPass / http://127.0.0.1:8080/ - ProxyPassReverse / http://127.0.0.1:8080/ - - ProxyPreserveHost On - ProxyAddHeaders On - - # This header does not need to be set when using http - RequestHeader set X-Forwarded-Proto "https" - - your-ssl-configuration-here - [...] - - # If you plan to proxy to a HTTPS host: - #SSLProxyEngine On - - # If you plan to proxy to an untrusted HTTPS host: - #SSLProxyVerify none - #SSLProxyCheckPeerCN off - #SSLProxyCheckPeerName off - #SSLProxyCheckPeerExpire off - -``` - -### Nginx -``` -server { - listen 443; - server_name mail.example.org autodiscover.example.org autoconfig.example.org; - - [...] - your-ssl-configuration-here - - location / { - proxy_pass http://127.0.0.1:8080/; - proxy_set_header Host $http_host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - [...] -} -``` - -### HAProxy -``` -frontend https-in - bind :::443 v4v6 ssl crt mailcow.pem - default_backend mailcow - -backend mailcow - option forwardfor - http-request set-header X-Forwarded-Proto https if { ssl_fc } - http-request set-header X-Forwarded-Proto http if !{ ssl_fc } - server mailcow 127.0.0.1:8080 check -``` - -## Optional: Setup a relayhost - -Insert these lines to `data/conf/postfix/main.cf`. "relayhost" does already exist (empty), just change its value. -``` -relayhost = [your-relayhost]:587 -smtp_sasl_password_maps = hash:/opt/postfix/conf/smarthost_passwd -smtp_sasl_auth_enable = yes -``` - -Create the credentials file: -``` -echo "your-relayhost username:password" > data/conf/postfix/smarthost_passwd -``` - -Run: -``` -docker-compose exec postfix-mailcow postmap /opt/postfix/conf/smarthost_passwd -docker-compose exec postfix-mailcow chown root:postfix /opt/postfix/conf/smarthost_passwd /opt/postfix/conf/smarthost_passwd.db -docker-compose exec postfix-mailcow chmod 660 /opt/postfix/conf/smarthost_passwd /opt/postfix/conf/smarthost_passwd.db -docker-compose exec postfix-mailcow postfix reload -``` - -### Helper script - -There is a helper script `mailcow-setup-relayhost.sh` you can run to setup a relayhost. - -``` bash -Usage: - -Setup a relayhost: -./mailcow-setup-relayhost.sh relayhost port (username) (password) -Username and password are optional parameters. - -Reset to defaults: -./mailcow-setup-relayhost.sh reset -``` - -## Optional: Log to Syslog - -Enable Rsyslog to receive logs on 524/tcp: - -``` -# This setting depends on your Rsyslog version and configuration format. -# For most Debian derivates it will work like this... -$ModLoad imtcp -$TCPServerAddress 127.0.0.1 -$InputTCPServerRun 524 - -# ...while for Ubuntu 16.04 it looks like this: -module(load="imtcp") -input(type="imtcp" address="127.0.0.1" port="524") - -# No matter your Rsyslog version, you should set this option to off -# if you plan to use Fail2ban -$RepeatedMsgReduction off -``` - -Restart rsyslog after enabling the TCP listener. - -Now setup Docker daemon to start with the syslog driver. -This enables the syslog driver for all containers! - -Debian users can change the startup configuration in `/etc/default/docker` while CentOS users find it in `/etc/sysconfig/docker`: -``` -... -DOCKER_OPTS="--log-driver=syslog --log-opt syslog-address=tcp://127.0.0.1:524" -... -``` - -**Caution:** For some reason Ubuntu 16.04 and some, but not all, systemd based distros do not read the defaults file parameters. - -Just run `systemctl edit docker.service` and add the following content to fix it. - -**Note:** If "systemctl edit" is not available, just copy the content to `/etc/systemd/system/docker.service.d/override.conf`. - -The first empty ExecStart parameter is not a mistake. - -``` -[Service] -EnvironmentFile=/etc/default/docker -ExecStart= -ExecStart=/usr/bin/docker daemon -H fd:// $DOCKER_OPTS -``` - -Restart the Docker daemon and run `docker-compose down && docker-compose up -d` to recreate the containers. - -### Use Fail2ban - -**This is a subsection of "Log to Syslog", which is required for Fail2ban to work.** - -Open `/etc/fail2ban/filter.d/common.conf` and search for the prefix_line parameter, change it to ".*": - -``` -__prefix_line = .* -``` - -Create `/etc/fail2ban/jail.d/dovecot.conf`... -``` -[dovecot] -enabled = true -filter = dovecot -logpath = /var/log/syslog -chain = FORWARD -``` - -and `jail.d/postfix-sasl.conf`: -``` -[postfix-sasl] -enabled = true -filter = postfix-sasl -logpath = /var/log/syslog -chain = FORWARD -``` - -Restart Fail2ban. - -## Install a local MTA - -The easiest option would be to disable the listener on port 25/tcp. - -**Postfix** users disable the listener by commenting the following line (starting with `smtp` or `25`) in `/etc/postfix/master.cf`: -``` -#smtp inet n - - - - smtpd -``` -Restart Postfix after applying your changes. - -## Sender and receiver model - -When a mailbox is created, a user is allowed to send mail from and receive mail for his own mailbox address. - - Mailbox me@example.org is created. example.org is a primary domain. - Note: a mailbox cannot be created in an alias domain. - - me@example.org is only known as me@example.org. - me@example.org is allowed to send as me@example.org. - -We can add an alias domain for example.org: - - Alias domain alias.com is added and assigned to primary domain example.org. - me@example.org is now known as me@example.org and me@alias.com. - me@example.org is now allowed to send as me@example.org and me@alias.com. - -We can add aliases for a mailbox to receive mail for and to send from this new address. - -It is important to know, that you are not able to receive mail for `my-alias@my-alias-domain.tld`. You would need to create this particular alias. - - me@example.org is assigned the alias alias@example.org - me@example.org is now known as alias@example.org, me@alias.com, alias@example.org - - me@example.org is NOT known as alias@alias.com. - -Administrators and domain administrators can edit mailboxes to allow specific users to send as other mailbox users ("delegate" them). - -You can choose between mailbox users or completely disable the sender check for domains. - -### SOGo "mail from" addresses - -Mailbox users can, obviously, select their own mailbox address, as well as all alias addresses and aliases that exist through alias domains. - -If you want to select another _existing_ mailbox user as your "mail from" address, this user has to delegate you access through SOGo (see SOGo documentation). Moreover a mailcow (domain) administrator -needs to grant you access as described above. diff --git a/docs/gogs.md b/docs/gogs.md new file mode 100644 index 000000000..b196ccf37 --- /dev/null +++ b/docs/gogs.md @@ -0,0 +1,64 @@ +With Gogs' ability to authenticate over SMTP it is trivial to integrate it with mailcow. Few changes are needed: + +1\. Open `docker-compose.yml` and add gogs: + +``` + gogs-mailcow: + image: gogs/gogs + volumes: + - ./data/gogs:/data + networks: + mailcow-network: + ipv4_address: 172.22.1.123 + aliases: + - gogs + ports: + - "${GOGS_SSH_PORT:-50022}:22" + - "${GOGS_WWW_PORT:-50080}:3000" + dns: + - 172.22.1.254 + +``` + +2\. Open `data/conf/nginx/site.conf` and add in each `server{}` block +``` +location /gogs/ { + proxy_pass http://172.22.1.123:3000/; +} +``` + +3\. Open `mailcow.conf` and define ports you want gogs to open, as well as future database password. Example: + +``` +GOGS_WWW_PORT=3000 +GOGS_SSH_PORT=4000 +DBGOGS=CorrectHorseBatteryStaple +``` + +4\. Create database and user for Gogs to use. + +``` +. ./mailcow.conf +docker-compose exec mysql-mailcow mysql -uroot -p$DBROOT +mysql> CREATE USER gogs IDENTIFIED BY 'CorrectHorseBatteryStaple'; +mysql> CREATE DATABASE gogs; +mysql> GRANT ALL PRIVILEGES ON gogs.* to gogs; +``` + +5\. Run `docker-compose up -d` to bring up Gogs container. Verify with `curl http://172.22.1.123:3000/` that it is running. + +6\. Proceed to installer from browser, for the time being using direct url `http://${MAILCOW_HOSTNAME}:${GOGS_WWW_PORT}/`, for example `http://example.org:3000/`. For database details set `172.22.1.2` as database host, user `gogs`, database name `gogs` and password as set above + +7\. Once install is complete, login as admin and in settings - authorization enable SMTP. SMTP Host should be `172.22.1.8` with port `587`. You'll probably want to set `Skip TLS Verify`. + +8\. Edit `data/gogs/gogs/conf/app.ini` and set following values. You can consult [Gogs cheat sheet](https://gogs.io/docs/advanced/configuration_cheat_sheet) for their meaning and other possible values. + +``` +[server] +SSH_LISTEN_PORT = 22 +SSH_DOMAIN = [domain where ssh is available - used for ssh clone url] +SSH_PORT = [port where ssh is open on host - used for ssh clone url] +ROOT_URL = https://[url]/gogs/ +``` + +9\. Restart Gogs with `docker-compose restart gogs-mailcow`. Your users should be able to login with mailcow managed accounts. diff --git a/docs/index.md b/docs/index.md index 0e8e88187..dadf351d3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,24 @@ -# mailcow: dockerized - 🐮 + 🐋 = 💕 +# 🐮 + 🐋 = 💕 -[![Servercow](https://www.servercow.de/img/cow_globe_200.svg)](https://www.servercow.de) +## Help mailcow -If you want to support mailcow, consider hosting mailcow on a Servercow virtual machine @ Servercow! +Let us know about your ideas in #mailcow @ Freenode. + +[Servercow](https://www.servercow.de) - hosted mailcow, KVM based virtual servers, webhosting and more. + +[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=JWBSYHF4SMC68) + +## Get support + +### Commercial support + +For commercial support contact [info@servercow.de](mailto:info@servercow.de). + +### Community support + +- IRC @ [Freenode, #mailcow](irc://irc.freenode.org:6667/mailcow) +- Forum @ [forum.mailcow.email](forum.mailcow.email) +- GitHub @ [mailcow/mailcow-dockerized](https://github.com/mailcow/mailcow-dockerized) ## Screenshots @@ -10,6 +26,20 @@ You can find screenshots [on Imgur](http://imgur.com/a/oewYt). ## Overview +The integrated **mailcow UI** allows administrative work on your mail server instance as well as separated domain administrator and mailbox user access: + +- DKIM key management +- Black- and whitelists per domain and per user +- Spam score managment per-user (reject spam, mark spam, greylist) +- Allow mailbox users to create temporary spam aliases +- Prepend mail tags to subject or move mail to subfolder (per-user) +- Allow mailbox users to toggle incoming and outgoing TLS enforcement +- Allow users to reset SOGo ActiveSync device caches +- imapsync to migrate or pull remote mailboxes regularly +- TFA: Yubi OTP and U2F USB (Google Chrome and derivates only), TOTP +- Add domains, mailboxes, aliases, domain aliases and SOGo resources +- Add whitelisted hosts to forward mail to mailcow + mailcow dockerized comes with **12 containers** linked in **one bridged network**. Each container represents a single application. @@ -35,19 +65,3 @@ Each container represents a single application. - rspamd-vol-1 - postfix-vol-1 - crypt-vol-1 - -The integrated **mailcow UI** allows administrative work on your mail server instance as well as separated domain administrator and mailbox user access: - -- DKIM key management -- Black- and whitelists per domain and per user -- Spam score managment per-user (reject spam, mark spam, greylist) -- Allow mailbox users to create temporary spam aliases -- Prepend mail tags to subject or move mail to subfolder (per-user) -- Allow mailbox users to toggle incoming and outgoing TLS enforcement -- Allow users to reset SOGo ActiveSync device caches -- imapsync to migrate or pull remote mailboxes regularly -- TFA: Yubi OTP and U2F USB (Google Chrome and derivates only), TOTP -- Add domains, mailboxes, aliases, domain aliases and SOGo resources -- Add whitelisted hosts to forward mail to mailcow - -*[Looking for a farm to host your cow?](https://www.servercow.de)* diff --git a/docs/install.md b/docs/install.md index b9322f00b..38c792b22 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,5 +1,3 @@ -## Install mailcow - **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. @@ -50,77 +48,3 @@ Done! You can now access **https://${MAILCOW_HOSTNAME}** with the default credentials `admin` + password `moohoo`. The database will be initialized right after a connection to MySQL can be established. - -## Update mailcow - -There is no update routine. You need to refresh your pulled repository clone and apply your local changes (if any). Actually there are many ways to merge local changes. - -### Step 1, method 1 -Stash all local changes, pull changes from the remote master branch and apply your stash on top of it. You will most likely see warnings about non-commited changes; you can ignore them: - -``` -# Stash local changes -git stash -# Re-pull master -git pull -# Apply stash and remove it -git stash pop -``` - -### Step 1, method 2 -Fetch new data from GitHub, commit changes and merge remote repository: - -``` -# Get updates/changes -git fetch -# Add all changed files to local clone -git add -A -# Commit changes, ignore git complaining about username and mail address -git commit -m "Local config aat $(date)" -# Merge changes -git merge -``` - -If git complains about conflicts, solve them! Example: -``` -CONFLICT (content): Merge conflict in data/web/index.php -``` - -Open `data/web/index.php`, solve the conflict, close the file and run `git add -A` + `git commit -m "Solved conflict"`. - -### Step 1, method 3 - -Thanks to fabreg @ GitHub! - -In case both methods do not work (for many reason like you're unable to fix the CONFLICTS or any other reasons) you can simply start all over again. - -Keep in mind that all local changes _to configuration files_ will be lost. However, your volumes will not be removed. - -- Copy mailcow.conf somewhere outside the mailcow-dockerized directory -- Stop and remove mailcow containers: `docker-compose down` -- Delete the directory or rename it -- Clone the remote repository again (`git clone https://github.com/andryyy/mailcow-dockerized && cd mailcow-dockerized`). **Pay attention** to this step - the folder must have the same name of the previous one! -- Copy back your previous `mailcow.conf` into the mailcow-dockerizd folder - -If you forgot to stop Docker before deleting the cloned directoy, you can use the following commands: -``` -docker stop $(docker ps -a -q) -docker rm $(docker ps -a -q) -``` - -### Step 2 - -Pull new images (if any) and recreate changed containers: - -``` -docker-compose pull -docker-compose up -d --remove-orphans -``` - -### Step 3 -Clean-up dangling (unused) images and volumes: - -``` -docker rmi -f $(docker images -f "dangling=true" -q) -docker volume rm $(docker volume ls -qf dangling=true) -``` diff --git a/docs/local_mta.md b/docs/local_mta.md new file mode 100644 index 000000000..954e0e93a --- /dev/null +++ b/docs/local_mta.md @@ -0,0 +1,7 @@ +The easiest option would be to disable the listener on port 25/tcp. + +**Postfix** users disable the listener by commenting the following line (starting with `smtp` or `25`) in `/etc/postfix/master.cf`: +``` +#smtp inet n - - - - smtpd +``` +Restart Postfix after applying your changes. diff --git a/docs/mailcow_ui.md b/docs/mailcow_ui.md new file mode 100644 index 000000000..885e4b6e7 --- /dev/null +++ b/docs/mailcow_ui.md @@ -0,0 +1,14 @@ +Several configuration parameters of the mailcow UI can be changed by creating a file `data/web/inc/vars.local.inc.php` which overrides defaults settings found in `data/web/inc/vars.inc.php`. + +The local configuration file is persistent over updates of mailcow. Try not to change values inside `data/web/inc/vars.inc.php`, but use them as template for the local override. + +mailcow UI configuration parameters can be to... + +- ...change the default language* +- ...change the default bootstrap theme +- ...set a password complexity regex +- ...add mailcow app buttons to the login screen +- ...set a pagination trigger +- ...set action after submitting forms (stay in form, return to previous page) + +\* To change SOGos default language, you will need to edit `data/conf/sogo/sogo.conf` and replace "English" by your preferred language. diff --git a/docs/mysql.md b/docs/mysql.md new file mode 100644 index 000000000..715c74b4a --- /dev/null +++ b/docs/mysql.md @@ -0,0 +1,68 @@ +### Connect +``` +source mailcow.conf +docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} +``` + +### Backup +``` +cd /path/to/mailcow-dockerized +source mailcow.conf +DATE=$(date +"%Y%m%d_%H%M%S") +docker-compose exec mysql-mailcow mysqldump --default-character-set=utf8mb4 -u${DBUSER} -p${DBPASS} ${DBNAME} > backup_${DBNAME}_${DATE}.sql +``` + +### Restore + +You should redirect the sql dump without Docker-Compose to prevent parsing errors. + +``` +cd /path/to/mailcow-dockerized +source mailcow.conf +docker exec -i $(docker-compose ps -q mysql-mailcow) mysql -u${DBUSER} -p${DBPASS} ${DBNAME} < backup_file.sql +``` + +### Reset MySQL passwords + +Stop the stack by running `docker-compose stop`. + +When the containers came to a stop, run this command: + +``` +docker-compose run --rm --entrypoint '/bin/sh -c "gosu mysql mysqld --skip-grant-tables & sleep 10 && mysql -hlocalhost -uroot && exit 0"' mysql-mailcow +``` + +**1\. Find database name** + +``` +MariaDB [(none)]> show databases; ++--------------------+ +| Database | ++--------------------+ +| information_schema | +| mailcow_database | <===== +| mysql | +| performance_schema | ++--------------------+ +4 rows in set (0.00 sec) +``` + +**2\. Reset one or more users** + +Both "password" and "authentication_string" exist. Currently "password" is used, but better set both. + +``` +MariaDB [(none)]> SELECT user FROM mysql.user; ++--------------+ +| user | ++--------------+ +| mailcow_user | <===== +| root | ++--------------+ +2 rows in set (0.00 sec) + +MariaDB [(none)]> FLUSH PRIVILEGES; +MariaDB [(none)]> UPDATE mysql.user SET authentication_string = PASSWORD('gotr00t'), password = PASSWORD('gotr00t') WHERE User = 'root' AND Host = '%'; +MariaDB [(none)]> UPDATE mysql.user SET authentication_string = PASSWORD('mookuh'), password = PASSWORD('mookuh') WHERE User = 'mailcow' AND Host = '%'; +MariaDB [(none)]> FLUSH PRIVILEGES; +``` diff --git a/docs/portainer.md b/docs/portainer.md new file mode 100644 index 000000000..7dba226dd --- /dev/null +++ b/docs/portainer.md @@ -0,0 +1,53 @@ +In order to enable Portainer, the docker-compose.yml and site.conf for nginx must be modified. + +1\. docker-compose.yml: Insert this block for portainer +``` + portainer-mailcow: + image: portainer/portainer + volumes: + - /var/run/docker.sock:/var/run/docker.sock + restart: always + dns: + - 172.22.1.254 + dns_search: mailcow-network + networks: + mailcow-network: + aliases: + - portainer +``` +2a\. data/conf/nginx/site.conf: Just beneath the opening line, at the same level as a server { block, add this: +``` +upstream portainer { + server portainer-mailcow:9000; +} + +map $http_upgrade $connection_upgrade { + default upgrade; + '' close; +} +``` + +2b\. data/conf/nginx/site.conf: Then, inside **both** (ssl and plain) server blocks, add this: +``` + location /portainer/ { + proxy_http_version 1.1; + proxy_set_header Host $http_host; # required for docker client's sake + proxy_set_header X-Real-IP $remote_addr; # pass on real client's IP + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_read_timeout 900; + + proxy_set_header Connection ""; + proxy_buffers 32 4k; + proxy_pass http://portainer/; + } + + location /portainer/api/websocket/ { + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_pass http://portainer/api/websocket/; + } +``` + +Now you can simply navigate to https://${MAILCOW_HOSTNAME}/portainer/ to view your Portainer container monitoring page. You’ll then be prompted to specify a new password for the **admin** account. After specifying your password, you’ll then be able to connect to the Portainer UI. diff --git a/docs/redis.md b/docs/redis.md new file mode 100644 index 000000000..996a4723a --- /dev/null +++ b/docs/redis.md @@ -0,0 +1,23 @@ +### Client + +``` +docker-compose exec redis-mailcow redis-cli +``` + +## Remove persistent data + +- Remove volume `mysql-vol-1` to remove all MySQL data. +- Remove volume `redis-vol-1` to remove all Redis data. +- Remove volume `vmail-vol-1` to remove all contents of `/var/vmail` mounted to `dovecot-mailcow`. +- Remove volume `dkim-vol-1` to remove all DKIM keys. +- 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/relayhost.md b/docs/relayhost.md new file mode 100644 index 000000000..3c330cc41 --- /dev/null +++ b/docs/relayhost.md @@ -0,0 +1,34 @@ +Insert these lines to `data/conf/postfix/main.cf`. "relayhost" does already exist (empty), just change its value. +``` +relayhost = [your-relayhost]:587 +smtp_sasl_password_maps = hash:/opt/postfix/conf/smarthost_passwd +smtp_sasl_auth_enable = yes +``` + +Create the credentials file: +``` +echo "your-relayhost username:password" > data/conf/postfix/smarthost_passwd +``` + +Run: +``` +docker-compose exec postfix-mailcow postmap /opt/postfix/conf/smarthost_passwd +docker-compose exec postfix-mailcow chown root:postfix /opt/postfix/conf/smarthost_passwd /opt/postfix/conf/smarthost_passwd.db +docker-compose exec postfix-mailcow chmod 660 /opt/postfix/conf/smarthost_passwd /opt/postfix/conf/smarthost_passwd.db +docker-compose exec postfix-mailcow postfix reload +``` + +### Helper script + +There is a helper script `mailcow-setup-relayhost.sh` you can run to setup a relayhost. + +``` bash +Usage: + +Setup a relayhost: +./mailcow-setup-relayhost.sh relayhost port (username) (password) +Username and password are optional parameters. + +Reset to defaults: +./mailcow-setup-relayhost.sh reset +``` diff --git a/docs/roundcube.md b/docs/roundcube.md new file mode 100644 index 000000000..8fdc15eb9 --- /dev/null +++ b/docs/roundcube.md @@ -0,0 +1,83 @@ +Download Roundcube 1.3.x (beta at the time of Feb 2017) to the web htdocs directory and extract it (here `rc/`): +``` +cd data/web/rc +wget -O - https://github.com/roundcube/roundcubemail/releases/download/1.3-beta/roundcubemail-1.3-beta-complete.tar.gz | tar xfvz - +# Change folder name +mv roundcubemail-1.3* rc +# Change permissions +chown -R root: rc/ +``` + +Create a file `data/web/rc/config/config.inc.php` with the following content. + +**Change the `des_key` parameter to a random value.** It is used to temporarily store your IMAP password. + +``` + array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +$config['enable_installer'] = false; +$config['smtp_conn_options'] = array( +'ssl' => array('verify_peer' => false, 'verify_peer_name' => false, 'allow_self_signed' => true) +); +``` + +Point your browser to `https://myserver/rc/installer` and follow the instructions. +Initialize the database and leave the installer. + +**Delete the directory `data/web/rc/installer` after a successful installation!** + +### Enable change password function in Roundcube + +Open `data/web/rc/config/config.inc.php` and enable the password plugin: + +``` +... +$config['plugins'] = array( + 'archive', + 'password', +); +... +``` + +Open `data/web/rc/plugins/password/password.php`, search for `case 'ssha':` and add above: + +``` + case 'ssha256': + $salt = rcube_utils::random_bytes(8); + $crypted = base64_encode( hash('sha256', $password . $salt, TRUE ) . $salt ); + $prefix = '{SSHA256}'; + break; +``` + +Open `data/web/rc/plugins/password/config.inc.php` and change the following parameters (or add them at the bottom of that file): + +``` +$config['password_driver'] = 'sql'; +$config['password_algorithm'] = 'ssha256'; +$config['password_algorithm_prefix'] = '{SSHA256}'; +$config['password_query'] = "UPDATE mailbox SET password = %P WHERE username = %u"; +``` diff --git a/docs/rp.md b/docs/rp.md new file mode 100644 index 000000000..f00d5f182 --- /dev/null +++ b/docs/rp.md @@ -0,0 +1,80 @@ +You don't need to change the Nginx site that comes with mailcow: dockerized. +mailcow: dockerized trusts the default gateway IP 172.22.1.1 as proxy. This is very important to control access to Rspamd's web UI. + +1\. Make sure you change HTTP_BIND and HTTPS_BIND in `mailcow.conf` to a local address and set the ports accordingly, for example: +``` bash +HTTP_BIND=127.0.0.1 +HTTP_PORT=8080 +HTTPS_PORT=127.0.0.1 +HTTPS_PORT=8443 +``` +** IMPORTANT: Do not use port 8081 ** + +Recreate affected containers by running `docker-compose up -d`. + +2\. Configure your local webserver as reverse proxy: + +### Apache 2.4 +``` apache + + ServerName mail.example.org + ServerAlias autodiscover.example.org + ServerAlias autoconfig.example.org + + [...] + # You should proxy to a plain HTTP session to offload SSL processing + ProxyPass / http://127.0.0.1:8080/ + ProxyPassReverse / http://127.0.0.1:8080/ + + ProxyPreserveHost On + ProxyAddHeaders On + + # This header does not need to be set when using http + RequestHeader set X-Forwarded-Proto "https" + + your-ssl-configuration-here + [...] + + # If you plan to proxy to a HTTPS host: + #SSLProxyEngine On + + # If you plan to proxy to an untrusted HTTPS host: + #SSLProxyVerify none + #SSLProxyCheckPeerCN off + #SSLProxyCheckPeerName off + #SSLProxyCheckPeerExpire off + +``` + +### Nginx +``` +server { + listen 443; + server_name mail.example.org autodiscover.example.org autoconfig.example.org; + + [...] + your-ssl-configuration-here + + location / { + proxy_pass http://127.0.0.1:8080/; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + [...] +} +``` + +### HAProxy +``` +frontend https-in + bind :::443 v4v6 ssl crt mailcow.pem + default_backend mailcow + +backend mailcow + option forwardfor + http-request set-header X-Forwarded-Proto https if { ssl_fc } + http-request set-header X-Forwarded-Proto http if !{ ssl_fc } + server mailcow 127.0.0.1:8080 check +``` \ No newline at end of file diff --git a/docs/rspamd.md b/docs/rspamd.md new file mode 100644 index 000000000..a80b2359f --- /dev/null +++ b/docs/rspamd.md @@ -0,0 +1,36 @@ +### Learn spam and ham + +Rspamd learns mail as spam or ham when you move a message in or out of the junk folder to any mailbox besides trash. +This is archived by using the Dovecot plugin "antispam" and a simple parser script. + +Rspamd also auto-learns mail when a high or low score is detected (see https://rspamd.com/doc/configuration/statistic.html#autolearning) + +The bayes statistics are written to Redis as keys `BAYES_HAM` and `BAYES_SPAM`. + +You can also use Rspamd's web ui to learn ham and/or spam. + +### Learn ham or spam from existing directory + +You can use a one-liner to learn mail in plain-text (uncompressed) format: +``` +# Ham +for file in /my/folder/cur/*; do docker exec -i $(docker-compose ps -q rspamd-mailcow) rspamc learn_ham < $file; done +# Spam +for file in /my/folder/.Junk/cur/*; do docker exec -i $(docker-compose ps -q rspamd-mailcow) rspamc learn_spam < $file; done +``` + +Consider attaching a local folder as new volume to `rspamd-mailcow` in `docker-compose.yml` and learn given files inside the container. This can be used as workaround to parse compressed data with zcat. Example: + +``` +for file in /data/old_mail/.Junk/cur/*; do rspamc learn_spam < zcat $file; done +``` + +### CLI tools + +``` +docker-compose exec rspamd-mailcow rspamc --help +docker-compose exec rspamd-mailcow rspamadm --help +``` + +See [Rspamd documentation](https://rspamd.com/doc/index.html) + diff --git a/docs/rspamd_ui.md b/docs/rspamd_ui.md new file mode 100644 index 000000000..39cca4cd3 --- /dev/null +++ b/docs/rspamd_ui.md @@ -0,0 +1,20 @@ +At first you may want to setup Rspamds web interface which provides some useful features and information. + +1\. Generate a Rspamd controller password hash: +``` +docker-compose exec rspamd-mailcow rspamadm pw +``` + +2\. Replace the default hash in `data/conf/rspamd/override.d/worker-controller.inc` by your newly generated: +``` +enable_password = "myhash"; +``` + +You can use `password = "myhash";` instead of `enable_password` to disable write-access in the web UI. + +3\. Restart rspamd: +``` +docker-compose restart rspamd-mailcow +``` + +Open https://${MAILCOW_HOSTNAME}/rspamd in a browser and login! diff --git a/docs/sender_rcv.md b/docs/sender_rcv.md new file mode 100644 index 000000000..dd3e2e5db --- /dev/null +++ b/docs/sender_rcv.md @@ -0,0 +1,33 @@ +When a mailbox is created, a user is allowed to send mail from and receive mail for his own mailbox address. + + Mailbox me@example.org is created. example.org is a primary domain. + Note: a mailbox cannot be created in an alias domain. + + me@example.org is only known as me@example.org. + me@example.org is allowed to send as me@example.org. + +We can add an alias domain for example.org: + + Alias domain alias.com is added and assigned to primary domain example.org. + me@example.org is now known as me@example.org and me@alias.com. + me@example.org is now allowed to send as me@example.org and me@alias.com. + +We can add aliases for a mailbox to receive mail for and to send from this new address. + +It is important to know, that you are not able to receive mail for `my-alias@my-alias-domain.tld`. You would need to create this particular alias. + + me@example.org is assigned the alias alias@example.org + me@example.org is now known as alias@example.org, me@alias.com, alias@example.org + + me@example.org is NOT known as alias@alias.com. + +Administrators and domain administrators can edit mailboxes to allow specific users to send as other mailbox users ("delegate" them). + +You can choose between mailbox users or completely disable the sender check for domains. + +### SOGo "mail from" addresses + +Mailbox users can, obviously, select their own mailbox address, as well as all alias addresses and aliases that exist through alias domains. + +If you want to select another _existing_ mailbox user as your "mail from" address, this user has to delegate you access through SOGo (see SOGo documentation). Moreover a mailcow (domain) administrator +needs to grant you access as described above. diff --git a/docs/ssl.md b/docs/ssl.md new file mode 100644 index 000000000..aa672f37c --- /dev/null +++ b/docs/ssl.md @@ -0,0 +1,52 @@ +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_HOSTNAME} +- autodiscover.**example.org** +- autoconfig.**example.org** + +### Let's Encrypt + +This is just an example of how to obtain certificates with certbot. There are several methods! + +1\. Get the certbot client: +``` bash +wget https://dl.eff.org/certbot-auto -O /usr/local/sbin/certbot && chmod +x /usr/local/sbin/certbot +``` + +2\. Make sure you set `HTTP_BIND=0.0.0.0` and `HTTP_PORT=80` in `mailcow.conf` or setup a reverse proxy to enable connections to port 80. If you changed HTTP_BIND, then rebuild Nginx: +``` bash +docker-compose up -d +``` + +3\. Request the certificate with the webroot method: +``` bash +cd /path/to/git/clone/mailcow-dockerized +source mailcow.conf +certbot certonly \ + --webroot \ + -w ${PWD}/data/web \ + -d ${MAILCOW_HOSTNAME} \ + -d autodiscover.example.org \ + -d autoconfig.example.org \ + --email you@example.org \ + --agree-tos +``` + +**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} +mv data/assets/ssl/key.{pem,pem.backup} +ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/fullchain.pem) data/assets/ssl/cert.pem +ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/privkey.pem) data/assets/ssl/key.pem +``` + +5\. Restart affected containers: +``` +docker-compose restart postfix-mailcow dovecot-mailcow nginx-mailcow +``` + +When renewing certificates, run the last two steps (link + restart) as post-hook in a script. diff --git a/docs/syslog.md b/docs/syslog.md new file mode 100644 index 000000000..1b1c1d126 --- /dev/null +++ b/docs/syslog.md @@ -0,0 +1,76 @@ +Enable Rsyslog to receive logs on 524/tcp: + +``` +# This setting depends on your Rsyslog version and configuration format. +# For most Debian derivates it will work like this... +$ModLoad imtcp +$TCPServerAddress 127.0.0.1 +$InputTCPServerRun 524 + +# ...while for Ubuntu 16.04 it looks like this: +module(load="imtcp") +input(type="imtcp" address="127.0.0.1" port="524") + +# No matter your Rsyslog version, you should set this option to off +# if you plan to use Fail2ban +$RepeatedMsgReduction off +``` + +Restart rsyslog after enabling the TCP listener. + +Now setup Docker daemon to start with the syslog driver. +This enables the syslog driver for all containers! + +Debian users can change the startup configuration in `/etc/default/docker` while CentOS users find it in `/etc/sysconfig/docker`: +``` +... +DOCKER_OPTS="--log-driver=syslog --log-opt syslog-address=tcp://127.0.0.1:524" +... +``` + +**Caution:** For some reason Ubuntu 16.04 and some, but not all, systemd based distros do not read the defaults file parameters. + +Just run `systemctl edit docker.service` and add the following content to fix it. + +**Note:** If "systemctl edit" is not available, just copy the content to `/etc/systemd/system/docker.service.d/override.conf`. + +The first empty ExecStart parameter is not a mistake. + +``` +[Service] +EnvironmentFile=/etc/default/docker +ExecStart= +ExecStart=/usr/bin/docker daemon -H fd:// $DOCKER_OPTS +``` + +Restart the Docker daemon and run `docker-compose down && docker-compose up -d` to recreate the containers. + +### Fail2ban + +**This is a subsection of "Log to Syslog", which is required for Fail2ban to work.** + +Open `/etc/fail2ban/filter.d/common.conf` and search for the prefix_line parameter, change it to ".*": + +``` +__prefix_line = .* +``` + +Create `/etc/fail2ban/jail.d/dovecot.conf`... +``` +[dovecot] +enabled = true +filter = dovecot +logpath = /var/log/syslog +chain = FORWARD +``` + +and `jail.d/postfix-sasl.conf`: +``` +[postfix-sasl] +enabled = true +filter = postfix-sasl +logpath = /var/log/syslog +chain = FORWARD +``` + +Restart Fail2ban. diff --git a/docs/tagging.md b/docs/tagging.md new file mode 100644 index 000000000..36101d5e7 --- /dev/null +++ b/docs/tagging.md @@ -0,0 +1,5 @@ +Mailbox users can tag their mail address like in `me+facebook@example.org` and choose between to setups to handle this tag: + +1\. Move this message to a subfolder "facebook" (will be created lower case if not existing) + +2\. Prepend the tag to the subject: "[facebook] Subject" diff --git a/docs/tfa.md b/docs/tfa.md new file mode 100644 index 000000000..60ad71df0 --- /dev/null +++ b/docs/tfa.md @@ -0,0 +1,31 @@ +So far three methods for TFA are implemented. + +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. + +The key used to login will be displayed in green, while other keys remain grey. + +### Yubi OTP + +The Yubi API ID and Key will be checked against the Yubico Cloud API. When setting up TFA you will be asked for your personal API account for this key. +The API ID, API key and the first 12 characters (your YubiKeys ID in modhex) are stored in the MySQL table as secret. + +### U2F + +Only Google Chrome (+derivates) and Opera support U2F authentication to this day natively. +For Firefox you will need to install the "U2F Support Add-on" as provided on [mozilla.org](https://addons.mozilla.org/en-US/firefox/addon/u2f-support-add-on/). + +U2F works without an internet connection. + +### TOTP + +The best known TFA method mostly used with a smartphone. diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 000000000..ee3d97891 --- /dev/null +++ b/docs/update.md @@ -0,0 +1,71 @@ +There is no update routine. You need to refresh your pulled repository clone and apply your local changes (if any). Actually there are many ways to merge local changes. + +### Step 1, method 1 +Stash all local changes, pull changes from the remote master branch and apply your stash on top of it. You will most likely see warnings about non-commited changes; you can ignore them: + +``` +# Stash local changes +git stash +# Re-pull master +git pull +# Apply stash and remove it +git stash pop +``` + +### Step 1, method 2 +Fetch new data from GitHub, commit changes and merge remote repository: + +``` +# Get updates/changes +git fetch +# Add all changed files to local clone +git add -A +# Commit changes, ignore git complaining about username and mail address +git commit -m "Local config aat $(date)" +# Merge changes +git merge +``` + +If git complains about conflicts, solve them! Example: +``` +CONFLICT (content): Merge conflict in data/web/index.php +``` + +Open `data/web/index.php`, solve the conflict, close the file and run `git add -A` + `git commit -m "Solved conflict"`. + +### Step 1, method 3 + +Thanks to fabreg @ GitHub! + +In case both methods do not work (for many reason like you're unable to fix the CONFLICTS or any other reasons) you can simply start all over again. + +Keep in mind that all local changes _to configuration files_ will be lost. However, your volumes will not be removed. + +- Copy mailcow.conf somewhere outside the mailcow-dockerized directory +- Stop and remove mailcow containers: `docker-compose down` +- Delete the directory or rename it +- Clone the remote repository again (`git clone https://github.com/andryyy/mailcow-dockerized && cd mailcow-dockerized`). **Pay attention** to this step - the folder must have the same name of the previous one! +- Copy back your previous `mailcow.conf` into the mailcow-dockerizd folder + +If you forgot to stop Docker before deleting the cloned directoy, you can use the following commands: +``` +docker stop $(docker ps -a -q) +docker rm $(docker ps -a -q) +``` + +### Step 2 + +Pull new images (if any) and recreate changed containers: + +``` +docker-compose pull +docker-compose up -d --remove-orphans +``` + +### Step 3 +Clean-up dangling (unused) images and volumes: + +``` +docker rmi -f $(docker images -f "dangling=true" -q) +docker volume rm $(docker volume ls -qf dangling=true) +``` diff --git a/docs/why_bind9.md b/docs/why_bind9.md new file mode 100644 index 000000000..c7d43a5d7 --- /dev/null +++ b/docs/why_bind9.md @@ -0,0 +1,6 @@ +For DNS blacklist lookups and DNSSEC. + +Most systems use either a public or a local caching DNS resolver. +That's a very bad idea when it comes to filter spam using DNS-based blackhole lists (DNSBL) or similar technics. +Most if not all providers apply a rate limit based on the DNS resolver that is used to query their service. +Using a public resolver like Googles 4x8, OpenDNS or any other shared DNS resolver like your ISPs will hit that limit very soon. diff --git a/mkdocs.yml b/mkdocs.yml index a0156231f..02e7859bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,21 +2,46 @@ site_name: "mailcow: dockerized documentation" repo_url: https://github.com/mailcow/mailcow-dockerized remote_branch: gh-pages theme: material +markdown_extensions: + - codehilite(guess_lang=true) + - toc(permalink=true) +pages: +- 'Information and support': 'index.md' +- 'Installation & update': + - 'Installation': 'install.md' + - 'Update': 'update.md' +- 'First Steps': + - 'SSL': 'ssl.md' + - 'Rspamd Web UI': 'rspamd_ui.md' + - 'Reverse Proxy': 'rp.md' + - 'Setup a relayhost (optional)': 'relayhost.md' + - 'Log to Syslog': 'syslog.md' + - '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' + - 'Redis': 'redis.md' + - 'MySQL': 'mysql.md' + - 'Rspamd': 'rspamd.md' + - 'Tagging': 'tagging.md' + - 'Why bind9?': 'why_bind9.md' +- 'Third party apps': + - 'Roundcube': 'roundcube.md' + - 'Portainer': 'portainer.md' + - 'Gogs': 'gogs.md' extra: + logo: 'images/logo.svg' palette: primary: 'indigo' - accent: 'yellow' - logo: 'images/logo.svg' - -markdown_extensions: - - admonition - - codehilite(guess_lang=true) - - footnotes - - meta - - toc(permalink=true) - -pages: - - 'About mailcow: dockerized': 'index.md' - - 'Installation': 'install.md' - - 'First Steps': 'first_steps.md' - - 'Usage & Examples': 'u_and_e.md' + accent: 'orange'