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

solve conflict

Quellcode durchsuchen
Dieser Commit ist enthalten in:
andryyy 2021-08-16 12:40:33 +02:00
Commit 2071d6fec9
20 geänderte Dateien mit 226 neuen und 341 gelöschten Zeilen
Statistiken anzeigen Patch-Datei herunterladen Diff-Datei herunterladen Alle Dateien ausklappen Alle Dateien einklappen

4
.github/workflows/gh-pages.yml gevendort
Datei anzeigen

@ -14,14 +14,14 @@ jobs:
run: | run: |
sudo apt-get -y update sudo apt-get -y update
sudo apt-get -y install python3-pip sudo apt-get -y install python3-pip
pip install mkdocs-material==7.1.5 pygments==2.9.0 mkdocs-redirects==1.0.3 pip install mkdocs-material==7.2.4 pygments==2.10.0 mkdocs-redirects==1.0.3
- name: Build site 🔧 - name: Build site 🔧
run: | run: |
mkdocs build --verbose --clean mkdocs build --verbose --clean
- name: Deploy 🚀 - name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@4.1.3 uses: JamesIves/github-pages-deploy-action@4.1.4
with: with:
branch: gh-pages # The branch the action should deploy to. branch: gh-pages # The branch the action should deploy to.
folder: site # The folder the action should deploy. folder: site # The folder the action should deploy.

2
README.md
Datei anzeigen

