mirror/docker-mailserver.docker-mailserver
1
0
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver.git synced 2025-08-30 23:00:04 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs(refactor): Large refactor + additions + fixes

Browse source 
Consistency pass, formatting cleanup and fixes, introduce admonitions, add front-matter.

---

docs: Add front-matter

---

docs: Fix and format links

- Some links were invalid (eg files moved or renamed)
- Some were valid but had invalid section headers (content removed or migrated)
- Some use `http://` instead of `https://` when the website supports a secure connection.
- Some already used the `[name][reference]` convention but often with a number that wasn't as useful for maintenance.
- All referenced docs needed URLs replaced. Opted for the `[name][reference]` approach to group them all clearly at the bottom of the doc, especially with the relative URLs and in some cases many duplicate entries.
- All `tomav` references from the original repo prior to switch to an organization have been corrected.
- Minor cosmetic changes to the `name` part of the URL, such as for referencing issues to be consistent.
- Some small changes to text body, usually due to duplicate URL reference that was unnecessary (open relay, youtous)
- Switched other links to use the `[name][reference]` format when there was a large group of URLs such as wikipedia or kubernetes. Github repos that reference projects related to `docker-mailserver` also got placed here so they're noticed better by maintainers. This also helped quite a bit with `mermaid` external links that are very long.
- There was a Github Wiki supported syntax in use `[[name | link]]` for `fetchmail` page that isn't compatible by default with MkDocs (needs a plugin), converted to `[name][reference]` instead since it's a relative link.

---

docs: Update commit link for LDAP override script

Logic moved to another file, keeping the permalink commit reference so it's unaffected by any changes in the file referenced in future.

---

docs: Heading corrections

Consistency pass. Helps with the Table of Contents (top-right UI) aka Document Outline.
docs: codefence cleanup

---

docs: misc cleanup

---

docs: Add Admonitions

Switches `<details>` usage for collapsible admonitions (`???`) while other text content is switched to the visually more distinct admoniton (`!!!` or `???+`) style.

This does affect editor syntax highlighting a bit and markdown linting as it's custom non-standard markdown syntax.
This commit is contained in:
polarathene 2021-03-01 23:41:19 +13:00
parent f13df19b87
commit 021e942c4c
30 changed files with 1369 additions and 1027 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/content/config/best-practices/autodiscover.md
View file

