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

docs: renamings (#3242)

Browse source
This commit is contained in:
Georg Lauterbach 2023-04-10 15:36:34 +02:00 • committed by GitHub
parent 34a1fd613f
commit ddcc1dcc5c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
24 changed files with 119 additions and 119 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/content/config/security/fail2ban.md
View file

@ -29,7 +29,8 @@ Example configuration volume bind:
```
!!! attention
`docker-mailserver` must be launched with the `NET_ADMIN` capability in order to be able to install the nftables rules that actually ban IP addresses.
DMS must be launched with the `NET_ADMIN` capability in order to be able to install the nftables rules that actually ban IP addresses.
Thus either include `--cap-add=NET_ADMIN` in the `docker run` command, or the equivalent in `docker-compose.yml`:

44
docs/content/config/security/ssl.md
View file

@ -25,12 +25,12 @@ After installation, you can test your setup with:
## The FQDN
An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qualified Domain Name_) such as `mail.example.com` is required for `docker-mailserver` to function correctly, especially for looking up the correct SSL certificate to use.
An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qualified Domain Name_) such as `mail.example.com` is required for DMS to function correctly, especially for looking up the correct SSL certificate to use.
- `mail.example.com` will still use `user@example.com` as the mail address. You do not need a bare domain for that.
- We usually discourage assigning a bare domain (_When your DNS MX record does not point to a subdomain_) to represent `docker-mailserver`. However, an FQDN of [just `example.com` is also supported][docs-faq-baredomain].
- We usually discourage assigning a bare domain (_When your DNS MX record does not point to a subdomain_) to represent DMS. However, an FQDN of [just `example.com` is also supported][docs-faq-baredomain].
- Internally, `hostname -f` will be used to retrieve the FQDN as configured in the below examples.
- Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by `docker-mailserver`.
- Wildcard certificates (eg: `*.example.com`) are supported for `SSL_TYPE=letsencrypt`. Your configured FQDN below may be `mail.example.com`, and your wildcard certificate provisioned to `/etc/letsencrypt/live/example.com` which will be checked as a fallback FQDN by DMS.
!!! example "Setting the hostname correctly"
@ -40,9 +40,9 @@ An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qua
# CLI:
docker run --hostname mail.example.com
```
or
```yml
# docker-compose.yml
services:
@ -54,10 +54,10 @@ An [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) (_Fully Qua
### Let's Encrypt (Recommended)
To enable _Let's Encrypt_ for `docker-mailserver`, you have to:
To enable _Let's Encrypt_ for DMS, you have to:
1. Get your certificate using the _Let's Encrypt_ client [Certbot][certbot::github].
2. For your `docker-mailserver` container:
2. For your DMS container:
- Add the environment variable `SSL_TYPE=letsencrypt`.
- Mount [your local `letsencrypt` folder][certbot::certs-storage] as a volume to `/etc/letsencrypt`.
@ -68,7 +68,7 @@ You don't have to do anything else. Enjoy!
`/etc/letsencrypt/live` stores provisioned certificates in individual folders named by their FQDN.
Make sure that the entire folder is mounted to `docker-mailserver` as there are typically symlinks from `/etc/letsencrypt/live/mail.example.com` to `/etc/letsencrypt/archive`.
Make sure that the entire folder is mounted to DMS as there are typically symlinks from `/etc/letsencrypt/live/mail.example.com` to `/etc/letsencrypt/archive`.
!!! example
@ -86,7 +86,7 @@ You don't have to do anything else. Enjoy!
#### Example using Docker for _Let's Encrypt_ { data-toc-label='Certbot with Docker' }
Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by `docker-mailserver` container. You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot.
Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store these, so that they can later be accessed by DMS container. You may also want to persist Certbot [logs][certbot::log-rotation], just in case you need to troubleshoot.
1. Getting a certificate is this simple! (_Referencing: [Certbot docker instructions][certbot::docker] and [`certonly --standalone` mode][certbot::standalone]_):
@ -99,7 +99,7 @@ Certbot provisions certificates to `/etc/letsencrypt`. Add a volume to store the
certbot/certbot certonly --standalone -d mail.example.com
```
2. Add a volume for `docker-mailserver` that maps the _local `certbot/certs/` folder_ to the container path `/etc/letsencrypt/`.
2. Add a volume for DMS that maps the _local `certbot/certs/` folder_ to the container path `/etc/letsencrypt/`.
!!! example
@ -172,7 +172,7 @@ Obtain a Cloudflare API token:
# Set SSL certificate type.
- SSL_TYPE=letsencrypt
volumes:
# Mount the cert folder generated by Certbot into mail-server:
# Mount the cert folder generated by Certbot:
- ./docker-data/certbot/certs/:/etc/letsencrypt/:ro
certbot-cloudflare:
@ -280,7 +280,7 @@ After completing the steps above, your certificate should be ready to use.
If you are running a web server already, port 80 will be in use which Certbot requires. You could use the [Certbot `--webroot`][certbot::webroot] feature, but it is more common to leverage a _reverse proxy_ that manages the provisioning and renewal of certificates for your services automatically.
In the following example, we show how `docker-mailserver` can be run alongside the docker containers [`nginx-proxy`][nginx-proxy::github] and [`acme-companion`][acme-companion::github] (_Referencing: [`acme-companion` documentation][acme-companion::docs]_):
In the following example, we show how DMS can be run alongside the docker containers [`nginx-proxy`][nginx-proxy::github] and [`acme-companion`][acme-companion::github] (_Referencing: [`acme-companion` documentation][acme-companion::docs]_):
1. Start the _reverse proxy_ (`nginx-proxy`):
@ -314,7 +314,7 @@ In the following example, we show how `docker-mailserver` can be run alongside t
3. Start the rest of your web server containers as usual.
4. Start a _dummy container_ to provision certificates for your FQDN (eg: `mail.example.com`). `acme-companion` will detect the container and generate a _Let's Encrypt_ certificate for your domain, which can be used by `docker-mailserver`:
4. Start a _dummy container_ to provision certificates for your FQDN (eg: `mail.example.com`). `acme-companion` will detect the container and generate a _Let's Encrypt_ certificate for your domain, which can be used by DMS:
```sh
docker run --detach \
@ -341,7 +341,7 @@ In the following example, we show how `docker-mailserver` can be run alongside t
#### Example using `nginx-proxy` and `acme-companion` with `docker-compose` { data-toc-label='nginx-proxy with docker-compose' }
The following example is the [basic setup][acme-companion::basic-setup] you need for using `nginx-proxy` and `acme-companion` with `docker-mailserver` (_Referencing: [`acme-companion` documentation][acme-companion::docs]_):
The following example is the [basic setup][acme-companion::basic-setup] you need for using `nginx-proxy` and `acme-companion` with DMS (_Referencing: [`acme-companion` documentation][acme-companion::docs]_):
???+ example "Example: `docker-compose.yml`"
@ -412,7 +412,7 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
[`acme-companion` ENV for default settings][acme-companion::env-config] that apply to all containers using `LETSENCRYPT_HOST`:
- `DEFAULT_EMAIL`: An email address that the CA (_eg: Let's Encrypt_) can contact you about expiring certificates, failed renewals, or for account recovery. You may want to use an email address not handled by your mail-server to ensure deliverability in the event your mail-server breaks.
- `DEFAULT_EMAIL`: An email address that the CA (_eg: Let's Encrypt_) can contact you about expiring certificates, failed renewals, or for account recovery. You may want to use an email address not handled by your mail server to ensure deliverability in the event your mail server breaks.
- `CERTS_UPDATE_INTERVAL`: If you need to adjust the frequency to check for renewals. 3600 seconds (1 hour) by default.
- `DEBUG=1`: Should be helpful when [troubleshooting provisioning issues][acme-companion::troubleshooting] from `acme-companion` logs.
- `ACME_CA_URI`: Useful in combination with `CA_BUNDLE` to use a private CA. To change the default _Let's Encrypt_ endpoint to the staging endpoint, use `https://acme-staging-v02.api.letsencrypt.org/directory`.
@ -461,7 +461,7 @@ The following example is the [basic setup][acme-companion::basic-setup] you need
Version 6.2 and later of the Synology NAS DSM OS now come with an interface to generate and renew letencrypt certificates. Navigation into your DSM control panel and go to Security, then click on the tab Certificate to generate and manage letsencrypt certificates.
Amongst other things, you can use these to secure your mail-server. DSM locates the generated certificates in a folder below `/usr/syno/etc/certificate/_archive/`.
Amongst other things, you can use these to secure your mail server. DSM locates the generated certificates in a folder below `/usr/syno/etc/certificate/_archive/`.
Navigate to that folder and note the 6 character random folder name of the certificate you'd like to use. Then, add the following to your `docker-compose.yml` declaration file:
@ -576,7 +576,7 @@ volumes:
Wildcard certificates are supported. If your FQDN is `mail.example.com` and your wildcard certificate is `*.example.com`, add the ENV: `#!bash SSL_DOMAIN=example.com`.
The mail-server will select it's certificate from `acme.json` checking these ENV for a matching FQDN (_in order of priority_):
DMS will select it's certificate from `acme.json` checking these ENV for a matching FQDN (_in order of priority_):
1. `#!bash ${SSL_DOMAIN}`
2. `#!bash ${HOSTNAME}`
@ -639,13 +639,13 @@ This feature requires you to provide the following files into your [`docker-data
- `<FQDN>-cert.pem`
- `demoCA/cacert.pem`
Where `<FQDN>` is the FQDN you've configured for your `docker-mailserver` container.
Where `<FQDN>` is the FQDN you've configured for your DMS container.
Add `SSL_TYPE=self-signed` to your `docker-mailserver` environment variables. Postfix and Dovecot will be configured to use the provided certificate (_`.pem` files above_) during container startup.
Add `SSL_TYPE=self-signed` to your DMS environment variables. Postfix and Dovecot will be configured to use the provided certificate (_`.pem` files above_) during container startup.
#### Generating a self-signed certificate
One way to generate self-signed certificates is with [Smallstep's `step` CLI](https://smallstep.com/docs/step-cli). This is exactly what [`docker-mailserver` does for creating test certificates][github-file::tls-readme].
One way to generate self-signed certificates is with [Smallstep's `step` CLI](https://smallstep.com/docs/step-cli). This is exactly what [DMS does for creating test certificates][github-file::tls-readme].
For example with the FQDN `mail.example.test`, you can generate the required files by running:
@ -709,7 +709,7 @@ The local and internal paths may be whatever you prefer, so long as both `SSL_CE
!!! info
You may have to restart `docker-mailserver` once the certificates change.
You may have to restart DMS once the certificates change.
## Testing a Certificate is Valid
@ -870,7 +870,7 @@ fi
## Custom DH Parameters
By default `docker-mailserver` uses [`ffdhe4096`][ffdhe4096-src] from [IETF RFC 7919][ietf::rfc::ffdhe]. These are standardized pre-defined DH groups and the only available DH groups for TLS 1.3. It is [discouraged to generate your own DH parameters][dh-avoid-selfgenerated] as it is often less secure.
By default DMS uses [`ffdhe4096`][ffdhe4096-src] from [IETF RFC 7919][ietf::rfc::ffdhe]. These are standardized pre-defined DH groups and the only available DH groups for TLS 1.3. It is [discouraged to generate your own DH parameters][dh-avoid-selfgenerated] as it is often less secure.
Despite this, if you must use non-standard DH parameters or you would like to swap `ffdhe4096` for a different group (eg `ffdhe2048`); Add your own PEM encoded DH params file via a volume to `/tmp/docker-mailserver/dhparams.pem`. This will replace DH params for both Dovecot and Postfix services during container startup.

19
docs/content/config/security/understanding-the-ports.md
View file

@ -15,8 +15,8 @@ Prefer ports with Implicit [TLS][wikipedia-tls] ports, they're more secure than
| POP3 | 110 | 995 | Retrieval | No |
| IMAP4 | 143 | 993 | Retrieval | Yes |
1. A connection _may_ be secured over TLS when both ends support `STARTTLS`. On ports 110, 143 and 587, `docker-mailserver` will reject a connection that cannot be secured. Port 25 is [required][ref-port25-mandatory] to support insecure connections.
2. Receives email, `docker-mailserver` additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the _submission_ ports (465, 587) - which require authentication. Unless a relay host is configured (eg: SendGrid), outgoing email will leave the server via port 25 (_thus outbound traffic must not be blocked by your provider or firewall_).
1. A connection _may_ be secured over TLS when both ends support `STARTTLS`. On ports 110, 143 and 587, DMS will reject a connection that cannot be secured. Port 25 is [required][ref-port25-mandatory] to support insecure connections.
2. Receives email, DMS additionally filters for spam and viruses. For submitting email to the server to be sent to third-parties, you should prefer the _submission_ ports (465, 587) - which require authentication. Unless a relay host is configured (eg: SendGrid), outgoing email will leave the server via port 25 (_thus outbound traffic must not be blocked by your provider or firewall_).
3. A _submission_ port since 2018 ([RFC 8314][rfc-8314]).
??? warning "Beware of outdated advice on port 465"
@ -29,7 +29,6 @@ Prefer ports with Implicit [TLS][wikipedia-tls] ports, they're more secure than
Understand that port 587 is more broadly supported due to this history and that lots of software in that time has been built or configured with that port in mind. [`STARTTLS` is known to have various CVEs discovered even in recent years][starttls-vulnerabilities], do not be misled by any advice implying it should be preferred over implicit TLS. Trust in more official sources, such as the [config Postfix has][postfix-upstream-config-mastercf] which acknowledges the `submissions` port (465).
### What Ports Should I Use? (SMTP)
```mermaid
@ -67,18 +66,18 @@ Mail arriving at your server will be processed and stored in a mailbox, or sent
- **Port 25:**
- Think of this like a physical mailbox, anyone can deliver mail to you here. Typically most mail is delivered to you on this port.
-`docker-mailserver` will actively filter email delivered on this port for spam or viruses, and refuse mail from known bad sources.
- DMS will actively filter email delivered on this port for spam or viruses, and refuse mail from known bad sources.
- Connections to this port may be secure through STARTTLS, but is not mandatory as [mail is allowed to arrive via an unencrypted connection][ref-port25-mandatory].
- It is possible for internal clients to submit mail to be sent outbound (_without requiring authentication_), but that is discouraged. Prefer the _submission_ ports.
- **Port 465 and 587:**
- This is the equivalent of a post office box where you would send email to be delivered on your behalf (_`docker-mailserver` is that metaphorical post office, aka the MTA_).
- This is the equivalent of a post office box where you would send email to be delivered on your behalf (_DMS is that metaphorical post office, aka the MTA_).
- These two ports are known as the _submission_ ports, they enable mail to be sent outbound to another MTA (eg: Outlook or Gmail) but require authentication via a [mail account][docs-accounts].
- For inbound traffic, this is relevant when you send mail from your MUA (eg: ThunderBird). It's also used when `docker-mailserver` is configured as a mail relay, or when you have a service sending transactional mail (_eg: order confirmations, password resets, notifications_) through `docker-mailserver`.
- For inbound traffic, this is relevant when you send mail from your MUA (eg: ThunderBird). It's also used when DMS is configured as a mail relay, or when you have a service sending transactional mail (_eg: order confirmations, password resets, notifications_) through DMS.
- _**Prefer port 465**_ over port 587, as 465 provides Implicit TLS.
!!! note
When submitting mail (inbound) to be sent (outbound), this involves two separate connections to negotiate and secure. There may be additional intermediary connections which `docker-mailserver` is not involved in, and thus unable to ensure encrypted transit throughout delivery.
When submitting mail (inbound) to be sent (outbound), this involves two separate connections to negotiate and secure. There may be additional intermediary connections which DMS is not involved in, and thus unable to ensure encrypted transit throughout delivery.
#### Outbound Traffic (On the Right)
@ -94,7 +93,7 @@ Mail being sent from your server is either being relayed through another MTA (eg
!!! tip
`docker-mailserver` can function as a relay too, but professional relay services have a trusted reputation (_which increases success of delivery_).
DMS can function as a relay too, but professional relay services have a trusted reputation (_which increases success of delivery_).
An MTA with low reputation can affect if mail is treated as junk, or even rejected.
@ -113,7 +112,7 @@ Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for
!!! note
- By default, `docker-mailserver` is configured to reject connections that fail to establish a secure connection (_when authentication is required_), rather than allow an insecure connection.
- By default, DMS is configured to reject connections that fail to establish a secure connection (_when authentication is required_), rather than allow an insecure connection.
- Port 25 does not require authentication. If `STARTTLS` is unsuccessful, mail can be received over an unencrypted connection. You can better secure this port between trusted parties with the addition of MTA-STS, [STARTTLS Policy List][starttls-policy-list], DNSSEC and DANE.
!!! warning
@ -140,7 +139,7 @@ While Explicit TLS can provide the same benefit (_when `STARTTLS` is successfull
A related section or page on ciphers used may be useful, although less important for users to be concerned about.
### TLS connections for a Mail-Server, compared to web browsers
### TLS connections for a Mail Server, compared to web browsers
Unlike with HTTP where a web browser client communicates directly with the server providing a website, a secure TLS connection as discussed below does not provide the equivalent safety that HTTPS does when the transit of email (receiving or sending) is sent through third-parties, as the secure connection is only between two machines, any additional machines (MTAs) between the MUA and the MDA depends on them establishing secure connections between one another successfully.