@ -9,6 +9,6 @@ https://mailcow.github.io/mailcow-dockerized-docs
To build it locally, you need the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), [MkDocs](https://www.mkdocs.org/) itself and [Pygments](http://pygments.org/). To install these with [pip](https://pip.pypa.io/en/stable/) and get it up and running, fire up your terminal and enter To build it locally, you need the [Material theme for MkDocs](https://squidfunk.github.io/mkdocs-material/), [MkDocs](https://www.mkdocs.org/) itself and [Pygments](http://pygments.org/). To install these with [pip](https://pip.pypa.io/en/stable/) and get it up and running, fire up your terminal and enter
``` ```
pip install mkdocs-material==7.1.5 pygments==2.9.0 mkdocs-redirects==1.0.3 pip install mkdocs-material==7.2.4 pygments==2.10.0 mkdocs-redirects==1.0.3
mkdocs serve mkdocs serve
``` ```

23
docs/b_n_r_backup.md
Datei anzeigen

@ -72,3 +72,26 @@ if [ $RESULT -ne 0 ]
cat "$OUT" cat "$OUT"
fi fi
``` ```
# Backup strategy with rsync and mailcow backup script
Create the destination directory for mailcows helper script:
```
mkdir -p /external_share/backups/backup_script
```
Create cronjobs:
```
25 1 * * * rsync -aH --delete /opt/mailcow-dockerized /external_share/backups/mailcow-dockerized
40 2 * * * rsync -aH --delete /var/lib/docker/volumes /external_share/backups/var_lib_docker_volumes
5 4 * * * cd /opt/mailcow-dockerized/; BACKUP_LOCATION=/external_share/backups/backup_script /opt/mailcow-dockerized/helper-scripts/backup_and_restore.sh backup mysql crypt redis --delete-days 3
# If you want to, use the acl util to backup permissions of some/all folders/files: getfacl -Rn /path
```
On the destination (in this case `/external_share/backups`) you may want to have snapshot capabilities (ZFS, Btrfs etc.). Snapshot daily and keep for n days for a consistent backup.
Do **not** rsync to a Samba share, you need to keep the correct permissions!
To restore you'd simply need to run rsync the other way round and restart Docker to re-read the volumes. Run `docker-compose pull` and `docker-compose up -d`.
If you are lucky Redis and MariaDB can automatically fix the inconsistent databases (if they _are_ inconsistent).
In case of a corrupted database you'd need to use the helper script to restore the inconsistent elements. If a restore fails, try to extract the backups and copy the files back manually. Keep the file permissions!

1
docs/client/client-gajim_xmpp_client.md
Datei anzeigen

@ -1 +0,0 @@
# WIP

2
docs/debug-reset_pw.md
Datei anzeigen

@ -1,6 +1,6 @@
## mailcow Admin Account ## mailcow Admin Account
Reset mailcow admin to `admin:moohoo`. Older mailcow: dockerized installations may find `mailcow-reset-admin.sh` in their mailcow root directory (mailcow_path). Resets the mailcow admin account to a random password. Older mailcow: dockerized installations may find the `mailcow-reset-admin.sh` script in their mailcow root directory (mailcow_path).
``` ```
cd mailcow_path cd mailcow_path

1
docs/firststeps-disable_ipv6.md
Datei anzeigen

@ -38,6 +38,7 @@ version: '2.1'
services: services:
ipv6nat-mailcow: ipv6nat-mailcow:
image: bash:latest
restart: "no" restart: "no"
entrypoint: ["echo", "ipv6nat disabled in compose.override.yml"] entrypoint: ["echo", "ipv6nat disabled in compose.override.yml"]
``` ```

2
docs/firststeps-logging.md
Datei anzeigen

@ -39,7 +39,7 @@ services:
logging: logging:
driver: "gelf" driver: "gelf"
options: options:
gelf-address: "udp://graylog:12201" gelf-address: "udp://graylog:12201"
``` ```
Another example for **Syslog**: Another example for **Syslog**:

10
docs/firststeps-rp.md
Datei anzeigen

@ -48,13 +48,11 @@ Let's Encrypt will follow our rewrite, certificate requests in mailcow will work
**Take care of highlighted lines.** **Take care of highlighted lines.**
``` apache hl_lines="2 5 6 12 13 19 22 23 26 27 28 29 34 35" ``` apache hl_lines="2 10 11 17 22 23 24 25 30 31"
<VirtualHost *:80> <VirtualHost *:80>
ServerName CHANGE_TO_MAILCOW_HOSTNAME ServerName CHANGE_TO_MAILCOW_HOSTNAME
ServerAlias autodiscover.* ServerAlias autodiscover.*
ServerAlias autoconfig.* ServerAlias autoconfig.*
ServerAlias xmpp_prefix_if_any.domain
ServerAlias *.xmpp_prefix_if_any.domain
RewriteEngine on RewriteEngine on
RewriteCond %{HTTPS} off RewriteCond %{HTTPS} off
@ -70,8 +68,6 @@ Let's Encrypt will follow our rewrite, certificate requests in mailcow will work
ServerName CHANGE_TO_MAILCOW_HOSTNAME ServerName CHANGE_TO_MAILCOW_HOSTNAME
ServerAlias autodiscover.* ServerAlias autodiscover.*
ServerAlias autoconfig.* ServerAlias autoconfig.*
ServerAlias xmpp_prefix_if_any.domain
ServerAlias *.xmpp_prefix_if_any.domain
# You should proxy to a plain HTTP session to offload SSL processing # You should proxy to a plain HTTP session to offload SSL processing
ProxyPass /Microsoft-Server-ActiveSync http://127.0.0.1:8080/Microsoft-Server-ActiveSync connectiontimeout=4000 ProxyPass /Microsoft-Server-ActiveSync http://127.0.0.1:8080/Microsoft-Server-ActiveSync connectiontimeout=4000
@ -106,13 +102,13 @@ Let's Encrypt will follow our rewrite, certificate requests will work fine.
server { server {
listen 80 default_server; listen 80 default_server;
listen [::]:80 default_server; listen [::]:80 default_server;
server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.* xmpp_prefix_if_any.domain *.xmpp_prefix_if_any.domain; server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.*;
return 301 https://$host$request_uri; return 301 https://$host$request_uri;
} }
server { server {
listen 443 ssl http2; listen 443 ssl http2;
listen [::]:443 ssl http2; listen [::]:443 ssl http2;
server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.* xmpp_prefix_if_any.domain *.xmpp_prefix_if_any.domain; server_name CHANGE_TO_MAILCOW_HOSTNAME autodiscover.* autoconfig.*;
ssl_certificate MAILCOW_PATH/data/assets/ssl/cert.pem; ssl_certificate MAILCOW_PATH/data/assets/ssl/cert.pem;
ssl_certificate_key MAILCOW_PATH/data/assets/ssl/key.pem; ssl_certificate_key MAILCOW_PATH/data/assets/ssl/key.pem;

5
docs/i_u_m_install.md
Datei anzeigen

@ -3,7 +3,7 @@
**We do not recommend** CentOS 8 anymore. **We do not recommend** CentOS 8 anymore.
You need Docker and Docker Compose. You need Docker (a version >= `20.10.2` is required) and Docker Compose.
**1\.** Learn how to install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/). **1\.** Learn how to install [Docker](https://docs.docker.com/install/) and [Docker Compose](https://docs.docker.com/compose/install/).
@ -13,8 +13,7 @@ Quick installation for most operation systems:
``` ```
curl -sSL https://get.docker.com/ | CHANNEL=stable sh curl -sSL https://get.docker.com/ | CHANNEL=stable sh
# After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7) # After the installation process is finished, you may need to enable the service and make sure it is started (e.g. CentOS 7)
systemctl enable docker.service systemctl enable --now docker
systemctl start docker.service
``` ```
- Docker-Compose - Docker-Compose

4
docs/i_u_m_update.md
Datei anzeigen

@ -66,6 +66,10 @@ docker-compose pull
docker-compose up -d docker-compose up -d
``` ```
### Hooks
You can hook into the update mechanism by adding scripts called `pre_commit_hook.sh` and `post_commit_hook.sh` to your mailcows root directory. See [this](./u_e-update-hooks.md) for more details.
## Footnotes ## Footnotes
- There is no release cycle regarding updates. - There is no release cycle regarding updates.

BIN
docs/images/favicon.png
Datei anzeigen

Binäre Datei nicht angezeigt.
Nebeneinander Wischen Ăśberlagert

Vorher

Breite:  |  Höhe:  |  Größe: 6,7 KiB

Nachher

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

7
docs/index.md
Datei anzeigen

@ -67,7 +67,6 @@ Each container represents a single application.
- [ACME](https://letsencrypt.org/) - [ACME](https://letsencrypt.org/)
- [ClamAV](https://www.clamav.net/) (optional) - [ClamAV](https://www.clamav.net/) (optional)
- [Dovecot](https://www.dovecot.org/) - [Dovecot](https://www.dovecot.org/)
- [ejabberd](https://www.ejabberd.im/)
- [MariaDB](https://mariadb.org/) - [MariaDB](https://mariadb.org/)
- [Memcached](https://www.memcached.org/) - [Memcached](https://www.memcached.org/)
- [Netfilter](https://www.netfilter.org/) (Fail2ban-like integration by [@mkuron](https://github.com/mkuron)) - [Netfilter](https://www.netfilter.org/) (Fail2ban-like integration by [@mkuron](https://github.com/mkuron))
@ -78,7 +77,7 @@ Each container represents a single application.
- [Redis](https://redis.io/) - [Redis](https://redis.io/)
- [Rspamd](https://www.rspamd.com/) - [Rspamd](https://www.rspamd.com/)
- [SOGo](https://sogo.nu/) - [SOGo](https://sogo.nu/)
- [Solr](http://lucene.apache.org/solr/) (optional) - [Solr](https://solr.apache.org/) (optional)
- [Unbound](https://unbound.net/) - [Unbound](https://unbound.net/)
- A Watchdog to provide basic monitoring - A Watchdog to provide basic monitoring
@ -94,6 +93,4 @@ Each container represents a single application.
- sogo-web-vol-1 - sogo-web-vol-1
- solr-vol-1 - solr-vol-1
- vmail-index-vol-1 - vmail-index-vol-1
- vmail-vol-1 - vmail-vol-1
- xmpp-upload-vol-1
- xmpp-vol-1

8
docs/prerequisite-dns.md
Datei anzeigen

@ -60,7 +60,7 @@ _dmarc IN TXT "v=DMARC1; p=reject; rua=mailto:mailauth-reports@
_autodiscover._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME}) _autodiscover._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
_caldavs._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME}) _caldavs._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
_caldavs._tcp IN TXT "path=/SOGo/dav/" _caldavs._tcp IN TXT "path=/SOGo/dav/"
_carddavs._tcp IN SRV 0 1 443 Mail.example.org. (your ${MAILCOW_HOSTNAME}) _carddavs._tcp IN SRV 0 1 443 mail.example.org. (your ${MAILCOW_HOSTNAME})
_carddavs._tcp IN TXT "path=/SOGo/dav/" _carddavs._tcp IN TXT "path=/SOGo/dav/"
_imap._tcp IN SRV 0 1 143 mail.example.org. (your ${MAILCOW_HOSTNAME}) _imap._tcp IN SRV 0 1 143 mail.example.org. (your ${MAILCOW_HOSTNAME})
_imaps._tcp IN SRV 0 1 993 mail.example.org. (your ${MAILCOW_HOSTNAME}) _imaps._tcp IN SRV 0 1 993 mail.example.org. (your ${MAILCOW_HOSTNAME})
@ -90,7 +90,7 @@ If you are interested in statistics, you can additionally register with some of
!!! Tip !!! Tip
It is worth considering that if you request DMARC statistic reports to your mailcow server and your mailcow server is not configured correctly to receive these reports, you may not get accurate and complete results. Please consider using an alternative email domain for receiving DMARC reports. It is worth considering that if you request DMARC statistic reports to your mailcow server and your mailcow server is not configured correctly to receive these reports, you may not get accurate and complete results. Please consider using an alternative email domain for receiving DMARC reports.
It is worth mentioning, that the following suggestions are not a comprehensive list of all services and tools avaialble, but only a small few of the many choices. It is worth mentioning, that the following suggestions are not a comprehensive list of all services and tools available, but only a small few of the many choices.
- [Postmaster Tool](https://gmail.com/postmaster) - [Postmaster Tool](https://gmail.com/postmaster)
- [parsedmarc](https://github.com/domainaware/parsedmarc) (self-hosted) - [parsedmarc](https://github.com/domainaware/parsedmarc) (self-hosted)
@ -100,7 +100,7 @@ It is worth mentioning, that the following suggestions are not a comprehensive l
!!! Tip !!! Tip
These services may provide you with a TXT record you need to insert into your DNS records as the provider specifies. Please ensure to read the providers documentation from the service you choose as this process may vary. These services may provide you with a TXT record you need to insert into your DNS records as the provider specifies. Please ensure you read the provider's documentation from the service you choose as this process may vary.
### Email test for SPF, DKIM and DMARC: ### Email test for SPF, DKIM and DMARC:
@ -127,4 +127,4 @@ The full report will contain more technical details.
### Fully Qualified Domain Name (FQDN) ### Fully Qualified Domain Name (FQDN)
[^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`. [^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, the domain name, and the Top Level Domain (**TLD** for short). In the example of `mx.mailcow.email` the hostname would be `mx`, the domain name `mailcow` and the TLD `email`.

3
docs/prerequisite-system.md
Datei anzeigen

@ -70,9 +70,6 @@ If you have a firewall in front of mailcow, please make sure that these ports ar
| Dovecot POP3S | TCP | 995 | dovecot-mailcow | `${POPS_PORT}` | | Dovecot POP3S | TCP | 995 | dovecot-mailcow | `${POPS_PORT}` |
| Dovecot ManageSieve | TCP | 4190 | dovecot-mailcow | `${SIEVE_PORT}` | | Dovecot ManageSieve | TCP | 4190 | dovecot-mailcow | `${SIEVE_PORT}` |
| HTTP(S) | TCP | 80/443 | nginx-mailcow | `${HTTP_PORT}` / `${HTTPS_PORT}` | | HTTP(S) | TCP | 80/443 | nginx-mailcow | `${HTTP_PORT}` / `${HTTPS_PORT}` |
| XMPP (c2s) | TCP | 5222 | ejabberd-mailcow | `${XMPP_C2S_PORT}` |
| XMPP (s2s) | TCP | 5269 | ejabberd-mailcow | `${XMPP_C2S_PORT}` |
| XMPP (upload) | TCP | 5443 | ejabberd-mailcow | `${XMPP_HTTPS_PORT}` |
To bind a service to an IP address, you can prepend the IP like this: `SMTP_PORT=1.2.3.4:25` To bind a service to an IP address, you can prepend the IP like this: `SMTP_PORT=1.2.3.4:25`

30
docs/u_e-mailcow_ui-tfa.md
Datei anzeigen

@ -1,10 +1,10 @@
So far three methods for *Two-Factor Authentication* are implemented: U2F, Yubi OTP, and TOTP So far three methods for _Two-Factor Authentication_ are implemented: U2F, Yubi OTP, and TOTP
- For U2F to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key. - For U2F to work, you need an encrypted connection to the server (HTTPS) as well as a FIDO security key.
- Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com). - Both U2F and Yubi OTP work well with the fantastic [Yubikey](https://www.yubico.com).
- While Yubi OTP needs an active internet connection and an API ID + key, U2F will work with any FIDO U2F USB key out of the box, but can only be used when mailcow is accessed over HTTPS. - While Yubi OTP needs an active internet connection and an API ID + key, U2F will work with any FIDO U2F USB key out of the box, but can only be used when mailcow is accessed over HTTPS.
- U2F and Yubi OTP support multiple keys per user. - U2F and Yubi OTP support multiple keys per user.
- 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 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. As administrator you are able to temporary disable a domain administrators TFA login until they successfully logged in.
@ -19,8 +19,22 @@ The API ID, API key and the first 12 characters (your YubiKeys ID in modhex) are
### U2F ### U2F
Only Google Chrome (+derivatives) and Opera support U2F authentication to this day natively. To use U2F, the browser must support this standard.
Since version 67 Mozilla Firefox can handle U2F natively. ([Source](https://support.yubico.com/support/solutions/articles/15000017511-enabling-u2f-support-in-mozilla-firefox))
The following desktop browsers support this authentication type:
- Edge (>=79)
- Firefox (>=47, enabled by default since version 67)
- Chrome (>=41)
- Safari (>=13)
- Opera (40, >=42, not 41)
The following mobile browsers support this authentication type:
- Safari on iOS (>=13.3)
- Firefox on Android (>=68)
Sources: [caniuse.com](https://caniuse.com/u2f), [blog.mozilla.org](https://blog.mozilla.org/security/2019/08/05/web-authentication-in-firefox-for-android/)
U2F works without an internet connection. U2F works without an internet connection.

31
docs/u_e-nginx.md
Datei anzeigen

@ -1,11 +1,19 @@
## SSL
Please see [Advanced SSL](https://mailcow.github.io/mailcow-dockerized-docs/firststeps-ssl/) and explicitly check `ADDITIONAL_SERVER_NAMES` for SSL configuration.
Please do not add ADDITIONAL_SERVER_NAMES when you plan to use a different web root.
## New site
To create persistent (over updates) sites hosted by mailcow: dockerized, a new site configuration must be placed inside `data/conf/nginx/`: To create persistent (over updates) sites hosted by mailcow: dockerized, a new site configuration must be placed inside `data/conf/nginx/`:
A good template to begin with:
``` ```
nano data/conf/nginx/my_custom_site.conf nano data/conf/nginx/my_custom_site.conf
``` ```
A good template to begin with:
``` hl_lines="16" ``` hl_lines="16"
server { server {
ssl_certificate /etc/ssl/mail/cert.pem; ssl_certificate /etc/ssl/mail/cert.pem;
@ -19,15 +27,20 @@ server {
ssl_session_tickets off; ssl_session_tickets off;
index index.php index.html; index index.php index.html;
client_max_body_size 0; client_max_body_size 0;
# Location: data/web
root /web; root /web;
# Location: data/web/mysite.com
#root /web/mysite.com
include /etc/nginx/conf.d/listen_plain.active; include /etc/nginx/conf.d/listen_plain.active;
include /etc/nginx/conf.d/listen_ssl.active; include /etc/nginx/conf.d/listen_ssl.active;
server_name mysite.example.org; server_name mysite.example.org;
server_tokens off; server_tokens off;
# This allows acme to be validated even with a different web root
location ^~ /.well-known/acme-challenge/ { location ^~ /.well-known/acme-challenge/ {
allow all;
default_type "text/plain"; default_type "text/plain";
rewrite /.well-known/acme-challenge/(.*) /$1 break;
root /web/.well-known/acme-challenge/;
} }
if ($scheme = http) { if ($scheme = http) {
@ -36,8 +49,14 @@ server {
} }
``` ```
## New site with proxy to a remote location
Another example with a reverse proxy configuration: Another example with a reverse proxy configuration:
```
nano data/conf/nginx/my_custom_site.conf
```
``` hl_lines="16 28" ``` hl_lines="16 28"
server { server {
ssl_certificate /etc/ssl/mail/cert.pem; ssl_certificate /etc/ssl/mail/cert.pem;
@ -77,8 +96,9 @@ server {
} }
``` ```
## Config expansion in mailcows Nginx
The filename is not important, as long as the filename carries a .conf extension. The filename used for a new site is not important, as long as the filename carries a .conf extension.
It is also possible to extend the configuration of the default file `site.conf` file: It is also possible to extend the configuration of the default file `site.conf` file:
@ -86,7 +106,7 @@ It is also possible to extend the configuration of the default file `site.conf`
nano data/conf/nginx/site.my_content.custom nano data/conf/nginx/site.my_content.custom
``` ```
This filename does not need to have a ".conf" extension, but follows the pattern `site.*.custom`, where `*` is a custom name. This filename does not need to have a ".conf" extension but follows the pattern `site.*.custom`, where `*` is a custom name.
If PHP is to be included in a custom site, please use the PHP-FPM listener on phpfpm:9002 or create a new listener in `data/conf/phpfpm/php-fpm.d/pools.conf`. If PHP is to be included in a custom site, please use the PHP-FPM listener on phpfpm:9002 or create a new listener in `data/conf/phpfpm/php-fpm.d/pools.conf`.
@ -96,3 +116,4 @@ Restart Nginx (and PHP-FPM, if a new listener was created):
docker-compose restart nginx-mailcow docker-compose restart nginx-mailcow
docker-compose restart php-fpm-mailcow docker-compose restart php-fpm-mailcow
``` ```

10
docs/u_e-update-hooks.md Normale Datei
Datei anzeigen

@ -0,0 +1,10 @@
It is possible to add pre- and post-update-hooks to the `update.sh` script that upgrades your whole mailcow installation.
To do so, just add the corresponding bash script into your mailcows root directory:
* `pre_update_hook.sh` for commands that should run before the update
* `post_uddate_hook.sh` for commands that should run after the update is completed
Keep in mind that `pre_update_hook.sh` runs every time you call `update.sh` and `post_update_hook.sh` will only run if the update was successful and the script doesn't have to be re-run.
The scripts will be run by bash, an interpreter (e.g. `#!/bin/bash`) as well as an execute permission flag ("+x") are not required.

98
docs/u_e-xmpp-enable.md
Datei anzeigen

@ -1,98 +0,0 @@
XMPP is provided by ejabberd, which describes itself as robust, scalable and extensible XMPP Server.
So first of all, thanks to ejabberd and its contributers!
## Enable XMPP in mailcow
To enable XMPP for a domain, you need to edit the given domain in mailcow UI:
![Screen1](https://i.imgur.com/oLyHBke.png)
The chosen prefix will be used to derive your XMPP login.
A prefix **xmpp_prefix** for the mailbox user `cowboy@develcow.de` would equal to the JID `cowboy@xmpp_prefix.develcow.de`.
!!! info
The login passwords for mail and XMPP are the same. XMPP users are authenticated against mailcow.
Before enabling XMPP for a domain, you should create two CNAME records in DNS:
```
# CNAMES
# Name Type Value
xmpp_prefix IN CNAME mail.example.org. (your ${MAILCOW_HOSTNAME})
*.xmpp_prefix IN CNAME mail.example.org. (your ${MAILCOW_HOSTNAME})
```
These two CNAMEs are essential for acquiring a certificate. Please **do not** add "xmpp_prefix.domain.tld" as name to `ADDITIONAL_SAN`.
Make sure your CNAMEs are correct. Enable XMPP for your domain now.
If you enabled XMPP first and then added your DNS records there is no need to worry. You will just need to wait for ejabberd to automatically acquire the certificates or
simply restart ejabberd-mailcow to trigger the process immediately: `docker-compose restart ejabberd-mailcow`.
Once ejabberd is enabled, you may want to re-run the DNS check in the mailcow UI where you will find two more SRV records:
![Screen2](https://i.imgur.com/IxlUZ7y.png)
```
# SRV records
# Name Type Value
_xmpp-client._tcp.xmpp_prefix IN SRV 10 1 5222 mail.example.org. (your ${MAILCOW_HOSTNAME})
_xmpp-server._tcp.xmpp_prefix IN SRV 10 1 5269 mail.example.org. (your ${MAILCOW_HOSTNAME})
```
There is no need to restart ejabberd, add these SRV records whenever you like. These records are crucial for autoconfiguration of XMPP clients and server-to-server connections.
## ACL
A domain administrator can be given the right to toggle XMPP access for domains and mailboxes, promoting users to XMPP administrators (WIP) and to change the prefix:
![Screen3](https://i.imgur.com/OxKuDFU.png)
## Verify certificates
Once everything is setup, make sure ejabberd was able to acquire certificates:
If you see a message similar to...
```
ejabberd-mailcow_1 | 2021-02-13 14:40:19.507956+01:00 [error] Failed to request certificate for im.example.org, pubsub.im.example.org and 3 more hosts: Challenge failed for domain conference.im.example.org: ACME server reported: DNS problem: NXDOMAIN looking up A for conference.im.example.org - check that a DNS record exists for this domain (error type: dns)
```
...you may need to recheck your DNS configuration or restart ejabberd-mailcow to restart the process in case of slow DNS propagation.
Opening `https://xmpp_prefix.domain.tld:5443/upload` should point you to a 404 page with a valid certificate.
## Why can't we use no prefix?
It does not matter which server name we point our SRV to, Jabber will always rely on the domain given in a JID. We would need to acquire a certificate for the SLD `domain.tld`, which hardly anyone wants to point to its mail system.
We are sorry for this circumstance. As soon as we implemented Servercows DNS API, this may be reconsidered.
## My reverse proxy does not work anymore
If your reverse proxy is configured to point to a site like `webmail.domain.tld` **which mailcow is not aware of** (as in MAILCOW_HOSTNAME does **not** match `webmail.domain.tld`), you may now be redirected to the default ejabberd Nginx site.
That's because mailcow does not know it should respond to `webmail.domain.tld` with mailcow UI.
### Method 1
A more simple approach is defining `ADDITIONAL_SERVER_NAMES` in `mailcow.conf`:
```
ADDITIONAL_SERVER_NAMES=webmail.domain.tld
```
Run `docker-compose up -d` to apply.
### Method 2
In your reverse proxy configuration, make sure you set a "Host" header that mailcow actually services, similar to this (Nginx example):
```
proxy_set_header Host MAILCOW_HOSTNAME;
# Instead of proxy_set_header Host $http_host;
```
Now you can use whatever name you like, as long mailcow receives a known "Host" header.

76
docs/u_e-xmpp-faq.md
Datei anzeigen

@ -1,76 +0,0 @@
## FAQ
Please find the most frequently asked questions with their corresponding configuration in `data/conf/ejabberd/ejabberd.yml` (if any).
- **I do not want to run ejabberd, is there a `SKIP_XMPP` variable?**
No, there is not. But you don't need one either.
The xmppd behaves the same way as SOGo or Solr do when disabled. A shell will be idling and ejabberd will **not** be started (but open unconnected ports).
As soon as a domain is enabled for XMPP, the container will be restarted and ejabberd bootstrapped.
ejabberd is **very** light on resources, you may want to give it a try.
- **Are messages stored on the server?**
Not by default. The default setting is to disable the message archive via mod_mam but allow users to enable the function if they want to:
```
mod_mam:
clear_archive_on_room_destroy: true
default: never
compress_xml: true
request_activates_archiving: true
```
- **Are uploaded files stored on the server?**
Yes, uploaded files are stored in the volume `xmpp-uploads-vol-1`.
The retention policy saves them for 30 days:
```
mod_http_upload_quota:
max_days: 30
```
- **Are messages stored when a JID is offline?**
Yes, up to 1000 messages are stored for "normal" users and administrators:
```
shaper_rules:
max_user_offline_messages:
1000: admin
1000: all
```
- **Are messages written in group chats stored?**
No, messages are not stored:
```
mod_muc:
default_room_options:
mam: false
```
- **Are group chats persistent when the last participant leaves?**
No, they will vanish:
```
mod_muc:
default_room_options:
persistent: false
```
- **How many client sessions can be open at the same time?**
10 sessions are allowed per user.
```
shaper_rules:
max_user_sessions: 10
```

250
mkdocs.yml
Datei anzeigen

@ -1,11 +1,14 @@
site_name: 'mailcow: dockerized documentation' site_name: "mailcow: dockerized documentation"
site_url: https://mailcow.github.io/mailcow-dockerized-docs/ site_url: https://mailcow.github.io/mailcow-dockerized-docs/
copyright: 'Copyright &copy; 2021 André Peters' copyright: "Copyright &copy; 2021 André Peters"
repo_name: mailcow/mailcow-dockerized repo_name: mailcow/mailcow-dockerized
repo_url: https://github.com/mailcow/mailcow-dockerized repo_url: https://github.com/mailcow/mailcow-dockerized
edit_uri: ../mailcow-dockerized-docs/edit/master/docs/ edit_uri: ../mailcow-dockerized-docs/edit/master/docs/
remote_branch: gh-pages remote_branch: gh-pages
theme: material theme:
name: material
logo: images/logo.svg
favicon: images/favicon.png
markdown_extensions: markdown_extensions:
- codehilite: - codehilite:
guess_lang: true guess_lang: true
@ -20,134 +23,129 @@ markdown_extensions:
- pymdownx.extra - pymdownx.extra
- footnotes - footnotes
nav: nav:
- 'Information & Support': 'index.md' - 'Information & Support': 'index.md'
- 'Prerequisites': - 'Prerequisites':
- 'Prepare your system': 'prerequisite-system.md' - 'Prepare your system': 'prerequisite-system.md'
- 'DNS setup': 'prerequisite-dns.md' - 'DNS setup': 'prerequisite-dns.md'
- 'Installation, Update & Migration': - 'Installation, Update & Migration':
- 'Installation': 'i_u_m_install.md' - 'Installation': 'i_u_m_install.md'
- 'Update': 'i_u_m_update.md' - 'Update': 'i_u_m_update.md'
- 'Migration': 'i_u_m_migration.md' - 'Migration': 'i_u_m_migration.md'
- 'Deinstallation': 'i_u_m_deinstall.md' - 'Deinstallation': 'i_u_m_deinstall.md'
- 'Post Installation Tasks': - 'Post Installation Tasks':
- 'Advanced SSL': 'firststeps-ssl.md' - 'Advanced SSL': 'firststeps-ssl.md'
- 'Disable IPv6': 'firststeps-disable_ipv6.md' - 'Disable IPv6': 'firststeps-disable_ipv6.md'
- 'IP bindings': 'firststeps-ip_bindings.md' - 'IP bindings': 'firststeps-ip_bindings.md'
- 'Local MTA on Docker host': 'firststeps-local_mta.md' - 'Local MTA on Docker host': 'firststeps-local_mta.md'
- 'Logging': 'firststeps-logging.md' - 'Logging': 'firststeps-logging.md'
- 'Relayhosts': 'firststeps-relayhost.md' - 'Relayhosts': 'firststeps-relayhost.md'
- 'Reverse Proxy': 'firststeps-rp.md' - 'Reverse Proxy': 'firststeps-rp.md'
- 'Rspamd UI': 'firststeps-rspamd_ui.md' - 'Rspamd UI': 'firststeps-rspamd_ui.md'
- 'SNAT': 'firststeps-snat.md' - 'SNAT': 'firststeps-snat.md'
- 'Sync job migration': 'firststeps-sync_jobs_migration.md' - 'Sync job migration': 'firststeps-sync_jobs_migration.md'
- 'Add trusted networks': 'firststeps-trust_networks.md' - 'Add trusted networks': 'firststeps-trust_networks.md'
- 'Models': - 'Models':
- 'ACL': 'model-acl.md' - 'ACL': 'model-acl.md'
- 'Password hashing': 'model-passwd.md' - 'Password hashing': 'model-passwd.md'
- 'Sender and receiver model': 'model-sender_rcv.md' - 'Sender and receiver model': 'model-sender_rcv.md'
- 'General Troubleshooting': - 'General Troubleshooting':
- 'Introduction': debug.md - 'Introduction': 'debug.md'
- 'Logs': 'debug-logs.md' - 'Logs': 'debug-logs.md'
- 'Attach a Container': 'debug-attach_service.md' - 'Attach a Container': 'debug-attach_service.md'
- 'Reset Passwords (incl. SQL)': 'debug-reset_pw.md' - 'Reset Passwords (incl. SQL)': 'debug-reset_pw.md'
- 'Manual MySQL upgrade': 'debug-mysql_upgrade.md' - 'Manual MySQL upgrade': 'debug-mysql_upgrade.md'
- 'Remove Persistent Data': 'debug-rm_volumes.md' - 'Remove Persistent Data': 'debug-rm_volumes.md'
- 'Common Problems': 'debug-common_problems.md' - 'Common Problems': 'debug-common_problems.md'
- 'Admin login to SOGo': 'debug-admin_login_sogo.md' - 'Admin login to SOGo': 'debug-admin_login_sogo.md'
- 'Reset TLS certificates': 'debug-reset-tls.md' - 'Reset TLS certificates': 'debug-reset-tls.md'
- 'Backup & Restore': - 'Backup & Restore':
- 'Helper script': - 'Helper script':
- 'Backup': 'b_n_r_backup.md' - 'Backup': 'b_n_r_backup.md'
- 'Restore': 'b_n_r_restore.md' - 'Restore': 'b_n_r_restore.md'
- 'Manually': - 'Manually':
- 'Maildir': 'u_e-backup_restore-maildir.md' - 'Maildir': 'u_e-backup_restore-maildir.md'
- 'MySQL': 'u_e-backup_restore-mysql.md' - 'MySQL': 'u_e-backup_restore-mysql.md'
- 'Automatic backups' - 'Automatic backups':
- 'Recover accidentally deleted data': 'b_n_r_accidental_deletion.md' - 'Recover accidentally deleted data': 'b_n_r_accidental_deletion.md'
- 'Manual/Guides/Examples': - 'Manual/Guides/Examples':
- 'mailcow UI': - 'mailcow UI':
- 'Configuration': 'u_e-mailcow_ui-config.md' - 'Configuration': 'u_e-mailcow_ui-config.md'
- 'CSS overrides': 'u_e-mailcow_ui-css.md' - 'CSS overrides': 'u_e-mailcow_ui-css.md'
- 'Blacklist / Whitelist': 'u_e-mailcow_ui-bl_wl.md' - 'Blacklist / Whitelist': 'u_e-mailcow_ui-bl_wl.md'
- 'Pushover': 'u_e-mailcow_ui-pushover.md' - 'Pushover': 'u_e-mailcow_ui-pushover.md'
- 'Spamfilter': 'u_e-mailcow_ui-spamfilter.md' - 'Spamfilter': 'u_e-mailcow_ui-spamfilter.md'
- 'Temporary email aliases': 'u_e-mailcow_ui-spamalias.md' - 'Temporary email aliases': 'u_e-mailcow_ui-spamalias.md'
- 'Tagging': 'u_e-mailcow_ui-tagging.md' - 'Tagging': 'u_e-mailcow_ui-tagging.md'
- 'Two-Factor Authentication': 'u_e-mailcow_ui-tfa.md' - 'Two-Factor Authentication': 'u_e-mailcow_ui-tfa.md'
- 'WebAuthn / FIDO2': 'u_e-fido2.md' - 'WebAuthn / FIDO2': 'u_e-fido2.md'
- 'Postfix': - 'Postfix':
- 'Custom transport maps': 'u_e-postfix-custom_transport.md' - 'Custom transport maps': 'u_e-postfix-custom_transport.md'
- 'Whitelist IP in Postscreen': 'u_e-postfix-postscreen_whitelist.md' - 'Whitelist IP in Postscreen': 'u_e-postfix-postscreen_whitelist.md'
- 'Customize/Expand main.cf': 'u_e-postfix-extra_cf.md' - 'Customize/Expand main.cf': 'u_e-postfix-extra_cf.md'
- 'Disable Sender Addresses Verification': 'u_e-postfix-disable_sender_verification.md' - 'Disable Sender Addresses Verification': 'u_e-postfix-disable_sender_verification.md'
- 'Max. message size (attachment size)': 'u_e-postfix-attachment_size.md' - 'Max. message size (attachment size)': 'u_e-postfix-attachment_size.md'
- 'Statistics with pflogsumm': 'u_e-postfix-pflogsumm.md' - 'Statistics with pflogsumm': 'u_e-postfix-pflogsumm.md'
- 'Unbound': - 'Unbound':
- 'Using an external DNS service': 'u_e-unbound-fwd.md' - 'Using an external DNS service': 'u_e-unbound-fwd.md'
- 'Dovecot': - 'Dovecot':
- 'Enable "any" ACL settings': 'u_e-dovecot-any_acl.md' - 'Enable "any" ACL settings': 'u_e-dovecot-any_acl.md'
- 'Expunge a Users mails': 'u_e-dovecot-expunge.md' - 'Expunge a Users mails': 'u_e-dovecot-expunge.md'
- 'Customize/Expand dovecot.conf': 'u_e-dovecot-extra_conf.md' - 'Customize/Expand dovecot.conf': 'u_e-dovecot-extra_conf.md'
- 'FTS (Solr)': 'u_e-dovecot-fts.md' - 'FTS (Solr)': 'u_e-dovecot-fts.md'
- 'IMAP IDLE interval': 'u_e-dovecot-idle_interval.md' - 'IMAP IDLE interval': 'u_e-dovecot-idle_interval.md'
- 'Mail crypt': 'u_e-dovecot-mail-crypt.md' - 'Mail crypt': 'u_e-dovecot-mail-crypt.md'
- 'More Examples with DOVEADM': 'u_e-dovecot-more.md' - 'More Examples with DOVEADM': 'u_e-dovecot-more.md'
- 'Move Maildir (vmail)': 'u_e-dovecot-vmail-volume.md' - 'Move Maildir (vmail)': 'u_e-dovecot-vmail-volume.md'
- 'Public folders': 'u_e-dovecot-public_folder.md' - 'Public folders': 'u_e-dovecot-public_folder.md'
- 'Static master user': 'u_e-dovecot-static_master.md' - 'Static master user': 'u_e-dovecot-static_master.md'
- 'Nginx': - 'Nginx':
- 'Custom sites': 'u_e-nginx.md' - 'Custom sites': 'u_e-nginx.md'
- 'Create subdomain webmail.example.org': 'u_e-webmail-site.md' - 'Create subdomain webmail.example.org': 'u_e-webmail-site.md'
- 'Redis': 'u_e-redis.md' - 'Redis': 'u_e-redis.md'
- 'Rspamd': 'u_e-rspamd.md' - 'Rspamd': 'u_e-rspamd.md'
- 'SOGo': 'u_e-sogo.md' - 'SOGo': 'u_e-sogo.md'
- 'XMPP': - 'Docker':
- 'FAQ': 'u_e-xmpp-faq.md' - 'Customize Dockerfiles': 'u_e-docker-cust_dockerfiles.md'
- 'Enable XMPP': 'u_e-xmpp-enable.md' - 'Docker Compose Bash Completion': 'u_e-docker-dc_bash_compl.md'
- 'Docker': - 'Why unbound?': 'u_e-why_unbound.md'
- 'Customize Dockerfiles': 'u_e-docker-cust_dockerfiles.md' - 'Autodiscover / Autoconfig': 'u_e-autodiscover_config.md'
- 'Docker Compose Bash Completion': 'u_e-docker-dc_bash_compl.md' - 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md'
- 'Why unbound?': 'u_e-why_unbound.md' - 'Re-enable TLS 1.0 and TLS 1.1': 'u_e-reeanble-weak-protocols.md'
- 'Autodiscover / Autoconfig': 'u_e-autodiscover_config.md' - "Run scripts before and after updates": "u_e-update-hooks.md"
- 'Redirect HTTP to HTTPS': 'u_e-80_to_443.md' - 'Client Configuration':
- 'Re-enable TLS 1.0 and TLS 1.1': 'u_e-reeanble-weak-protocols.md' - 'Overview': 'client.md'
- 'Client Configuration': - 'Android': 'client/client-android.md'
- 'Overview': 'client.md' - 'Apple macOS / iOS': 'client/client-apple.md'
- 'Android': 'client/client-android.md' - 'eM Client': 'client/client-emclient.md'
- 'Apple macOS / iOS': 'client/client-apple.md' - 'KDE Kontact': 'client/client-kontact.md'
- 'eM Client': 'client/client-emclient.md' - 'Microsoft Outlook': 'client/client-outlook.md'
- 'Gajim XMPP client': 'client/client-gajim_xmpp_client.md' - 'Mozilla Thunderbird': 'client/client-thunderbird.md'
- 'KDE Kontact': 'client/client-kontact.md' - 'Windows Mail': 'client/client-windows.md'
- 'Microsoft Outlook': 'client/client-outlook.md' - 'Windows Phone': 'client/client-windowsphone.md'
- 'Mozilla Thunderbird': 'client/client-thunderbird.md' - 'Manual configuration': 'client/client-manual.md'
- 'Windows Mail': 'client/client-windows.md' - 'Third party apps':
- 'Windows Phone': 'client/client-windowsphone.md' - 'Borgmatic Backup': 'third_party-borgmatic.md'
- 'Manual configuration': 'client/client-manual.md' - 'Exchange Hybrid Setup': 'third_party-exchange_onprem.md'
- 'Third party apps': - 'Gitea': 'third_party-gitea.md'
- 'Borgmatic Backup': 'third_party-borgmatic.md' - 'Gogs': 'third_party-gogs.md'
- 'Exchange Hybrid Setup': 'third_party-exchange_onprem.md' - 'Mailpiler Integration': 'third_party-mailpiler_integration.md'
- 'Gitea': 'third_party-gitea.md' - 'Nextcloud': 'third_party-nextcloud.md'
- 'Gogs': 'third_party-gogs.md' - 'Portainer': 'third_party-portainer.md'
- 'Mailpiler Integration': 'third_party-mailpiler_integration.md' - 'Roundcube': 'third_party-roundcube.md'
- 'Nextcloud': 'third_party-nextcloud.md' - 'SOGo Connector for Thunderbird': 'third_party-thunderbird.md'
- 'Portainer': 'third_party-portainer.md'
- 'Roundcube': 'third_party-roundcube.md'
- 'SOGo Connector for Thunderbird': 'third_party-thunderbird.md'
icon:
logo: 'images/logo.svg'
extra: extra:
palette: palette:
primary: 'indigo' primary: "indigo"
accent: 'orange' accent: "orange"
social: social:
- icon: fontawesome/solid/globe-americas - icon: fontawesome/solid/globe-americas
link: https://mailcow.email link: https://mailcow.email
- icon: fontawesome/brands/github-alt - icon: fontawesome/brands/github-alt
link: https://github.com/mailcow link: https://github.com/mailcow
extra_css: [extra.css] extra_css: [ extra.css ]
extra_javascript: [clients.js] extra_javascript: [ clients.js ]
plugins: plugins:
- search - search
- redirects: - redirects:
redirect_maps: redirect_maps:
'u_e-mailpiler-integration.md': 'third_party-mailpiler_integration.md' 'u_e-mailpiler-integration.md': 'third_party-mailpiler_integration.md'