@ -1,5 +1,11 @@
---
title: 'Best Practices | Auto-discovery'
hide:
- toc # Hide Table of Contents for this page
---
Email auto-discovery means a client email is able to automagically find out about what ports and security options to use, based on the mail server URL. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users.
Basically, email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address :heart:
Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address :heart:
There exists [autodiscover-email-settings](https://hub.docker.com/r/monogramm/autodiscover-email-settings/) on hub.docker.com which provides IMAP/POP/SMTP/LDAP autodiscover capabilities on Microsoft Outlook/Apple Mail, autoconfig capabilities for Thunderbird or kmail and configuration profiles for iOS/Apple Mail.
There exists [autodiscover-email-settings](https://hub.docker.com/r/monogramm/autodiscover-email-settings/) on which provides IMAP/POP/SMTP/LDAP autodiscover capabilities on Microsoft Outlook/Apple Mail, autoconfig capabilities for Thunderbird or kmail and configuration profiles for iOS/Apple Mail.

43
docs/content/config/best-practices/dkim.md
View file

@ -1,35 +1,39 @@
---
title: 'Best Practices | DKIM'
---
DKIM is a security measure targeting email spoofing. It is greatly recommended one activates it. See [the Wikipedia page](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) for more details on DKIM.
#### Enabling DKIM signature
## Enabling DKIM Signature
To enable DKIM signature, **you must have created at least one email account**. Once its done, just run the following command to generate the signature:
``` BASH
```sh
./setup.sh config dkim
```
After generating DKIM keys, you should restart the mail server. DNS edits may take a few minutes to hours to propagate. The script assumes you're being in the directory where the `config/` directory is located. The default keysize when generating the signature is 4096 bits for now. If you need to change it (e.g. your DNS provider limits the size), then provide the size as the first parameter of the command:
``` BASH
```sh
./setup.sh config dkim <keysize>
```
For LDAP systems that do not have any directly created user account you can run the following command (since `8.0.0`) to generate the signature by additionally providing the desired domain name (if you have multiple domains use the command multiple times or provide a comma-separated list of domains):
``` BASH
```sh
./setup.sh config dkim <key-size> <domain.tld>[,<domain2.tld>]
```
Now the keys are generated, you can configure your DNS server with DKIM signature, simply by adding a TXT record. If you have direct access to your DNS zone file, then it's only a matter of pasting the content of `config/opendkim/keys/domain.tld/mail.txt` in your `domain.tld.hosts` zone.
``` BASH
```console
$ dig mail._domainkey.domain.tld TXT
---
;; ANSWER SECTION
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN"
```
#### Configuration using a web interface
## Configuration using a Web Interface
1. Generate a new record of the type `TXT`.
2. Paste `mail._domainkey` the `Name` txt field.
@ -37,24 +41,25 @@ mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWX
4. In `TTL` (time to live): Time span in seconds. How long the DNS server should cache the `TXT` record.
5. Save.
**Note**: Sometimes the key in `config/opendkim/keys/domain.tld/mail.txt` can be on multiple lines. If so then you need to concatenate the values in the TXT record:
!!! note
Sometimes the key in `config/opendkim/keys/domain.tld/mail.txt` can be on multiple lines. If so then you need to concatenate the values in the TXT record:
``` BASH
```console
$ dig mail._domainkey.domain.tld TXT
---
;; ANSWER SECTION
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; "
"p=AZERTYUIOPQSDF..."
"asdfQWERTYUIOPQSDF..."
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; "
"p=AZERTYUIOPQSDF..."
"asdfQWERTYUIOPQSDF..."
```
The target (or value) field must then have all the parts together: `v=DKIM1; k=rsa; p=AZERTYUIOPQSDF...asdfQWERTYUIOPQSDF...`
#### Verify-only
## Verify-Only
If you want DKIM to only _verify_ incoming emails, the following version of /etc/opendkim.conf may be useful (right now there is no easy mechanism for installing it other than forking the repo):
If you want DKIM to only _verify_ incoming emails, the following version of `/etc/opendkim.conf` may be useful (right now there is no easy mechanism for installing it other than forking the repo):
``` TXT
```conf
# This is a simple config file verifying messages only
#LogWhy yes
@ -70,12 +75,12 @@ SendReports yes
Mode v
```
#### Debugging
## Debugging
- [DKIM-verifer](https://addons.mozilla.org/en-US/thunderbird/addon/dkim-verifier): A add-on for the mail client Thunderbird.
- You can debug your TXT records with the `dig` tool.
``` BASH
```console
$ dig TXT mail._domainkey.domain.tld
---
; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.domain.tld
@ -90,7 +95,7 @@ $ dig TXT mail._domainkey.domain.tld
;mail._domainkey.domain.tld. IN TXT
;; ANSWER SECTION:
mail._domainkey.domain.tld. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB"
mail._domainkey.domain.tld. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB"
;; Query time: 50 msec
;; SERVER: 127.0.1.1#53(127.0.1.1)
@ -98,6 +103,6 @@ mail._domainkey.domain.tld. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBA
;; MSG SIZE rcvd: 310
```
#### Switch off DKIM
## Switch Off DKIM
Simply remove the DKIM key by recreating (not just relaunching) the mailserver container.
Simply remove the DKIM key by recreating (not just relaunching) the mailserver container.

13
docs/content/config/best-practices/dmarc.md
View file

@ -1,10 +1,16 @@
---
title: 'Best Practices | DMARC'
hide:
- toc # Hide Table of Contents for this page
---
DMARC Guide: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md
## Enabling DMARC
In `docker-mailserver`, DMARC is pre-configured out-of the box. The only thing you need to do in order to enable it, is to add new TXT entry to your DNS.
In contrast with [DKIM](https://github.com/tomav/docker-mailserver/wiki/Configure-DKIM), DMARC DNS entry does not require any keys, but merely setting the [configuration values](https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md#overview-of-dmarc-configuration-tags). You can either handcraft the entry by yourself or use one of available generators (like https://dmarcguide.globalcyberalliance.org/).
In contrast with [DKIM][docs-dkim], DMARC DNS entry does not require any keys, but merely setting the [configuration values](https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md#overview-of-dmarc-configuration-tags). You can either handcraft the entry by yourself or use one of available generators (like https://dmarcguide.globalcyberalliance.org/).
Typically something like this should be good to start with (don't forget to replace `@domain.com` to your actual domain)
```
@ -18,4 +24,7 @@ _dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc.report@domain.com; ruf=m
DMARC status is not being displayed instantly in Gmail for instance. If you want to check it directly after DNS entries, you can use some services around the Internet such as https://dmarcguide.globalcyberalliance.org/ or https://ondmarc.redsift.com/. In other case, email clients will show "DMARC: PASS" in ~1 day or so.
Reference: [#1511](https://github.com/tomav/docker-mailserver/issues/1511)
Reference: [#1511][github-issue-1511]
[docs-dkim]: ./dkim.md
[github-issue-1511]: https://github.com/docker-mailserver/docker-mailserver/issues/1511

38
docs/content/config/best-practices/spf.md
View file

@ -1,35 +1,44 @@
---
title: 'Best Practices | SPF'
hide:
- toc # Hide Table of Contents for this page
---
From [Wikipedia](https://en.wikipedia.org/wiki/Sender_Policy_Framework):
> Sender Policy Framework (SPF) is a simple email-validation system designed to detect email spoofing by providing a mechanism to allow receiving mail exchangers to check that incoming mail from a domain comes from a host authorized by that domain's administrators. The list of authorized sending hosts for a domain is published in the Domain Name System (DNS) records for that domain in the form of a specially formatted TXT record. Email spam and phishing often use forged "from" addresses, so publishing and checking SPF records can be considered anti-spam techniques.
For a more technical review: https://github.com/internetstandards/toolbox-wiki/blob/master/SPF-how-to.md
## Add a SPF record
## Add a SPF Record
To add a SPF record in your DNS, insert the following line in your DNS zone:
; MX record must be declared for SPF to work
domain.com. IN MX 1 mail.domain.com.
```txt
; MX record must be declared for SPF to work
domain.com. IN MX 1 mail.domain.com.
; SPF record
domain.com. IN TXT "v=spf1 mx ~all"
; SPF record
domain.com. IN TXT "v=spf1 mx ~all"
```
This enables the _Softfail_ mode for SPF. You could first add this SPF record with a very low TTL.
_SoftFail_ is a good setting for getting started and testing, as it lets all email through, with spams tagged as such in the mailbox.
After verification, you _might_ want to change your SPF record to `v=spf1 mx -all` so as to enforce the _HardFail_ policy. See http://www.open-spf.org/SPF_Record_Syntax/ for more details about SPF policies.
After verification, you _might_ want to change your SPF record to `v=spf1 mx -all` so as to enforce the _HardFail_ policy. See http://www.open-spf.org/SPF_Record_Syntax for more details about SPF policies.
In any case, increment the SPF record's TTL to its final value.
## Backup MX, Secondary MX
For whitelisting a IP-Address from the SPF test, you can create a config file (see [policyd-spf.conf](http://www.linuxcertif.com/man/5/policyd-spf.conf/)) and mount that file into `/etc/postfix-policyd-spf-python/policyd-spf.conf`.
For whitelisting a IP Address from the SPF test, you can create a config file (see [`policyd-spf.conf`](https://www.linuxcertif.com/man/5/policyd-spf.conf)) and mount that file into `/etc/postfix-policyd-spf-python/policyd-spf.conf`.
**Example:**
Create and edit a policyd-spf.conf file here `/<your Docker-Mailserver dir>/config/postfix-policyd-spf.conf`:
```shell
debugLevel = 1
Create and edit a `policyd-spf.conf` file here `/<your docker-mailserver dir>/config/postfix-policyd-spf.conf`:
```conf
debugLevel = 1
#0(only errors)-4(complete data received)
skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
@ -37,10 +46,11 @@ skip_addresses = 127.0.0.0/8,::ffff:127.0.0.0/104,::1
# Preferably use IP-Addresses for whitelist lookups:
Whitelist = 192.168.0.0/31,192.168.1.0/30
# Domain_Whitelist = mx1.mybackupmx.com,mx2.mybackupmx.com
```
Then add this line to `docker-compose.yml` below the `volumes:` section
Then add this line to `docker-compose.yml`:
```yaml
- ./config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
```
volumes:
- ./config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
```