diff --git a/docs/attach_service.md b/docs/debug-attach_service.md similarity index 85% rename from docs/attach_service.md rename to docs/debug-attach_service.md index a45a10ce6..826c66207 100644 --- a/docs/attach_service.md +++ b/docs/debug-attach_service.md @@ -8,7 +8,7 @@ docker-compose exec $Service_Name /bin/bash ### Connecting to Services -If you whant to connect to a service / application directly it is always a good idea to `source mailcow.conf` to get all relevant variables in your environment. +If you want to connect to a service / application directly it is always a good idea to `source mailcow.conf` to get all relevant variables into your environment. #### MySQL @@ -33,7 +33,7 @@ Here is a brief overview of what container / service does what: | mysql-mailcow | Stores SOGo's and 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 | +| redis-mailcow | Storage back-end 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 | diff --git a/docs/debug-common_problems.md b/docs/debug-common_problems.md new file mode 100644 index 000000000..cf712e11c --- /dev/null +++ b/docs/debug-common_problems.md @@ -0,0 +1,71 @@ +Here we list common problems and possible solutions: + +## Mail loops back to myself + +Please check in your mailcow UI if you made the domain a **backup MX**: + +![Check your MX Backup settings](images/mailcow-backupmx.png) + +## I can receive but not send mails + +There are a lot of things that could prevent you from sending mail: + +- Check if your IP is on any blacklists. You could use [dnsbl.info](http://www.dnsbl.info/) or any other similar service to check for your IP. +- There are some consumer ISP routers out there, that block mail ports for non whitelisted domains. Please check if you can reach your server on the ports `465` or `587`: + +``` +# telnet 74.125.133.27 465 +Trying 74.125.133.27... +Connected to 74.125.133.27. +Escape character is '^]'. +``` + +## My mails are identified as Spam + +Please read our guide on [DNS configuration](prerequesite-dns.md). + +## docker-compose throws weird errors + +... like: + +- `ERROR: Invalid interpolation format ...` +- `AttributeError: 'NoneType' object has no attribute 'keys'`. +- `ERROR: In file './docker-compose.yml' service 'version' doesn't have any configuration options`. + +When you encounter one or similar messages while trying to run mailcow: dockerized please check if you have the **latest** version of **Docker** and **docker-compose** + +## Container XY is unhealthy + +This error tries to tell you that one of the (health) conditions for a certain container are not met. Therefore it can't be started. This can have several reasons, the most common one is an updated git clone but old docker image or vice versa. + +A wrong configured firewall could also cause such a failure. The containers need to be able to talk to each other over the network 172.22.1.1/24. + +It might also be wrongly linked file (i.e. SSL certificate) that prevents a crucial container (nginx) from starting, so always check your logs to get an Idea where your problem is coming from. + + +## Address already in use + +If you get an error message like: + +``` +ERROR: for postfix-mailcow Cannot start service postfix-mailcow: driver failed programming external connectivity on endpoint mailcowdockerized_postfix-mailcow_1: Error starting userland proxy: listen tcp 0.0.0.0:25: bind: address already in use +``` + +while trying to start / install mailcow: dockerized, make sure you've followed our section on the [prerequisites](prerequesite-system/#firewall-ports). + +## XYZ can't connect to ... + +Please check your local firewall! + +If you experience connection problems from home, please check your ISP router's firewall too, some of them block mail traffic on the *SMTP* (587) or *SMTPS* (465) ports. It could also be, that your ISP is blocking the ports for *SUBMISSION* (25). + +While Linux users can chose from a variety of tools[^1] to check if a port is open, the Windows user has only the command `telnet host port` available by default (and it has to be activated since Windows Vista). + +To enable telnet on a Windows after Vista please check this [guide](https://social.technet.microsoft.com/wiki/contents/articles/910.windows-7-enabling-telnet-client.aspx) or enter the following command in an terminal **with administrator priviliges**: + +``` +dism /online /Enable-Feature /FeatureName:TelnetClient +``` + + +[^1]: [netcat](https://linux.die.net/man/1/nc), [nmap](https://linux.die.net/man/1/nmap), [openssl](https://wiki.openssl.org/index.php/Manual:S_client(1)), [telnet](https://linux.die.net/man/1/telnet), etc. diff --git a/docs/debug_logs.md b/docs/debug-logs.md similarity index 79% rename from docs/debug_logs.md rename to docs/debug-logs.md index d3ec41f0c..1926ce420 100644 --- a/docs/debug_logs.md +++ b/docs/debug-logs.md @@ -1,4 +1,4 @@ -To view the logs of all mailcow: dockerized related containers, you can use `docker-compose logs` inside your mailcow-dockerized folder that contains your `mailcow.conf`. This is usually a bit mutch but you could trim the output with `--tail=100` to the last 100 lines, or add a `-f` to follow the live output of all your services. +To view the logs of all mailcow: dockerized related containers, you can use `docker-compose logs` inside your mailcow-dockerized folder that contains your `mailcow.conf`. This is usually a bit much, but you could trim the output with `--tail=100` to the last 100 lines per container, or add a `-f` to follow the live output of all your services. To view the logs of a specific service you can use `docker-compose logs [options] $Service_Name` diff --git a/docs/reset_pw.md b/docs/debug-reset_pw.md similarity index 80% rename from docs/reset_pw.md rename to docs/debug-reset_pw.md index e455fa01a..48b5f4eb3 100644 --- a/docs/reset_pw.md +++ b/docs/debug-reset_pw.md @@ -7,12 +7,6 @@ cd mailcow_path bash mailcow-reset-admin.sh ``` -## Remove Two-Factor Authentication - -``` - -``` - ## Reset MySQL Passwords Stop the stack by running `docker-compose stop`. @@ -26,6 +20,8 @@ docker-compose run --rm --entrypoint '/bin/sh -c "gosu mysql mysqld --skip-grant ### 1\. Find database name ``` +# source mailcow.conf +# docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} MariaDB [(none)]> show databases; +--------------------+ | Database | @@ -57,3 +53,12 @@ MariaDB [(none)]> UPDATE mysql.user SET authentication_string = PASSWORD('gotr00 MariaDB [(none)]> UPDATE mysql.user SET authentication_string = PASSWORD('mookuh'), password = PASSWORD('mookuh') WHERE User = 'mailcow' AND Host = '%'; MariaDB [(none)]> FLUSH PRIVILEGES; ``` + +## Remove Two-Factor Authentication + +This works similar to resetting a MySQL password, now we do it from the host without connecting to the MySQL CLI: + +``` +source mailcow.conf +docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DELETE FROM tfa WHERE username='YOUR_USERNAME';" +``` diff --git a/docs/rm_volumes.md b/docs/debug-rm_volumes.md similarity index 89% rename from docs/rm_volumes.md rename to docs/debug-rm_volumes.md index 74ed50280..3bdbb52a0 100644 --- a/docs/rm_volumes.md +++ b/docs/debug-rm_volumes.md @@ -1,4 +1,4 @@ -You may want to remove a set of persistend data to resolve a conflict or to start over: +You may want to remove a set of persistent data to resolve a conflict or to start over: ``` docker volume rm mailcowdockerized_${VOLUME_NAME} diff --git a/docs/debug.md b/docs/debug.md index b45debb89..aa05b950d 100644 --- a/docs/debug.md +++ b/docs/debug.md @@ -1,9 +1,16 @@ When a problem occurs, then always for a reason! What you want to do in such a case is: 1. Read your logs; follow them to see what the reason for your problem is. +<<<<<<< HEAD 2. Follow the leads given to you in your logfiles and start investigating. 3. Restarting the troubled service or the whole stack to see if the problem persists. 4. Read the documentation of the troubled service and search it's bugtracker for your problem. 5. Search our [issues](https://github.com/mailcow/mailcow-dockerized/issues) for your problem. +======= +2. Follow the leads given to you in your log files and start investigating. +3. Restart the troubled service or the whole stack to see if the problem persists. +4. Read the documentation of the troubled service and search it's bug tracker for your problem. +5. Search our [issues](https://github.com/mailcow/mailcow-dockerized/issues) and [forum](https://forum.mailcow.email/) for topics related to your problem. +>>>>>>> 2ef7ae0f89cf3f9e8c7a73c99449cc50215450d7 6. [Create an issue](https://github.com/mailcow/mailcow-dockerized/issues) over at our GitHub repository if you think your problem might be a bug or a missing feature you badly need. But please make sure, that you include **all the logs** and a full description to your problem. 8. Connect to IRC ([chat.freenode.net](https://webchat.freenode.net/)) and join our IRC channel [#mailcow](irc://chat.freenode.net:6667/mailcow). diff --git a/docs/local_mta.md b/docs/firststeps-local_mta.md similarity index 100% rename from docs/local_mta.md rename to docs/firststeps-local_mta.md diff --git a/docs/relayhost.md b/docs/firststeps-relayhost.md similarity index 100% rename from docs/relayhost.md rename to docs/firststeps-relayhost.md diff --git a/docs/rp.md b/docs/firststeps-rp.md similarity index 100% rename from docs/rp.md rename to docs/firststeps-rp.md diff --git a/docs/rspamd_ui.md b/docs/firststeps-rspamd_ui.md similarity index 100% rename from docs/rspamd_ui.md rename to docs/firststeps-rspamd_ui.md diff --git a/docs/sender_rcv.md b/docs/firststeps-sender_rcv.md similarity index 97% rename from docs/sender_rcv.md rename to docs/firststeps-sender_rcv.md index dd3e2e5db..abbc2acfe 100644 --- a/docs/sender_rcv.md +++ b/docs/firststeps-sender_rcv.md @@ -1,6 +1,6 @@ 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. + 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. diff --git a/docs/ssl.md b/docs/firststeps-ssl.md similarity index 67% rename from docs/ssl.md rename to docs/firststeps-ssl.md index ea0f1895b..96c20a8f6 100644 --- a/docs/ssl.md +++ b/docs/firststeps-ssl.md @@ -1,4 +1,5 @@ -mailcow dockerized comes with a snakeoil CA "mailcow" and a server certificate in `data/assets/ssl`. Please use your own trusted certificates. +!!! warning + mailcow dockerized comes with a snake-oil CA "mailcow" and a server certificate in `data/assets/ssl`. Please use your own trusted certificates. mailcow uses **at least** 3 domain names that should be covered by your new certificate: @@ -6,7 +7,7 @@ mailcow uses **at least** 3 domain names that should be covered by your new cert - autodiscover.**example.org** - autoconfig.**example.org** -### Let's Encrypt +## Let's Encrypt This is just an example of how to obtain certificates with certbot. There are several methods! @@ -35,7 +36,7 @@ certbot certonly \ ``` !!! warning - Remember to replace the example.org domain with your own domain, this command will not work if you dont. + Remember to replace the example.org domain with your own domain, this command will not work if you don't. 4\. Create hard links to the full path of the new certificates. Assuming you are still in the mailcow root folder: ``` bash @@ -51,3 +52,18 @@ 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. + +## Check your configuration + +To check if nginx serves the correct certificate, simply use a browser of your choice and check the displayed certificate. + +To check the certificate served by dovecot or postfix we will use `openssl`: + +``` +# Connect via SMTP (25) +openssl s_client -starttls smtp -crlf -connect mx.mailcow.email:25 +# Connect via SMTPS (465) +openssl s_client -showcerts -connect mx.mailcow.email:465 +# Connect via SUBMISSION (587) +openssl s_client -starttls smtp -crlf -connect mx.mailcow.email:587 +``` diff --git a/docs/syslog.md b/docs/firststeps-syslog.md similarity index 100% rename from docs/syslog.md rename to docs/firststeps-syslog.md diff --git a/docs/images/mailcow-backupmx.png b/docs/images/mailcow-backupmx.png new file mode 100644 index 000000000..889b2f7a1 Binary files /dev/null and b/docs/images/mailcow-backupmx.png differ diff --git a/docs/index.md b/docs/index.md index b6770e712..31d739462 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ Let us know about your ideas in #mailcow @ Freenode. -[Servercow](https://www.servercow.de) - hosted mailcow, KVM based virtual servers, webhosting and more. +[Servercow](https://www.servercow.de) - hosted mailcow, KVM based virtual servers, web-hosting 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) @@ -29,13 +29,13 @@ The integrated **mailcow UI** allows administrative work on your mail server ins - DKIM key management - Black- and whitelists per domain and per user -- Spam score managment per-user (reject spam, mark spam, greylist) +- Spam score management 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) +- Prepend mail tags to subject or move mail to sub folder (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 +- TFA: Yubi OTP and U2F USB (Google Chrome and derivatives only), TOTP - Add domains, mailboxes, aliases, domain aliases and SOGo resources - Add whitelisted hosts to forward mail to mailcow diff --git a/docs/update.md b/docs/install-update.md similarity index 90% rename from docs/update.md rename to docs/install-update.md index ee3d97891..2329b3f8e 100644 --- a/docs/update.md +++ b/docs/install-update.md @@ -13,7 +13,7 @@ git stash pop ``` ### Step 1, method 2 -Fetch new data from GitHub, commit changes and merge remote repository: +Fetch new data from GitHub, commit changes and merge remote repository: ``` # Get updates/changes @@ -21,7 +21,7 @@ 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)" +git commit -m "Local config at $(date)" # Merge changes git merge ``` @@ -45,9 +45,9 @@ Keep in mind that all local changes _to configuration files_ will be lost. Howev - 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 +- 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: +If you forgot to stop Docker before deleting the cloned directory, you can use the following commands: ``` docker stop $(docker ps -a -q) docker rm $(docker ps -a -q) diff --git a/docs/install.md b/docs/install.md index dc5bcbd4d..d3af20da1 100644 --- a/docs/install.md +++ b/docs/install.md @@ -35,7 +35,7 @@ If you plan to use a reverse proxy, you can, for example, bind HTTPS to 127.0.0. You may need to stop an existing pre-installed MTA which blocks port 25/tcp. See [this chapter](https://andryyy.github.io/mailcow-dockerized/first_steps/#install-a-local-mta) to learn how to reconfigure Postfix to run besides mailcow after a successful installation. -5\. Pull the images and run the composer file. The paramter `-d` will start mailcow: dockerized detached: +5\. Pull the images and run the composer file. The parameter `-d` will start mailcow: dockerized detached: ``` docker-compose pull docker-compose up -d diff --git a/docs/mc14_migrate.md b/docs/migrate-mc014.md similarity index 91% rename from docs/mc14_migrate.md rename to docs/migrate-mc014.md index 74d007f9a..0bd0d47a5 100644 --- a/docs/mc14_migrate.md +++ b/docs/migrate-mc014.md @@ -4,7 +4,7 @@ !!! info 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. + Lastly please check the section on how to [import / restore](u_e-backup_restore-maildir/#restore) your maildir backup to get an idea how to migrate your mails. ## Create mailcow db backups @@ -57,7 +57,7 @@ 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} \ + --host ${DBHOST} -u${DBUSER} -p${DBPASS} ${DBNAME} \ alias alias_domain domain domain_admins mailbox quota2 sender_acl > backup_mailcow.sql ``` @@ -85,19 +85,19 @@ MariaDB [mailcow]> show tables; ## Import your backups: - ``` - # source mailcow.conf - # docker exec -i $(docker-compose ps -q mysql-mailcow) mysql -u${DBUSER} -p${DBPASS} ${DBNAME} < backup_mailcow.sql - ``` +``` +# 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`: +Recalculate used quota with `doveadm`: - ``` - # docker-compose exec dovecot-mailcow doveadm quota recalc -A - ``` +``` +# docker-compose exec dovecot-mailcow doveadm quota recalc -A +``` - Restart services: +Restart services: - ``` - # docker-compose restart - ``` +``` +# docker-compose restart +``` diff --git a/docs/dns.md b/docs/prerequesite-dns.md similarity index 91% rename from docs/dns.md rename to docs/prerequesite-dns.md index ef573eb06..ebaf53114 100644 --- a/docs/dns.md +++ b/docs/prerequesite-dns.md @@ -3,9 +3,9 @@ Below you can find a list of **recommended DNS records**. While some are mandato ## References - A good article covering all relevant topics: - ["3 DNS Records Every Email Marketer Must Know"](https://www.rackaid.com/blog/email-dns-records) + ["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) + ["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/) @@ -37,7 +37,7 @@ In the example DNS zone file snippet below, a simple **SPF** TXT record is used 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) for further reading. ``` -default._domainkey IN TXT "v=DKIM1; k=rsa; t=s; s=email; p=..." +dkim._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)). @@ -77,4 +77,4 @@ If you are interested in statistics, you can additionally register with the [Pos @ IN TXT "google-site-verification=..." ``` -[^1]: A **Fully Qualified Domain Name** (**FQDN**) is the complete (absolute) domain name for a specific computer or host, on the Internet. The FQDN consists of at least three parts devided by a dot: the hostname (myhost), the domain name (mydomain) and the toplevel domain in short **tld** (com). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name 'mailcow' and the tld `email`. +[^1]: A **Fully Qualified Domain Name** (**FQDN**) is the complete (absolute) domain name for a specific computer or host, on the Internet. The FQDN consists of at least three parts divided by a dot: the hostname (myhost), the domain name (mydomain) and the top level domain in short **tld** (com). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name 'mailcow' and the tld `email`. diff --git a/docs/requirements.md b/docs/prerequesite-system.md similarity index 89% rename from docs/requirements.md rename to docs/prerequesite-system.md index 74efcbca2..d4dbf4ac7 100644 --- a/docs/requirements.md +++ b/docs/prerequesite-system.md @@ -12,12 +12,12 @@ Before you run **mailcow: dockerized**, there are a few requirements that you sh 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 | +| Resource | mailcow: dockerized | +| ----------------------- | --------------------- | +| CPU | 1 GHz | +| RAM                     | 1 GiB         | +| Disk | 5 GiB (without mails) | +| System Type | x86_64 | ## Firewall & Ports @@ -31,7 +31,7 @@ If this command returns any results please remove or stop the application runnin ### Default Ports -If you have a firewall already up and running please make sure that these ports are open for incomming connections: +If you have a firewall already up and running please make sure that these ports are open for incoming connections: | Service | Protocol | Port | Container | Variable | | --------------------|:--------:|:-------|:----------------|--------------------------------| @@ -67,7 +67,7 @@ NTP synchronized: yes 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. +The lines `NTP enabled: yes` and `NTP synchronized: yes` indicate wether you have NTP enabled and if it's synchronized. To enable NTP you need to run the command `timedatectl set-ntp true`. You also need to edit your `/etc/systemd/timesyncd.conf`: diff --git a/docs/gogs.md b/docs/third_party-gogs.md similarity index 92% rename from docs/gogs.md rename to docs/third_party-gogs.md index b196ccf37..2aa744dcb 100644 --- a/docs/gogs.md +++ b/docs/third_party-gogs.md @@ -1,6 +1,6 @@ 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: +1\. Open `docker-compose.yml` and add Gogs: ``` gogs-mailcow: @@ -27,7 +27,7 @@ location /gogs/ { } ``` -3\. Open `mailcow.conf` and define ports you want gogs to open, as well as future database password. Example: +3\. Open `mailcow.conf` and define ports you want Gogs to open, as well as future database password. Example: ``` GOGS_WWW_PORT=3000 diff --git a/docs/portainer.md b/docs/third_party-portainer.md similarity index 100% rename from docs/portainer.md rename to docs/third_party-portainer.md diff --git a/docs/roundcube.md b/docs/third_party-roundcube.md similarity index 100% rename from docs/roundcube.md rename to docs/third_party-roundcube.md diff --git a/docs/80_to_443.md b/docs/u_e-80_to_443.md similarity index 100% rename from docs/80_to_443.md rename to docs/u_e-80_to_443.md diff --git a/docs/autodiscover_config.md b/docs/u_e-autodiscover_config.md similarity index 100% rename from docs/autodiscover_config.md rename to docs/u_e-autodiscover_config.md diff --git a/docs/backup_maildir.md b/docs/u_e-backup_restore-maildir.md similarity index 100% rename from docs/backup_maildir.md rename to docs/u_e-backup_restore-maildir.md diff --git a/docs/mysql.md b/docs/u_e-backup_restore-mysql.md similarity index 65% rename from docs/mysql.md rename to docs/u_e-backup_restore-mysql.md index 27d4c9bda..817d7b3b5 100644 --- a/docs/mysql.md +++ b/docs/u_e-backup_restore-mysql.md @@ -1,5 +1,3 @@ -MySQL is used to store the settings and / or usertables of the whole mail-stack (mailcow UI, SOGo, dovecot, postfix). - ## Backup ``` @@ -11,7 +9,8 @@ docker-compose exec mysql-mailcow mysqldump --default-character-set=utf8mb4 -u${ ## Restore -You should redirect the sql dump without Docker-Compose to prevent parsing errors. +!!! warning + You should redirect the SQL dump without `docker-compose` to prevent parsing errors. ``` cd /path/to/mailcow-dockerized diff --git a/docs/change_config.md b/docs/u_e-change_config.md similarity index 100% rename from docs/change_config.md rename to docs/u_e-change_config.md diff --git a/docs/deinstall.md b/docs/u_e-deinstall.md similarity index 77% rename from docs/deinstall.md rename to docs/u_e-deinstall.md index 09954536b..696351b67 100644 --- a/docs/deinstall.md +++ b/docs/u_e-deinstall.md @@ -7,5 +7,5 @@ docker-compose down -v --rmi all --remove-orphans !!! info - **-v** Remove named volumes declared in the `volumes` section of the Compose file and anonymous volumes attached to containers. - **--rmi ** Remove images. Type must be one of: `all`: Remove all images used by any service. `local`: Remove only images that don't have a custom tag set by the `image` field. - - **--remove-orphans** Remove containsers for services not defined in the compose file. - - By default `docker-compose down` only removes currently active containers and networks devinded in the `docker-compose.yml`. + - **--remove-orphans** Remove containers for services not defined in the compose file. + - By default `docker-compose down` only removes currently active containers and networks defined in the `docker-compose.yml`. diff --git a/docs/cust_dockerfiles.md b/docs/u_e-docker-cust_dockerfiles.md similarity index 100% rename from docs/cust_dockerfiles.md rename to docs/u_e-docker-cust_dockerfiles.md diff --git a/docs/dc_bash_compl.md b/docs/u_e-docker-dc_bash_compl.md similarity index 66% rename from docs/dc_bash_compl.md rename to docs/u_e-docker-dc_bash_compl.md index 3b82321dc..071e8fb3a 100644 --- a/docs/dc_bash_compl.md +++ b/docs/u_e-docker-dc_bash_compl.md @@ -1,3 +1,5 @@ +To get some sexy bash completion inside your containers simply execute the following: + ``` 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/u_e-dovecot-expunge.md b/docs/u_e-dovecot-expunge.md new file mode 100644 index 000000000..19cd21a14 --- /dev/null +++ b/docs/u_e-dovecot-expunge.md @@ -0,0 +1,44 @@ +If you want to delete old mails out of the `.Junk` or `.Trash` folders or maybe delete all read mails that are older than a certain amount of time you may use dovecot's tool doveadm [man doveadm-expunge](https://wiki.dovecot.org/Tools/Doveadm/Expunge). + +## The manual way + +That said, let's dive in: + +Delete a user's mails inside the junk folder that **are read** and **older** than 4 hours + +``` +docker-compose exec dovecot-mailcow doveadm expunge -u 'mailbox@example.com' mailbox 'Junk' SEEN not SINCE 4h +``` + +Delete **all** user's mails in the junk folder that are **older** than 7 days + +``` +docker-compose exec dovecot-mailcow doveadm expunge -A mailbox 'Junk' savedbefore 7d +``` + +Delete mails inside a custom folder **inside** a user's inbox that are **not** flagged and **older** than 2 weeks + +``` +docker-compose exec dovecot-mailcow doveadm expunge -u 'mailbox@example.com' mailbox 'INBOX/custom-folder' not FLAGGED not SINCE 2w +``` + +!!! info + For possible [time spans](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery#section_date_specification) or [search keys](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery#section_search_keys) have a look at [man doveadm-search-query](https://wiki.dovecot.org/Tools/Doveadm/SearchQuery) + +## Make it automatic + +If you want to automate such a task you can create a cron job on your host that calls a script like the one below: + +``` +#!/bin/bash +/usr/local/bin/docker-compose exec -T doveadm dovecot-mailcow doveadm expunge -A mailbox 'Junk' savedbefore 2w +/usr/local/bin/docker-compose exec -T doveadm expunge -A mailbox 'Junk' SEEN not SINCE 12h +[...] +``` + +To create a cron job you may execute `crontab -e` and insert something like the following to execute a script: + +``` +# Execute everyday at 04:00 A.M. +0 4 * * * /path/to/your/expunge_mailboxes.sh +``` diff --git a/docs/u_e-dovecot-more.md b/docs/u_e-dovecot-more.md new file mode 100644 index 000000000..09d0856ac --- /dev/null +++ b/docs/u_e-dovecot-more.md @@ -0,0 +1,48 @@ +Here is just an unsorted list of useful `doveadm` commands that could be useful. + +## doveadm quota + +The `quota get` and `quota recalc`[^1] commands are used to display or recalculate the current user's quota usage. The reported values are in *kilobytes*. + +To list the current quota status for a user / mailbox, do: + +``` +doveadm quota get -u 'mailbox@example.org' +``` + +To list the quota storage value for **all** users, do: + +``` +doveadm quota get -A |grep "STORAGE" +``` + +Recalculate a single user's quota usage: + +``` +doveadm quota recalc -u 'mailbox@example.org' +``` + +## doveadm search + +The `doveadm search`[^2] command is used to find messages matching your query. It can return the username, mailbox-GUID / -UID and message-GUIDs / -UIDs. + +To view the number of messages, by user, in their **.Trash** folder: + +``` +doveadm search -A mailbox 'Trash' | awk '{print $1}' | sort | uniq -c +``` + +Show all messages in a user's **inbox** older then 90 days: + +``` +doveadm search -u 'mailbox@example.org' mailbox 'INBOX' savedbefore 90d +``` + +Show **all messages** in **any folder** that are **older** then 30 days for `mailbox@example.org`: + +``` +doveadm search -u 'mailbox@example.org' mailbox "*" savedbefore 30d +``` + +[^1]:https://wiki.dovecot.org/Tools/Doveadm/Quota +[^2]:https://wiki.dovecot.org/Tools/Doveadm/Search diff --git a/docs/bl_wl.md b/docs/u_e-mailcow_ui-bl_wl.md similarity index 59% rename from docs/bl_wl.md rename to docs/u_e-mailcow_ui-bl_wl.md index c7ac71790..2c39b1112 100644 --- a/docs/bl_wl.md +++ b/docs/u_e-mailcow_ui-bl_wl.md @@ -4,4 +4,4 @@ To add or edit an entry to your **domain wide** filter table, login to your *mai !!! info - Be aware that a user [may override](spamfilter.md) this setting by setting his own black- and whitelist! + Be aware that a user [may override](u_e-mailcow_ui-spamfilter.md) this setting by setting his own black- and whitelist! diff --git a/docs/mailcow_ui.md b/docs/u_e-mailcow_ui-config.md similarity index 77% rename from docs/mailcow_ui.md rename to docs/u_e-mailcow_ui-config.md index 885e4b6e7..5b19433ab 100644 --- a/docs/mailcow_ui.md +++ b/docs/u_e-mailcow_ui-config.md @@ -4,11 +4,11 @@ The local configuration file is persistent over updates of mailcow. Try not to c mailcow UI configuration parameters can be to... -- ...change the default language* +- ...change the default language[^1] - ...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. +[^1]: 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/spamalias.md b/docs/u_e-mailcow_ui-spamalias.md similarity index 62% rename from docs/spamalias.md rename to docs/u_e-mailcow_ui-spamalias.md index 40e225a1a..17fd11d9b 100644 --- a/docs/spamalias.md +++ b/docs/u_e-mailcow_ui-spamalias.md @@ -1,5 +1,5 @@ These temporary email aliases are mostly used for places where we need to provide an email address but don't want future correspondence with. They are also called spam alias. -To create, delete or extend a temporary email aliase you need to login to mailcow's UI as a mailbox user and navigate to the tab **Temporary email aliases**: +To create, delete or extend a temporary email aliases you need to login to mailcow's UI as a mailbox user and navigate to the tab **Temporary email aliases**: ![How to set spam- or temporary email aliases in mailcow](images/mailcow-spamalias.png) diff --git a/docs/spamfilter.md b/docs/u_e-mailcow_ui-spamfilter.md similarity index 82% rename from docs/spamfilter.md rename to docs/u_e-mailcow_ui-spamfilter.md index 37c39b490..e41d4b19f 100644 --- a/docs/spamfilter.md +++ b/docs/u_e-mailcow_ui-spamfilter.md @@ -3,6 +3,6 @@ A mailbox user may adjust the spam filter and black- / whitelist settings for hi ![Where to adjust the users spam, black- and whitelist settings](images/mailcow-spamfilter.png) !!! info - For global adjustments on your spam filter please check our section on [Rspamd](rspamd.md). + For global adjustments on your spam filter please check our section on [Rspamd](u_e-rspamd.md). - For a domain wide black- and whitelist please check our guide on [Black / Whitelist](bl_wl.md) + For a domain wide black- and whitelist please check our guide on [Black / Whitelist](u_e-mailcow_ui-bl_wl.md) diff --git a/docs/tagging.md b/docs/u_e-mailcow_ui-tagging.md similarity index 53% rename from docs/tagging.md rename to docs/u_e-mailcow_ui-tagging.md index 74110e46d..b3d5ad0a8 100644 --- a/docs/tagging.md +++ b/docs/u_e-mailcow_ui-tagging.md @@ -1,9 +1,9 @@ -Mailbox users can tag their mail address like in `me+facebook@example.org`. They can control the taghandling in the users **mailcow UI** panel. +Mailbox users can tag their mail address like in `me+facebook@example.org`. They can control the tag handling in the users **mailcow UI** panel. ![mailcow mail tagging settings](images/mailcow-tagging.png) ### Available Actions -1\. Move this message to a subfolder "facebook" (will be created lower case if not existing) +1\. Move this message to a sub folder "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/u_e-mailcow_ui-tfa.md similarity index 88% rename from docs/tfa.md rename to docs/u_e-mailcow_ui-tfa.md index c1961a46f..403bd8daa 100644 --- a/docs/tfa.md +++ b/docs/u_e-mailcow_ui-tfa.md @@ -4,7 +4,7 @@ So far three methods for *Two-Factor Authentication* are implemented: U2F, Yubi - 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 the third TFA method mailcow uses TOTP: time-based one-time passwords. Those passwords 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. @@ -17,7 +17,7 @@ The API ID, API key and the first 12 characters (your YubiKeys ID in modhex) are ### U2F -Only Google Chrome (+derivates) and Opera support U2F authentication to this day natively. +Only Google Chrome (+derivatives) 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. diff --git a/docs/anonym_headers.md b/docs/u_e-postfix-anonym_headers.md similarity index 60% rename from docs/anonym_headers.md rename to docs/u_e-postfix-anonym_headers.md index edd6283c1..0fc959b11 100644 --- a/docs/anonym_headers.md +++ b/docs/u_e-postfix-anonym_headers.md @@ -1,4 +1,4 @@ -Save as `data/conf/postfix/mailcow_anonymize_headers.pcre`: +To disguise your users details like IP, email client, etc. we have to create a new file in `data/conf/postfix/mailcow_anonymize_headers.pcre` and insert the following: ``` /^\s*Received:[^\)]+\)\s+\(Authenticated sender:(.+)/ @@ -10,7 +10,8 @@ Save as `data/conf/postfix/mailcow_anonymize_headers.pcre`: /^\s*X-Forward/ IGNORE ``` -Add this to `data/conf/postfix/main.cf`: +Next we need to add the following to `data/conf/postfix/main.cf`: + ``` smtp_header_checks = pcre:/opt/postfix/conf/mailcow_anonymize_headers.pcre ``` diff --git a/docs/disable_sender_verification.md b/docs/u_e-postfix-disable_sender_verification.md similarity index 90% rename from docs/disable_sender_verification.md rename to docs/u_e-postfix-disable_sender_verification.md index 4d2546096..73e35c9b8 100644 --- a/docs/disable_sender_verification.md +++ b/docs/u_e-postfix-disable_sender_verification.md @@ -1,4 +1,4 @@ -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. +This option is not best-practice and should only be implemented when there is no other option available to achieve 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. ``` diff --git a/docs/redis.md b/docs/u_e-redis.md similarity index 68% rename from docs/redis.md rename to docs/u_e-redis.md index 4f9d3be42..850cb981f 100644 --- a/docs/redis.md +++ b/docs/u_e-redis.md @@ -1,4 +1,4 @@ -Redis is used as a key-value store for (some of) mailcow's and rspamd's settings and data. If you are unfamilliar with redis please read the [introduction to redis](https://redis.io/topics/introduction) and maybe visit this [wonderfull guide](http://try.redis.io/) on how to use it. +Redis is used as a key-value store for rspamd's and (some of) mailcow's settings and data. If you are unfamiliar with redis please read the [introduction to redis](https://redis.io/topics/introduction) and maybe visit this [wonderfull guide](http://try.redis.io/) on how to use it. ## Client @@ -30,7 +30,7 @@ OK Get all keys matching your pattern: ``` - +KEYS * ``` ##### PING diff --git a/docs/rspamd.md b/docs/u_e-rspamd.md similarity index 78% rename from docs/rspamd.md rename to docs/u_e-rspamd.md index a98bee23b..fb536a1a8 100644 --- a/docs/rspamd.md +++ b/docs/u_e-rspamd.md @@ -1,4 +1,4 @@ -Rspamd is used for av handling, dkim signing and spam handling. It's a powerfull and fast filter system. For a more in-depth documentation on Rspamd please visit it's [own documentation](https://rspamd.com/doc/index.html). +Rspamd is used for AV handling, DKIM signing and SPAM handling. It's a powerful and fast filter system. For a more in-depth documentation on Rspamd please visit it's [own documentation](https://rspamd.com/doc/index.html). ## Learn Spam & Ham @@ -9,7 +9,7 @@ Rspamd also auto-learns mail when a high or low score is detected (see https://r 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. +You can also use Rspamd's web UI to learn ham and / or spam or to adjust certain settings of Rspamd. ### Learn Spam or Ham from existing directory diff --git a/docs/why_bind9.md b/docs/u_e-why_bind9.md similarity index 87% rename from docs/why_bind9.md rename to docs/u_e-why_bind9.md index c7d43a5d7..d0676d25a 100644 --- a/docs/why_bind9.md +++ b/docs/u_e-why_bind9.md @@ -1,6 +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. +That's a very bad idea when it comes to filter spam using DNS-based black hole 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 4632fb050..6c327d105 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,53 +14,58 @@ markdown_extensions: pages: - 'Information & Support': 'index.md' - 'Prerequisites': - - 'Prepare Your System': 'requirements.md' - - 'DNS Setup': 'dns.md' -- 'Migrating from mailcow 0.14': 'mc14_migrate.md' + - 'Prepare Your System': 'prerequesite-system.md' + - 'DNS Setup': 'prerequesite-dns.md' +- 'Migrating from mailcow 0.14': 'migrate-mc014.md' - 'Installation & Update': - 'Installation': 'install.md' - - 'Update': 'update.md' + - 'Update': 'install-update.md' - 'First Steps (optional)': - - 'SSL': 'ssl.md' - - 'Rspamd Web UI': 'rspamd_ui.md' - - 'Reverse Proxy': 'rp.md' - - 'Setup a relayhost': 'relayhost.md' - - 'Log to Syslog': 'syslog.md' - - 'Local MTA on Docker host': 'local_mta.md' - - 'Sender and receiver model': 'sender_rcv.md' + - 'SSL': 'firststeps-ssl.md' + - 'Rspamd Web UI': 'firststeps-rspamd_ui.md' + - 'Reverse Proxy': 'firststeps-rp.md' + - 'Setup a relayhost': 'firststeps-relayhost.md' + - 'Log to Syslog': 'firststeps-syslog.md' + - 'Local MTA on Docker host': 'firststeps-local_mta.md' + - 'Sender and receiver model': 'firststeps-sender_rcv.md' - 'Debugging & Troubleshooting': - 'Introduction': debug.md - - 'Logs': 'debug_logs.md' - - 'Attach a Container': 'attach_service.md' - - 'Reset Passwords': 'reset_pw.md' - - 'Remove Persistent Data': 'rm_volumes.md' + - 'Logs': 'debug-logs.md' + - 'Attach a Container': 'debug-attach_service.md' + - 'Reset Passwords': 'debug-reset_pw.md' + - 'Remove Persistent Data': 'debug-rm_volumes.md' + - 'Common Problems': 'debug-common_problems.md' - 'Usage & Examples': - 'mailcow UI': - - 'Configuration': 'mailcow_ui.md' - - 'Blacklist / Whitelist': 'bl_wl.md' - - 'Spamfilter': 'spamfilter.md' - - 'Temporary email aliase': 'spamalias.md' - - 'Tagging': 'tagging.md' - - 'Two-Factor Authentication': 'tfa.md' - - 'Redis': 'redis.md' - - 'Rspamd': 'rspamd.md' + - 'Configuration': 'u_e-mailcow_ui-config.md' + - 'Blacklist / Whitelist': 'u_e-mailcow_ui-bl_wl.md' + - 'Spamfilter': 'u_e-mailcow_ui-spamfilter.md' + - 'Temporary email aliase': 'u_e-mailcow_ui-spamalias.md' + - 'Tagging': 'u_e-mailcow_ui-tagging.md' + - 'Two-Factor Authentication': 'u_e-mailcow_ui-tfa.md' - 'Postfix': - - 'Anonymize Headers': 'anonym_headers.md' - - 'Disable Sender Addresses Verification': 'disable_sender_verification.md' - - 'Why bind9?': 'why_bind9.md' + - 'Anonymize Headers': 'u_e-postfix-anonym_headers.md' + - 'Disable Sender Addresses Verification': 'u_e-postfix-disable_sender_verification.md' + - 'Dovecot': + - "Expunge a User's Mails": 'u_e-dovecot-expunge.md' + - 'More Examples with DOVEADM': 'u_e-dovecot-more.md' + - 'Redis': 'u_e-redis.md' + - 'Rspamd': 'u_e-rspamd.md' + - 'Docker': + - 'Customize Dockerfiles': 'u_e-docker-cust_dockerfiles.md' + - 'Docker Compose Bash Completion': 'u_e-docker-dc_bash_compl.md' + - 'Why bind9?': 'u_e-why_bind9.md' - 'Backup & Restore': - - 'Backup Maildir': 'backup_maildir.md' - - 'MySQL': 'mysql.md' - - 'Autodiscover / Autoconfig': 'autodiscover_config.md' - - 'Redirect HTTP to HTTPS': '80_to_443.md' - - 'Adjust Service Configurations': 'change_config.md' - - 'Customize Dockerfiles': 'cust_dockerfiles.md' - - 'Docker Compose Bash Completion': 'dc_bash_compl.md' - - 'Deinstall': 'deinstall.md' + - 'Backup Maildir': 'u_e-backup_restore-maildir.md' + - 'MySQL': 'u_e-backup_restore-mysql.md' + - 'Autodiscover / Autoconfig': 'u_e-autodiscover_config.md' + - 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md' + - 'Adjust Service Configurations': 'u_e-change_config.md' + - 'Deinstall': 'u_e-deinstall.md' - 'Third party apps': - - 'Roundcube': 'roundcube.md' - - 'Portainer': 'portainer.md' - - 'Gogs': 'gogs.md' + - 'Roundcube': 'third_party-roundcube.md' + - 'Portainer': 'third_party-portainer.md' + - 'Gogs': 'third_party-gogs.md' extra: logo: 'images/logo.svg' palette: