mirror of
https://github.com/docker-mailserver/docker-mailserver.git
synced 2025-08-02 17:14:31 +02:00
docs(chore): Normalize for consistency (#2206)
"Brief" summary/overview of changes. See the PR discussion or individual commits from the PR for more details.
---
Only applies to the `docs/content/**` content (_and `setup` command_). `target/` and `test/` can be normalized at a later date.
* Normalize to `example.com`
- Domains normalized to `example.com`: `mywebserver.com`, `myserver.tld`, `domain.com`, `domain.tld`, `mydomain.net`, `my-domain.tld`, `my-domain.com`, `example.org`, `whoami.com`.
- Alternative domains normalized to `not-example.com`: `otherdomain.com`, `otherdomain.tld`, `domain2.tld`, `mybackupmx.com`, `whoareyou.org`.
- Email addresses normalized to `admin@example.com` (in `ssl.md`): `foo@bar.com`, `yourcurrentemail@gmail.com`, `email@email.com`, `admin@domain.tld`.
- Email addresses normalized to `external-account@gmail.com`: `bill@gates321boom.com`, `external@gmail.com`, `myemail@gmail.com`, `real-email-address@external-domain.com`.
- **`faq.md`:** A FAQ entry title with `sample.domain.com` changed to `subdomain.example.com`.
- **`mail-fetchmail.md`:** Config examples with FQDNs for `imap`/`pop3` used `example.com` domain for a third-party, changed to `gmail.com` as more familiar third-party/external MTA.
* Normalize config volume path
- Normalizing local config path references to `./docker-data/dms/config/`: `./config/`, `config/`, \``config`\`, `/etc/` (_volume mount src path prefix_).
- Normalize DMS volume paths to `docker-data/dms/mail-{data,state,log}`: `./mail`, `./mail-state` `./data/mail`, `./data/state`, `./data/logs`, `./data/maildata`, `./data/mailstate`, `./data/maillogs`, (_dropped/converted data volumes: `maildata`, `mailstate`_).
- Other docker images also adopt the `docker-data/{service name}/` prefix.
* `ssl.md` - Use `dms/custom-certs` where appropriate.
* Apply normalizations to README and example `docker-compose.yml`
---
Common terms, sometimes interchangeably used or now invalid depending on context: `mail`, `mail container`, `mail server`, `mail-server`, `mailserver`,`docker-mailserver`, `Docker Mailserver`.
Rough transformations applied to most matches (_conditionally, depending on context_):
- 'Docker Mailserver' => '`docker-mailserver`'
- 'mail container' => '`docker-mailserver`' (_optionally retaining ' container'_)
- 'mail server' => 'mail-server' / '`docker-mailserver`'
- 'mail-server' => '`docker-mailserver`'
- 'mailserver' => 'mail-server' / '`docker-mailserver`'
Additionally I checked `docker run` (_plus `exec`, `logs`, etc, sub-commands_) and `docker-compose` commands. Often finding usage of `mail` instead of the expected `mailserver`
Additionally changes `mailserver` hostname in k8s to `mail` to align with other non-k8s examples.
---
* drive-by revisions
Mostly minor revisions or improvements to docs that aren't related to normalization effort.
This commit is contained in:
Brennan Kinney
GitHub
parent
5b9d1f9120
commit
a0ee472501
40 changed files with 544 additions and 503 deletions
|
|
@ -4,7 +4,7 @@ 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.
|
||||
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 URI. It can help simplify the tedious / confusing task of adding own's email account for non-tech savvy users.
|
||||
|
||||
Email clients will search for auto-discoverable settings and prefill almost everything when a user enters its email address :heart:
|
||||
|
||||
|
|
|
|||
|
|
@ -15,22 +15,26 @@ To enable DKIM signature, **you must have created at least one email account**.
|
|||
./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:
|
||||
After generating DKIM keys, you should restart `docker-mailserver`. DNS edits may take a few minutes to hours to propagate.
|
||||
|
||||
The script should ideally be run with a volume for _config_ attached (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`), otherwise by default it will mount `./config/:/tmp/docker-mailserver/`.
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
./setup.sh config dkim keysize <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):
|
||||
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):
|
||||
|
||||
```sh
|
||||
./setup.sh config dkim keysize <key-size> domain <domain.tld>[,<domain2.tld>]
|
||||
./setup.sh config dkim keysize <key-size> domain <example.com>[,<not-example.com>]
|
||||
```
|
||||
|
||||
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.
|
||||
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 `docker-data/dms/config/opendkim/keys/example.com/mail.txt` in your `example.com.hosts` zone.
|
||||
|
||||
```console
|
||||
$ dig mail._domainkey.domain.tld TXT
|
||||
$ dig mail._domainkey.example.com TXT
|
||||
---
|
||||
;; ANSWER SECTION
|
||||
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN/AZERTYUIOPQSDFGHJKLMWXCVBN"
|
||||
|
|
@ -45,10 +49,10 @@ mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; p=AZERTYUIOPQSDFGHJKLMWX
|
|||
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:
|
||||
Sometimes the key in `docker-data/dms/config/opendkim/keys/example.com/mail.txt` can be on multiple lines. If so then you need to concatenate the values in the TXT record:
|
||||
|
||||
```console
|
||||
$ dig mail._domainkey.domain.tld TXT
|
||||
$ dig mail._domainkey.example.com TXT
|
||||
---
|
||||
;; ANSWER SECTION
|
||||
mail._domainkey.<DOMAIN> 300 IN TXT "v=DKIM1; k=rsa; "
|
||||
|
|
@ -72,7 +76,7 @@ SyslogSuccess yes
|
|||
Socket inet:12301@localhost
|
||||
PidFile /var/run/opendkim/opendkim.pid
|
||||
|
||||
ReportAddress postmaster@my-domain.com
|
||||
ReportAddress postmaster@example.com
|
||||
SendReports yes
|
||||
|
||||
Mode v
|
||||
|
|
@ -80,7 +84,7 @@ Mode v
|
|||
|
||||
## 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 `docker-mailserver` container.
|
||||
|
||||
## Debugging
|
||||
|
||||
|
|
@ -88,9 +92,9 @@ Simply remove the DKIM key by recreating (not just relaunching) the mailserver c
|
|||
- You can debug your TXT records with the `dig` tool.
|
||||
|
||||
```console
|
||||
$ dig TXT mail._domainkey.domain.tld
|
||||
$ dig TXT mail._domainkey.example.com
|
||||
---
|
||||
; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.domain.tld
|
||||
; <<>> DiG 9.10.3-P4-Debian <<>> TXT mail._domainkey.example.com
|
||||
;; global options: +cmd
|
||||
;; Got answer:
|
||||
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 39669
|
||||
|
|
@ -99,10 +103,10 @@ $ dig TXT mail._domainkey.domain.tld
|
|||
;; OPT PSEUDOSECTION:
|
||||
; EDNS: version: 0, flags:; udp: 512
|
||||
;; QUESTION SECTION:
|
||||
;mail._domainkey.domain.tld. IN TXT
|
||||
;mail._domainkey.example.com. IN TXT
|
||||
|
||||
;; ANSWER SECTION:
|
||||
mail._domainkey.domain.tld. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCxBSjG6RnWAdU3oOlqsdf2WC0FOUmU8uHVrzxPLW2R3yRBPGLrGO1++yy3tv6kMieWZwEBHVOdefM6uQOQsZ4brahu9lhG8sFLPX4MaKYN/NR6RK4gdjrZu+MYSdfk3THgSbNwIDAQAB"
|
||||
mail._domainkey.example.com. 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)
|
||||
|
|
@ -114,6 +118,6 @@ mail._domainkey.domain.tld. 3600 IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBA
|
|||
|
||||
!!! warning "Key sizes >=4096-bit"
|
||||
|
||||
Keys of 4096 bits could de denied by some mailservers. According to https://tools.ietf.org/html/rfc6376 keys are preferably between 512 and 2048 bits. See issue [#1854][github-issue-1854].
|
||||
Keys of 4096 bits could de denied by some mail-servers. According to https://tools.ietf.org/html/rfc6376 keys are preferably between 512 and 2048 bits. See issue [#1854][github-issue-1854].
|
||||
|
||||
[github-issue-1854]: https://github.com/docker-mailserver/docker-mailserver/issues/1854
|
||||
|
|
|
|||
|
|
@ -4,28 +4,33 @@ hide:
|
|||
- toc # Hide Table of Contents for this page
|
||||
---
|
||||
|
||||
!!! note
|
||||
DMARC Guide: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md
|
||||
More information at [DMARC Guide][dmarc-howto].
|
||||
|
||||
## 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 `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][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/).
|
||||
In contrast with [DKIM][docs-dkim], the DMARC DNS entry does not require any keys, but merely setting the [configuration values][dmarc-howto-configtags]. You can either handcraft the entry by yourself or use one of available generators (like [this one][dmarc-tool::gca]).
|
||||
|
||||
Typically something like this should be good to start with (_don't forget to replace `@example.com` to your actual domain_):
|
||||
|
||||
Typically something like this should be good to start with (don't forget to replace `@domain.com` to your actual domain)
|
||||
```
|
||||
_dmarc.domain.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc.report@domain.com; ruf=mailto:dmarc.report@domain.com; sp=none; ri=86400"
|
||||
_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; sp=none; ri=86400"
|
||||
```
|
||||
|
||||
Or a bit more strict policies (mind `p=quarantine` and `sp=quarantine`):
|
||||
Or a bit more strict policies (_mind `p=quarantine` and `sp=quarantine`_):
|
||||
|
||||
```
|
||||
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc.report@domain.com; ruf=mailto:dmarc.report@domain.com; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; sp=quarantine"
|
||||
_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; sp=quarantine"
|
||||
```
|
||||
|
||||
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.
|
||||
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 from [Global Cyber Alliance][dmarc-tool::gca] or [RedSift][dmarc-tool::redsift]. In other cases, email clients will show "DMARC: PASS" in ~1 day or so.
|
||||
|
||||
Reference: [#1511][github-issue-1511]
|
||||
|
||||
[docs-dkim]: ./dkim.md
|
||||
[github-issue-1511]: https://github.com/docker-mailserver/docker-mailserver/issues/1511
|
||||
[dmarc-howto]: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md
|
||||
[dmarc-howto::configtags]: https://github.com/internetstandards/toolbox-wiki/blob/master/DMARC-how-to.md#overview-of-dmarc-configuration-tags
|
||||
[dmarc-tool::gca]: https://dmarcguide.globalcyberalliance.org
|
||||
[dmarc-tool::redsift]: https://ondmarc.redsift.com
|
||||
|
|
|
|||
|
|
@ -18,13 +18,14 @@ To add a SPF record in your DNS, insert the following line in your DNS zone:
|
|||
|
||||
```txt
|
||||
; MX record must be declared for SPF to work
|
||||
domain.com. IN MX 1 mail.domain.com.
|
||||
example.com. IN MX 1 mail.example.com.
|
||||
|
||||
; SPF record
|
||||
domain.com. IN TXT "v=spf1 mx ~all"
|
||||
example.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.
|
||||
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.
|
||||
|
|
@ -37,7 +38,7 @@ For whitelisting a IP Address from the SPF test, you can create a config file (s
|
|||
|
||||
**Example:**
|
||||
|
||||
Create and edit a `policyd-spf.conf` file here `/<your docker-mailserver dir>/config/postfix-policyd-spf.conf`:
|
||||
Create and edit a `policyd-spf.conf` file at `docker-data/dms/config/postfix-policyd-spf.conf`:
|
||||
|
||||
```conf
|
||||
debugLevel = 1
|
||||
|
|
@ -47,12 +48,12 @@ 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
|
||||
# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com
|
||||
```
|
||||
|
||||
Then add this line to `docker-compose.yml`:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
|
||||
- ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue