Compare commits
No commits in common. "master" and "gh-pages" have entirely different histories.
|
|
@ -1,2 +0,0 @@
|
||||||
*
|
|
||||||
!target
|
|
||||||
|
|
@ -1,25 +0,0 @@
|
||||||
# -----------------------------------------------
|
|
||||||
# --- General -----------------------------------
|
|
||||||
# --- https://editorconfig.org ------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
root = true
|
|
||||||
|
|
||||||
[*]
|
|
||||||
charset = utf-8
|
|
||||||
end_of_line = lf
|
|
||||||
indent_size = 2
|
|
||||||
indent_style = space
|
|
||||||
insert_final_newline = true
|
|
||||||
trim_trailing_whitespace = true
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Specific ----------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
[{Makefile,.gitmodules}]
|
|
||||||
indent_style = tab
|
|
||||||
indent_size = 4
|
|
||||||
|
|
||||||
[*.md]
|
|
||||||
trim_trailing_whitespace = false
|
|
||||||
|
|
@ -1,158 +0,0 @@
|
||||||
# Normalize line endings of all non-binary files to LF upon check-in (`git add` / `git commit`):
|
|
||||||
* text=auto
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### General ###################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
## GENERIC
|
|
||||||
### CI + docs/mkdocs.yml
|
|
||||||
*.yml text
|
|
||||||
### Documentation (Project, Tests, Docs site)
|
|
||||||
*.md text
|
|
||||||
### TLS certs (test/files/) + DHE params (target/shared/)
|
|
||||||
*.pem text
|
|
||||||
*.pem.sha512sum text
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Project ###################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
## BUILD:
|
|
||||||
.dockerignore text
|
|
||||||
Dockerfile text eol=lf
|
|
||||||
Makefile
|
|
||||||
|
|
||||||
## EXAMPLE (RUNTIME):
|
|
||||||
*.env text
|
|
||||||
*.yaml text
|
|
||||||
|
|
||||||
## PROJECT
|
|
||||||
.editorconfig text export-ignore
|
|
||||||
.gitattributes text export-ignore
|
|
||||||
.gitignore text export-ignore
|
|
||||||
.gitkeep text export-ignore
|
|
||||||
.gitmodules text export-ignore
|
|
||||||
LICENSE text
|
|
||||||
|
|
||||||
## SOURCE CODE
|
|
||||||
*.sh text eol=lf
|
|
||||||
### acme.json extractor (target/bin/)
|
|
||||||
*.py text eol=lf
|
|
||||||
### Only contain scripts (glob for extensionless)
|
|
||||||
target/bin/** text eol=lf
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Config ####################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
## CONFIG
|
|
||||||
### Contains all text files (glob for extensionless)
|
|
||||||
target/amavis/** text
|
|
||||||
target/fetchmail/** text
|
|
||||||
target/getmail/** text
|
|
||||||
target/opendkim/** text
|
|
||||||
target/opendmarc/** text
|
|
||||||
target/postgrey/** text
|
|
||||||
target/postsrsd/** text
|
|
||||||
### Generic target/ + test/config/
|
|
||||||
*.cf text
|
|
||||||
*.conf text
|
|
||||||
### Dovecot
|
|
||||||
*.ext text
|
|
||||||
*.sieve text
|
|
||||||
### Dovecot + Rspamd
|
|
||||||
*.inc text
|
|
||||||
### Fail2Ban + Postgrey (test/config/)
|
|
||||||
*.local text
|
|
||||||
### Postfix
|
|
||||||
*.pcre text
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Tests #####################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
## BATS
|
|
||||||
*.bash text eol=lf
|
|
||||||
*.bats text eol=lf
|
|
||||||
|
|
||||||
## CONFIG (test/config/)
|
|
||||||
### OpenLDAP image
|
|
||||||
*.ldif text
|
|
||||||
### OpenDKIM
|
|
||||||
*.private text
|
|
||||||
KeyTable text
|
|
||||||
SigningTable text
|
|
||||||
TrustedHosts text
|
|
||||||
### Postgrey
|
|
||||||
whitelist_recipients text
|
|
||||||
|
|
||||||
## MISC
|
|
||||||
### test/config/ + test/files/
|
|
||||||
*.txt text
|
|
||||||
### test/linting/ (.ecrc.json) + test/files/ (*.acme.json):
|
|
||||||
*.json text
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Documentation Website #####################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
## DOCUMENTATION
|
|
||||||
### docs/content/assets/
|
|
||||||
*.css text
|
|
||||||
*.png binary
|
|
||||||
*.svg text -diff
|
|
||||||
*.woff binary
|
|
||||||
### docs/overrides/
|
|
||||||
*.html text
|
|
||||||
*.ico binary
|
|
||||||
*.webp binary
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Info # #####################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
### WHAT IS THIS FILE?
|
|
||||||
# `.gitattributes` - Pattern-based overrides (Project specific)
|
|
||||||
# Documentation: https://git-scm.com/docs/gitattributes
|
|
||||||
#
|
|
||||||
# Travels with the project and can override the defaults from `.gitconfig`.
|
|
||||||
# This helps to enforce consistent line endings (CRLF / LF) where needed via
|
|
||||||
# patterns (_when the git client supports `.gitattributes`_).
|
|
||||||
|
|
||||||
# `.gitconfig` - Global Git defaults (Dev environment)
|
|
||||||
# Documentation: https://git-scm.com/docs/git-config
|
|
||||||
#
|
|
||||||
# Git settings `core.autocrlf` and `core.eol` can vary across dev environments.
|
|
||||||
# Those defaults can introduce subtle bugs due to incompatible line endings.
|
|
||||||
|
|
||||||
|
|
||||||
### WHY SHOULD I CARE?
|
|
||||||
# The desired result is to ensure the repo contains normalized LF line endings,
|
|
||||||
# notably avoiding unhelpful noise in diffs or issues incurred from mixed line
|
|
||||||
# endings. Storing as LF ensures no surprises for line endings during checkout.
|
|
||||||
# Additionally for checkout to the local working directory, line endings can be
|
|
||||||
# forced to CRLF or LF per file where appropriate, which ensures the files have
|
|
||||||
# compatible line endings where software expects a specific kind.
|
|
||||||
#
|
|
||||||
# Examples:
|
|
||||||
# Diffs with nothing visual changed. Line endings appear invisible.
|
|
||||||
# Tests that compare text from two sources where only line endings differ fail.
|
|
||||||
# /bin/sh with a shebang fails to run a binary at the given path due to a CRLF.
|
|
||||||
|
|
||||||
|
|
||||||
### ATTRIBUTES
|
|
||||||
# `text` normalizes the line endings of a file to LF upon commit (CRLF -> LF).
|
|
||||||
# `text=auto` sets `text` if Git doesn't consider the file as binary data.
|
|
||||||
|
|
||||||
# `eol` sets an explicit line ending to write files to the working directory.
|
|
||||||
# `core.eol` is used for any files not explicitly set with an `eol` attr value.
|
|
||||||
# `core.eol` uses the native line endings for your platform by default.
|
|
||||||
# `core.autocrlf` (if set to `true` or `input`) overrides the `core.eol` value.
|
|
||||||
|
|
||||||
# `binary` is an alias for `-text -diff`. The file won't be normalized (-text).
|
|
||||||
# `-diff` indicates to avoid creating a diff. Useful when diffs are unlikely
|
|
||||||
# to be meaningful, such as generated content (SVG, Source Maps, Lockfiles).
|
|
||||||
|
|
||||||
# `export-ignore` excludes matched files and directories during `git archive`,
|
|
||||||
# which services like Github use to create releases with archived source files.
|
|
||||||
|
|
@ -1,11 +0,0 @@
|
||||||
github: [georglauterbach]
|
|
||||||
# patreon: # Replace with a single Patreon username
|
|
||||||
# open_collective: # Replace with a single Open Collective username
|
|
||||||
# ko_fi: # Replace with a single Ko-fi username
|
|
||||||
# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
|
|
||||||
# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
|
|
||||||
# liberapay: # Replace with a single Liberapay username
|
|
||||||
# issuehunt: # Replace with a single IssueHunt username
|
|
||||||
# otechie: # Replace with a single Otechie username
|
|
||||||
# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
|
|
||||||
# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
|
|
||||||
|
|
@ -1,69 +0,0 @@
|
||||||
name: Bug Report
|
|
||||||
description: Submit a bug report to help us improve
|
|
||||||
title: 'bug report: '
|
|
||||||
labels:
|
|
||||||
- kind/bug/report
|
|
||||||
- meta/needs triage
|
|
||||||
|
|
||||||
body:
|
|
||||||
- type: checkboxes
|
|
||||||
id: preliminary-checks
|
|
||||||
attributes:
|
|
||||||
label: 📝 Preliminary Checks
|
|
||||||
description: |
|
|
||||||
By submitting this issue, you agree to our [Code of Conduct](https://github.com/docker-mailserver/docker-mailserver/blob/master/CODE_OF_CONDUCT.md).
|
|
||||||
options:
|
|
||||||
- label: I tried searching for an existing issue and followed the [debugging docs](https://docker-mailserver.github.io/docker-mailserver/latest/config/debugging/) advice, but still need assistance.
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: what-happened
|
|
||||||
attributes:
|
|
||||||
label: 👀 What Happened?
|
|
||||||
description: How did this differ from your expectations?
|
|
||||||
placeholder: Although `LOG_LEVEL=debug` is set, the logs are missing debug output.
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: steps-to-reproduce
|
|
||||||
attributes:
|
|
||||||
label: 👟 Reproduction Steps
|
|
||||||
description: |
|
|
||||||
How did you trigger this bug? Please walk us through it step by step.
|
|
||||||
Please use [fenced code blocks](https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#fenced-code-blocks) when pasting lots of text!
|
|
||||||
placeholder: The easier it is for us to reproduce your issue, the sooner we can help resolve it 😉
|
|
||||||
- type: input
|
|
||||||
id: mailserver-version
|
|
||||||
attributes:
|
|
||||||
label: 🐋 DMS Version
|
|
||||||
description: On which version (image tag) did you encounter this bug?
|
|
||||||
placeholder: v12.1.0 (do not put "latest")
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: input
|
|
||||||
id: operating-system
|
|
||||||
attributes:
|
|
||||||
label: 💻 Operating System and Architecture
|
|
||||||
description: |
|
|
||||||
Which OS is your docker host running on?
|
|
||||||
**NOTE:** Windows and macOS have limited support.
|
|
||||||
placeholder: Debian 11 (Bullseye) x86_64, Fedora 38 ARM64
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: container-configuration-files
|
|
||||||
attributes:
|
|
||||||
label: ⚙️ Container configuration files
|
|
||||||
description: |
|
|
||||||
Show us the `compose.yaml` file or command that you used to run DMS (and possibly other related services).
|
|
||||||
- This field is formatted as YAML.
|
|
||||||
- If you are using Kubernetes, you can alternatively share your manifest files here.
|
|
||||||
render: yml
|
|
||||||
- type: textarea
|
|
||||||
id: relevant-log-output
|
|
||||||
attributes:
|
|
||||||
label: 📜 Relevant log output
|
|
||||||
description: |
|
|
||||||
Show us relevant log output here.
|
|
||||||
- This field expects only plain text (_rendered as a fenced code block_).
|
|
||||||
- You can enable debug output by setting the environment variable `LOG_LEVEL` to `debug` or `trace`.
|
|
||||||
render: Text
|
|
||||||
|
|
@ -1,12 +0,0 @@
|
||||||
blank_issues_enabled: false
|
|
||||||
|
|
||||||
contact_links:
|
|
||||||
- name: Documentation | Landing Page
|
|
||||||
url: https://docker-mailserver.github.io/docker-mailserver/latest
|
|
||||||
about: Visit this first before opening issues!
|
|
||||||
- name: Documentation | Environment Variables Page
|
|
||||||
url: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/
|
|
||||||
about: Read this page for information about mail server variables.
|
|
||||||
- name: Documentation | Debugging Page
|
|
||||||
url: https://docker-mailserver.github.io/docker-mailserver/latest/config/debugging/
|
|
||||||
about: Read this page for information on how to debug DMS.
|
|
||||||
|
|
@ -1,62 +0,0 @@
|
||||||
name: Feature Request
|
|
||||||
description: Suggest an idea for this project
|
|
||||||
title: 'feature request: '
|
|
||||||
labels:
|
|
||||||
- kind/new feature
|
|
||||||
- meta/needs triage
|
|
||||||
projects:
|
|
||||||
- DMS Core Backlog
|
|
||||||
|
|
||||||
body:
|
|
||||||
- type: markdown
|
|
||||||
attributes:
|
|
||||||
value: |
|
|
||||||
Markdown formatting can be used in almost all text fields. The description will tell you if this is not the case for a specific field.
|
|
||||||
|
|
||||||
Be as precise as possible, and if in doubt, it's best to add more information that too few.
|
|
||||||
|
|
||||||
---
|
|
||||||
- type: textarea
|
|
||||||
id: context
|
|
||||||
attributes:
|
|
||||||
label: Context
|
|
||||||
description: Tell us how your request is related to DMS, one of its components or another issue / PR. Also **link all conected issues and PRs here**!
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: description
|
|
||||||
attributes:
|
|
||||||
label: Description
|
|
||||||
description: Describe the solution you would like to have implemented. Be as precise as possible!
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: alternatives
|
|
||||||
attributes:
|
|
||||||
label: Alternatives
|
|
||||||
description: Which alternatives have you considered?
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: applicable-users
|
|
||||||
attributes:
|
|
||||||
label: Applicable Users
|
|
||||||
description: Who will that feature be useful to?
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: dropdown
|
|
||||||
id: implementer
|
|
||||||
attributes:
|
|
||||||
label: Are you going to implement it?
|
|
||||||
options:
|
|
||||||
- Yes, because I know the probability of someone else doing it is low and I can learn from it.
|
|
||||||
- No, and I understand that it is highly likely no one will implement it. Furthermore, I understand that this issue will likely become stale and will be closed.
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: contribution
|
|
||||||
attributes:
|
|
||||||
label: What are you going to contribute?
|
|
||||||
description: You may also tell us what you have already done.
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
|
|
@ -1,30 +0,0 @@
|
||||||
name: Other
|
|
||||||
description: Miscellaneous questions and reports for the project (not support)
|
|
||||||
title: 'other: '
|
|
||||||
labels:
|
|
||||||
- meta/help wanted
|
|
||||||
|
|
||||||
body:
|
|
||||||
- type: dropdown
|
|
||||||
id: subject
|
|
||||||
attributes:
|
|
||||||
label: Subject
|
|
||||||
options:
|
|
||||||
- I would like to contribute to the project
|
|
||||||
- I would like to configure a not documented mail server use case
|
|
||||||
- I would like some feedback concerning a use case
|
|
||||||
- Something else that requires developers attention
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
- type: textarea
|
|
||||||
id: description
|
|
||||||
validations:
|
|
||||||
required: true
|
|
||||||
attributes:
|
|
||||||
label: Description
|
|
||||||
value: |
|
|
||||||
<!---
|
|
||||||
Please do not use this form to bypass doing a proper bug report.
|
|
||||||
The issue tracker is for anything relevant to the project itself, not individual support queries.
|
|
||||||
If you don't want to fill out a bug report, please ask support questions at our community discussions page: https://github.com/orgs/docker-mailserver/discussions
|
|
||||||
-->
|
|
||||||
|
|
@ -1,19 +0,0 @@
|
||||||
version: 2
|
|
||||||
updates:
|
|
||||||
- package-ecosystem: "github-actions"
|
|
||||||
directory: "/"
|
|
||||||
schedule:
|
|
||||||
interval: "weekly"
|
|
||||||
labels:
|
|
||||||
- "area/ci"
|
|
||||||
- "kind/update"
|
|
||||||
- "priority/low"
|
|
||||||
|
|
||||||
- package-ecosystem: "docker"
|
|
||||||
directory: /
|
|
||||||
schedule:
|
|
||||||
interval: "weekly"
|
|
||||||
labels:
|
|
||||||
- "area/ci"
|
|
||||||
- "kind/update"
|
|
||||||
- "priority/medium"
|
|
||||||
|
|
@ -1,29 +0,0 @@
|
||||||
# Description
|
|
||||||
|
|
||||||
<!--
|
|
||||||
Include a summary of the change.
|
|
||||||
Please also include relevant motivation and context.
|
|
||||||
-->
|
|
||||||
|
|
||||||
<!-- Link the issue which will be fixed (if any) here: -->
|
|
||||||
Fixes #
|
|
||||||
|
|
||||||
## Type of change
|
|
||||||
|
|
||||||
<!-- Delete options that are not relevant. -->
|
|
||||||
|
|
||||||
- [ ] Bug fix (non-breaking change which fixes an issue)
|
|
||||||
- [ ] New feature (non-breaking change which adds functionality)
|
|
||||||
- [ ] Improvement (non-breaking change that does improve existing functionality)
|
|
||||||
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
|
||||||
- [ ] This change requires a documentation update
|
|
||||||
|
|
||||||
## Checklist
|
|
||||||
|
|
||||||
- [ ] My code follows the style guidelines of this project
|
|
||||||
- [ ] I have performed a self-review of my code
|
|
||||||
- [ ] I have commented my code, particularly in hard-to-understand areas
|
|
||||||
- [ ] I have made corresponding changes to the documentation (README.md or the documentation under `docs/`)
|
|
||||||
- [ ] If necessary, I have added tests that prove my fix is effective or that my feature works
|
|
||||||
- [ ] New and existing unit tests pass locally with my changes
|
|
||||||
- [ ] **I have added information about changes made in this PR to `CHANGELOG.md`**
|
|
||||||
|
|
@ -1,39 +0,0 @@
|
||||||
name: 'Build, Test & Deploy'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
push:
|
|
||||||
branches:
|
|
||||||
- master
|
|
||||||
paths:
|
|
||||||
- target/**
|
|
||||||
- .dockerignore
|
|
||||||
- .gitmodules
|
|
||||||
- Dockerfile
|
|
||||||
- setup.sh
|
|
||||||
tags:
|
|
||||||
- '*.*.*'
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
packages: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-image:
|
|
||||||
name: 'Build AMD64 Image'
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_build.yml@master
|
|
||||||
|
|
||||||
run-tests:
|
|
||||||
name: 'Test AMD64 Image'
|
|
||||||
needs: build-image
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_test.yml@master
|
|
||||||
with:
|
|
||||||
cache-key: ${{ needs.build-image.outputs.build-cache-key }}
|
|
||||||
|
|
||||||
publish-images:
|
|
||||||
name: 'Publish AMD64 and ARM64 Image'
|
|
||||||
needs: [build-image, run-tests]
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_publish.yml@master
|
|
||||||
with:
|
|
||||||
cache-key: ${{ needs.build-image.outputs.build-cache-key }}
|
|
||||||
secrets: inherit
|
|
||||||
|
|
@ -1,166 +0,0 @@
|
||||||
name: 'Documentation (Deploy)'
|
|
||||||
|
|
||||||
on:
|
|
||||||
# This workflow runs off the primary branch which provides access to the `secrets` context:
|
|
||||||
workflow_run:
|
|
||||||
workflows: ['Documentation (PR)']
|
|
||||||
types:
|
|
||||||
- completed
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
# Required by `actions/download-artifact`:
|
|
||||||
actions: read
|
|
||||||
# Required by `set-pr-context`:
|
|
||||||
contents: read
|
|
||||||
# Required by `marocchino/sticky-pull-request-comment` (write) + `set-pr-context` (read):
|
|
||||||
pull-requests: write
|
|
||||||
# Required by `myrotvorets/set-commit-status-action`:
|
|
||||||
statuses: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
# NOTE: This is handled as pre-requisite job to minimize the noise from acquiring these two outputs needed for `deploy-preview` ENV:
|
|
||||||
pr-context:
|
|
||||||
name: 'Acquire PR Context'
|
|
||||||
runs-on: ubuntu-24.04
|
|
||||||
outputs:
|
|
||||||
PR_HEADSHA: ${{ steps.set-pr-context.outputs.head-sha }}
|
|
||||||
PR_NUMBER: ${{ steps.set-pr-context.outputs.number }}
|
|
||||||
if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request' }}
|
|
||||||
steps:
|
|
||||||
- name: 'Get PR context'
|
|
||||||
id: set-pr-context
|
|
||||||
env:
|
|
||||||
# Token is required for the GH CLI:
|
|
||||||
GH_TOKEN: ${{ github.token }}
|
|
||||||
# Best practice for scripts is to reference via ENV at runtime. Avoid using GHA context expressions in the script content directly:
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/pull/4247#discussion_r1827067475
|
|
||||||
PR_TARGET_REPO: ${{ github.repository }}
|
|
||||||
# If the PR is from a fork, prefix it with `<owner-login>:`, otherwise only the PR branch name is relevant:
|
|
||||||
PR_BRANCH: |-
|
|
||||||
${{
|
|
||||||
(github.event.workflow_run.head_repository.owner.login != github.event.workflow_run.repository.owner.login)
|
|
||||||
&& format('{0}:{1}', github.event.workflow_run.head_repository.owner.login, github.event.workflow_run.head_branch)
|
|
||||||
|| github.event.workflow_run.head_branch
|
|
||||||
}}
|
|
||||||
# Use the GH CLI to query the PR branch, which provides the PR number and head SHA to assign as outputs:
|
|
||||||
# (`--jq` formats JSON to `key=value` pairs and renames `headRefOid` to `head-sha`)
|
|
||||||
run: |
|
|
||||||
gh pr view --repo "${PR_TARGET_REPO}" "${PR_BRANCH}" \
|
|
||||||
--json 'number,headRefOid' \
|
|
||||||
--jq '"number=\(.number)\nhead-sha=\(.headRefOid)"' \
|
|
||||||
>> "${GITHUB_OUTPUT}"
|
|
||||||
|
|
||||||
deploy-preview:
|
|
||||||
name: 'Deploy Preview'
|
|
||||||
runs-on: ubuntu-24.04
|
|
||||||
needs: [pr-context]
|
|
||||||
env:
|
|
||||||
# NOTE: Keep this in sync with the equivalent ENV in `docs-preview-prepare.yml`:
|
|
||||||
BUILD_DIR: docs/site/
|
|
||||||
# PR head SHA (latest commit):
|
|
||||||
PR_HEADSHA: ${{ needs.pr-context.outputs.PR_HEADSHA }}
|
|
||||||
PR_NUMBER: ${{ needs.pr-context.outputs.PR_NUMBER }}
|
|
||||||
# Deploy URL preview prefix (the site name for this prefix is managed at Netlify):
|
|
||||||
PREVIEW_SITE_PREFIX: pullrequest-${{ needs.pr-context.outputs.PR_NUMBER }}
|
|
||||||
steps:
|
|
||||||
- name: 'Retrieve and extract the built docs preview'
|
|
||||||
uses: actions/download-artifact@v4
|
|
||||||
with:
|
|
||||||
name: preview-build
|
|
||||||
path: ${{ env.BUILD_DIR }}
|
|
||||||
# These are needed due this approach relying on `workflow_run`, so that it can access the build artifact:
|
|
||||||
# (uploaded from the associated `docs-preview-prepare.yml` workflow run)
|
|
||||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
run-id: ${{ github.event.workflow_run.id }}
|
|
||||||
|
|
||||||
# ==================== #
|
|
||||||
# Deploy preview build #
|
|
||||||
# ==================== #
|
|
||||||
|
|
||||||
# Manage workflow deployment status (Part 1/2):
|
|
||||||
# NOTE:
|
|
||||||
# - `workflow_run` trigger does not appear on the PR/commit checks status, only the initial prepare workflow triggered.
|
|
||||||
# This adds our own status check for this 2nd half of the workflow starting as `pending`, followed by `success` / `failure` at the end.
|
|
||||||
# - `enable-commit-status` from `nwtgck/actions-netlify` would have handled this,
|
|
||||||
# but the context `github.sha` that action tries to use references the primary branch commit that this workflow runs from, not the relevant PR commit.
|
|
||||||
- name: 'Commit Status (1/2) - Set Workflow Status as Pending'
|
|
||||||
uses: myrotvorets/set-commit-status-action@v2.0.1
|
|
||||||
with:
|
|
||||||
token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
status: pending
|
|
||||||
sha: ${{ env.PR_HEADSHA }}
|
|
||||||
context: 'Deploy Preview (pull_request => workflow_run)'
|
|
||||||
|
|
||||||
- name: 'Send preview build to Netlify'
|
|
||||||
uses: nwtgck/actions-netlify@v3.0
|
|
||||||
id: preview-netlify
|
|
||||||
timeout-minutes: 1
|
|
||||||
env:
|
|
||||||
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
|
|
||||||
NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
|
|
||||||
with:
|
|
||||||
# Fail the job when the required Netlify credentials are missing from ENV:
|
|
||||||
fails-without-credentials: true
|
|
||||||
# Set/create the Netlify deploy URL prefix:
|
|
||||||
alias: ${{ env.PREVIEW_SITE_PREFIX }}
|
|
||||||
# Only publish the contents of the build output:
|
|
||||||
publish-dir: ${{ env.BUILD_DIR }}
|
|
||||||
# Custom message for the deploy log on Netlify:
|
|
||||||
deploy-message: 'Preview Build (PR #${{ env.PR_NUMBER }} @ commit: ${{ env.PR_HEADSHA }}'
|
|
||||||
|
|
||||||
# Disable unwanted action defaults:
|
|
||||||
# This input does not fallback to the GITHUB_TOKEN taken from context, nor log that it will skip extra features of the action when this input is not set:
|
|
||||||
# https://github.com/nwtgck/actions-netlify/issues/1219
|
|
||||||
# github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
# NOTE: These features won't work correctly when the triggered workflow is not run from the PR branch due to assumed `pull_request` context:
|
|
||||||
# https://github.com/nwtgck/actions-netlify/issues/545
|
|
||||||
# Disable adding a comment to the commit belonging to context `github.sha` about the successful deployment (redundant and often wrong commit):
|
|
||||||
enable-commit-comment: false
|
|
||||||
# Disable adding a "Netlify - Netlify deployment" PR check status (workflow job status is sufficient):
|
|
||||||
enable-commit-status: false
|
|
||||||
# Disable adding a comment about successful deployment status to the PR.
|
|
||||||
# Prefer `marocchino/sticky-pull-request-comment` instead (more flexible and allows custom message):
|
|
||||||
enable-pull-request-comment: false
|
|
||||||
# Opt-out of deployment feature:
|
|
||||||
# NOTE:
|
|
||||||
# - When affected by `nwtgck/actions-netlify/issues/545`, the deployments published reference the wrong commit and thus information.
|
|
||||||
# - While the feature creates or assigns a deployment to associate the build with, it is unrelated to the related environments feature (secrets/vars):
|
|
||||||
# https://github.com/nwtgck/actions-netlify/issues/538#issuecomment-833983970
|
|
||||||
# https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history
|
|
||||||
# https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment
|
|
||||||
enable-github-deployment: false
|
|
||||||
# Assign to non-default Deployment Environment for better management:
|
|
||||||
# github-deployment-environment: documentation-previews
|
|
||||||
# github-deployment-description: 'Preview deploy for documentation PRs'
|
|
||||||
|
|
||||||
# If a `netlify.toml` config is ever needed, enable this:
|
|
||||||
# netlify-config-path: ./docs/netlify.toml
|
|
||||||
# If ever switching from Github Pages, enable this only when not deploying a preview build (false by default):
|
|
||||||
# production-deploy: false
|
|
||||||
|
|
||||||
- name: 'Comment on PR with preview link'
|
|
||||||
uses: marocchino/sticky-pull-request-comment@v2
|
|
||||||
with:
|
|
||||||
number: ${{ env.PR_NUMBER }}
|
|
||||||
header: preview-comment
|
|
||||||
recreate: true
|
|
||||||
message: |
|
|
||||||
[Documentation preview for this PR](${{ steps.preview-netlify.outputs.deploy-url }}) is ready! :tada:
|
|
||||||
|
|
||||||
Built with commit: ${{ env.PR_HEADSHA }}
|
|
||||||
|
|
||||||
# Manage workflow deployment status (Part 2/2):
|
|
||||||
- name: 'Commit Status (2/2) - Update deployment status'
|
|
||||||
uses: myrotvorets/set-commit-status-action@v2.0.1
|
|
||||||
# Always run this step regardless of the job failing early:
|
|
||||||
if: ${{ always() }}
|
|
||||||
# Custom status descriptions:
|
|
||||||
env:
|
|
||||||
DEPLOY_SUCCESS: Successfully deployed preview.
|
|
||||||
DEPLOY_FAILURE: Failed to deploy preview.
|
|
||||||
with:
|
|
||||||
token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
status: ${{ job.status == 'success' && 'success' || 'failure' }}
|
|
||||||
sha: ${{ env.PR_HEADSHA }}
|
|
||||||
context: 'Deploy Preview (pull_request => workflow_run)'
|
|
||||||
description: ${{ job.status == 'success' && env.DEPLOY_SUCCESS || env.DEPLOY_FAILURE }}
|
|
||||||
|
|
@ -1,74 +0,0 @@
|
||||||
name: 'Documentation (PR)'
|
|
||||||
|
|
||||||
on:
|
|
||||||
pull_request:
|
|
||||||
paths:
|
|
||||||
- 'docs/**'
|
|
||||||
- '.github/workflows/scripts/docs/build-docs.sh'
|
|
||||||
- '.github/workflows/docs-preview-prepare.yml'
|
|
||||||
|
|
||||||
# If this workflow is triggered while already running for the PR, cancel any earlier running instances:
|
|
||||||
# Instances of the 2nd phase of this workflow (via `workflow_run`) lack any concurrency limits due to added complexity.
|
|
||||||
concurrency:
|
|
||||||
group: deploypreview-pullrequest-${{ github.event.pull_request.number }}
|
|
||||||
cancel-in-progress: true
|
|
||||||
|
|
||||||
env:
|
|
||||||
# Build output directory (created by the mkdocs-material container, keep this in sync with `build-docs.sh`):
|
|
||||||
BUILD_DIR: docs/site/
|
|
||||||
# These two are only needed to construct `PREVIEW_URL`:
|
|
||||||
PREVIEW_SITE_NAME: dms-doc-previews
|
|
||||||
PREVIEW_SITE_PREFIX: pullrequest-${{ github.event.pull_request.number }}
|
|
||||||
|
|
||||||
# `pull_request` workflow is unreliable alone: Non-collaborator contributions lack access to secrets for security reasons.
|
|
||||||
# A separate workflow (docs-preview-deploy.yml) handles the deploy after the potentially untrusted code is first run in this workflow.
|
|
||||||
# See: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
|
|
||||||
permissions:
|
|
||||||
# Required by `actions/checkout` for git checkout:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
prepare-preview:
|
|
||||||
name: 'Build Preview'
|
|
||||||
runs-on: ubuntu-24.04
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
|
|
||||||
# ================== #
|
|
||||||
# Build docs preview #
|
|
||||||
# ================== #
|
|
||||||
|
|
||||||
- name: 'Build with mkdocs-material via Docker'
|
|
||||||
working-directory: docs/
|
|
||||||
env:
|
|
||||||
PREVIEW_URL: 'https://${{ env.PREVIEW_SITE_PREFIX }}--${{ env.PREVIEW_SITE_NAME }}.netlify.app/'
|
|
||||||
run: |
|
|
||||||
# Adjust `mkdocs.yml` for the preview build requirements:
|
|
||||||
# - Replace production `site_url` with the preview URL (only affects the canonical link: https://en.wikipedia.org/wiki/Canonical_link_element#HTML)
|
|
||||||
# - Prepend Netlify logo link to `copyright` content
|
|
||||||
sed -i "s|^site_url:.*|site_url: '${{ env.PREVIEW_URL }}'|" mkdocs.yml
|
|
||||||
|
|
||||||
# Insert branding into page content (Netlify OSS plan requirement):
|
|
||||||
# - `mkdocs-material` does not provide a better way to do this.
|
|
||||||
# - Prepends HTML to the copyright text and then aligns the logo to the right-side of the page.
|
|
||||||
NETLIFY_BRANDING='<a href="https://www.netlify.com/"><img alt="Deploys by Netlify" src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" style="float: right;"></a>'
|
|
||||||
sed -i "s|^copyright: '|copyright: '${NETLIFY_BRANDING}|" mkdocs.yml
|
|
||||||
# Override a CSS media query for the parent element to always be full width:
|
|
||||||
echo '.md-footer-copyright { width: 100%; }' >> content/assets/css/customizations.css
|
|
||||||
|
|
||||||
# Build and prepare for upload:
|
|
||||||
echo "::group::Build (stdout)"
|
|
||||||
bash ../.github/workflows/scripts/docs/build-docs.sh
|
|
||||||
echo "::endgroup::"
|
|
||||||
|
|
||||||
# ============================== #
|
|
||||||
# Volley over to secure workflow #
|
|
||||||
# ============================== #
|
|
||||||
|
|
||||||
# Archives directory `path` into a ZIP file:
|
|
||||||
- name: 'Upload artifact for workflow transfer'
|
|
||||||
uses: actions/upload-artifact@v4
|
|
||||||
with:
|
|
||||||
name: preview-build
|
|
||||||
path: ${{ env.BUILD_DIR }}
|
|
||||||
retention-days: 1
|
|
||||||
|
|
@ -1,136 +0,0 @@
|
||||||
name: 'Documentation'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
push:
|
|
||||||
branches:
|
|
||||||
- master
|
|
||||||
paths:
|
|
||||||
- '.github/workflows/deploy-docs.yml'
|
|
||||||
- 'docs/**'
|
|
||||||
# Responds to tags being pushed (branches and paths conditions above do not apply to tags).
|
|
||||||
# Takes a snapshot of the docs from the tag (unaffected by branch or path restraints above),
|
|
||||||
# Stores build in a subdirectory with name matching the git tag `v<MAJOR>.<MINOR>` substring:
|
|
||||||
tags:
|
|
||||||
- 'v[0-9]+.[0-9]+*'
|
|
||||||
|
|
||||||
env:
|
|
||||||
# Default docs version to build and deploy:
|
|
||||||
DOCS_VERSION: edge
|
|
||||||
# Assign commit authorship to official Github Actions bot when pushing to the `gh-pages` branch:
|
|
||||||
GIT_USER: 'github-actions[bot]'
|
|
||||||
GIT_EMAIL: '41898282+github-actions[bot]@users.noreply.github.com'
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
deploy:
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
name: 'Deploy Docs'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
steps:
|
|
||||||
- uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: 'Check if deploy is for a `v<major>.<minor>` tag version instead of `edge`'
|
|
||||||
if: startsWith(github.ref, 'refs/tags/')
|
|
||||||
working-directory: docs
|
|
||||||
run: |
|
|
||||||
DOCS_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}")
|
|
||||||
echo "DOCS_VERSION=${DOCS_VERSION}" >> "${GITHUB_ENV}"
|
|
||||||
|
|
||||||
# Docs should build referencing the tagged version instead:
|
|
||||||
sed -i "s|^\(site_url:.*\)edge|\1${DOCS_VERSION}|" mkdocs.yml
|
|
||||||
|
|
||||||
- name: 'Build with mkdocs-material via Docker'
|
|
||||||
working-directory: docs
|
|
||||||
run: '../.github/workflows/scripts/docs/build-docs.sh'
|
|
||||||
|
|
||||||
- name: 'If a tagged version, fix canonical links and remove `404.html`'
|
|
||||||
if: startsWith(github.ref, 'refs/tags/')
|
|
||||||
working-directory: docs/site
|
|
||||||
run: |
|
|
||||||
# 404 is not useful due to how Github Pages implement custom 404 support:
|
|
||||||
# (Note the edge 404.html isn't useful either as it's not copied to the `gh-pages` branch root)
|
|
||||||
rm 404.html
|
|
||||||
|
|
||||||
# Replace the tagged '${DOCS_VERSION}' in the 'canonical' link element of HTML files,
|
|
||||||
# to point to the 'edge' version of docs as the authoritative source:
|
|
||||||
find . -type f -name "*.html" -exec \
|
|
||||||
sed -i "s|^\(.*<link rel=\"canonical\".*\)${DOCS_VERSION}|\1latest|" \
|
|
||||||
{} +
|
|
||||||
|
|
||||||
- name: 'Deploy to Github Pages'
|
|
||||||
uses: peaceiris/actions-gh-pages@v4.0.0
|
|
||||||
with:
|
|
||||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
# Build directory contents to publish to the `gh-pages` branch:
|
|
||||||
publish_dir: ./docs/site
|
|
||||||
# Directory to place `publish_dir` contents on the `gh-pages` branch:
|
|
||||||
destination_dir: ${{ env.DOCS_VERSION }}
|
|
||||||
user_name: ${{ env.GIT_USER }}
|
|
||||||
user_email: ${{ env.GIT_EMAIL }}
|
|
||||||
|
|
||||||
add-version-to-docs:
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
name: 'Update `versions.json` if necessary'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
if: startsWith(github.ref, 'refs/tags/')
|
|
||||||
# Avoid race condition with pushing to `gh-pages` branch by waiting for `deploy` to complete first
|
|
||||||
needs: deploy
|
|
||||||
steps:
|
|
||||||
- name: 'Checkout the tagged commit (shallow clone)'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: 'Checkout the docs deployment branch to a subdirectory'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
ref: gh-pages
|
|
||||||
path: gh-pages
|
|
||||||
|
|
||||||
# Updates `env.DOCS_VERSION` to the tag version; if invalid exits job early.
|
|
||||||
- name: 'Ensure `versions.json` has `v<major>.<minor>` substring from tag name'
|
|
||||||
id: add-version
|
|
||||||
continue-on-error: true
|
|
||||||
working-directory: gh-pages
|
|
||||||
run: '../.github/workflows/scripts/docs/update-versions-json.sh'
|
|
||||||
|
|
||||||
# If an actual change was made to `versions.json`, commit and push it.
|
|
||||||
# Otherwise the step is skipped instead of reporting job failure.
|
|
||||||
- name: 'Push update for `versions.json`'
|
|
||||||
if: ${{ steps.add-version.outcome == 'success' }}
|
|
||||||
working-directory: gh-pages
|
|
||||||
run: |
|
|
||||||
git config user.name ${{ env.GIT_USER }}
|
|
||||||
git config user.email ${{ env.GIT_EMAIL }}
|
|
||||||
git add versions.json
|
|
||||||
git commit -m "chore: Add ${{ env.DOCS_VERSION }} to version selector list"
|
|
||||||
git push
|
|
||||||
|
|
||||||
update-latest-symlink:
|
|
||||||
permissions:
|
|
||||||
contents: write
|
|
||||||
name: 'update `latest` symlink if neccessary'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
if: startsWith(github.ref, 'refs/tags/')
|
|
||||||
needs: add-version-to-docs
|
|
||||||
steps:
|
|
||||||
- name: 'Checkout the docs deployment branch'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
ref: gh-pages
|
|
||||||
|
|
||||||
- name: 'Ensure `latest` symlink refers to the substring from tag name'
|
|
||||||
id: update-latest
|
|
||||||
run: |
|
|
||||||
DOCS_VERSION=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}")
|
|
||||||
echo "DOCS_VERSION=${DOCS_VERSION}" >>"${GITHUB_ENV}"
|
|
||||||
rm latest
|
|
||||||
ln -s "${DOCS_VERSION}" latest
|
|
||||||
|
|
||||||
- name: 'Push update for `latest` symlink'
|
|
||||||
run: |
|
|
||||||
git config user.name ${{ env.GIT_USER }}
|
|
||||||
git config user.email ${{ env.GIT_EMAIL }}
|
|
||||||
git add latest
|
|
||||||
git commit -m "chore: Update \`latest\` symlink to point to ${{ env.DOCS_VERSION }}"
|
|
||||||
git push
|
|
||||||
|
|
@ -1,107 +0,0 @@
|
||||||
name: 'Build the DMS Container Image'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_call:
|
|
||||||
inputs:
|
|
||||||
platforms:
|
|
||||||
required: false
|
|
||||||
type: string
|
|
||||||
default: linux/amd64
|
|
||||||
outputs:
|
|
||||||
build-cache-key:
|
|
||||||
description: The cache key to use when restoring an image later
|
|
||||||
value: ${{ jobs.build-image.outputs.build-cache-key }}
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
# `actions/cache` does not upload a new cache until completing a job successfully.
|
|
||||||
# To better cache image builds, tests are handled in a dependent job afterwards.
|
|
||||||
# This way failing tests will not prevent caching of an image. Useful when the build context
|
|
||||||
# is not changed by new commits.
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-image:
|
|
||||||
name: 'Build'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
outputs:
|
|
||||||
build-cache-key: ${{ steps.derive-image-cache-key.outputs.digest }}
|
|
||||||
steps:
|
|
||||||
- name: 'Checkout'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
submodules: recursive
|
|
||||||
|
|
||||||
# Can potentially be replaced by: `${{ hashFiles('target/**', 'Dockerfile') }}`
|
|
||||||
# Must not be affected by file metadata changes and have a consistent sort order:
|
|
||||||
# https://docs.github.com/en/actions/learn-github-actions/expressions#hashfiles
|
|
||||||
# Keying by the relevant build context is more re-usable than a commit SHA.
|
|
||||||
- name: 'Derive Docker image cache key from content'
|
|
||||||
id: derive-image-cache-key
|
|
||||||
shell: bash
|
|
||||||
run: |
|
|
||||||
ADDITIONAL_FILES=( 'Dockerfile' )
|
|
||||||
|
|
||||||
# Recursively collect file paths from `target/` and pipe a list of
|
|
||||||
# checksums to be sorted (by hash value) and finally generate a checksum
|
|
||||||
# of that list, using `awk` to only return the hash value (digest):
|
|
||||||
IMAGE_CHECKSUM=$(\
|
|
||||||
find ./target -type f -exec sha256sum "${ADDITIONAL_FILES[@]}" {} + \
|
|
||||||
| sort \
|
|
||||||
| sha256sum \
|
|
||||||
| awk '{ print $1 }' \
|
|
||||||
)
|
|
||||||
|
|
||||||
echo "digest=${IMAGE_CHECKSUM}" >>"${GITHUB_OUTPUT}"
|
|
||||||
|
|
||||||
# Attempts to restore the build cache from a prior build run.
|
|
||||||
# If the exact key is not restored, then upon a successful job run
|
|
||||||
# the new cache is uploaded for this key containing the contents at `path`.
|
|
||||||
# Cache storage has a limit of 10GB, and uploads expire after 7 days.
|
|
||||||
# When full, the least accessed cache upload is evicted to free up storage.
|
|
||||||
# https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows
|
|
||||||
- name: 'Handle Docker build layer cache'
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /tmp/.buildx-cache
|
|
||||||
key: cache-buildx-${{ steps.derive-image-cache-key.outputs.digest }}
|
|
||||||
# If no exact cache-hit for key found, lookup caches with a `cache-buildx-` key prefix:
|
|
||||||
# This is safe due to cache layer invalidation via the image build context.
|
|
||||||
restore-keys: |
|
|
||||||
cache-buildx-
|
|
||||||
|
|
||||||
- name: 'Set up QEMU'
|
|
||||||
uses: docker/setup-qemu-action@v3.6.0
|
|
||||||
with:
|
|
||||||
platforms: arm64
|
|
||||||
|
|
||||||
- name: 'Set up Docker Buildx'
|
|
||||||
uses: docker/setup-buildx-action@v3.10.0
|
|
||||||
|
|
||||||
# NOTE: AMD64 can build within 2 minutes
|
|
||||||
- name: 'Build images'
|
|
||||||
uses: docker/build-push-action@v6.15.0
|
|
||||||
with:
|
|
||||||
context: .
|
|
||||||
# Build at least the AMD64 image (which runs against the test suite).
|
|
||||||
platforms: ${{ inputs.platforms }}
|
|
||||||
# Paired with steps `actions/cache` and `Replace cache` (replace src with dest):
|
|
||||||
# NOTE: `mode=max` is only for `cache-to`, it configures exporting all image layers.
|
|
||||||
# https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#cache-from
|
|
||||||
cache-from: type=local,src=/tmp/.buildx-cache
|
|
||||||
cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
|
|
||||||
# This job just builds the image and stores to cache, no other exporting required:
|
|
||||||
# https://github.com/docker/build-push-action/issues/546#issuecomment-1122631106
|
|
||||||
outputs: type=cacheonly
|
|
||||||
# Disable provenance attestation: https://docs.docker.com/build/attestations/slsa-provenance/
|
|
||||||
provenance: false
|
|
||||||
|
|
||||||
# WORKAROUND: The `cache-to: type=local` input for `build-push-action` persists old-unused cache.
|
|
||||||
# The workaround is to write the new build cache to a different location that replaces the
|
|
||||||
# original restored cache after build, reducing frequency of eviction due to cache storage limit (10GB).
|
|
||||||
# https://github.com/docker/build-push-action/blob/965c6a410d446a30e95d35052c67d6eded60dad6/docs/advanced/cache.md?plain=1#L193-L199
|
|
||||||
# NOTE: This does not affect `cache-hit == 'true'` (which skips upload on direct cache key hit)
|
|
||||||
- name: 'Replace cache'
|
|
||||||
run: |
|
|
||||||
rm -rf /tmp/.buildx-cache
|
|
||||||
mv /tmp/.buildx-cache-new /tmp/.buildx-cache
|
|
||||||
|
|
@ -1,81 +0,0 @@
|
||||||
name: 'Publish the DMS Container Image'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_call:
|
|
||||||
inputs:
|
|
||||||
cache-key:
|
|
||||||
required: true
|
|
||||||
type: string
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
packages: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
publish-images:
|
|
||||||
name: 'Publish'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
steps:
|
|
||||||
- name: 'Checkout'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
submodules: recursive
|
|
||||||
|
|
||||||
- name: 'Prepare tags'
|
|
||||||
id: prep
|
|
||||||
uses: docker/metadata-action@v5.7.0
|
|
||||||
with:
|
|
||||||
images: |
|
|
||||||
${{ secrets.DOCKER_REPOSITORY }}
|
|
||||||
${{ secrets.GHCR_REPOSITORY }}
|
|
||||||
tags: |
|
|
||||||
type=edge,branch=master
|
|
||||||
type=semver,pattern={{major}}
|
|
||||||
type=semver,pattern={{major}}.{{minor}}
|
|
||||||
type=semver,pattern={{major}}.{{minor}}.{{patch}}
|
|
||||||
|
|
||||||
- name: 'Set up QEMU'
|
|
||||||
uses: docker/setup-qemu-action@v3.6.0
|
|
||||||
with:
|
|
||||||
platforms: arm64
|
|
||||||
|
|
||||||
- name: 'Set up Docker Buildx'
|
|
||||||
uses: docker/setup-buildx-action@v3.10.0
|
|
||||||
|
|
||||||
# Try get the cached build layers from a prior `generic_build.yml` job.
|
|
||||||
# NOTE: Until adopting `type=gha` scoped cache exporter (in `docker/build-push-action`),
|
|
||||||
# only AMD64 image is expected to be cached, ARM images will build from scratch.
|
|
||||||
- name: 'Retrieve image build from build cache'
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /tmp/.buildx-cache
|
|
||||||
key: cache-buildx-${{ inputs.cache-key }}
|
|
||||||
restore-keys: |
|
|
||||||
cache-buildx-
|
|
||||||
|
|
||||||
- name: 'Login to DockerHub'
|
|
||||||
uses: docker/login-action@v3
|
|
||||||
with:
|
|
||||||
username: ${{ secrets.DOCKER_USERNAME }}
|
|
||||||
password: ${{ secrets.DOCKER_PASSWORD }}
|
|
||||||
|
|
||||||
- name: 'Login to GitHub Container Registry'
|
|
||||||
uses: docker/login-action@v3
|
|
||||||
with:
|
|
||||||
registry: ghcr.io
|
|
||||||
username: ${{ github.actor }}
|
|
||||||
password: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
|
|
||||||
- name: 'Build and publish images'
|
|
||||||
uses: docker/build-push-action@v6.15.0
|
|
||||||
with:
|
|
||||||
context: .
|
|
||||||
build-args: |
|
|
||||||
DMS_RELEASE=${{ github.ref_type == 'tag' && github.ref_name || 'edge' }}
|
|
||||||
VCS_REVISION=${{ github.sha }}
|
|
||||||
platforms: linux/amd64,linux/arm64
|
|
||||||
push: true
|
|
||||||
tags: ${{ steps.prep.outputs.tags }}
|
|
||||||
cache-from: type=local,src=/tmp/.buildx-cache
|
|
||||||
# Disable provenance attestation: https://docs.docker.com/build/attestations/slsa-provenance/
|
|
||||||
provenance: false
|
|
||||||
|
|
@ -1,59 +0,0 @@
|
||||||
name: 'Test the DMS Container Image'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_call:
|
|
||||||
inputs:
|
|
||||||
cache-key:
|
|
||||||
required: true
|
|
||||||
type: string
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
run-tests:
|
|
||||||
name: 'Test'
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
strategy:
|
|
||||||
matrix:
|
|
||||||
part: [serial, parallel/set1, parallel/set2, parallel/set3]
|
|
||||||
fail-fast: false
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
with:
|
|
||||||
# Required to retrieve bats (core + extras):
|
|
||||||
submodules: recursive
|
|
||||||
|
|
||||||
# Get the cached build layers from the build job:
|
|
||||||
# This should always be a cache-hit, thus `restore-keys` fallback is not used.
|
|
||||||
# No new cache uploads should ever happen for this job.
|
|
||||||
- name: 'Retrieve image built from build cache'
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /tmp/.buildx-cache
|
|
||||||
key: cache-buildx-${{ inputs.cache-key }}
|
|
||||||
|
|
||||||
# Configures buildx to use `docker-container` driver,
|
|
||||||
# Ensures consistent BuildKit version (not coupled to Docker Engine),
|
|
||||||
# and increased compatibility of the build cache vs mixing buildx drivers.
|
|
||||||
- name: 'Set up Docker Buildx'
|
|
||||||
uses: docker/setup-buildx-action@v3.10.0
|
|
||||||
|
|
||||||
# Importing from the cache should create the image within approx 30 seconds:
|
|
||||||
# NOTE: `qemu` step is not needed as we only test for AMD64.
|
|
||||||
- name: 'Build AMD64 image from cache'
|
|
||||||
uses: docker/build-push-action@v6.15.0
|
|
||||||
with:
|
|
||||||
context: .
|
|
||||||
tags: mailserver-testing:ci
|
|
||||||
# Export the built image to the Docker host for use with BATS:
|
|
||||||
load: true
|
|
||||||
# Rebuilds the AMD64 image from the cache:
|
|
||||||
platforms: linux/amd64
|
|
||||||
cache-from: type=local,src=/tmp/.buildx-cache
|
|
||||||
# Disable provenance attestation: https://docs.docker.com/build/attestations/slsa-provenance/
|
|
||||||
provenance: false
|
|
||||||
|
|
||||||
- name: 'Run tests'
|
|
||||||
run: make generate-accounts tests/${{ matrix.part }}
|
|
||||||
|
|
@ -1,67 +0,0 @@
|
||||||
# This workflow checks out code, re-builds an image from cache, performs a container image
|
|
||||||
# vulnerability scan with Anchore's Grype tool, and integrates the results with GitHub
|
|
||||||
# Advanced Security code scanning feature.
|
|
||||||
#
|
|
||||||
# For more information on the Anchore scan action usage and parameters, see
|
|
||||||
# https://github.com/anchore/scan-action. For more information on Anchore's container
|
|
||||||
# image scanning tool Grype, see https://github.com/anchore/grype.
|
|
||||||
name: "Anchore Grype Vulnerability Scan"
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_call:
|
|
||||||
inputs:
|
|
||||||
cache-key:
|
|
||||||
required: true
|
|
||||||
type: string
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
scan-image:
|
|
||||||
permissions:
|
|
||||||
contents: read # for actions/checkout to fetch code
|
|
||||||
security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
steps:
|
|
||||||
- name: 'Checkout'
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
# Get the cached build layers from the build job:
|
|
||||||
# This should always be a cache-hit, thus `restore-keys` fallback is not used.
|
|
||||||
# No new cache uploads should ever happen for this job.
|
|
||||||
- name: 'Retrieve image built from build cache'
|
|
||||||
uses: actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /tmp/.buildx-cache
|
|
||||||
key: cache-buildx-${{ inputs.cache-key }}
|
|
||||||
|
|
||||||
# Configures buildx to use `docker-container` driver,
|
|
||||||
# Ensures consistent BuildKit version (not coupled to Docker Engine),
|
|
||||||
# and increased compatibility of the build cache vs mixing buildx drivers.
|
|
||||||
- name: 'Set up Docker Buildx'
|
|
||||||
uses: docker/setup-buildx-action@v3.10.0
|
|
||||||
|
|
||||||
# Importing from the cache should create the image within approx 30 seconds:
|
|
||||||
# NOTE: `qemu` step is not needed as we only test for AMD64.
|
|
||||||
- name: 'Build AMD64 image from cache'
|
|
||||||
uses: docker/build-push-action@v6.15.0
|
|
||||||
with:
|
|
||||||
context: .
|
|
||||||
tags: mailserver-testing:ci
|
|
||||||
# Export the built image to the Docker host for later use:
|
|
||||||
load: true
|
|
||||||
# Rebuilds the AMD64 image from the cache:
|
|
||||||
platforms: linux/amd64
|
|
||||||
cache-from: type=local,src=/tmp/.buildx-cache
|
|
||||||
# Disable provenance attestation: https://docs.docker.com/build/attestations/slsa-provenance/
|
|
||||||
provenance: false
|
|
||||||
|
|
||||||
- name: 'Run the Anchore Grype scan action'
|
|
||||||
uses: anchore/scan-action@v6.1.0
|
|
||||||
id: scan
|
|
||||||
with:
|
|
||||||
image: mailserver-testing:ci
|
|
||||||
fail-build: false
|
|
||||||
|
|
||||||
- name: 'Upload vulnerability report'
|
|
||||||
uses: github/codeql-action/upload-sarif@v3
|
|
||||||
with:
|
|
||||||
sarif_file: ${{ steps.scan.outputs.sarif }}
|
|
||||||
|
|
@ -1,46 +0,0 @@
|
||||||
name: "Handle Stale Issues & Pull Requests"
|
|
||||||
|
|
||||||
on:
|
|
||||||
schedule:
|
|
||||||
- cron: "0 1 * * *"
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
stale:
|
|
||||||
permissions:
|
|
||||||
issues: write
|
|
||||||
pull-requests: write
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
steps:
|
|
||||||
- name: Close stale issues
|
|
||||||
uses: actions/stale@v9
|
|
||||||
with:
|
|
||||||
repo-token: ${{ secrets.GITHUB_TOKEN }}
|
|
||||||
days-before-stale: 20
|
|
||||||
days-before-close: 10
|
|
||||||
|
|
||||||
exempt-issue-labels: stale-bot/ignore
|
|
||||||
stale-issue-label: meta/stale
|
|
||||||
stale-issue-message: |
|
|
||||||
This issue has become stale because it has been open for 20 days without activity.
|
|
||||||
This issue will be closed in 10 days automatically unless:
|
|
||||||
|
|
||||||
- a maintainer removes the `meta/stale` label or adds the `stale-bot/ignore` label
|
|
||||||
- new activity occurs, such as a new comment
|
|
||||||
close-issue-label: "meta/closed due to age or inactivity"
|
|
||||||
close-issue-message: >
|
|
||||||
This issue was closed due to inactivity.
|
|
||||||
|
|
||||||
exempt-pr-labels: stale-bot/ignore
|
|
||||||
stale-pr-label: meta/stale
|
|
||||||
stale-pr-message: |
|
|
||||||
This pull request has become stale because it has been open for 20 days without activity.
|
|
||||||
This pull request will be closed in 10 days automatically unless:
|
|
||||||
|
|
||||||
- a maintainer removes the `meta/stale` label or adds the `stale-bot/ignore` label
|
|
||||||
- new activity occurs, such as a new comment
|
|
||||||
close-pr-label: "meta/closed due to age or inactivity"
|
|
||||||
close-pr-message: >
|
|
||||||
This PR was closed due to inactivity.
|
|
||||||
|
|
@ -1,28 +0,0 @@
|
||||||
name: Lint
|
|
||||||
|
|
||||||
on:
|
|
||||||
# A workflow that creates a PR will not trigger this workflow,
|
|
||||||
# Providing a manual trigger as a workaround
|
|
||||||
workflow_dispatch:
|
|
||||||
pull_request:
|
|
||||||
push:
|
|
||||||
branches: [ master ]
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
lint:
|
|
||||||
runs-on: ubuntu-22.04
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Hadolint
|
|
||||||
run: make hadolint
|
|
||||||
|
|
||||||
- name: ShellCheck
|
|
||||||
run: make shellcheck
|
|
||||||
|
|
||||||
- name: ECLint
|
|
||||||
run: make eclint
|
|
||||||
|
|
@ -1,33 +0,0 @@
|
||||||
name: 'Deploy :edge on Schedule'
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
schedule:
|
|
||||||
- cron: 0 0 * * 5
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
packages: write
|
|
||||||
security-events: write
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-images:
|
|
||||||
name: 'Build Images'
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_build.yml@master
|
|
||||||
with:
|
|
||||||
platforms: linux/amd64,linux/arm64
|
|
||||||
|
|
||||||
scan-image:
|
|
||||||
name: 'Scan Image for Vulnerabilities'
|
|
||||||
needs: build-images
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_vulnerability-scan.yml@master
|
|
||||||
with:
|
|
||||||
cache-key: ${{ needs.build-images.outputs.build-cache-key }}
|
|
||||||
|
|
||||||
publish-images:
|
|
||||||
name: 'Publish Images'
|
|
||||||
needs: build-images
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_publish.yml@master
|
|
||||||
with:
|
|
||||||
cache-key: ${{ needs.build-images.outputs.build-cache-key }}
|
|
||||||
secrets: inherit
|
|
||||||
|
|
@ -1,22 +0,0 @@
|
||||||
#!/bin/bash
|
|
||||||
set -ex
|
|
||||||
|
|
||||||
# PWD should be at the project docs/ folder.
|
|
||||||
# `--user` is required for build output file ownership to match the CI user,
|
|
||||||
# instead of the internal root user of the container.
|
|
||||||
# `build --strict` ensures the build fails when any warnings are omitted.
|
|
||||||
docker run \
|
|
||||||
--rm \
|
|
||||||
--quiet \
|
|
||||||
--user "$(id -u):$(id -g)" \
|
|
||||||
--volume "./:/docs" \
|
|
||||||
--name "build-docs" \
|
|
||||||
squidfunk/mkdocs-material:9.6 build --strict
|
|
||||||
|
|
||||||
# Remove unnecessary build artifacts: https://github.com/squidfunk/mkdocs-material/issues/2519
|
|
||||||
# site/ is the build output folder.
|
|
||||||
cd site
|
|
||||||
find . -type f -name '*.min.js.map' -delete -o -name '*.min.css.map' -delete
|
|
||||||
rm sitemap.xml.gz
|
|
||||||
rm assets/images/favicon.png
|
|
||||||
rm -r assets/javascripts/lunr
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# CI ENV `GITHUB_REF` from Github Actions CI provides the tag or branch that triggered the build
|
|
||||||
# See `github.ref`: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context
|
|
||||||
# https://docs.github.com/en/actions/reference/environment-variables
|
|
||||||
function _update_versions_json
|
|
||||||
{
|
|
||||||
# Extract the version tag, truncate `<PATCH>` version and any suffix beyond it.
|
|
||||||
local MAJOR_MINOR
|
|
||||||
MAJOR_MINOR=$(grep -oE 'v[0-9]+\.[0-9]+' <<< "${GITHUB_REF}")
|
|
||||||
# Github Actions CI method for exporting ENV vars to share across a jobs steps
|
|
||||||
# https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable
|
|
||||||
echo "DOCS_VERSION=${MAJOR_MINOR}" >> "${GITHUB_ENV}"
|
|
||||||
|
|
||||||
if [[ -z "${MAJOR_MINOR}" ]]
|
|
||||||
then
|
|
||||||
echo "Could not extract valid \`v<MAJOR>.<MINOR>\` substring, exiting.."
|
|
||||||
exit 1
|
|
||||||
fi
|
|
||||||
|
|
||||||
local VERSIONS_JSON='versions.json'
|
|
||||||
local IS_VALID
|
|
||||||
IS_VALID=$(jq '.' "${VERSIONS_JSON}")
|
|
||||||
|
|
||||||
if [[ ! -f "${VERSIONS_JSON}" ]] || [[ -z "${IS_VALID}" ]]
|
|
||||||
then
|
|
||||||
echo "'${VERSIONS_JSON}' doesn't exist or is invalid. Creating.."
|
|
||||||
echo '[{"version": "edge", "title": "edge", "aliases": []}]' > "${VERSIONS_JSON}"
|
|
||||||
fi
|
|
||||||
|
|
||||||
|
|
||||||
# Only add this tag version the first time it's encountered:
|
|
||||||
local VERSION_EXISTS
|
|
||||||
VERSION_EXISTS=$(jq --arg version "${MAJOR_MINOR}" '[.[].version == $version] | any' "${VERSIONS_JSON}")
|
|
||||||
|
|
||||||
if [[ ${VERSION_EXISTS} == "true" ]]
|
|
||||||
then
|
|
||||||
echo "${MAJOR_MINOR} docs are already supported. Nothing to change, exiting.."
|
|
||||||
exit 1
|
|
||||||
else
|
|
||||||
echo "Added support for ${MAJOR_MINOR} docs."
|
|
||||||
# Add any logic here if you want the version selector to have a different label (`title`) than the `version` URL/subdirectory.
|
|
||||||
local TITLE=${TITLE:-${MAJOR_MINOR}}
|
|
||||||
|
|
||||||
# Assumes the first element is always the "latest" unreleased version (`edge` for us), and then newest version to oldest.
|
|
||||||
# `jq` takes the first array element of array as slice, concats with new element, then takes the slice of remaining original elements to concat.
|
|
||||||
# Thus assumes this script is always triggered by newer versions, no older major/minor releases as our build workflow isn't setup to support rebuilding older docs.
|
|
||||||
local UPDATED_JSON
|
|
||||||
UPDATED_JSON=$(jq --arg version "${MAJOR_MINOR}" --arg title "${TITLE}" \
|
|
||||||
'.[:1] + [{version: $version, title: $title, aliases: []}] + .[1:]' \
|
|
||||||
"${VERSIONS_JSON}"
|
|
||||||
)
|
|
||||||
|
|
||||||
# See `jq` FAQ advising this approach to update file:
|
|
||||||
# https://github.com/stedolan/jq/wiki/FAQ
|
|
||||||
echo "${UPDATED_JSON}" > tmp.json && mv tmp.json "${VERSIONS_JSON}"
|
|
||||||
fi
|
|
||||||
}
|
|
||||||
|
|
||||||
_update_versions_json
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
name: "Test Merge Requests"
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
pull_request:
|
|
||||||
paths:
|
|
||||||
- target/**
|
|
||||||
- test/**
|
|
||||||
- .dockerignore
|
|
||||||
- .gitmodules
|
|
||||||
- Dockerfile
|
|
||||||
- Makefile
|
|
||||||
- setup.sh
|
|
||||||
|
|
||||||
permissions:
|
|
||||||
contents: read
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-image-amd64:
|
|
||||||
name: "Build AMD64 Image"
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_build.yml@master
|
|
||||||
|
|
||||||
run-tests:
|
|
||||||
name: "Test AMD64 Image"
|
|
||||||
needs: build-image-amd64
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_test.yml@master
|
|
||||||
with:
|
|
||||||
cache-key: ${{ needs.build-image-amd64.outputs.build-cache-key }}
|
|
||||||
|
|
||||||
job-build-arm:
|
|
||||||
name: "Build ARM64 Image"
|
|
||||||
# Dependency ensures the cache-key is only created for AMD64 builds.
|
|
||||||
# ARM64 will not be able to use this cache, building from scratch each time.
|
|
||||||
# Expect about 2 minutes extra build time until adopting `type=gha` with scopes for cache.
|
|
||||||
needs: build-image-amd64
|
|
||||||
uses: docker-mailserver/docker-mailserver/.github/workflows/generic_build.yml@master
|
|
||||||
with:
|
|
||||||
platforms: linux/arm64
|
|
||||||
|
|
@ -1,23 +0,0 @@
|
||||||
#################################################
|
|
||||||
### General ###################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
.env
|
|
||||||
compose.override.yaml
|
|
||||||
docs/site/
|
|
||||||
docker-data/
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### IDEs ######################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
.idea/
|
|
||||||
.vscode/
|
|
||||||
|
|
||||||
#################################################
|
|
||||||
### Tests #####################################
|
|
||||||
#################################################
|
|
||||||
|
|
||||||
test/duplicate_configs/
|
|
||||||
test/config/dovecot-masters.cf
|
|
||||||
test/config/postfix-accounts.cf
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
[submodule "test/bats"]
|
|
||||||
path = test/bats
|
|
||||||
url = https://github.com/bats-core/bats-core.git
|
|
||||||
[submodule "test/test_helper/bats-support"]
|
|
||||||
path = test/test_helper/bats-support
|
|
||||||
url = https://github.com/bats-core/bats-support
|
|
||||||
[submodule "test/test_helper/bats-assert"]
|
|
||||||
path = test/test_helper/bats-assert
|
|
||||||
url = https://github.com/bats-core/bats-assert
|
|
||||||
1093
CHANGELOG.md
1093
CHANGELOG.md
File diff suppressed because it is too large
Load Diff
|
|
@ -1,76 +0,0 @@
|
||||||
# Contributor Covenant Code of Conduct
|
|
||||||
|
|
||||||
## Our Pledge
|
|
||||||
|
|
||||||
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
|
||||||
|
|
||||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
|
|
||||||
|
|
||||||
## Our Standards
|
|
||||||
|
|
||||||
Examples of behavior that contributes to a positive environment for our community include:
|
|
||||||
|
|
||||||
- Demonstrating empathy and kindness toward other people
|
|
||||||
- Being respectful of differing opinions, viewpoints, and experiences
|
|
||||||
- Giving and gracefully accepting constructive feedback
|
|
||||||
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
|
|
||||||
- Focusing on what is best not just for us as individuals, but for the
|
|
||||||
overall community
|
|
||||||
|
|
||||||
Examples of unacceptable behavior include:
|
|
||||||
|
|
||||||
- The use of sexualized language or imagery, and sexual attention or advances of any kind
|
|
||||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
|
||||||
- Public or private harassment
|
|
||||||
- Publishing others' private information, such as a physical or email address, without their explicit permission
|
|
||||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
|
||||||
|
|
||||||
## Enforcement Responsibilities
|
|
||||||
|
|
||||||
Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
|
|
||||||
|
|
||||||
Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, documentation edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
|
|
||||||
|
|
||||||
## Scope
|
|
||||||
|
|
||||||
This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
|
||||||
|
|
||||||
## Enforcement
|
|
||||||
|
|
||||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement via issue. All complaints will be reviewed and investigated promptly and fairly.
|
|
||||||
|
|
||||||
All community leaders are obligated to respect the privacy and security of the reporter of any incident.
|
|
||||||
|
|
||||||
## Enforcement Guidelines
|
|
||||||
|
|
||||||
Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
|
|
||||||
|
|
||||||
### 1. Correction
|
|
||||||
|
|
||||||
**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
|
|
||||||
|
|
||||||
**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
|
|
||||||
|
|
||||||
### 2. Warning
|
|
||||||
|
|
||||||
**Community Impact**: A violation through a single incident or series of actions.
|
|
||||||
|
|
||||||
**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
|
|
||||||
|
|
||||||
### 3. Temporary Ban
|
|
||||||
|
|
||||||
**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
|
|
||||||
|
|
||||||
**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
|
|
||||||
|
|
||||||
### 4. Permanent Ban
|
|
||||||
|
|
||||||
**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
|
|
||||||
|
|
||||||
**Consequence**: A permanent ban from any sort of public interaction within the community.
|
|
||||||
|
|
||||||
## Attribution
|
|
||||||
|
|
||||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at <https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
|
|
||||||
|
|
||||||
[homepage]: https://www.contributor-covenant.org
|
|
||||||
335
Dockerfile
335
Dockerfile
|
|
@ -1,335 +0,0 @@
|
||||||
# syntax=docker.io/docker/dockerfile:1
|
|
||||||
|
|
||||||
# This Dockerfile provides four stages: stage-base, stage-compile, stage-main and stage-final
|
|
||||||
# This is in preparation for more granular stages (eg ClamAV and Fail2Ban split into their own)
|
|
||||||
|
|
||||||
ARG DEBIAN_FRONTEND=noninteractive
|
|
||||||
ARG DOVECOT_COMMUNITY_REPO=0
|
|
||||||
ARG LOG_LEVEL=trace
|
|
||||||
|
|
||||||
FROM docker.io/debian:12-slim AS stage-base
|
|
||||||
|
|
||||||
ARG DEBIAN_FRONTEND
|
|
||||||
ARG DOVECOT_COMMUNITY_REPO
|
|
||||||
ARG LOG_LEVEL
|
|
||||||
|
|
||||||
SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Install Basic Software --------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/bin/sedfile /usr/local/bin/sedfile
|
|
||||||
RUN <<EOF
|
|
||||||
chmod +x /usr/local/bin/sedfile
|
|
||||||
adduser --quiet --system --group --disabled-password --home /var/lib/clamav --no-create-home --uid 200 clamav
|
|
||||||
EOF
|
|
||||||
|
|
||||||
COPY target/scripts/build/packages.sh /build/
|
|
||||||
COPY target/scripts/helpers/log.sh /usr/local/bin/helpers/log.sh
|
|
||||||
|
|
||||||
RUN /bin/bash /build/packages.sh && rm -r /build
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Compile deb packages ----------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
FROM stage-base AS stage-compile
|
|
||||||
|
|
||||||
ARG LOG_LEVEL
|
|
||||||
ARG DEBIAN_FRONTEND
|
|
||||||
|
|
||||||
COPY target/scripts/build/compile.sh /build/
|
|
||||||
RUN /bin/bash /build/compile.sh
|
|
||||||
|
|
||||||
#
|
|
||||||
# main stage provides all packages, config, and adds scripts
|
|
||||||
#
|
|
||||||
|
|
||||||
FROM stage-base AS stage-main
|
|
||||||
|
|
||||||
ARG DEBIAN_FRONTEND
|
|
||||||
ARG LOG_LEVEL
|
|
||||||
|
|
||||||
SHELL ["/bin/bash", "-e", "-o", "pipefail", "-c"]
|
|
||||||
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- ClamAV & FeshClam -------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
# Copy over latest DB updates from official ClamAV image. This is better than running `freshclam`,
|
|
||||||
# which would require an extra memory of 500MB+ during an image build.
|
|
||||||
# When using `COPY --link`, the `--chown` option is only compatible with numeric ID values.
|
|
||||||
# hadolint ignore=DL3021
|
|
||||||
COPY --link --chown=200 --from=docker.io/clamav/clamav-debian:latest /var/lib/clamav /var/lib/clamav
|
|
||||||
|
|
||||||
RUN <<EOF
|
|
||||||
# `COPY --link --chown=200` has a bug when built by the buildx docker-container driver.
|
|
||||||
# Restore ownership of parent dirs (Bug: https://github.com/moby/buildkit/issues/3912)
|
|
||||||
chown root:root /var /var/lib
|
|
||||||
echo '0 */6 * * * clamav /usr/bin/freshclam --quiet' >/etc/cron.d/clamav-freshclam
|
|
||||||
chmod 644 /etc/clamav/freshclam.conf
|
|
||||||
sedfile -i 's/Foreground false/Foreground true/g' /etc/clamav/clamd.conf
|
|
||||||
mkdir /var/run/clamav
|
|
||||||
chown -R clamav:root /var/run/clamav
|
|
||||||
rm -rf /var/log/clamav/
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Dovecot -----------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
# install fts_xapian plugin
|
|
||||||
|
|
||||||
COPY --from=stage-compile dovecot-fts-xapian-*.deb /
|
|
||||||
RUN dpkg -i /dovecot-fts-xapian-*.deb && rm /dovecot-fts-xapian-*.deb
|
|
||||||
|
|
||||||
COPY target/dovecot/*.inc target/dovecot/*.conf /etc/dovecot/conf.d/
|
|
||||||
COPY target/dovecot/dovecot-purge.cron /etc/cron.d/dovecot-purge.disabled
|
|
||||||
RUN chmod 0 /etc/cron.d/dovecot-purge.disabled
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Rspamd ------------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/rspamd/local.d/ /etc/rspamd/local.d/
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- OAUTH2 ------------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/dovecot/dovecot-oauth2.conf.ext /etc/dovecot
|
|
||||||
COPY target/dovecot/auth-oauth2.conf.ext /etc/dovecot/conf.d
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- LDAP & SpamAssassin's Cron ----------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/dovecot/dovecot-ldap.conf.ext /etc/dovecot
|
|
||||||
COPY target/dovecot/auth-ldap.conf.ext /etc/dovecot/conf.d
|
|
||||||
COPY \
|
|
||||||
target/postfix/ldap-users.cf \
|
|
||||||
target/postfix/ldap-groups.cf \
|
|
||||||
target/postfix/ldap-aliases.cf \
|
|
||||||
target/postfix/ldap-domains.cf \
|
|
||||||
target/postfix/ldap-senders.cf \
|
|
||||||
/etc/postfix/
|
|
||||||
|
|
||||||
# hadolint ignore=SC2016
|
|
||||||
RUN <<EOF
|
|
||||||
# ref: https://github.com/docker-mailserver/docker-mailserver/pull/3403#discussion_r1306282387
|
|
||||||
echo 'CRON=1' >/etc/default/spamassassin
|
|
||||||
sedfile -i -r 's/^\$INIT restart/supervisorctl restart amavis/g' /etc/spamassassin/sa-update-hooks.d/amavisd-new
|
|
||||||
mkdir /etc/spamassassin/kam/
|
|
||||||
curl -sSfLo /etc/spamassassin/kam/kam.sa-channels.mcgrail.com.key https://mcgrail.com/downloads/kam.sa-channels.mcgrail.com.key
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- PostSRSD, Postgrey & Amavis ---------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/postsrsd/postsrsd /etc/default/postsrsd
|
|
||||||
COPY target/postgrey/postgrey /etc/default/postgrey
|
|
||||||
RUN <<EOF
|
|
||||||
mkdir /var/run/postgrey
|
|
||||||
chown postgrey:postgrey /var/run/postgrey
|
|
||||||
curl -Lsfo /etc/postgrey/whitelist_clients https://raw.githubusercontent.com/schweikert/postgrey/master/postgrey_whitelist_clients
|
|
||||||
EOF
|
|
||||||
|
|
||||||
COPY target/amavis/conf.d/* /etc/amavis/conf.d/
|
|
||||||
COPY target/amavis/postfix-amavis.cf /etc/dms/postfix/master.d/
|
|
||||||
RUN <<EOF
|
|
||||||
sedfile -i -r 's/#(@| \\%)bypass/\1bypass/g' /etc/amavis/conf.d/15-content_filter_mode
|
|
||||||
# add users clamav and amavis to each others group
|
|
||||||
adduser clamav amavis
|
|
||||||
adduser amavis clamav
|
|
||||||
# no syslog user in Debian compared to Ubuntu
|
|
||||||
adduser --system syslog
|
|
||||||
useradd -u 5000 -d /home/docker -s /bin/bash -p "$(echo docker | openssl passwd -1 -stdin)" docker
|
|
||||||
echo "0 4 * * * /usr/local/bin/virus-wiper" | crontab -
|
|
||||||
chmod 644 /etc/amavis/conf.d/*
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# overcomplication necessary for CI
|
|
||||||
# hadolint ignore=SC2086
|
|
||||||
RUN <<EOF
|
|
||||||
for _ in {1..10}; do
|
|
||||||
su - amavis -c "razor-admin -create"
|
|
||||||
sleep 3
|
|
||||||
if su - amavis -c "razor-admin -register"; then
|
|
||||||
EC=0
|
|
||||||
break
|
|
||||||
else
|
|
||||||
EC=${?}
|
|
||||||
fi
|
|
||||||
done
|
|
||||||
exit ${EC}
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Fail2Ban, DKIM & DMARC --------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/fail2ban/jail.local /etc/fail2ban/jail.local
|
|
||||||
COPY target/fail2ban/fail2ban.d/fixes.local /etc/fail2ban/fail2ban.d/fixes.local
|
|
||||||
RUN <<EOF
|
|
||||||
ln -s /var/log/mail/mail.log /var/log/mail.log
|
|
||||||
ln -sf /var/log/mail/fail2ban.log /var/log/fail2ban.log
|
|
||||||
EOF
|
|
||||||
|
|
||||||
COPY target/opendkim/opendkim.conf /etc/opendkim.conf
|
|
||||||
COPY target/opendkim/default-opendkim /etc/default/opendkim
|
|
||||||
|
|
||||||
COPY target/opendmarc/opendmarc.conf /etc/opendmarc.conf
|
|
||||||
COPY target/opendmarc/default-opendmarc /etc/default/opendmarc
|
|
||||||
COPY target/opendmarc/ignore.hosts /etc/opendmarc/ignore.hosts
|
|
||||||
|
|
||||||
# --------------------------------------------------
|
|
||||||
# --- postfix-mta-sts-daemon -----------------------
|
|
||||||
# --------------------------------------------------
|
|
||||||
COPY target/mta-sts-daemon/mta-sts-daemon.yml /etc/mta-sts-daemon.yml
|
|
||||||
RUN <<EOF
|
|
||||||
mkdir /var/run/mta-sts
|
|
||||||
chown -R _mta-sts:root /var/run/mta-sts
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# --------------------------------------------------
|
|
||||||
# --- Fetchmail, Getmail, Postfix & Let'sEncrypt ---
|
|
||||||
# --------------------------------------------------
|
|
||||||
|
|
||||||
# Remove invalid URL from SPF message
|
|
||||||
# https://bugs.launchpad.net/spf-engine/+bug/1896912
|
|
||||||
RUN echo 'Reason_Message = Message {rejectdefer} due to: {spf}.' >>/etc/postfix-policyd-spf-python/policyd-spf.conf
|
|
||||||
|
|
||||||
COPY target/fetchmail/fetchmailrc /etc/fetchmailrc_general
|
|
||||||
COPY target/getmail/getmailrc_general /etc/getmailrc_general
|
|
||||||
COPY target/getmail/getmail-service.sh /usr/local/bin/
|
|
||||||
COPY target/postfix/main.cf target/postfix/master.cf /etc/postfix/
|
|
||||||
|
|
||||||
# DH parameters for DHE cipher suites, ffdhe4096 is the official standard 4096-bit DH params now part of TLS 1.3
|
|
||||||
# This file is for TLS <1.3 handshakes that rely on DHE cipher suites
|
|
||||||
# Handled at build to avoid failures by doveadm validating ssl_dh filepath in 10-ssl.auth (eg generate-accounts)
|
|
||||||
COPY target/shared/ffdhe4096.pem /etc/postfix/dhparams.pem
|
|
||||||
COPY target/shared/ffdhe4096.pem /etc/dovecot/dh.pem
|
|
||||||
|
|
||||||
COPY \
|
|
||||||
target/postfix/header_checks.pcre \
|
|
||||||
target/postfix/sender_header_filter.pcre \
|
|
||||||
target/postfix/sender_login_maps.pcre \
|
|
||||||
/etc/postfix/maps/
|
|
||||||
|
|
||||||
RUN <<EOF
|
|
||||||
: >/etc/aliases
|
|
||||||
sedfile -i 's/START_DAEMON=no/START_DAEMON=yes/g' /etc/default/fetchmail
|
|
||||||
mkdir /var/run/fetchmail && chown fetchmail /var/run/fetchmail
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Logs --------------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
RUN <<EOF
|
|
||||||
sedfile -i -r "/^#?compress/c\compress\ncopytruncate" /etc/logrotate.conf
|
|
||||||
mkdir /var/log/mail
|
|
||||||
chown syslog:root /var/log/mail
|
|
||||||
touch /var/log/mail/clamav.log
|
|
||||||
chown -R clamav:root /var/log/mail/clamav.log
|
|
||||||
touch /var/log/mail/freshclam.log
|
|
||||||
chown -R clamav:root /var/log/mail/freshclam.log
|
|
||||||
sedfile -i -r 's|/var/log/mail|/var/log/mail/mail|g' /etc/rsyslog.conf
|
|
||||||
sedfile -i -r 's|;auth,authpriv.none|;mail.none;mail.error;auth,authpriv.none|g' /etc/rsyslog.conf
|
|
||||||
sedfile -i -r 's|LogFile /var/log/clamav/|LogFile /var/log/mail/|g' /etc/clamav/clamd.conf
|
|
||||||
sedfile -i -r 's|UpdateLogFile /var/log/clamav/|UpdateLogFile /var/log/mail/|g' /etc/clamav/freshclam.conf
|
|
||||||
sedfile -i -r 's|/var/log/clamav|/var/log/mail|g' /etc/logrotate.d/clamav-daemon
|
|
||||||
sedfile -i -r 's|invoke-rc.d.*|/usr/bin/supervisorctl signal hup clamav >/dev/null \|\| true|g' /etc/logrotate.d/clamav-daemon
|
|
||||||
sedfile -i -r 's|/var/log/clamav|/var/log/mail|g' /etc/logrotate.d/clamav-freshclam
|
|
||||||
sedfile -i -r '/postrotate/,/endscript/d' /etc/logrotate.d/clamav-freshclam
|
|
||||||
sedfile -i -r 's|/var/log/mail|/var/log/mail/mail|g' /etc/logrotate.d/rsyslog
|
|
||||||
sedfile -i -r '/\/var\/log\/mail\/mail.log/d' /etc/logrotate.d/rsyslog
|
|
||||||
sedfile -i 's|^/var/log/fail2ban.log {$|/var/log/mail/fail2ban.log {|' /etc/logrotate.d/fail2ban
|
|
||||||
# prevent syslog logrotate warnings
|
|
||||||
sedfile -i -e 's/\(printerror "could not determine current runlevel"\)/#\1/' /usr/sbin/invoke-rc.d
|
|
||||||
sedfile -i -e 's/^\(POLICYHELPER=\).*/\1/' /usr/sbin/invoke-rc.d
|
|
||||||
# prevent syslog warning about imklog permissions
|
|
||||||
sedfile -i -e 's/^module(load=\"imklog\")/#module(load=\"imklog\")/' /etc/rsyslog.conf
|
|
||||||
# this change is for our alternative process manager rather than part of
|
|
||||||
# a fix related to the change preceding it.
|
|
||||||
echo -e '\n/usr/bin/supervisorctl signal hup rsyslog >/dev/null' >>/usr/lib/rsyslog/rsyslog-rotate
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Logwatch ----------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/logwatch/maillog.conf /etc/logwatch/conf/logfiles/maillog.conf
|
|
||||||
COPY target/logwatch/ignore.conf /etc/logwatch/conf/ignore.conf
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Supervisord & Start -----------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
COPY target/supervisor/supervisord.conf /etc/supervisor/supervisord.conf
|
|
||||||
COPY target/supervisor/conf.d/* /etc/supervisor/conf.d/
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Scripts & Miscellaneous--------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
RUN <<EOF
|
|
||||||
rm -rf /usr/share/locale/*
|
|
||||||
rm -rf /usr/share/man/*
|
|
||||||
rm -rf /usr/share/doc/*
|
|
||||||
update-locale
|
|
||||||
EOF
|
|
||||||
|
|
||||||
COPY \
|
|
||||||
target/bin/* \
|
|
||||||
target/scripts/*.sh \
|
|
||||||
target/scripts/startup/*.sh \
|
|
||||||
/usr/local/bin/
|
|
||||||
|
|
||||||
RUN chmod +x /usr/local/bin/*
|
|
||||||
|
|
||||||
COPY target/scripts/helpers /usr/local/bin/helpers
|
|
||||||
COPY target/scripts/startup/setup.d /usr/local/bin/setup.d
|
|
||||||
|
|
||||||
#
|
|
||||||
# Final stage focuses only on image config
|
|
||||||
#
|
|
||||||
|
|
||||||
FROM stage-main AS stage-final
|
|
||||||
ARG DMS_RELEASE=edge
|
|
||||||
ARG VCS_REVISION=unknown
|
|
||||||
|
|
||||||
WORKDIR /
|
|
||||||
EXPOSE 25 587 143 465 993 110 995 4190
|
|
||||||
ENTRYPOINT ["/usr/bin/dumb-init", "--"]
|
|
||||||
CMD ["supervisord", "-c", "/etc/supervisor/supervisord.conf"]
|
|
||||||
|
|
||||||
# These ENVs are referenced in target/supervisor/conf.d/saslauth.conf
|
|
||||||
# and must be present when supervisord starts. Introduced by PR:
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/pull/676
|
|
||||||
# These ENV are also configured with the same defaults at:
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/blob/672e9cf19a3bb1da309e8cea6ee728e58f905366/target/scripts/helpers/variables.sh
|
|
||||||
ENV FETCHMAIL_POLL=300
|
|
||||||
ENV POSTGREY_AUTO_WHITELIST_CLIENTS=5
|
|
||||||
ENV POSTGREY_DELAY=300
|
|
||||||
ENV POSTGREY_MAX_AGE=35
|
|
||||||
ENV POSTGREY_TEXT="Delayed by Postgrey"
|
|
||||||
ENV SASLAUTHD_MECH_OPTIONS=""
|
|
||||||
|
|
||||||
# Add metadata to image:
|
|
||||||
LABEL org.opencontainers.image.title="docker-mailserver"
|
|
||||||
LABEL org.opencontainers.image.vendor="The Docker Mailserver Organization"
|
|
||||||
LABEL org.opencontainers.image.authors="The Docker Mailserver Organization on GitHub"
|
|
||||||
LABEL org.opencontainers.image.licenses="MIT"
|
|
||||||
LABEL org.opencontainers.image.description="A fullstack but simple mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). Only configuration files, no SQL database."
|
|
||||||
LABEL org.opencontainers.image.url="https://github.com/docker-mailserver"
|
|
||||||
LABEL org.opencontainers.image.documentation="https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md"
|
|
||||||
LABEL org.opencontainers.image.source="https://github.com/docker-mailserver/docker-mailserver"
|
|
||||||
# ARG invalidates cache when it is used by a layer (implicitly affects RUN)
|
|
||||||
# Thus to maximize cache, keep these lines last:
|
|
||||||
LABEL org.opencontainers.image.revision=${VCS_REVISION}
|
|
||||||
LABEL org.opencontainers.image.version=${DMS_RELEASE}
|
|
||||||
ENV DMS_RELEASE=${DMS_RELEASE}
|
|
||||||
23
LICENSE
23
LICENSE
|
|
@ -1,23 +0,0 @@
|
||||||
The MIT License (MIT)
|
|
||||||
|
|
||||||
Copyright © 2016 & 2017 Thomas Vial & Contributors
|
|
||||||
Copyright © 2016 - 2020 The GitHub Community & Contributors
|
|
||||||
Copyright © 2021 - PRESENT The Docker Mailserver Organization & Contributors
|
|
||||||
|
|
||||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
||||||
of this software and associated documentation files (the "Software"), to deal
|
|
||||||
in the Software without restriction, including without limitation the rights
|
|
||||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
||||||
copies of the Software, and to permit persons to whom the Software is
|
|
||||||
furnished to do so, subject to the following conditions:
|
|
||||||
|
|
||||||
The above copyright notice and this permission notice shall be included in all
|
|
||||||
copies or substantial portions of the Software.
|
|
||||||
|
|
||||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
||||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
||||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
||||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
||||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
||||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
||||||
SOFTWARE.
|
|
||||||
88
Makefile
88
Makefile
|
|
@ -1,88 +0,0 @@
|
||||||
SHELL := /bin/bash
|
|
||||||
.SHELLFLAGS += -e -u -o pipefail
|
|
||||||
|
|
||||||
export REPOSITORY_ROOT := $(CURDIR)
|
|
||||||
export IMAGE_NAME ?= mailserver-testing:ci
|
|
||||||
export NAME ?= $(IMAGE_NAME)
|
|
||||||
|
|
||||||
MAKEFLAGS += --no-print-directory
|
|
||||||
BATS_FLAGS ?= --timing
|
|
||||||
BATS_PARALLEL_JOBS ?= 2
|
|
||||||
|
|
||||||
.PHONY: ALWAYS_RUN
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Generic Targets ---------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
all: lint build generate-accounts tests clean
|
|
||||||
|
|
||||||
build: ALWAYS_RUN
|
|
||||||
@ docker build --tag $(IMAGE_NAME) .
|
|
||||||
|
|
||||||
generate-accounts: ALWAYS_RUN
|
|
||||||
@ cp test/config/templates/postfix-accounts.cf test/config/postfix-accounts.cf
|
|
||||||
@ cp test/config/templates/dovecot-masters.cf test/config/dovecot-masters.cf
|
|
||||||
|
|
||||||
# `docker ps`: Remove any lingering test containers
|
|
||||||
# `.gitignore`: Remove `test/duplicate_configs` and files copied via `make generate-accounts`
|
|
||||||
clean: ALWAYS_RUN
|
|
||||||
-@ while read -r LINE; do CONTAINERS+=("$${LINE}"); done < <(docker ps -qaf name='^(dms-test|mail)_.*') ; \
|
|
||||||
for CONTAINER in "$${CONTAINERS[@]}"; do docker rm -f "$${CONTAINER}"; done
|
|
||||||
-@ while read -r LINE; do [[ $${LINE} =~ test/.+ ]] && FILES+=("/mnt$${LINE#test}"); done < .gitignore ; \
|
|
||||||
docker run --rm -v "$(REPOSITORY_ROOT)/test/:/mnt" alpine ash -c "rm -rf $${FILES[@]}"
|
|
||||||
|
|
||||||
run-local-instance: ALWAYS_RUN
|
|
||||||
bash -c 'sleep 8 ; ./setup.sh email add postmaster@example.test 123' &
|
|
||||||
docker run --rm --interactive --tty --name dms-test_example \
|
|
||||||
--env OVERRIDE_HOSTNAME=mail.example.test \
|
|
||||||
--env POSTFIX_INET_PROTOCOLS=ipv4 \
|
|
||||||
--env DOVECOT_INET_PROTOCOLS=ipv4 \
|
|
||||||
--env ENABLE_CLAMAV=0 \
|
|
||||||
--env ENABLE_AMAVIS=0 \
|
|
||||||
--env ENABLE_RSPAMD=0 \
|
|
||||||
--env ENABLE_OPENDKIM=0 \
|
|
||||||
--env ENABLE_OPENDMARC=0 \
|
|
||||||
--env ENABLE_POLICYD_SPF=0 \
|
|
||||||
--env ENABLE_SPAMASSASSIN=0 \
|
|
||||||
--env LOG_LEVEL=trace \
|
|
||||||
$(IMAGE_NAME)
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Tests ------------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
tests: ALWAYS_RUN
|
|
||||||
# See https://github.com/docker-mailserver/docker-mailserver/pull/2857#issuecomment-1312724303
|
|
||||||
# on why `generate-accounts` is run before each set (TODO/FIXME)
|
|
||||||
@ for DIR in tests/{serial,parallel/set{1,2,3}} ; do $(MAKE) generate-accounts "$${DIR}" ; done
|
|
||||||
|
|
||||||
tests/serial: ALWAYS_RUN
|
|
||||||
@ shopt -s globstar ; ./test/bats/bin/bats $(BATS_FLAGS) test/$@/*.bats
|
|
||||||
|
|
||||||
tests/parallel/set%: ALWAYS_RUN
|
|
||||||
@ shopt -s globstar ; $(REPOSITORY_ROOT)/test/bats/bin/bats $(BATS_FLAGS) \
|
|
||||||
--no-parallelize-within-files \
|
|
||||||
--jobs $(BATS_PARALLEL_JOBS) \
|
|
||||||
test/$@/**/*.bats
|
|
||||||
|
|
||||||
test/%: ALWAYS_RUN
|
|
||||||
@ shopt -s globstar nullglob ; ./test/bats/bin/bats $(BATS_FLAGS) test/tests/**/{$*,}.bats
|
|
||||||
|
|
||||||
# -----------------------------------------------
|
|
||||||
# --- Lints -------------------------------------
|
|
||||||
# -----------------------------------------------
|
|
||||||
|
|
||||||
lint: ALWAYS_RUN eclint hadolint bashcheck shellcheck
|
|
||||||
|
|
||||||
hadolint: ALWAYS_RUN
|
|
||||||
@ ./test/linting/lint.sh hadolint
|
|
||||||
|
|
||||||
bashcheck: ALWAYS_RUN
|
|
||||||
@ ./test/linting/lint.sh bashcheck
|
|
||||||
|
|
||||||
shellcheck: ALWAYS_RUN
|
|
||||||
@ ./test/linting/lint.sh shellcheck
|
|
||||||
|
|
||||||
eclint: ALWAYS_RUN
|
|
||||||
@ ./test/linting/lint.sh eclint
|
|
||||||
56
README.md
56
README.md
|
|
@ -1,56 +0,0 @@
|
||||||
# Docker Mailserver
|
|
||||||
|
|
||||||
[![ci::status]][ci::github] [![docker::pulls]][docker::hub] [![documentation::badge]][documentation::web]
|
|
||||||
|
|
||||||
[ci::status]: https://img.shields.io/github/actions/workflow/status/docker-mailserver/docker-mailserver/default_on_push.yml?branch=master&color=blue&label=CI&logo=github&logoColor=white&style=for-the-badge
|
|
||||||
[ci::github]: https://github.com/docker-mailserver/docker-mailserver/actions
|
|
||||||
[docker::pulls]: https://img.shields.io/docker/pulls/mailserver/docker-mailserver.svg?style=for-the-badge&logo=docker&logoColor=white&color=blue
|
|
||||||
[docker::hub]: https://hub.docker.com/r/mailserver/docker-mailserver/
|
|
||||||
[documentation::badge]: https://img.shields.io/badge/DOCUMENTATION-GH%20PAGES-0078D4?style=for-the-badge&logo=googledocs&logoColor=white
|
|
||||||
[documentation::web]: https://docker-mailserver.github.io/docker-mailserver/latest/
|
|
||||||
|
|
||||||
## :page_with_curl: About
|
|
||||||
|
|
||||||
A production-ready fullstack but simple containerized mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.).
|
|
||||||
- Only configuration files, no SQL database. Keep it simple and versioned. Easy to deploy and upgrade.
|
|
||||||
- Originally created by [@tomav](https://github.com/tomav), this project is now maintained by volunteers since January 2021.
|
|
||||||
|
|
||||||
## <!-- Adds a thin line break separator style -->
|
|
||||||
|
|
||||||
> [!TIP]
|
|
||||||
> Be sure to read [our documentation][documentation::web]. It provides guidance on initial setup of your mail server.
|
|
||||||
|
|
||||||
> [!IMPORTANT]
|
|
||||||
> If you have issues, please search through [the documentation][documentation::web] **for your version** before opening an issue.
|
|
||||||
>
|
|
||||||
> The issue tracker is for issues, not for personal support.
|
|
||||||
> Make sure the version of the documentation matches the image version you're using!
|
|
||||||
|
|
||||||
## :link: Links to Useful Resources
|
|
||||||
|
|
||||||
1. [FAQ](https://docker-mailserver.github.io/docker-mailserver/latest/faq/)
|
|
||||||
2. [Usage](https://docker-mailserver.github.io/docker-mailserver/latest/usage/)
|
|
||||||
3. [Examples](https://docker-mailserver.github.io/docker-mailserver/latest/examples/tutorials/basic-installation/)
|
|
||||||
4. [Issues and Contributing](https://docker-mailserver.github.io/docker-mailserver/latest/contributing/issues-and-pull-requests/)
|
|
||||||
5. [Release Notes](./CHANGELOG.md)
|
|
||||||
6. [Environment Variables](https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/)
|
|
||||||
7. [Updating](https://docker-mailserver.github.io/docker-mailserver/latest/faq/#how-do-i-update-dms)
|
|
||||||
|
|
||||||
## :package: Included Services
|
|
||||||
|
|
||||||
- [Postfix](http://www.postfix.org) with SMTP or LDAP authentication and support for [extension delimiters](https://docker-mailserver.github.io/docker-mailserver/latest/config/account-management/overview/#aliases)
|
|
||||||
- [Dovecot](https://www.dovecot.org) with SASL, IMAP, POP3, LDAP, [basic Sieve support](https://docker-mailserver.github.io/docker-mailserver/latest/config/advanced/mail-sieve) and [quotas](https://docker-mailserver.github.io/docker-mailserver/latest/config/account-management/overview/#quotas)
|
|
||||||
- [Rspamd](https://rspamd.com/)
|
|
||||||
- [Amavis](https://www.amavis.org/)
|
|
||||||
- [SpamAssassin](http://spamassassin.apache.org/) supporting custom rules
|
|
||||||
- [ClamAV](https://www.clamav.net/) with automatic updates
|
|
||||||
- [OpenDKIM](http://www.opendkim.org) & [OpenDMARC](https://github.com/trusteddomainproject/OpenDMARC)
|
|
||||||
- [Fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page)
|
|
||||||
- [Fetchmail](http://www.fetchmail.info/fetchmail-man.html)
|
|
||||||
- [Getmail6](https://getmail6.org/documentation.html)
|
|
||||||
- [Postscreen](http://www.postfix.org/POSTSCREEN_README.html)
|
|
||||||
- [Postgrey](https://postgrey.schweikert.ch/)
|
|
||||||
- Support for [LetsEncrypt](https://letsencrypt.org/), manual and self-signed certificates
|
|
||||||
- A [setup script](https://docker-mailserver.github.io/docker-mailserver/latest/config/setup.sh) for easy configuration and maintenance
|
|
||||||
- SASLauthd with LDAP authentication
|
|
||||||
- OAuth2 authentication (_via `XOAUTH2` or `OAUTHBEARER` SASL mechanisms_)
|
|
||||||
14
SECURITY.md
14
SECURITY.md
|
|
@ -1,14 +0,0 @@
|
||||||
# Security Policy
|
|
||||||
|
|
||||||
## Supported Versions
|
|
||||||
|
|
||||||
Due to the way DMS is released, the most recent patches and the most current software is published on the `:edge` tag of the container image. Hence, security updates will land on this "rolling release tag". Older tags need manual updating, as we do not usually release an updated image for an existing tag; this will only be done in case of _severe_ vulnerabilities.
|
|
||||||
|
|
||||||
| Image Tags | Latest Packages & Patches |
|
|
||||||
|-------------|:-------------------------:|
|
|
||||||
| `:edge` | :white_check_mark: |
|
|
||||||
| not `:edge` | :x: |
|
|
||||||
|
|
||||||
## Reporting a Vulnerability
|
|
||||||
|
|
||||||
When reporting a vulnerability, you can use GitHub's "Private Vulnerability Reporting". Just navigate to the [Open an Issue](https://github.com/docker-mailserver/docker-mailserver/issues/new/choose) page and choose "Report a security vulnerability". This way, maintainers will privately notified first. Afterwards, in a best-case scenario, if the vulnerability is fixed, the report will be made public.
|
|
||||||
30
compose.yaml
30
compose.yaml
|
|
@ -1,30 +0,0 @@
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
|
|
||||||
hostname: mail.example.com
|
|
||||||
env_file: mailserver.env
|
|
||||||
# More information about the mail-server ports:
|
|
||||||
# https://docker-mailserver.github.io/docker-mailserver/latest/config/security/understanding-the-ports/
|
|
||||||
ports:
|
|
||||||
- "25:25" # SMTP (explicit TLS => STARTTLS, Authentication is DISABLED => use port 465/587 instead)
|
|
||||||
- "143:143" # IMAP4 (explicit TLS => STARTTLS)
|
|
||||||
- "465:465" # ESMTP (implicit TLS)
|
|
||||||
- "587:587" # ESMTP (explicit TLS => STARTTLS)
|
|
||||||
- "993:993" # IMAP4 (implicit TLS)
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
restart: always
|
|
||||||
stop_grace_period: 1m
|
|
||||||
# Uncomment if using `ENABLE_FAIL2BAN=1`:
|
|
||||||
# cap_add:
|
|
||||||
# - NET_ADMIN
|
|
||||||
healthcheck:
|
|
||||||
test: "ss --listening --tcp | grep -P 'LISTEN.+:smtp' || exit 1"
|
|
||||||
timeout: 3s
|
|
||||||
retries: 0
|
|
||||||
|
|
@ -1,3 +0,0 @@
|
||||||
# define user's quota in this file
|
|
||||||
# E.g;
|
|
||||||
# user@domain:50M
|
|
||||||
|
|
@ -1,4 +0,0 @@
|
||||||
# File for additional dovecot configurations.
|
|
||||||
# For more information read https://doc.dovecot.org/configuration_manual/quick_configuration/
|
|
||||||
|
|
||||||
#mail_max_userip_connections = 50
|
|
||||||
|
|
@ -1,92 +0,0 @@
|
||||||
# Fail2Ban main configuration file
|
|
||||||
#
|
|
||||||
# Comments: use '#' for comment lines and ';' (following a space) for inline comments
|
|
||||||
#
|
|
||||||
# Changes: in most of the cases you should not modify this
|
|
||||||
# file, but provide customizations in fail2ban.local file, e.g.:
|
|
||||||
#
|
|
||||||
# [DEFAULT]
|
|
||||||
# loglevel = DEBUG
|
|
||||||
#
|
|
||||||
|
|
||||||
[DEFAULT]
|
|
||||||
|
|
||||||
# Option: loglevel
|
|
||||||
# Notes.: Set the log level output.
|
|
||||||
# CRITICAL
|
|
||||||
# ERROR
|
|
||||||
# WARNING
|
|
||||||
# NOTICE
|
|
||||||
# INFO
|
|
||||||
# DEBUG
|
|
||||||
# Values: [ LEVEL ] Default: INFO
|
|
||||||
#
|
|
||||||
loglevel = INFO
|
|
||||||
|
|
||||||
# Option: logtarget
|
|
||||||
# Notes.: Set the log target. This could be a file, SYSTEMD-JOURNAL, SYSLOG, STDERR or STDOUT.
|
|
||||||
# Only one log target can be specified.
|
|
||||||
# If you change logtarget from the default value and you are
|
|
||||||
# using logrotate -- also adjust or disable rotation in the
|
|
||||||
# corresponding configuration file
|
|
||||||
# (e.g. /etc/logrotate.d/fail2ban on Debian systems)
|
|
||||||
# Values: [ STDOUT | STDERR | SYSLOG | SYSOUT | SYSTEMD-JOURNAL | FILE ] Default: STDERR
|
|
||||||
#
|
|
||||||
logtarget = /var/log/fail2ban.log
|
|
||||||
|
|
||||||
# Option: syslogsocket
|
|
||||||
# Notes: Set the syslog socket file. Only used when logtarget is SYSLOG
|
|
||||||
# auto uses platform.system() to determine predefined paths
|
|
||||||
# Values: [ auto | FILE ] Default: auto
|
|
||||||
syslogsocket = auto
|
|
||||||
|
|
||||||
# Option: socket
|
|
||||||
# Notes.: Set the socket file. This is used to communicate with the daemon. Do
|
|
||||||
# not remove this file when Fail2ban runs. It will not be possible to
|
|
||||||
# communicate with the server afterwards.
|
|
||||||
# Values: [ FILE ] Default: /var/run/fail2ban/fail2ban.sock
|
|
||||||
#
|
|
||||||
socket = /var/run/fail2ban/fail2ban.sock
|
|
||||||
|
|
||||||
# Option: pidfile
|
|
||||||
# Notes.: Set the PID file. This is used to store the process ID of the
|
|
||||||
# fail2ban server.
|
|
||||||
# Values: [ FILE ] Default: /var/run/fail2ban/fail2ban.pid
|
|
||||||
#
|
|
||||||
pidfile = /var/run/fail2ban/fail2ban.pid
|
|
||||||
|
|
||||||
# Option: allowipv6
|
|
||||||
# Notes.: Allows IPv6 interface:
|
|
||||||
# Default: auto
|
|
||||||
# Values: [ auto yes (on, true, 1) no (off, false, 0) ] Default: auto
|
|
||||||
#allowipv6 = auto
|
|
||||||
|
|
||||||
# Options: dbfile
|
|
||||||
# Notes.: Set the file for the fail2ban persistent data to be stored.
|
|
||||||
# A value of ":memory:" means database is only stored in memory
|
|
||||||
# and data is lost when fail2ban is stopped.
|
|
||||||
# A value of "None" disables the database.
|
|
||||||
# Values: [ None :memory: FILE ] Default: /var/lib/fail2ban/fail2ban.sqlite3
|
|
||||||
dbfile = /var/lib/fail2ban/fail2ban.sqlite3
|
|
||||||
|
|
||||||
# Options: dbpurgeage
|
|
||||||
# Notes.: Sets age at which bans should be purged from the database
|
|
||||||
# Values: [ SECONDS ] Default: 86400 (24hours)
|
|
||||||
dbpurgeage = 1d
|
|
||||||
|
|
||||||
# Options: dbmaxmatches
|
|
||||||
# Notes.: Number of matches stored in database per ticket (resolvable via
|
|
||||||
# tags <ipmatches>/<ipjailmatches> in actions)
|
|
||||||
# Values: [ INT ] Default: 10
|
|
||||||
dbmaxmatches = 10
|
|
||||||
|
|
||||||
[Definition]
|
|
||||||
|
|
||||||
|
|
||||||
[Thread]
|
|
||||||
|
|
||||||
# Options: stacksize
|
|
||||||
# Notes.: Specifies the stack size (in KiB) to be used for subsequently created threads,
|
|
||||||
# and must be 0 or a positive integer value of at least 32.
|
|
||||||
# Values: [ SIZE ] Default: 0 (use platform or configured default)
|
|
||||||
#stacksize = 0
|
|
||||||
|
|
@ -1,40 +0,0 @@
|
||||||
[DEFAULT]
|
|
||||||
|
|
||||||
# "bantime" is the number of seconds that a host is banned.
|
|
||||||
bantime = 1w
|
|
||||||
|
|
||||||
# A host is banned if it has generated "maxretry" during the last "findtime"
|
|
||||||
# seconds.
|
|
||||||
findtime = 1w
|
|
||||||
|
|
||||||
# "maxretry" is the number of failures before a host get banned.
|
|
||||||
maxretry = 6
|
|
||||||
|
|
||||||
# "ignoreip" can be a list of IP addresses, CIDR masks or DNS hosts. Fail2ban
|
|
||||||
# will not ban a host which matches an address in this list. Several addresses
|
|
||||||
# can be defined using space (and/or comma) separator.
|
|
||||||
ignoreip = 127.0.0.1/8
|
|
||||||
|
|
||||||
# default ban action
|
|
||||||
# nftables-multiport: block IP only on affected port
|
|
||||||
# nftables-allports: block IP on all ports
|
|
||||||
banaction = nftables-allports
|
|
||||||
|
|
||||||
[dovecot]
|
|
||||||
enabled = true
|
|
||||||
|
|
||||||
[postfix]
|
|
||||||
enabled = true
|
|
||||||
# For a reference on why this mode was chose, see
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/issues/3256#issuecomment-1511188760
|
|
||||||
mode = extra
|
|
||||||
|
|
||||||
[postfix-sasl]
|
|
||||||
enabled = true
|
|
||||||
|
|
||||||
# This jail is used for manual bans.
|
|
||||||
# To ban an IP address use: setup.sh fail2ban ban <IP>
|
|
||||||
[custom]
|
|
||||||
enabled = true
|
|
||||||
bantime = 180d
|
|
||||||
port = smtp,pop3,pop3s,imap,imaps,submission,submissions,sieve
|
|
||||||
|
|
@ -1,13 +0,0 @@
|
||||||
## Example configuration: IMAP
|
|
||||||
#poll imap.example.com with proto IMAP
|
|
||||||
# user 'username' there with
|
|
||||||
# password 'secret'
|
|
||||||
# is 'user1@domain.tld'
|
|
||||||
# here ssl
|
|
||||||
|
|
||||||
## Example configuration: POP3
|
|
||||||
#poll pop3.example.com with proto POP3
|
|
||||||
# user 'username' there with
|
|
||||||
# password 'secret'
|
|
||||||
# is 'user2@domain.tld'
|
|
||||||
# here options keep ssl
|
|
||||||
|
|
@ -1,11 +0,0 @@
|
||||||
# https://getmail6.org/configuration.html#conf-options
|
|
||||||
|
|
||||||
[options]
|
|
||||||
verbose = 0
|
|
||||||
read_all = false
|
|
||||||
delete = false
|
|
||||||
max_messages_per_session = 500
|
|
||||||
received = false
|
|
||||||
delivered_to = false
|
|
||||||
message_log_syslog = true
|
|
||||||
|
|
||||||
|
|
@ -1,13 +0,0 @@
|
||||||
# https://getmail6.org/configuration.html
|
|
||||||
|
|
||||||
[retriever]
|
|
||||||
type = SimpleIMAPSSLRetriever
|
|
||||||
server = imap.gmail.com
|
|
||||||
username = alice
|
|
||||||
password = notsecure
|
|
||||||
|
|
||||||
[destination]
|
|
||||||
type = MDA_external
|
|
||||||
path = /usr/lib/dovecot/deliver
|
|
||||||
allow_root_commands = true
|
|
||||||
arguments =("-d","user1@example.com")
|
|
||||||
|
|
@ -1,13 +0,0 @@
|
||||||
# https://getmail6.org/configuration.html
|
|
||||||
|
|
||||||
[retriever]
|
|
||||||
type = SimplePOP3SSLRetriever
|
|
||||||
server = pop3.gmail.com
|
|
||||||
username = alice
|
|
||||||
password = notsecure
|
|
||||||
|
|
||||||
[destination]
|
|
||||||
type = MDA_external
|
|
||||||
path = /usr/lib/dovecot/deliver
|
|
||||||
allow_root_commands = true
|
|
||||||
arguments =("-d","user1@example.com")
|
|
||||||
|
|
@ -1,12 +0,0 @@
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# This user patches script runs right before starting the daemons.
|
|
||||||
# That means, all the other configuration is in place, so the script
|
|
||||||
# can make final adjustments.
|
|
||||||
# If you modify any supervisord configuration, make sure to run
|
|
||||||
# "supervisorctl update" or "supervisorctl reload" afterwards.
|
|
||||||
|
|
||||||
# For more information, see
|
|
||||||
# https://docker-mailserver.github.io/docker-mailserver/edge/config/advanced/override-defaults/user-patches/
|
|
||||||
|
|
||||||
echo 'user-patches.sh successfully executed'
|
|
||||||
|
|
@ -1,60 +0,0 @@
|
||||||
# Docs: https://docker-mailserver.github.io/docker-mailserver/v15.0/config/advanced/mail-fetchmail
|
|
||||||
# Additional context, with CLI commands for verification:
|
|
||||||
# https://github.com/orgs/docker-mailserver/discussions/3994#discussioncomment-9290570
|
|
||||||
|
|
||||||
services:
|
|
||||||
dms-fetch:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
|
|
||||||
hostname: mail.example.test
|
|
||||||
environment:
|
|
||||||
ENABLE_FETCHMAIL: 1
|
|
||||||
# We change this setting to 10 for quicker testing:
|
|
||||||
FETCHMAIL_POLL: 10
|
|
||||||
# Link the DNS lookup `remote.test` to resolve to the `dms-remote` container IP (for `@remote.test` address):
|
|
||||||
# This is only for this example, since no real DNS service is configured, this is a Docker internal DNS feature:
|
|
||||||
links:
|
|
||||||
- "dms-remote:remote.test"
|
|
||||||
# NOTE: Optional, You only need to publish ports if you want to verify via your own mail client.
|
|
||||||
#ports:
|
|
||||||
# - "465:465" # ESMTP (implicit TLS)
|
|
||||||
# - "993:993" # IMAP4 (implicit TLS)
|
|
||||||
# You'd normally use `volumes` here but for simplicity of the example, all config is contained within `compose.yaml`:
|
|
||||||
configs:
|
|
||||||
- source: dms-accounts-fetch
|
|
||||||
target: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
- source: fetchmail
|
|
||||||
target: /tmp/docker-mailserver/fetchmail.cf
|
|
||||||
|
|
||||||
dms-remote:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest # :15.0
|
|
||||||
hostname: mail.remote.test
|
|
||||||
environment:
|
|
||||||
# Allows for us send a test mail easily by trusting any mail client run within this container (`swaks`):
|
|
||||||
PERMIT_DOCKER: container
|
|
||||||
# Alternatively, trust and accept any mail received from clients in same subnet of dms-fetch:
|
|
||||||
#PERMIT_DOCKER: connected-networks
|
|
||||||
configs:
|
|
||||||
- source: dms-accounts-remote
|
|
||||||
target: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
|
|
||||||
# Using the Docker Compose `configs.content` feature instead of volume mounting separate files.
|
|
||||||
# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
|
|
||||||
# https://github.com/compose-spec/compose-spec/pull/446
|
|
||||||
configs:
|
|
||||||
fetchmail:
|
|
||||||
content: |
|
|
||||||
poll 'mail.remote.test' proto imap
|
|
||||||
user 'jane.doe@remote.test'
|
|
||||||
pass 'secret'
|
|
||||||
is 'john.doe@example.test'
|
|
||||||
no sslcertck
|
|
||||||
|
|
||||||
# DMS requires an account to complete setup, configure one for each instance:
|
|
||||||
# NOTE: Both accounts are configured with the same password (SHA512-CRYPT hashed), `secret`.
|
|
||||||
dms-accounts-fetch:
|
|
||||||
content: |
|
|
||||||
john.doe@example.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.
|
|
||||||
|
|
||||||
dms-accounts-remote:
|
|
||||||
content: |
|
|
||||||
jane.doe@remote.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.
|
|
||||||
|
|
@ -1,147 +0,0 @@
|
||||||
# Docs: https://docker-mailserver.github.io/docker-mailserver/v15.0/config/advanced/mail-forwarding/relay-hosts/
|
|
||||||
# Additional context, with CLI commands for verification:
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/issues/4136#issuecomment-2253693490
|
|
||||||
|
|
||||||
services:
|
|
||||||
# This would represent your actual DMS container:
|
|
||||||
dms-sender:
|
|
||||||
image: mailserver/docker-mailserver:latest # :15.0
|
|
||||||
hostname: mail.example.test
|
|
||||||
environment:
|
|
||||||
# All outbound mail will be relayed through this host
|
|
||||||
# (change the port to 587 if you do not want the postfix-main.cf override)
|
|
||||||
- DEFAULT_RELAY_HOST=[smtp.relay-service.test]:465
|
|
||||||
# Your relay host credentials.
|
|
||||||
# (since the relay in the example is DMS, the relay account username is a full email address)
|
|
||||||
- RELAY_USER=relay-user@relay-service.test
|
|
||||||
- RELAY_PASSWORD=secret
|
|
||||||
# The mail client (swaks) needs to connect with TLS:
|
|
||||||
- SSL_TYPE=manual
|
|
||||||
- SSL_KEY_PATH=/tmp/tls/key.pem
|
|
||||||
- SSL_CERT_PATH=/tmp/tls/cert.pem
|
|
||||||
# You would usually have `volumes` instead of this `configs`:
|
|
||||||
configs:
|
|
||||||
- source: dms-main
|
|
||||||
target: /tmp/docker-mailserver/postfix-main.cf
|
|
||||||
- source: dms-accounts
|
|
||||||
target: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
# Authenticating on port 587 or 465 enforces TLS requirement:
|
|
||||||
- source: tls-cert
|
|
||||||
target: /tmp/tls/cert.pem
|
|
||||||
- source: tls-key
|
|
||||||
target: /tmp/tls/key.pem
|
|
||||||
# This is only needed if you want to verify the TLS cert chain with swaks
|
|
||||||
# (normally with public CA providers like LetsEncrypt this file is already available to a mail client)
|
|
||||||
- source: tls-ca-cert
|
|
||||||
target: /tmp/tls/ca-cert.pem
|
|
||||||
|
|
||||||
# Pretend this is your third-party relay service:
|
|
||||||
dms-relay:
|
|
||||||
image: mailserver/docker-mailserver:latest # :15.0
|
|
||||||
hostname: smtp.relay-service.test
|
|
||||||
environment:
|
|
||||||
# WORKAROUND: Bypass security checks from the mail-client (dms-sender container)
|
|
||||||
# (avoids needing expected DNS records to run this example)
|
|
||||||
- PERMIT_DOCKER=connected-networks
|
|
||||||
# TLS is required when relaying to dms-relay via ports 587 / 465
|
|
||||||
# (dms-relay will then relay the mail to dms-destination over port 25)
|
|
||||||
- SSL_TYPE=manual
|
|
||||||
- SSL_KEY_PATH=/tmp/tls/key.pem
|
|
||||||
- SSL_CERT_PATH=/tmp/tls/cert.pem
|
|
||||||
configs:
|
|
||||||
- source: dms-accounts-relay
|
|
||||||
target: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
- source: tls-cert
|
|
||||||
target: /tmp/tls/cert.pem
|
|
||||||
- source: tls-key
|
|
||||||
target: /tmp/tls/key.pem
|
|
||||||
|
|
||||||
# Pretend this is another mail server that your target recipient belongs to (like Gmail):
|
|
||||||
dms-destination:
|
|
||||||
image: mailserver/docker-mailserver:latest # :15.0
|
|
||||||
hostname: mail.destination.test
|
|
||||||
# WORKAROUND: dms-relay must be able to resolve DNS for `@destination.test` to the IP of this container:
|
|
||||||
# Normally a MX record would direct mail to the MTA (eg: `mail.destination.test`)
|
|
||||||
networks:
|
|
||||||
default:
|
|
||||||
aliases:
|
|
||||||
- destination.test
|
|
||||||
environment:
|
|
||||||
# WORKAROUND: Same workaround as needed for dms-relay
|
|
||||||
- PERMIT_DOCKER=connected-networks
|
|
||||||
configs:
|
|
||||||
- source: dms-accounts-destination
|
|
||||||
target: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
|
|
||||||
# Using the Docker Compose `configs.content` feature instead of volume mounting separate files.
|
|
||||||
# NOTE: This feature requires Docker Compose v2.23.1 (Nov 2023) or newer:
|
|
||||||
# https://github.com/compose-spec/compose-spec/pull/446
|
|
||||||
configs:
|
|
||||||
# `postfix-main.cf`, a single line change to make all outbound SMTP connections over implicit TLS instead of the default explicit TLS (StartTLS).
|
|
||||||
# NOTE: If you need to only selectively relay mail, you would need to instead adjust this on the relay service in `/etc/postfix/master.cf`,
|
|
||||||
# However DMS presently modifies this when using the DMS Relay Host feature support, which may override `postfix-master.cf` or `user-patches.sh` due to `check-for-changes.sh`.
|
|
||||||
dms-main:
|
|
||||||
content: |
|
|
||||||
smtp_tls_wrappermode=yes
|
|
||||||
|
|
||||||
# DMS expects an account to be configured to run, this example provides accounts already created.
|
|
||||||
# Login credentials:
|
|
||||||
# user: "john.doe@example.test" password: "secret"
|
|
||||||
# user: "relay-user@relay-service.test" password: "secret"
|
|
||||||
# user: "jane.doe@destination.test" password: "secret"
|
|
||||||
dms-accounts:
|
|
||||||
# NOTE: `$` needed to be repeated to escape it,
|
|
||||||
# which opts out of the `compose.yaml` variable interpolation feature.
|
|
||||||
content: |
|
|
||||||
john.doe@example.test|{SHA512-CRYPT}$$6$$sbgFRCmQ.KWS5ryb$$EsWrlYosiadgdUOxCBHY0DQ3qFbeudDhNMqHs6jZt.8gmxUwiLVy738knqkHD4zj4amkb296HFqQ3yDq4UXt8.
|
|
||||||
|
|
||||||
dms-accounts-relay:
|
|
||||||
content: |
|
|
||||||
relay-user@relay-service.test|{SHA512-CRYPT}$$6$$o65y1ZXC4ooOPLwZ$$7TF1nYowEtNJpH6BwJBgdj2pPAxaCvhIKQA6ww5zdHm/AA7aemY9eoHC91DOgYNaKj1HLxSeWNDdvrp6mbtUY.
|
|
||||||
|
|
||||||
dms-accounts-destination:
|
|
||||||
content: |
|
|
||||||
jane.doe@destination.test|{SHA512-CRYPT}$$6$$o65y1ZXC4ooOPLwZ$$7TF1nYowEtNJpH6BwJBgdj2pPAxaCvhIKQA6ww5zdHm/AA7aemY9eoHC91DOgYNaKj1HLxSeWNDdvrp6mbtUY.
|
|
||||||
|
|
||||||
# TLS files:
|
|
||||||
# - Use an ECDSA cert that's been signed by a self-signed CA for TLS cert verification.
|
|
||||||
# - This cert is only valid for mail.example.test, mail.destination.test, smtp.relay-service.test
|
|
||||||
|
|
||||||
# `swaks` run in the container will need to reference this CA cert file for successful verficiation (optional).
|
|
||||||
tls-ca-cert:
|
|
||||||
content: |
|
|
||||||
-----BEGIN CERTIFICATE-----
|
|
||||||
MIIBfTCCASKgAwIBAgIRAMAZttlRlkcuSun0yV0z4RwwCgYIKoZIzj0EAwIwHDEa
|
|
||||||
MBgGA1UEAxMRU21hbGxzdGVwIFJvb3QgQ0EwHhcNMjEwMTAxMDAwMDAwWhcNMzEw
|
|
||||||
MTAxMDAwMDAwWjAcMRowGAYDVQQDExFTbWFsbHN0ZXAgUm9vdCBDQTBZMBMGByqG
|
|
||||||
SM49AgEGCCqGSM49AwEHA0IABJX2hCtoK3+bM5I3rmyApXLJ1gOcVhtoSSwM8XXR
|
|
||||||
SEl25Kkc0n6mINuMK8UrBkiBUgexf6CYayx3xVr9TmMkg4KjRTBDMA4GA1UdDwEB
|
|
||||||
/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgEBMB0GA1UdDgQWBBQD8sBrApbyYyqU
|
|
||||||
y+/TlwGynx2V5jAKBggqhkjOPQQDAgNJADBGAiEAi8N2eOETI+6hY3+G+kzNMd3K
|
|
||||||
Sd3Ke8b++/nlwr5Fb/sCIQDYAjpKp/MpTDWICeHC2tcB5ptxoTdWkTBuG4rKcktA
|
|
||||||
0w==
|
|
||||||
-----END CERTIFICATE-----
|
|
||||||
|
|
||||||
tls-key:
|
|
||||||
content: |
|
|
||||||
-----BEGIN EC PRIVATE KEY-----
|
|
||||||
MHcCAQEEIOc6wqZmSDmT336K4O26dMk1RCVc0+cmnsO2eK4P5K5yoAoGCCqGSM49
|
|
||||||
AwEHoUQDQgAEFOWNgekKKvUZE89vJ7henUYxODYIvCiHitRc2ylwttjqt1KUY1cp
|
|
||||||
q3jof2fhURHfBUH3dHPXLHig5V9Jw5gqeg==
|
|
||||||
-----END EC PRIVATE KEY-----
|
|
||||||
|
|
||||||
tls-cert:
|
|
||||||
content: |
|
|
||||||
-----BEGIN CERTIFICATE-----
|
|
||||||
MIIB9DCCAZqgAwIBAgIQE53a/y2c//YXRsz2kLm6gDAKBggqhkjOPQQDAjAcMRow
|
|
||||||
GAYDVQQDExFTbWFsbHN0ZXAgUm9vdCBDQTAeFw0yMTAxMDEwMDAwMDBaFw0zMTAx
|
|
||||||
MDEwMDAwMDBaMBkxFzAVBgNVBAMTDlNtYWxsc3RlcCBMZWFmMFkwEwYHKoZIzj0C
|
|
||||||
AQYIKoZIzj0DAQcDQgAEFOWNgekKKvUZE89vJ7henUYxODYIvCiHitRc2ylwttjq
|
|
||||||
t1KUY1cpq3jof2fhURHfBUH3dHPXLHig5V9Jw5gqeqOBwDCBvTAOBgNVHQ8BAf8E
|
|
||||||
BAMCB4AwHQYDVR0lBBYwFAYIKwYBBQUHAwEGCCsGAQUFBwMCMB0GA1UdDgQWBBSz
|
|
||||||
w74g+O6dcBbwienD70D8A9ESmDAfBgNVHSMEGDAWgBQD8sBrApbyYyqUy+/TlwGy
|
|
||||||
nx2V5jBMBgNVHREERTBDghFtYWlsLmV4YW1wbGUudGVzdIIVbWFpbC5kZXN0aW5h
|
|
||||||
dGlvbi50ZXN0ghdzbXRwLnJlbGF5LXNlcnZpY2UudGVzdDAKBggqhkjOPQQDAgNI
|
|
||||||
ADBFAiEAoety5oClZtuBMkvlUIWRmWlyg1VIOZ544LSEbplsIhcCIHb6awMwNdXP
|
|
||||||
m/xHjFkuwH1+UjDDRW53Ih7KZoLrQ6Cp
|
|
||||||
-----END CERTIFICATE-----
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 32 KiB |
|
|
@ -1,30 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<svg
|
|
||||||
id="dmo-logo-monochromatic"
|
|
||||||
viewBox="20 244 512 512"
|
|
||||||
xmlns="http://www.w3.org/2000/svg"
|
|
||||||
>
|
|
||||||
<g id="envelope">
|
|
||||||
<path
|
|
||||||
id="base"
|
|
||||||
d="m 122,490 h 172 l 70,-27 a 10,10 0 0 0 6,-12 L 315,305 A 10,10 0 0 0 302,300 L 90,380 a 10,10 0 0 0 -6,12 z"
|
|
||||||
fill="#e3e3e3"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="bottom"
|
|
||||||
d="m 294,490 70,-27 a 10,10 0 0 0 5,-5 L 220,404 174,490 Z"
|
|
||||||
fill="#d4d4d4"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="top"
|
|
||||||
d="m 84,387 150,53 75,-140 a 10,10 0 0 0 -7,0 l -212,80 a 10,10 0 0 0 -6,6 z"
|
|
||||||
fill="#ffffff"
|
|
||||||
/>
|
|
||||||
</g>
|
|
||||||
<path
|
|
||||||
id="whale-silhouette"
|
|
||||||
d="M 403,153 C 401,153 398,154 396,156 c -2,3 -20,23 -16,69 1,3 0,7 -2,9 -1,2 -4,3 -7,3 H 16.6 c -2.6,0 -5.4,1 -7.6,3 -2,2 -3,5 -3,8 0,160 117,177 168,177 129,0 219,-78 258,-148 52,-8 74,-43 75,-45 3,-5 1,-11 -4,-14 -1,-1 -31,-20 -59,-15 -7,-29 -33,-47 -35,-48 -1.75,-1.3 -3.7,-1.86 -5.66,-1.8 z M 112,300 a 21,21 0 0 1 21,21 21,21 0 0 1 -21,21 21,21 0 0 1 -21,-21 21,21 0 0 1 21,-21 z"
|
|
||||||
fill="#ffffff"
|
|
||||||
transform="translate(20,244)"
|
|
||||||
/>
|
|
||||||
</svg>
|
|
||||||
|
Before Width: | Height: | Size: 1.1 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 52 KiB |
|
|
@ -1,55 +0,0 @@
|
||||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
|
||||||
<svg
|
|
||||||
id="dmo-logo"
|
|
||||||
viewBox="20 244 512 512"
|
|
||||||
xmlns="http://www.w3.org/2000/svg"
|
|
||||||
>
|
|
||||||
<g id="envelope">
|
|
||||||
<path
|
|
||||||
id="base"
|
|
||||||
d="m 122,490 h 172 l 70,-27 a 10,10 0 0 0 6,-12 L 315,305 A 10,10 0 0 0 302,300 L 90,380 a 10,10 0 0 0 -6,12 z"
|
|
||||||
fill="#f3ac47"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="bottom"
|
|
||||||
d="m 294,490 70,-27 a 10,10 0 0 0 5,-5 L 220,404 174,490 Z"
|
|
||||||
fill="#f19a3d"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="top"
|
|
||||||
d="m 84,387 150,53 75,-140 a 10,10 0 0 0 -7,0 l -212,80 a 10,10 0 0 0 -6,6 z"
|
|
||||||
fill="#ffd15c"
|
|
||||||
/>
|
|
||||||
</g>
|
|
||||||
<g id="whale">
|
|
||||||
<path
|
|
||||||
id="body-outline"
|
|
||||||
d="M 523 462 C 522 461 492 442 464 447 C 457 418 431 400 429 399 C 425 396 420 397 416 400 C 414 403 396 423 400 469 C 401 472 400 476 398 478 C 397 480 394 481 391 481 L 36.6 481 C 34 481 31.2 482 29 484 C 27 486 26 489 26 492 C 26 652 143 669 194 669 C 323 669 413 591 452 521 C 504 513 526 478 527 476 C 530 471 528 465 523 462 Z"
|
|
||||||
fill="#303c42"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="body-fill"
|
|
||||||
d="M 445 501 C 441 502 438 504 437 507 C 402 572 317 649 194 649 C 140 649 52 629 47 502 L 391 502 C 400 502 408 498 414 492 C 420 485 423 476 422 467 C 420 446 423 432 426 424 C 434 431 445 444 445 460 C 445 464 446 467 450 469 C 453 471 456 471 460 470 C 472 463 490 469 502 474 C 493 484 475 498 445 501 Z"
|
|
||||||
fill="#42a5f5"
|
|
||||||
/>
|
|
||||||
<path
|
|
||||||
id="body-shadow"
|
|
||||||
d="M 445 491 C 441 491 438 493 437 496 C 402 562 317 638 194 638 C 142 638 57 620 48 502 L 47 502 C 52 629 140 649 194 649 C 317 649 402 572 437 507 C 438 504 441 502 445 501 C 475 498 493 484 502 474 C 499 473 497 472 494 471 C 484 479 468 488 445 491 Z"
|
|
||||||
opacity="0.1"
|
|
||||||
/>
|
|
||||||
<circle
|
|
||||||
id="eye"
|
|
||||||
cx="132"
|
|
||||||
cy="565"
|
|
||||||
r="21"
|
|
||||||
fill="#303c42"
|
|
||||||
/>
|
|
||||||
<circle
|
|
||||||
id="eye-highlight"
|
|
||||||
cx="141"
|
|
||||||
cy="559"
|
|
||||||
r="6.76"
|
|
||||||
fill="#ffffff"
|
|
||||||
/>
|
|
||||||
</g>
|
|
||||||
</svg>
|
|
||||||
|
Before Width: | Height: | Size: 1.9 KiB |
|
|
@ -1,252 +0,0 @@
|
||||||
# Account Management - Overview
|
|
||||||
|
|
||||||
This page provides a technical reference for account management in DMS.
|
|
||||||
|
|
||||||
!!! note "Account provisioners and alternative authentication support"
|
|
||||||
|
|
||||||
Each [`ACCOUNT_PROVISIONER`][docs::env::account-provisioner] has a separate page for configuration guidance and caveats:
|
|
||||||
|
|
||||||
- [`FILE` provisioner docs][docs::account-provisioner::file]
|
|
||||||
- [`LDAP` provisioner docs][docs::account-provisioner::ldap]
|
|
||||||
|
|
||||||
Authentication from the provisioner can be supplemented with additional methods:
|
|
||||||
|
|
||||||
- [OAuth2 / OIDC][docs::account-auth::oauth2] (_allow login from an external authentication service_)
|
|
||||||
- [Master Accounts][docs::account-auth::master-accounts] (_access the mailbox of any DMS account_)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
For custom authentication requirements, you could [implement this with Lua][docs::examples::auth-lua].
|
|
||||||
|
|
||||||
## Accounts
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
To receive or send mail, you'll need to provision user accounts into DMS (_as each provisioner page documents_).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
A DMS account represents a user with their _login username_ + password, and optional config like aliases and quota.
|
|
||||||
|
|
||||||
- Sending mail from different addresses **does not require** aliases or separate accounts.
|
|
||||||
- Each account is configured with a _primary email address_ that a mailbox is associated to.
|
|
||||||
|
|
||||||
??? info "Primary email address"
|
|
||||||
|
|
||||||
The email address associated to an account creates a mailbox. This address is relevant:
|
|
||||||
|
|
||||||
- When DMS **receives mail** for that address as the recipient (_or an alias that resolves to it_), to identify which mailbox to deliver into.
|
|
||||||
- With **mail submission**:
|
|
||||||
- `SPOOF_PROTECTION=1` **restricts the sender address** to the DMS account email address (_unless additional sender addresses have been permitted via supported config_).
|
|
||||||
- `SPOOF_PROTECTION=0` allows DMS accounts to **use any sender address** (_only a single DMS account is necessary to send mail with different sender addresses_).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
For more details, see the [Technical Overview](#technical-overview) section.
|
|
||||||
|
|
||||||
??? note "Support for multiple mail domains"
|
|
||||||
|
|
||||||
No extra configuration in DMS is required after provisioning an account with an email address.
|
|
||||||
|
|
||||||
- The DNS records for a domain should direct mail to DMS and allow DMS to send mail on behalf of that domain.
|
|
||||||
- DMS does not need TLS certificates for your mail domains, only for the DMS FQDN (_the `hostname` setting_).
|
|
||||||
|
|
||||||
??? warning "Choosing a compatible email address"
|
|
||||||
|
|
||||||
An email address should conform to the standard [permitted charset and format][email-syntax::valid-charset-format] (`local-part@domain-part`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
DMS has features that need to reserve special characters to work correctly. Ensure those characters are not present in email addresses you configure for DMS, otherwise disable / opt-out of the feature.
|
|
||||||
|
|
||||||
- [Sub-addressing](#sub-addressing) is enabled by default with `+` as the _tag delimiter_. The tag can be changed, feature opt-out when the tag is explicitly unset.
|
|
||||||
|
|
||||||
### Aliases
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
Aliases allow receiving mail:
|
|
||||||
|
|
||||||
- As an alternative delivery address for a DMS account mailbox.
|
|
||||||
- To redirect / forward to an external address outside of DMS like `@gmail.com`.
|
|
||||||
|
|
||||||
??? abstract "Technical Details (_Local vs Virtual aliases_)"
|
|
||||||
|
|
||||||
Aliases are managed through Postfix which supports _local_ and _virtual_ aliases:
|
|
||||||
|
|
||||||
- **Local aliases** are for mail routed to the [`local` delivery agent][postfix::delivery-agent::local] (see [associated alias config format][postfix::config-table::local-alias])
|
|
||||||
- You rarely need to configure this. It is used internally for system unix accounts belonging to the services running in DMS (_including `root`_).
|
|
||||||
- `postmaster` may be a local alias to `root`, and `root` to a virtual alias or real email address.
|
|
||||||
- Any mail sent through the `local` delivery agent will not be delivered to an inbox managed by Dovecot (_unless you have configured a local alias to redirect mail to a valid address or alias_).
|
|
||||||
- The domain-part of an these aliases belongs to your DMS FQDN (_`hostname: mail.example.com`, thus `user@mail.example.com`_). Technically there is no domain-part at this point, that context is used when routing delivery, the local delivery agent only knows of the local-part (_an alias or unix account_).
|
|
||||||
- [**Virtual aliases**][postfix-docs::virtual-alias] are for mail routed to the [`virtual` delivery agent][postfix::delivery-agent::virtual] (see [associated alias config format][postfix::config-table::virtual-alias])
|
|
||||||
- When alias support in DMS is discussed without the context of being a local or virtual alias, it's likely the virtual kind (_but could also be agnostic_).
|
|
||||||
- The domain-part of an these aliases belongs to a mail domain managed by DMS (_like `user@example.com`_).
|
|
||||||
|
|
||||||
!!! tip "Verify alias resolves correctly"
|
|
||||||
|
|
||||||
You can run `postmap -q <alias> <table>` in the container to verify an alias resolves to the expected target. If the target is also an alias, the command will not expand that alias to resolve the actual recipient(s).
|
|
||||||
|
|
||||||
For the `FILE` provisioner, an example would be: `postmap -q alias1@example.com /etc/postfix/virtual`. For the `LDAP` provisioner you'd need to adjust the table path.
|
|
||||||
|
|
||||||
!!! info "Side effect - Dovecot Quotas (`ENABLE_QUOTAS=1`)"
|
|
||||||
|
|
||||||
As a side effect of the alias workaround for the `FILE` provisioner with this feature, aliases can be used for account login. This is not intentional.
|
|
||||||
|
|
||||||
### Quotas
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
Enables mail clients with the capability to query a mailbox for disk-space used and capacity limit.
|
|
||||||
|
|
||||||
- This feature is enabled by default, opt-out via [`ENABLE_QUOTAS=0`][docs::env::enable-quotas]
|
|
||||||
- **Not implemented** for the LDAP provisioner (_PR welcome! View the [feature request for implementation advice][gh-issue::dms-feature-request::dovecot-quotas-ldap]_)
|
|
||||||
|
|
||||||
??? tip "How are quotas useful?"
|
|
||||||
|
|
||||||
Without quota limits for disk storage, a mailbox could fill up the available storage which would cause delivery failures to all mailboxes.
|
|
||||||
|
|
||||||
Quotas help by preventing that abuse, so that only a mailbox exceeding the assigned quota experiences a delivery failure instead of negatively impacting others (_provided disk space is available_).
|
|
||||||
|
|
||||||
??? abstract "Technical Details"
|
|
||||||
|
|
||||||
The [Dovecot Quotas feature][gh-pr::dms-feature::dovecot-quotas] is configured by enabling the [Dovecot `imap-quota` plugin][dovecot-docs::plugin::imap-quota] and using the [`count` quota backend][dovecot-docs::config::quota-backend-count].
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Dovecot workaround for Postfix aliases**
|
|
||||||
|
|
||||||
When mail is delivered to DMS, Postfix will query Dovecot with the recipient(s) to verify quota has not been exceeded.
|
|
||||||
|
|
||||||
This allows early rejection of mail arriving to DMS, preventing a spammer from taking advantage of a [backscatter][wikipedia::backscatter] source if the mail was accepted by Postfix, only to later be rejected by Dovecot for storage when the quota limit was already reached.
|
|
||||||
|
|
||||||
However, Postfix does not resolve aliases until after the incoming mail is accepted.
|
|
||||||
|
|
||||||
1. Postfix queries Dovecot (_a [`check_policy_service` restriction tied to the Dovecot `quota-status` service][dms::workaround::dovecot-quotas::notes-1]_) with the recipient (_the alias_).
|
|
||||||
2. `dovecot: auth: passwd-file(alias@example.com): unknown user` is logged, Postfix is then informed that the recipient mailbox is not full even if it actually was (_since no such user exists in the Dovecot UserDB_).
|
|
||||||
3. However, when the real mailbox address that the alias would later resolve into does have a quota that exceeded the configured limit, Dovecot will refuse the mail delivery from Postfix which introduces a backscatter source for spammers.
|
|
||||||
|
|
||||||
As a [workaround to this problem with the `ENABLE_QUOTAS=1` feature][dms::workaround::dovecot-quotas::summary], DMS will add aliases as fake users into Dovecot UserDB (_that are configured with the same data as the real address the alias would resolve to, thus sharing the same mailbox location and quota limit_). This allows Postfix to properly be aware of an aliased mailbox having exceeded the allowed quota.
|
|
||||||
|
|
||||||
**NOTE:** This workaround **only supports** aliases to a single target recipient of a real account address / mailbox.
|
|
||||||
|
|
||||||
- Additionally, aliases that resolve to another alias or to an external address would both fail the UserDB lookup, unable to determine if enough storage is available.
|
|
||||||
- A proper fix would [implement a Postfix policy service][dms::workaround::dovecot-quotas::notes-2] that could correctly resolve aliases to valid entries in the Dovecot UserDB, querying the `quota-status` service and returning that response to Postfix.
|
|
||||||
|
|
||||||
## Sub-addressing
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
[Subaddressing][wikipedia::subaddressing] (_aka **Plus Addressing** or **Address Tags**_) is a feature that allows you to receive mail to an address which includes a tag appended to the `local-part` of a valid account address.
|
|
||||||
|
|
||||||
- A subaddress has a tag delimiter (_default: `+`_), followed by the tag: `<local-part>+<tag>@<domain-part>`
|
|
||||||
- The subaddress `user+github@example.com` would deliver mail to the same mailbox as `user@example.com`.
|
|
||||||
- Tags are dynamic. Anything between the `+` and `@` is understood as the tag, no additional configuration required.
|
|
||||||
- Only the first occurence of the tag delimiter is recognized. Any additional occurences become part of the tag value itself.
|
|
||||||
|
|
||||||
??? tip "When is subaddressing useful?"
|
|
||||||
|
|
||||||
A common use-case is to use a unique tag for each service you register your email address with.
|
|
||||||
|
|
||||||
- Routing delivery to different folders in your mailbox based on the tag (_via a [Sieve filter][docs::sieve::subaddressing]_).
|
|
||||||
- Data leaks or bulk sales of email addresses.
|
|
||||||
- If spam / phishing mail you receive has not removed the tag, you will have better insight into where your address was compromised from.
|
|
||||||
- When the expected tag is missing, this additionally helps identify bad actors. Especially when mail delivery is routed to subfolders by tag.
|
|
||||||
- For more use-cases, view the end of [this article][web::subaddress-use-cases].
|
|
||||||
|
|
||||||
??? tip "Changing the tag delimiter"
|
|
||||||
|
|
||||||
Add `recipient_delimiter = +` to these config override files (_replacing `+` with your preferred delimiter_):
|
|
||||||
|
|
||||||
- Postfix: `docker-data/dms/config/postfix-main.cf`
|
|
||||||
- Dovecot: `docker-data/dms/config/dovecot.cf`
|
|
||||||
|
|
||||||
??? tip "Opt-out of subaddressing"
|
|
||||||
|
|
||||||
Follow the advice to change the tag delimiter, but instead set an empty value (`recipient_delimiter =`).
|
|
||||||
|
|
||||||
??? warning "Only for receiving, not sending"
|
|
||||||
|
|
||||||
Do not attempt to send mail from these tagged addresses, they are not equivalent to aliases.
|
|
||||||
|
|
||||||
This feature is only intended to be used when a mail client sends to a DMS managed recipient address. While DMS does not restrict the sender address you choose to send mail from (_provided `SPOOF_PROTECTION` has not been enabled_), it is often [forbidden by mail services][ms-exchange-docs::limitations].
|
|
||||||
|
|
||||||
??? abstract "Technical Details"
|
|
||||||
|
|
||||||
The configured tag delimiter (`+`) allows both Postfix and Dovecot to recognize subaddresses. Without this feature configured, the subaddresses would be considered as separate mail accounts rather than routed to a common account address.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Internally DMS has the tag delimiter configured by:
|
|
||||||
|
|
||||||
- Applying the Postfix `main.cf` setting: [`recipient_delimiter = +`][postfix-docs::recipient-delimiter]
|
|
||||||
- Dovecot has the equivalent setting set as `+` by default: [`recipient_delimiter = +`][dovecot-docs::config::recipient-delimiter]
|
|
||||||
|
|
||||||
## Technical Overview
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
This section provides insight for understanding how Postfix and Dovecot services are involved. It is intended as a reference for maintainers and contributors.
|
|
||||||
|
|
||||||
- **Postfix** - Handles when mail is delivered (inbound) to DMS, or sent (outbound) from DMS.
|
|
||||||
- **Dovecot** - Manages access and storage for mail delivered to the DMS account mailboxes of your users.
|
|
||||||
|
|
||||||
??? abstract "Technical Details - Postfix (Inbound vs Outbound)"
|
|
||||||
|
|
||||||
Postfix needs to know how to handle inbound and outbound mail by asking these queries:
|
|
||||||
|
|
||||||
=== "Inbound"
|
|
||||||
|
|
||||||
- What mail domains is DMS responsible for handling? (_for accepting mail delivered_)
|
|
||||||
- What are valid mail addresses for those mail domains? (_reject delivery for users that don't exist_)
|
|
||||||
- Are there any aliases to redirect mail to 1 or more users, or forward to externally?
|
|
||||||
|
|
||||||
=== "Outbound"
|
|
||||||
|
|
||||||
- When `SPOOF_PROTECTION=1`, how should DMS restrict the sender address? (_eg: Users may only send mail from their associated mailbox address_)
|
|
||||||
|
|
||||||
??? abstract "Technical Details - Dovecot (Authentication)"
|
|
||||||
|
|
||||||
Dovecot additionally handles authenticating user accounts for sending and retrieving mail:
|
|
||||||
|
|
||||||
- Over the ports for IMAP and POP3 connections (_110, 143, 993, 995_).
|
|
||||||
- As the default configured SASL provider, which Postfix delegates user authentication through (_for the submission(s) ports 465 & 587_). Saslauthd can be configured as an alternative SASL provider.
|
|
||||||
|
|
||||||
Dovecot splits all authentication lookups into two categories:
|
|
||||||
|
|
||||||
- A [PassDB][dovecot::docs::passdb] lookup most importantly authenticates the user. It may also provide any other necessary pre-login information.
|
|
||||||
- A [UserDB][dovecot::docs::userdb] lookup retrieves post-login information specific to a user.
|
|
||||||
|
|
||||||
[docs::env::account-provisioner]: ../environment.md#account_provisioner
|
|
||||||
[docs::account-provisioner::file]: ./provisioner/file.md
|
|
||||||
[docs::account-provisioner::ldap]: ./provisioner/ldap.md
|
|
||||||
[docs::account-auth::oauth2]: ./supplementary/oauth2.md
|
|
||||||
[docs::account-auth::master-accounts]: ./supplementary/master-accounts.md
|
|
||||||
[docs::examples::auth-lua]: ../../examples/use-cases/auth-lua.md
|
|
||||||
[email-syntax::valid-charset-format]: https://stackoverflow.com/questions/2049502/what-characters-are-allowed-in-an-email-address/2049510#2049510
|
|
||||||
|
|
||||||
[postfix-docs::virtual-alias]: http://www.postfix.org/VIRTUAL_README.html#virtual_alias
|
|
||||||
[postfix-docs::recipient-delimiter]: http://www.postfix.org/postconf.5.html#recipient_delimiter
|
|
||||||
[dovecot-docs::config::recipient-delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter
|
|
||||||
[postfix::delivery-agent::local]: https://www.postfix.org/local.8.html
|
|
||||||
[postfix::delivery-agent::virtual]: https://www.postfix.org/virtual.8.html
|
|
||||||
[postfix::config-table::local-alias]: https://www.postfix.org/aliases.5.html
|
|
||||||
[postfix::config-table::virtual-alias]: https://www.postfix.org/virtual.5.html
|
|
||||||
|
|
||||||
[docs::env::enable-quotas]: ../environment.md#enable_quotas
|
|
||||||
[gh-issue::dms-feature-request::dovecot-quotas-ldap]: https://github.com/docker-mailserver/docker-mailserver/issues/2957
|
|
||||||
[dovecot-docs::config::quota-backend-count]: https://doc.dovecot.org/configuration_manual/quota/quota_count/#quota-backend-count
|
|
||||||
[dovecot-docs::plugin::imap-quota]: https://doc.dovecot.org/settings/plugin/imap-quota-plugin/
|
|
||||||
[gh-pr::dms-feature::dovecot-quotas]: https://github.com/docker-mailserver/docker-mailserver/pull/1469
|
|
||||||
[wikipedia::backscatter]: https://en.wikipedia.org/wiki/Backscatter_%28email%29
|
|
||||||
[dms::workaround::dovecot-quotas::notes-1]: https://github.com/docker-mailserver/docker-mailserver/issues/2091#issuecomment-954298788
|
|
||||||
[dms::workaround::dovecot-quotas::notes-2]: https://github.com/docker-mailserver/docker-mailserver/pull/2248#issuecomment-953754532
|
|
||||||
[dms::workaround::dovecot-quotas::summary]: https://github.com/docker-mailserver/docker-mailserver/pull/2248#issuecomment-955088677
|
|
||||||
|
|
||||||
[docs::sieve::subaddressing]: ../advanced/mail-sieve.md#subaddress-mailbox-routing
|
|
||||||
[web::subaddress-use-cases]: https://www.codetwo.com/admins-blog/plus-addressing
|
|
||||||
[wikipedia::subaddressing]: https://en.wikipedia.org/wiki/Email_address#Sub-addressing
|
|
||||||
[ms-exchange-docs::limitations]: https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/plus-addressing-in-exchange-online#using-plus-addresses
|
|
||||||
|
|
||||||
[dovecot::docs::passdb]: https://doc.dovecot.org/configuration_manual/authentication/password_databases_passdb
|
|
||||||
[dovecot::docs::userdb]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb
|
|
||||||
|
|
@ -1,206 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Account Management | Provisioner (File)'
|
|
||||||
---
|
|
||||||
|
|
||||||
# Provisioner - File
|
|
||||||
|
|
||||||
## Management via the `setup` CLI
|
|
||||||
|
|
||||||
The best way to manage DMS accounts and related config files is through our `setup` CLI provided within the container.
|
|
||||||
|
|
||||||
!!! example "Using the `setup` CLI"
|
|
||||||
|
|
||||||
Try the following within the DMS container (`docker exec -it <CONTAINER NAME> bash`):
|
|
||||||
|
|
||||||
- Add an account: `setup email add <EMAIL ADDRESS>`
|
|
||||||
- Add an alias: `setup alias add <FROM ALIAS> <TO TARGET ADDRESS>`
|
|
||||||
- Learn more about the available subcommands via: `setup help`
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Starts a basic DMS instance and then shells into the container to use the `setup` CLI:
|
|
||||||
docker run --rm -itd --name dms --hostname mail.example.com mailserver/docker-mailserver
|
|
||||||
docker exec -it dms bash
|
|
||||||
|
|
||||||
# Create an account:
|
|
||||||
setup email add hello@example.com your-password-here
|
|
||||||
|
|
||||||
# Create an alias:
|
|
||||||
setup alias add your-alias-here@example.com hello@example.com
|
|
||||||
|
|
||||||
# Limit the mailbox capacity to 10 MiB:
|
|
||||||
setup quota set hello@example.com 10M
|
|
||||||
```
|
|
||||||
|
|
||||||
??? tip "Secure password input"
|
|
||||||
|
|
||||||
When you don't provide a password to the command, you will be prompted for one. This avoids the password being captured in your shell history.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# As you input your password it will not update.
|
|
||||||
# Press the ENTER key to apply the hidden password input.
|
|
||||||
$ setup email add hello@example.com
|
|
||||||
Enter Password:
|
|
||||||
Confirm Password:
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note "Account removal via `setup email del`"
|
|
||||||
|
|
||||||
When you remove a DMS account with this command, it will also remove any associated aliases and quota.
|
|
||||||
|
|
||||||
The command will also prompt for deleting the account mailbox from disk, or can be forced with the `-y` flag.
|
|
||||||
|
|
||||||
## Config Reference
|
|
||||||
|
|
||||||
These config files belong to the [Config Volume][docs::volumes::config].
|
|
||||||
|
|
||||||
### Accounts
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
**Config file:** `docker-data/dms/config/postfix-accounts.cf`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
The config format is line-based with two fields separated by the delimiter `|`:
|
|
||||||
|
|
||||||
- **User:** The primary email address for the account mailbox to use.
|
|
||||||
- **Password:** A SHA512-CRYPT hash of the account password (_in this example it is `secret`_).
|
|
||||||
|
|
||||||
??? tip "Password hash without the `setup email add` command"
|
|
||||||
|
|
||||||
A compatible password hash can be generated with:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
doveadm pw -s SHA512-CRYPT -u hello@example.com -p secret
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! example "`postfix-accounts.cf` config file"
|
|
||||||
|
|
||||||
In this example DMS manages mail for the domain `example.com`:
|
|
||||||
|
|
||||||
```cf title="postfix-accounts.cf"
|
|
||||||
hello@example.com|{SHA512-CRYPT}$6$W4rxRQwI6HNMt9n3$riCi5/OqUxnU8eZsOlZwoCnrNgu1gBGPkJc.ER.LhJCu7sOg9i1kBrRIistlBIp938GdBgMlYuoXYUU5A4Qiv0
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Dovecot "extra fields"**
|
|
||||||
|
|
||||||
[Appending a third column will customize "extra fields"][gh-issue::provisioner-file::accounts-extra-fields] when converting account data into a Dovecot UserDB entry.
|
|
||||||
|
|
||||||
DMS is not aware of these customizations beyond carrying them over, expect potential for bugs when this feature breaks any assumed conventions used in the scripts (_such as changing the mailbox path or type_).
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
Account creation will normalize the provided email address to lowercase, as DMS does not support multiple case-sensitive address variants.
|
|
||||||
|
|
||||||
The email address chosen will also represent the _login username_ credential for mail clients to authenticate with.
|
|
||||||
|
|
||||||
### Aliases
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
**Config file:** `docker-data/dms/config/postfix-virtual.cf`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
The config format is line-based with key value pairs (**alias** --> **target address**), with white-space as a delimiter.
|
|
||||||
|
|
||||||
!!! example "`postfix-virtual.cf` config file"
|
|
||||||
|
|
||||||
In this example DMS manages mail for the domain `example.com`:
|
|
||||||
|
|
||||||
```cf-extra title="postfix-virtual.cf"
|
|
||||||
# Alias delivers to an existing account:
|
|
||||||
alias1@example.com hello@example.com
|
|
||||||
|
|
||||||
# Alias forwards to an external email address:
|
|
||||||
alias2@example.com external-account@gmail.com
|
|
||||||
```
|
|
||||||
|
|
||||||
??? warning "Known Issues"
|
|
||||||
|
|
||||||
**`setup` CLI prevents an alias and account sharing an address:**
|
|
||||||
|
|
||||||
You cannot presently add a new account (`setup email add`) or alias (`setup alias add`) with an address which already exists as an alias or account in DMS.
|
|
||||||
|
|
||||||
This [restriction was enforced][gh-issue::bugs::account-alias-overlap] due to [problems it could cause][gh-issue::bugs::account-alias-overlap-problem], although there are [use-cases where you may legitimately require this functionality][gh-issue::feature-request::allow-account-alias-overlap].
|
|
||||||
|
|
||||||
For now you must manually edit the `postfix-virtual.cf` file as a workaround. There are no run-time checks outside of the `setup` CLI related to this restriction.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Wildcard catch-all support (`@example.com`):**
|
|
||||||
|
|
||||||
While this type of alias without a local-part is supported, you must keep in mind that aliases in Postfix have a higher precedence than a real address associated to a DMS account.
|
|
||||||
|
|
||||||
As a result, the wildcard is matched first and will direct mail for that entire domain to the alias target address. To work around this, [you will need an alias for each non-alias address of that domain][gh-issue::bugs::wildcard-catchall].
|
|
||||||
|
|
||||||
Additionally, Postfix will read the alias config and choose the alias value that matches the recipient address first. Ensure your more specific aliases for the domain are declared above the wildcard alias in the config file.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Aliasing to another alias or multiple recipients:**
|
|
||||||
|
|
||||||
[While aliasing to multiple recipients is possible][gh-discussions::no-support::alias-multiple-targets], DMS does not officially support that.
|
|
||||||
|
|
||||||
- You may experience issues when our feature integrations don't expect more than one target per alias.
|
|
||||||
- These concerns also apply to the usage of nested aliases (_where the recipient target provided is to an alias instead of a real address_). An example is the [incompatibility with `setup alias add`][gh-issue::bugs::alias-nested].
|
|
||||||
|
|
||||||
#### Configuring RegEx aliases
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
**Config file:** `docker-data/dms/config/postfix-regexp.cf`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
This config file is similar to the above `postfix-virtual.cf`, but the alias value is instead configured with a regex pattern.
|
|
||||||
|
|
||||||
There is **no `setup` CLI support** for this feature, it is config only.
|
|
||||||
|
|
||||||
!!! example "`postfix-regexp.cf` config file"
|
|
||||||
|
|
||||||
Deliver all mail for `test` users to `qa@example.com` instead:
|
|
||||||
|
|
||||||
```cf-extra title="postfix-regexp.cf"
|
|
||||||
# Remember to escape regex tokens like `.` => `\.`, otherwise
|
|
||||||
# your alias pattern may be more permissive than you intended:
|
|
||||||
/^test[0-9][0-9]*@example\.com/ qa@example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
??? abstract "Technical Details"
|
|
||||||
|
|
||||||
`postfix-virtual.cf` has precedence, `postfix-regexp.cf` will only be checked if no alias match was found in `postfix-virtual.cf`.
|
|
||||||
|
|
||||||
These files are both copied internally to `/etc/postfix/` and configured in `main.cf` for the `virtual_alias_maps` setting. As `postfix-virtual.cf` is declared first for that setting, it will be processed before using `postfix-regexp.cf` as a fallback.
|
|
||||||
|
|
||||||
### Quotas
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
**Config file:** `docker-data/dms/config/dovecot-quotas.cf`
|
|
||||||
|
|
||||||
----
|
|
||||||
|
|
||||||
The config format is line-based with two fields separated by the delimiter `:`:
|
|
||||||
|
|
||||||
- **Dovecot UserDB account:** The user DMS account. It should have a matching field in `postfix-accounts.cf`.
|
|
||||||
- **Quota limit:** Expressed in bytes (_binary unit suffix is supported: `M` => `MiB`, `G` => `GiB`_).
|
|
||||||
|
|
||||||
!!! example "`dovecot-quotas.cf` config file"
|
|
||||||
|
|
||||||
For the account with the mailbox address of `hello@example.com`, it may not exceed 5 GiB in storage:
|
|
||||||
|
|
||||||
```cf-extra title="dovecot-quotas.cf"
|
|
||||||
hello@example.com:5G
|
|
||||||
```
|
|
||||||
|
|
||||||
[docs::volumes::config]: ../../advanced/optional-config.md#volumes-config
|
|
||||||
[gh-issue::provisioner-file::accounts-extra-fields]: https://github.com/docker-mailserver/docker-mailserver/issues/4117
|
|
||||||
[gh-issue::feature-request::allow-account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3528
|
|
||||||
[gh-issue::bugs::account-alias-overlap-problem]: https://github.com/docker-mailserver/docker-mailserver/issues/3350#issuecomment-1550528898
|
|
||||||
[gh-issue::bugs::account-alias-overlap]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1807816689
|
|
||||||
[gh-issue::bugs::wildcard-catchall]: https://github.com/docker-mailserver/docker-mailserver/issues/3022#issuecomment-1610452561
|
|
||||||
[gh-issue::bugs::alias-nested]: https://github.com/docker-mailserver/docker-mailserver/issues/3622#issuecomment-1794504849
|
|
||||||
[gh-discussions::no-support::alias-multiple-targets]: https://github.com/orgs/docker-mailserver/discussions/3805#discussioncomment-8215417
|
|
||||||
|
|
@ -1,308 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Account Management | Provisioner (LDAP)'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
Getting started with ldap and DMS we need to take 3 parts in account:
|
|
||||||
|
|
||||||
- `postfix` for incoming & outgoing email
|
|
||||||
- `dovecot` for accessing mailboxes
|
|
||||||
- `saslauthd` for SMTP authentication (this can also be delegated to dovecot)
|
|
||||||
|
|
||||||
## Variables to Control Provisioning by the Container
|
|
||||||
|
|
||||||
Have a look at [the ENV page][docs-environment] for information on the default values.
|
|
||||||
|
|
||||||
### `LDAP_QUERY_FILTER_*`
|
|
||||||
|
|
||||||
Those variables contain the LDAP lookup filters for postfix, using `%s` as the placeholder for the domain or email address in question. This means that...
|
|
||||||
|
|
||||||
- ...for incoming email, the domain must return an entry for the `DOMAIN` filter (see [`virtual_alias_domains`](http://www.postfix.org/postconf.5.html#virtual_alias_domains)).
|
|
||||||
- ...for incoming email, the inboxes which receive the email are chosen by the `USER`, `ALIAS` and `GROUP` filters.
|
|
||||||
- The `USER` filter specifies personal mailboxes, for which only one should exist per address, for example `(mail=%s)` (also see [`virtual_mailbox_maps`](http://www.postfix.org/postconf.5.html#virtual_mailbox_maps))
|
|
||||||
- The `ALIAS` filter specifies aliases for mailboxes, using [`virtual_alias_maps`](http://www.postfix.org/postconf.5.html#virtual_alias_maps), for example `(mailAlias=%s)`
|
|
||||||
- The `GROUP` filter specifies the personal mailboxes in a group (for emails that multiple people shall receive), using [`virtual_alias_maps`](http://www.postfix.org/postconf.5.html#virtual_alias_maps), for example `(mailGroupMember=%s)`.
|
|
||||||
- Technically, there is no difference between `ALIAS` and `GROUP`, but ideally you should use `ALIAS` for personal aliases for a singular person (like `ceo@example.org`) and `GROUP` for multiple people (like `hr@example.org`).
|
|
||||||
- ...for outgoing email, the sender address is put through the `SENDERS` filter, and only if the authenticated user is one of the returned entries, the email can be sent.
|
|
||||||
- This only applies if `SPOOF_PROTECTION=1`.
|
|
||||||
- If the `SENDERS` filter is missing, the `USER`, `ALIAS` and `GROUP` filters will be used in a disjunction (OR).
|
|
||||||
- To for example allow users from the `admin` group to spoof any sender email address, and to force everyone else to only use their personal mailbox address for outgoing email, you can use something like this: `(|(memberOf=cn=admin,*)(mail=%s))`
|
|
||||||
|
|
||||||
???+ example
|
|
||||||
|
|
||||||
A really simple `LDAP_QUERY_FILTER` configuration, using only the _user filter_ and allowing only `admin@*` to spoof any sender addresses.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- LDAP_START_TLS=yes
|
|
||||||
- ACCOUNT_PROVISIONER=LDAP
|
|
||||||
- LDAP_SERVER_HOST=ldap.example.org
|
|
||||||
- LDAP_SEARCH_BASE=dc=example,dc=org"
|
|
||||||
- LDAP_BIND_DN=cn=admin,dc=example,dc=org
|
|
||||||
- LDAP_BIND_PW=mypassword
|
|
||||||
- SPOOF_PROTECTION=1
|
|
||||||
|
|
||||||
- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
|
|
||||||
- LDAP_QUERY_FILTER_USER=(mail=%s)
|
|
||||||
- LDAP_QUERY_FILTER_ALIAS=(|) # doesn't match anything
|
|
||||||
- LDAP_QUERY_FILTER_GROUP=(|) # doesn't match anything
|
|
||||||
- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(mail=admin@*))
|
|
||||||
```
|
|
||||||
|
|
||||||
### `DOVECOT_*_FILTER` & `DOVECOT_*_ATTRS`
|
|
||||||
|
|
||||||
These variables specify the LDAP filters that dovecot uses to determine if a user can log in to their IMAP account, and which mailbox is responsible to receive email for a specific postfix user.
|
|
||||||
|
|
||||||
This is split into the following two lookups, both using `%u` as the placeholder for the full login name ([see dovecot documentation for a full list of placeholders](https://doc.dovecot.org/configuration_manual/config_file/config_variables/)). Usually you only need to set `DOVECOT_USER_FILTER`, in which case it will be used for both filters.
|
|
||||||
|
|
||||||
- `DOVECOT_USER_FILTER` is used to get the account details (uid, gid, home directory, quota, ...) of a user.
|
|
||||||
- `DOVECOT_PASS_FILTER` is used to get the password information of the user, and is in pretty much all cases identical to `DOVECOT_USER_FILTER` (which is the default behavior if left away).
|
|
||||||
|
|
||||||
If your directory doesn't have the [postfix-book schema](https://github.com/variablenix/ldap-mail-schema/blob/master/postfix-book.schema) installed, then you must change the internal attribute handling for dovecot. For this you have to change the `pass_attr` and the `user_attr` mapping, as shown in the example below:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- DOVECOT_PASS_ATTRS=<YOUR_USER_IDENTIFIER_ATTRIBUTE>=user,<YOUR_USER_PASSWORD_ATTRIBUTE>=password
|
|
||||||
- DOVECOT_USER_ATTRS=<YOUR_USER_HOME_DIRECTORY_ATTRIBUTE>=home,<YOUR_USER_MAILSTORE_ATTRIBUTE>=mail,<YOUR_USER_MAIL_UID_ATTRIBUTE>=uid,<YOUR_USER_MAIL_GID_ATTRIBUTE>=gid
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
For `DOVECOT_*_ATTRS`, you can replace `ldapAttr=dovecotAttr` with `=dovecotAttr=%{ldap:ldapAttr}` for more flexibility, like for example `=home=/var/mail/%{ldap:uid}` or just `=uid=5000`.
|
|
||||||
|
|
||||||
A list of dovecot attributes can be found [in the dovecot documentation](https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/#authentication-user-database).
|
|
||||||
|
|
||||||
???+ example "Defaults"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- DOVECOT_USER_ATTRS=mailHomeDirectory=home,mailUidNumber=uid,mailGidNumber=gid,mailStorageDirectory=mail
|
|
||||||
- DOVECOT_PASS_ATTRS=uniqueIdentifier=user,userPassword=password
|
|
||||||
- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
|
|
||||||
```
|
|
||||||
|
|
||||||
???+ example
|
|
||||||
|
|
||||||
Setup for a directory that has the [qmail-schema](https://github.com/amery/qmail/blob/master/qmail.schema) installed and uses `uid`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- DOVECOT_PASS_ATTRS=uid=user,userPassword=password
|
|
||||||
- DOVECOT_USER_ATTRS=homeDirectory=home,qmailUID=uid,qmailGID=gid,mailMessageStore=mail
|
|
||||||
- DOVECOT_USER_FILTER=(&(objectClass=qmailUser)(uid=%u)(accountStatus=active))
|
|
||||||
```
|
|
||||||
|
|
||||||
The LDAP server configuration for dovecot will be taken mostly from postfix, other options can be found in [the environment section in the docs][docs-environment].
|
|
||||||
|
|
||||||
### `DOVECOT_AUTH_BIND`
|
|
||||||
|
|
||||||
Set this to `yes` to enable authentication binds ([more details in the dovecot documentation](https://wiki.dovecot.org/AuthDatabase/LDAP/AuthBinds)). Currently, only DN lookup is supported without further changes to the configuration files, so this is only useful when you want to bind as a readonly user without the permission to read passwords.
|
|
||||||
|
|
||||||
### `SASLAUTHD_LDAP_FILTER`
|
|
||||||
|
|
||||||
This filter is used for `saslauthd`, which is called by postfix when someone is authenticating through SMTP (assuming that `SASLAUTHD_MECHANISMS=ldap` is being used). Note that you'll need to set up the LDAP server for saslauthd separately from postfix.
|
|
||||||
|
|
||||||
The filter variables are explained in detail [in the `LDAP_SASLAUTHD` file](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD#L121), but unfortunately, this method doesn't really support domains right now - that means that `%U` is the only token that makes sense in this variable.
|
|
||||||
|
|
||||||
!!! note "When to use this and how to avoid it"
|
|
||||||
|
|
||||||
Using a separate filter for SMTP authentication allows you to for example allow `noreply@example.org` to send email, but not log in to IMAP or receive email: `(&(mail=%U@example.org)(|(memberOf=cn=email,*)(mail=noreply@example.org)))`
|
|
||||||
|
|
||||||
If you don't want to use a separate filter for SMTP authentication, you can set `SASLAUTHD_MECHANISMS=rimap` and `SASLAUTHD_MECH_OPTIONS=127.0.0.1` to authenticate against dovecot instead - this means that the `DOVECOT_USER_FILTER` and `DOVECOT_PASS_FILTER` will be used for SMTP authentication as well.
|
|
||||||
|
|
||||||
???+ example "Configure LDAP with `saslauthd`"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- ENABLE_SASLAUTHD=1
|
|
||||||
- SASLAUTHD_MECHANISMS=ldap
|
|
||||||
- SASLAUTHD_LDAP_FILTER=(mail=%U@example.org)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Secure Connection with LDAPS or StartTLS
|
|
||||||
|
|
||||||
To enable LDAPS, all you need to do is to add the protocol to `LDAP_SERVER_HOST`, for example `ldaps://example.org:636`.
|
|
||||||
|
|
||||||
To enable LDAP over StartTLS (on port 389), you need to set the following environment variables instead (the **protocol must not be `ldaps://`** in this case!):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- LDAP_START_TLS=yes
|
|
||||||
- DOVECOT_TLS=yes
|
|
||||||
- SASLAUTHD_LDAP_START_TLS=yes
|
|
||||||
```
|
|
||||||
|
|
||||||
## Active Directory Configurations (Tested with Samba4 AD Implementation)
|
|
||||||
|
|
||||||
In addition to LDAP explanation above, when Docker Mailserver is intended to be used with Active Directory (or the equivalent implementations like Samba4 AD DC) the following points should be taken into consideration:
|
|
||||||
|
|
||||||
- Samba4 Active Directory requires a **secure connection** to the domain controller (DC), either via SSL/TLS (LDAPS) or via StartTLS.
|
|
||||||
- The username equivalent in Active Directory is: `sAMAccountName`.
|
|
||||||
- `proxyAddresses` can be used to store email aliases of single users. The convention is to prefix the email aliases with `smtp:` (e.g: `smtp:some.name@example.com`).
|
|
||||||
- Active Directory is used typically not only as LDAP Directory storage, but also as a _domain controller_, i.e., it will do many things including authenticating users. Mixing Linux and Windows clients requires the usage of [RFC2307 attributes](https://wiki.samba.org/index.php/Administer_Unix_Attributes_in_AD_using_samba-tool_and_ldb-tools), namely `uidNumber`, `gidNumber` instead of the typical `uid`. Assigning different owner to email folders can also be done in this approach, nevertheless [there is a bug at the moment in Docker Mailserver that overwrites all permissions](https://github.com/docker-mailserver/docker-mailserver/pull/2256) when starting the container. Either a manual fix is necessary now, or a temporary workaround to use a hard-coded `ldap:uidNumber` that equals to `5000` until this issue is fixed.
|
|
||||||
- To deliver the emails to different members of Active Directory **Security Group** or **Distribution Group** (similar to mailing lists), use a [`user-patches.sh` script][docs-userpatches] to modify `ldap-groups.cf` so that it includes `leaf_result_attribute = mail` and `special_result_attribute = member`. This can be achieved simply by:
|
|
||||||
|
|
||||||
The configuration shown to get the Group to work is from [here](https://doc.zarafa.com/trunk/Administrator_Manual/en-US/html/_MTAIntegration.html) and [here](https://kb.kopano.io/display/WIKI/Postfix).
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# user-patches.sh
|
|
||||||
|
|
||||||
...
|
|
||||||
grep -q '^leaf_result_attribute = mail$' /etc/postfix/ldap-groups.cf || echo "leaf_result_attribute = mail" >> /etc/postfix/ldap-groups.cf
|
|
||||||
grep -q '^special_result_attribute = member$' /etc/postfix/ldap-groups.cf || echo "special_result_attribute = member" >> /etc/postfix/ldap-groups.cf
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
- In `/etc/ldap/ldap.conf`, if the `TLS_REQCERT` is `demand` / `hard` (default), the CA certificate used to verify the LDAP server certificate must be recognized as a trusted CA. This can be done by volume mounting the `ca.crt` file and updating the trust store via a `user-patches.sh` script:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# user-patches.sh
|
|
||||||
|
|
||||||
...
|
|
||||||
cp /MOUNTED_FOLDER/ca.crt /usr/local/share/ca-certificates/
|
|
||||||
update-ca-certificates
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
The changes on the configurations necessary to work with Active Directory (**only changes are listed, the rest of the LDAP configuration can be taken from the other examples** shown in this documentation):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# If StartTLS is the chosen method to establish a secure connection with Active Directory.
|
|
||||||
- LDAP_START_TLS=yes
|
|
||||||
- SASLAUTHD_LDAP_START_TLS=yes
|
|
||||||
- DOVECOT_TLS=yes
|
|
||||||
|
|
||||||
- LDAP_QUERY_FILTER_USER=(&(objectclass=person)(mail=%s))
|
|
||||||
- LDAP_QUERY_FILTER_ALIAS=(&(objectclass=person)(proxyAddresses=smtp:%s))
|
|
||||||
# Filters Active Directory groups (mail lists). Additional changes on ldap-groups.cf are also required as shown above.
|
|
||||||
- LDAP_QUERY_FILTER_GROUP=(&(objectClass=group)(mail=%s))
|
|
||||||
- LDAP_QUERY_FILTER_DOMAIN=(mail=*@%s)
|
|
||||||
# Allows only Domain admins to send any sender email address, otherwise the sender address must match the LDAP attribute `mail`.
|
|
||||||
- SPOOF_PROTECTION=1
|
|
||||||
- LDAP_QUERY_FILTER_SENDERS=(|(mail=%s)(proxyAddresses=smtp:%s)(memberOf=cn=Domain Admins,cn=Users,dc=*))
|
|
||||||
|
|
||||||
- DOVECOT_USER_FILTER=(&(objectclass=person)(sAMAccountName=%n))
|
|
||||||
# At the moment to be able to use %{ldap:uidNumber}, a manual bug fix as described above must be used. Otherwise %{ldap:uidNumber} %{ldap:uidNumber} must be replaced by the hard-coded value 5000.
|
|
||||||
- DOVECOT_USER_ATTRS==uid=%{ldap:uidNumber},=gid=5000,=home=/var/mail/%Ln,=mail=maildir:~/Maildir
|
|
||||||
- DOVECOT_PASS_ATTRS=sAMAccountName=user,userPassword=password
|
|
||||||
- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
|
|
||||||
```
|
|
||||||
|
|
||||||
## LDAP Setup Examples
|
|
||||||
|
|
||||||
???+ example "Basic Setup"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
hostname: mail.example.com
|
|
||||||
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "143:143"
|
|
||||||
- "587:587"
|
|
||||||
- "993:993"
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
|
|
||||||
environment:
|
|
||||||
- ENABLE_SPAMASSASSIN=1
|
|
||||||
- ENABLE_CLAMAV=1
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
- ENABLE_POSTGREY=1
|
|
||||||
|
|
||||||
# >>> Postfix LDAP Integration
|
|
||||||
- ACCOUNT_PROVISIONER=LDAP
|
|
||||||
- LDAP_SERVER_HOST=ldap.example.org
|
|
||||||
- LDAP_BIND_DN=cn=admin,ou=users,dc=example,dc=org
|
|
||||||
- LDAP_BIND_PW=mypassword
|
|
||||||
- LDAP_SEARCH_BASE=dc=example,dc=org
|
|
||||||
- LDAP_QUERY_FILTER_DOMAIN=(|(mail=*@%s)(mailAlias=*@%s)(mailGroupMember=*@%s))
|
|
||||||
- LDAP_QUERY_FILTER_USER=(&(objectClass=inetOrgPerson)(mail=%s))
|
|
||||||
- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=inetOrgPerson)(mailAlias=%s))
|
|
||||||
- LDAP_QUERY_FILTER_GROUP=(&(objectClass=inetOrgPerson)(mailGroupMember=%s))
|
|
||||||
- LDAP_QUERY_FILTER_SENDERS=(&(objectClass=inetOrgPerson)(|(mail=%s)(mailAlias=%s)(mailGroupMember=%s)))
|
|
||||||
- SPOOF_PROTECTION=1
|
|
||||||
# <<< Postfix LDAP Integration
|
|
||||||
|
|
||||||
# >>> Dovecot LDAP Integration
|
|
||||||
- DOVECOT_USER_FILTER=(&(objectClass=inetOrgPerson)(mail=%u))
|
|
||||||
- DOVECOT_PASS_ATTRS=uid=user,userPassword=password
|
|
||||||
- DOVECOT_USER_ATTRS==home=/var/mail/%{ldap:uid},=mail=maildir:~/Maildir,uidNumber=uid,gidNumber=gid
|
|
||||||
# <<< Dovecot LDAP Integration
|
|
||||||
|
|
||||||
# >>> SASL LDAP Authentication
|
|
||||||
- ENABLE_SASLAUTHD=1
|
|
||||||
- SASLAUTHD_MECHANISMS=ldap
|
|
||||||
- SASLAUTHD_LDAP_FILTER=(&(mail=%U@example.org)(objectClass=inetOrgPerson))
|
|
||||||
# <<< SASL LDAP Authentication
|
|
||||||
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
- PERMIT_DOCKER=host
|
|
||||||
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN
|
|
||||||
```
|
|
||||||
|
|
||||||
??? example "Kopano / Zarafa"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
hostname: mail.example.com
|
|
||||||
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "143:143"
|
|
||||||
- "587:587"
|
|
||||||
- "993:993"
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
|
|
||||||
environment:
|
|
||||||
# We are not using dovecot here
|
|
||||||
- SMTP_ONLY=1
|
|
||||||
- ENABLE_SPAMASSASSIN=1
|
|
||||||
- ENABLE_CLAMAV=1
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
- ENABLE_POSTGREY=1
|
|
||||||
- SASLAUTHD_PASSWD=
|
|
||||||
|
|
||||||
# >>> SASL Authentication
|
|
||||||
- ENABLE_SASLAUTHD=1
|
|
||||||
- SASLAUTHD_LDAP_FILTER=(&(sAMAccountName=%U)(objectClass=person))
|
|
||||||
- SASLAUTHD_MECHANISMS=ldap
|
|
||||||
# <<< SASL Authentication
|
|
||||||
|
|
||||||
# >>> Postfix Ldap Integration
|
|
||||||
- ACCOUNT_PROVISIONER=LDAP
|
|
||||||
- LDAP_SERVER_HOST=<yourLdapContainer/yourLdapServer>
|
|
||||||
- LDAP_SEARCH_BASE=dc=mydomain,dc=loc
|
|
||||||
- LDAP_BIND_DN=cn=Administrator,cn=Users,dc=mydomain,dc=loc
|
|
||||||
- LDAP_BIND_PW=mypassword
|
|
||||||
- LDAP_QUERY_FILTER_USER=(&(objectClass=user)(mail=%s))
|
|
||||||
- LDAP_QUERY_FILTER_GROUP=(&(objectclass=group)(mail=%s))
|
|
||||||
- LDAP_QUERY_FILTER_ALIAS=(&(objectClass=user)(otherMailbox=%s))
|
|
||||||
- LDAP_QUERY_FILTER_DOMAIN=(&(|(mail=*@%s)(mailalias=*@%s)(mailGroupMember=*@%s))(mailEnabled=TRUE))
|
|
||||||
# <<< Postfix Ldap Integration
|
|
||||||
|
|
||||||
# >>> Kopano Integration
|
|
||||||
- POSTFIX_DAGENT=lmtp:kopano:2003
|
|
||||||
# <<< Kopano Integration
|
|
||||||
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
- PERMIT_DOCKER=host
|
|
||||||
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN
|
|
||||||
```
|
|
||||||
|
|
||||||
[docs-environment]: ../../environment.md
|
|
||||||
[docs-userpatches]: ../../advanced/override-defaults/user-patches.md
|
|
||||||
|
|
@ -1,70 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Account Management | Master Accounts (Dovecot)'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
This feature is useful for administrative tasks like hot backups.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
This feature is presently [not supported with `ACCOUNT_PROVISIONER=LDAP`][dms::feature::dovecot-master-accounts::caveat-ldap].
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
A _Master Account_:
|
|
||||||
|
|
||||||
- Can login as any user (DMS account) and access their mailbox.
|
|
||||||
- Is not associated to a separate DMS account, nor is it a DMS account itself.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**`setup` CLI support**
|
|
||||||
|
|
||||||
Use the `setup dovecot-master <add|update|del|list>` commands. These are roughly equivalent to the `setup email` subcommands.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Config file:** `docker-data/dms/config/dovecot-masters.cf`
|
|
||||||
|
|
||||||
The config format is the same as [`postfix-accounts.cf` for `ACCOUNT_PROVISIONER=FILE`][docs::account-management::file::accounts].
|
|
||||||
|
|
||||||
The only difference is the account field has no `@domain-part` suffix, it is only a username.
|
|
||||||
|
|
||||||
??? abstract "Technical Details"
|
|
||||||
|
|
||||||
[The _Master Accounts_ feature][dms::feature::dovecot-master-accounts] in DMS configures the [Dovecot Master Users][dovecot-docs::auth::master-users] feature with the Dovecot setting [`auth_master_user_separator`][dovecot-docs::config::auth-master-user-separator] (_where the default value is `*`_).
|
|
||||||
|
|
||||||
## Login via Master Account
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
To login as another DMS account (`user@example.com`) with POP3 or IMAP, use the following credentials format:
|
|
||||||
|
|
||||||
- Username: `<LOGIN USERNAME>*<MASTER USER>` (`user@example.com*admin`)
|
|
||||||
- Password: `<MASTER PASSWORD>`
|
|
||||||
|
|
||||||
!!! example "Verify login functionality"
|
|
||||||
|
|
||||||
In the DMS container, you can verify with the `testsaslauthd` command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Prerequisites:
|
|
||||||
# A regular DMS account to test login through a Master Account:
|
|
||||||
setup email add user@example.com secret
|
|
||||||
# Add a new Master Account:
|
|
||||||
setup dovecot-master add admin top-secret
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Login with credentials format as described earlier:
|
|
||||||
testsaslauthd -u 'user@example.com*admin' -p 'top-secret'
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternatively, any mail client should be able to login the equivalent credentials.
|
|
||||||
|
|
||||||
[dms::feature::dovecot-master-accounts]: https://github.com/docker-mailserver/docker-mailserver/pull/2535
|
|
||||||
[dms::feature::dovecot-master-accounts::caveat-ldap]: https://github.com/docker-mailserver/docker-mailserver/pull/2535#issuecomment-1118056745
|
|
||||||
[dovecot-docs::auth::master-users]: https://doc.dovecot.org/configuration_manual/authentication/master_users/
|
|
||||||
[dovecot-docs::config::auth-master-user-separator]: https://doc.dovecot.org/settings/core/#core_setting-auth_master_user_separator
|
|
||||||
[docs::account-management::file::accounts]: ../provisioner/file.md#accounts
|
|
||||||
|
|
@ -1,145 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Account Management | OAuth2 Support'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
# Authentication - OAuth2 / OIDC
|
|
||||||
|
|
||||||
This feature enables support for delegating DMS account authentication through to an external _Identity Provider_ (IdP).
|
|
||||||
|
|
||||||
!!! warning "Receiving mail requires a DMS account to exist"
|
|
||||||
|
|
||||||
If you expect DMS to receive mail, you must provision an account into DMS in advance. Otherwise DMS has no awareness of your externally manmaged users and will reject delivery.
|
|
||||||
|
|
||||||
There are [plans to implement support to provision users through a SCIM 2.0 API][dms-feature-request::scim-api]. An IdP that can operate as a SCIM Client (eg: Authentik) would then integrate with DMS for user provisioning. Until then you must keep your user accounts in sync manually via your configured [`ACCOUNT_PROVISIONER`][docs::env::account-provisioner].
|
|
||||||
|
|
||||||
??? info "How the feature works"
|
|
||||||
|
|
||||||
1. A **mail client must have support** to acquire an OAuth2 token from your IdP (_however many clients lack generic OAuth2 / OIDC provider support_).
|
|
||||||
2. The mail client then provides that token as the user password via the login mechanism `XOAUTH2` or `OAUTHBEARER`.
|
|
||||||
3. DMS (Dovecot) will then check the validity of that token against the Authentication Service it was configured with.
|
|
||||||
4. If the response returned is valid for the user account, authentication is successful.
|
|
||||||
|
|
||||||
[**XOAUTH2**][google::xoauth2-docs] (_Googles widely adopted implementation_) and **OAUTHBEARER** (_the newer variant standardized by [RFC 7628][rfc::7628] in 2015_) are supported as standards for verifying that a OAuth Bearer Token (_[RFC 6750][rfc::6750] from 2012_) is valid at the identity provider that created the token. The token itself in both cases is expected to be can an opaque _Access Token_, but it is possible to use a JWT _ID Token_ (_which encodes additional information into the token itself_).
|
|
||||||
|
|
||||||
A mail client like Thunderbird has limited OAuth2 / OIDC support. The software maintains a hard-coded list of providers supported. Roundcube is a webmail client that does have support for generic providers, allowing you to integrate with a broader range of IdP services.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Documentation for this feature is WIP**
|
|
||||||
|
|
||||||
See the [initial feature support][dms-feature::oauth2-pr] and [existing issues][dms-feature::oidc-issues] for guidance that has not yet been documented officially.
|
|
||||||
|
|
||||||
??? tip "Verify authentication works"
|
|
||||||
|
|
||||||
If you have a compatible mail client you can verify login through that.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
??? example "CLI - Verify with `curl`"
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Shell into your DMS container:
|
|
||||||
docker exec -it dms bash
|
|
||||||
|
|
||||||
# Adjust these variables for the methods below to use:
|
|
||||||
export AUTH_METHOD='OAUTHBEARER' USER_ACCOUNT='hello@example.com' ACCESS_TOKEN='DMS_YWNjZXNzX3Rva2Vu'
|
|
||||||
|
|
||||||
# Authenticate via IMAP (Dovecot):
|
|
||||||
curl --silent --url 'imap://localhost:143' \
|
|
||||||
--login-options "AUTH=${AUTH_METHOD}" --user "${USER_ACCOUNT}" --oauth2-bearer "${ACCESS_TOKEN}" \
|
|
||||||
--request 'LOGOUT' \
|
|
||||||
&& grep "dovecot: imap-login: Login: user=<${USER_ACCOUNT}>, method=${AUTH_METHOD}" /var/log/mail/mail.log
|
|
||||||
|
|
||||||
# Authenticate via SMTP (Postfix), sending a mail with the same sender(from) and recipient(to) address:
|
|
||||||
# NOTE: `curl` seems to require `--upload-file` with some mail content provided to test SMTP auth.
|
|
||||||
curl --silent --url 'smtp://localhost:587' \
|
|
||||||
--login-options "AUTH=${AUTH_METHOD}" --user "${USER_ACCOUNT}" --oauth2-bearer "${ACCESS_TOKEN}" \
|
|
||||||
--mail-from "${USER_ACCOUNT}" --mail-rcpt "${USER_ACCOUNT}" --upload-file - <<< 'RFC 5322 content - not important' \
|
|
||||||
&& grep "postfix/submission/smtpd.*, sasl_method=${AUTH_METHOD}, sasl_username=${USER_ACCOUNT}" /var/log/mail/mail.log
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Troubleshooting:**
|
|
||||||
|
|
||||||
- Add `--verbose` to the curl options. This will output the protocol exchange which includes if authentication was successful or failed.
|
|
||||||
- The above example chains the `curl` commands with `grep` on DMS logs (_for Dovecot and Postfix services_). When not running `curl` from the DMS container, ensure you check the logs correctly, or inspect the `--verbose` output instead.
|
|
||||||
|
|
||||||
!!! warning "`curl` bug with `XOAUTH2`"
|
|
||||||
|
|
||||||
[Older releases of `curl` have a bug with `XOAUTH2` support][gh-issue::curl::xoauth2-bug] since `7.80.0` (Nov 2021) but fixed from `8.6.0` (Jan 2024). It treats `XOAUTH2` as `OAUTHBEARER`.
|
|
||||||
|
|
||||||
If you use `docker exec` to run `curl` from within DMS, the current DMS v14 release (_Debian 12 with curl `7.88.1`_) is affected by this bug.
|
|
||||||
|
|
||||||
## Config Examples
|
|
||||||
|
|
||||||
### Authentik with Roundcube
|
|
||||||
|
|
||||||
This example assumes you have already set up:
|
|
||||||
|
|
||||||
- A working DMS server
|
|
||||||
- An Authentik server ([documentation][authentik::docs::install])
|
|
||||||
- A Roundcube server ([docker image][roundcube::dockerhub-image] or [bare metal install][roundcube::docs::install])
|
|
||||||
|
|
||||||
!!! example "Setup Instructions"
|
|
||||||
|
|
||||||
=== "1. Docker Mailserver"
|
|
||||||
|
|
||||||
Update your Docker Compose ENV config to include:
|
|
||||||
|
|
||||||
```env title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
env:
|
|
||||||
# Enable the feature:
|
|
||||||
- ENABLE_OAUTH2=1
|
|
||||||
# Specify the user info endpoint URL of the oauth2 server for token inspection:
|
|
||||||
- OAUTH2_INTROSPECTION_URL=https://authentik.example.com/application/o/userinfo/
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "2. Authentik"
|
|
||||||
|
|
||||||
1. Create a new OAuth2 provider.
|
|
||||||
2. Note the client id and client secret. Roundcube will need this.
|
|
||||||
3. Set the allowed redirect url to the equivalent of `https://roundcube.example.com/index.php/login/oauth` for your RoundCube instance.
|
|
||||||
|
|
||||||
=== "3. Roundcube"
|
|
||||||
|
|
||||||
Add the following to `oauth2.inc.php` ([documentation][roundcube::docs::config]):
|
|
||||||
|
|
||||||
```php
|
|
||||||
$config['oauth_provider'] = 'generic';
|
|
||||||
$config['oauth_provider_name'] = 'Authentik';
|
|
||||||
$config['oauth_client_id'] = '<insert client id here>';
|
|
||||||
$config['oauth_client_secret'] = '<insert client secret here>';
|
|
||||||
$config['oauth_auth_uri'] = 'https://authentik.example.com/application/o/authorize/';
|
|
||||||
$config['oauth_token_uri'] = 'https://authentik.example.com/application/o/token/';
|
|
||||||
$config['oauth_identity_uri'] = 'https://authentik.example.com/application/o/userinfo/';
|
|
||||||
|
|
||||||
// Optional: disable SSL certificate check on HTTP requests to OAuth server. For possible values, see:
|
|
||||||
// http://docs.guzzlephp.org/en/stable/request-options.html#verify
|
|
||||||
$config['oauth_verify_peer'] = false;
|
|
||||||
|
|
||||||
$config['oauth_scope'] = 'email openid profile';
|
|
||||||
$config['oauth_identity_fields'] = ['email'];
|
|
||||||
|
|
||||||
// Boolean: automatically redirect to OAuth login when opening Roundcube without a valid session
|
|
||||||
$config['oauth_login_redirect'] = false;
|
|
||||||
```
|
|
||||||
|
|
||||||
[dms-feature::oauth2-pr]: https://github.com/docker-mailserver/docker-mailserver/pull/3480
|
|
||||||
[dms-feature::oidc-issues]: https://github.com/docker-mailserver/docker-mailserver/issues?q=label%3Afeature%2Fauth-oidc
|
|
||||||
[docs::env::account-provisioner]: ../../environment.md#account_provisioner
|
|
||||||
[dms-feature-request::scim-api]: https://github.com/docker-mailserver/docker-mailserver/issues/4090
|
|
||||||
|
|
||||||
[google::xoauth2-docs]: https://developers.google.com/gmail/imap/xoauth2-protocol#the_sasl_xoauth2_mechanism
|
|
||||||
[rfc::6750]: https://datatracker.ietf.org/doc/html/rfc6750
|
|
||||||
[rfc::7628]: https://datatracker.ietf.org/doc/html/rfc7628
|
|
||||||
[gh-issue::curl::xoauth2-bug]: https://github.com/curl/curl/issues/10259#issuecomment-1907192556
|
|
||||||
|
|
||||||
[authentik::docs::install]: https://goauthentik.io/docs/installation/
|
|
||||||
[roundcube::dockerhub-image]: https://hub.docker.com/r/roundcube/roundcubemail
|
|
||||||
[roundcube::docs::install]: https://github.com/roundcube/roundcubemail/wiki/Installation
|
|
||||||
[roundcube::docs::config]: https://github.com/roundcube/roundcubemail/wiki/Configuration
|
|
||||||
|
|
@ -1,144 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Full-Text Search'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Full-text search allows all messages to be indexed, so that mail clients can quickly and efficiently search messages by their full text content. Dovecot supports a variety of community supported [FTS indexing backends](https://doc.dovecot.org/configuration_manual/fts/).
|
|
||||||
|
|
||||||
DMS comes pre-installed with two plugins that can be enabled with a dovecot config file.
|
|
||||||
|
|
||||||
Please be aware that indexing consumes memory and takes up additional disk space.
|
|
||||||
|
|
||||||
### Xapian
|
|
||||||
|
|
||||||
The [dovecot-fts-xapian](https://github.com/grosjo/fts-xapian) plugin makes use of [Xapian](https://xapian.org/). Xapian enables embedding an FTS engine without the need for additional backends.
|
|
||||||
|
|
||||||
The indexes will be stored as a subfolder named `xapian-indexes` inside your local `mail-data` folder (_`/var/mail` internally_). With the default settings, 10GB of email data may generate around 4GB of indexed data.
|
|
||||||
|
|
||||||
While indexing is memory intensive, you can configure the plugin to limit the amount of memory consumed by the index workers. With Xapian being small and fast, this plugin is a good choice for low memory environments (2GB).
|
|
||||||
|
|
||||||
#### Setup
|
|
||||||
|
|
||||||
1. To configure `fts-xapian` as a dovecot plugin, create a file at `docker-data/dms/config/dovecot/fts-xapian-plugin.conf` and place the following in it:
|
|
||||||
|
|
||||||
```
|
|
||||||
mail_plugins = $mail_plugins fts fts_xapian
|
|
||||||
|
|
||||||
plugin {
|
|
||||||
fts = xapian
|
|
||||||
fts_xapian = partial=3 full=20 verbose=0
|
|
||||||
|
|
||||||
fts_autoindex = yes
|
|
||||||
fts_enforced = yes
|
|
||||||
|
|
||||||
# disable indexing of folders
|
|
||||||
# fts_autoindex_exclude = \Trash
|
|
||||||
|
|
||||||
# Index attachements
|
|
||||||
# fts_decoder = decode2text
|
|
||||||
}
|
|
||||||
|
|
||||||
service indexer-worker {
|
|
||||||
# limit size of indexer-worker RAM usage, ex: 512MB, 1GB, 2GB
|
|
||||||
vsz_limit = 1GB
|
|
||||||
}
|
|
||||||
|
|
||||||
# service decode2text {
|
|
||||||
# executable = script /usr/libexec/dovecot/decode2text.sh
|
|
||||||
# user = dovecot
|
|
||||||
# unix_listener decode2text {
|
|
||||||
# mode = 0666
|
|
||||||
# }
|
|
||||||
# }
|
|
||||||
```
|
|
||||||
|
|
||||||
adjust the settings to tune for your desired memory limits, exclude folders and enable searching text inside of attachments
|
|
||||||
|
|
||||||
2. Update `compose.yaml` to load the previously created dovecot plugin config file:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
hostname: mail.example.com
|
|
||||||
env_file: mailserver.env
|
|
||||||
ports:
|
|
||||||
- "25:25" # SMTP (explicit TLS => STARTTLS)
|
|
||||||
- "143:143" # IMAP4 (explicit TLS => STARTTLS)
|
|
||||||
- "465:465" # ESMTP (implicit TLS)
|
|
||||||
- "587:587" # ESMTP (explicit TLS => STARTTLS)
|
|
||||||
- "993:993" # IMAP4 (implicit TLS)
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- ./docker-data/dms/config/dovecot/fts-xapian-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
restart: always
|
|
||||||
stop_grace_period: 1m
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Recreate containers:
|
|
||||||
|
|
||||||
```
|
|
||||||
docker compose down
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Initialize indexing on all users for all mail:
|
|
||||||
|
|
||||||
```
|
|
||||||
docker compose exec mailserver doveadm index -A -q \*
|
|
||||||
```
|
|
||||||
|
|
||||||
5. Run the following command in a daily cron job:
|
|
||||||
|
|
||||||
```
|
|
||||||
docker compose exec mailserver doveadm fts optimize -A
|
|
||||||
```
|
|
||||||
Or like the [Spamassassin example][docs-faq-sa-learn-cron] shows, you can instead use `cron` from within DMS to avoid potential errors if the mail server is not running:
|
|
||||||
|
|
||||||
??? example
|
|
||||||
|
|
||||||
Create a _system_ cron file:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# in the compose.yaml root directory
|
|
||||||
mkdir -p ./docker-data/dms/cron # if you didn't have this folder before
|
|
||||||
touch ./docker-data/dms/cron/fts_xapian
|
|
||||||
chown root:root ./docker-data/dms/cron/fts_xapian
|
|
||||||
chmod 0644 ./docker-data/dms/cron/fts_xapian
|
|
||||||
```
|
|
||||||
|
|
||||||
Edit the system cron file `nano ./docker-data/dms/cron/fts_xapian`, and set an appropriate configuration:
|
|
||||||
|
|
||||||
```conf
|
|
||||||
# Adding `MAILTO=""` prevents cron emailing notifications of the task outcome each run
|
|
||||||
MAILTO=""
|
|
||||||
#
|
|
||||||
# m h dom mon dow user command
|
|
||||||
#
|
|
||||||
# Everyday 4:00AM, optimize index files
|
|
||||||
0 4 * * * root doveadm fts optimize -A
|
|
||||||
```
|
|
||||||
|
|
||||||
Then with `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/cron/fts_xapian:/etc/cron.d/fts_xapian
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Further Discussion
|
|
||||||
|
|
||||||
See [#905](https://github.com/docker-mailserver/docker-mailserver/issues/905)
|
|
||||||
|
|
||||||
[docs-faq-sa-learn-cron]: ../../faq.md#how-can-i-make-spamassassin-better-recognize-spam
|
|
||||||
|
|
@ -1,217 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | IPv6'
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! bug "Ample Opportunities for Issues"
|
|
||||||
|
|
||||||
Numerous bug reports have been raised in the past about IPv6. Please make sure your setup around DMS is correct when using IPv6!
|
|
||||||
|
|
||||||
## IPv6 networking problems with Docker defaults
|
|
||||||
|
|
||||||
### What can go wrong?
|
|
||||||
|
|
||||||
If your host system supports IPv6 and an `AAAA` DNS record exists to direct IPv6 traffic to DMS, you may experience issues when an IPv6 connection is made:
|
|
||||||
|
|
||||||
- The original client IP is replaced with the gateway IP of a docker network.
|
|
||||||
- Connections fail or hang.
|
|
||||||
|
|
||||||
The impact of losing the real IP of the client connection can negatively affect DMS:
|
|
||||||
|
|
||||||
- Users unable to login (_Fail2Ban action triggered by repeated login failures all seen as from the same internal Gateway IP_)
|
|
||||||
- Mail inbound to DMS is rejected (_[SPF verification failure][gh-issue-1438-spf], IP mismatch_)
|
|
||||||
- Delivery failures from [sender reputation][sender-score] being reduced (_due to [bouncing inbound mail][gh-issue-3057-bounce] from rejected IPv6 clients_)
|
|
||||||
- Some services may be configured to trust connecting clients within the containers subnet, which includes the Gateway IP. This can risk bypassing or relaxing security measures, such as exposing an [open relay][wikipedia-openrelay].
|
|
||||||
|
|
||||||
### Why does this happen?
|
|
||||||
|
|
||||||
When the host network receives a connection to a containers published port, it is routed to the containers internal network managed by Docker (_typically a bridge network_).
|
|
||||||
|
|
||||||
By default, the Docker daemon only assigns IPv4 addresses to containers, thus it will only accept IPv4 connections (_unless a `docker-proxy` process is listening, which the default daemon setting `userland-proxy: true` enables_). With the daemon setting `userland-proxy: true` (default), IPv6 connections from the host can also be accepted and routed to containers (_even when they only have IPv4 addresses assigned_). `userland-proxy: false` will require the container to have atleast an IPv6 address assigned.
|
|
||||||
|
|
||||||
This can be problematic for IPv6 host connections when internally the container is no longer aware of the original client IPv6 address, as it has been proxied through the IPv4 or IPv6 gateway address of it's connected network (_eg: `172.17.0.1` - Docker allocates networks from a set of [default subnets][docker-subnets]_).
|
|
||||||
|
|
||||||
This can be fixed by enabling a Docker network to assign IPv6 addresses to containers, along with some additional configuration. Alternatively you could configure the opposite to prevent IPv6 connections being made.
|
|
||||||
|
|
||||||
## Prevent IPv6 connections
|
|
||||||
|
|
||||||
- Avoiding an `AAAA` DNS record for your DMS FQDN would prevent resolving an IPv6 address to connect to.
|
|
||||||
- You can also use `userland-proxy: false`, which will fail to establish a remote connection to DMS (_provided no IPv6 address was assigned_).
|
|
||||||
|
|
||||||
!!! tip "With UFW or Firewalld"
|
|
||||||
|
|
||||||
When one of these firewall frontends are active, remote clients should fail to connect instead of being masqueraded as the docker network gateway IP. Keep in mind that this only affects remote clients, it does not affect local IPv6 connections originating within the same host.
|
|
||||||
|
|
||||||
## Enable proper IPv6 support
|
|
||||||
|
|
||||||
You can enable IPv6 support in Docker for container networks, however [compatibility concerns][docs-compat] may affect your success.
|
|
||||||
|
|
||||||
The [official Docker documentation on enabling IPv6][docker-docs-enable-ipv6] has been improving and is a good resource to reference.
|
|
||||||
|
|
||||||
Enable `ip6tables` support so that Docker will manage IPv6 networking rules as well. This will allow for IPv6 NAT to work like the existing IPv4 NAT already does for your containers, avoiding the above issue with external connections having their IP address seen as the container network gateway IP (_provided an IPv6 address is also assigned to the container_).
|
|
||||||
|
|
||||||
!!! example "Configure the following in `/etc/docker/daemon.json`"
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"ip6tables": true,
|
|
||||||
"experimental" : true,
|
|
||||||
"userland-proxy": true
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- `experimental: true` is currently required for `ip6tables: true` to work.
|
|
||||||
- `userland-proxy` setting [can potentially affect connection behavior][gh-pull-3244-proxy] for local connections.
|
|
||||||
|
|
||||||
Now restart the daemon if it's running: `systemctl restart docker`.
|
|
||||||
|
|
||||||
Next, configure a network with an IPv6 subnet for your container with any of these examples:
|
|
||||||
|
|
||||||
???+ example "Create an IPv6 ULA subnet"
|
|
||||||
|
|
||||||
??? info "About these examples"
|
|
||||||
|
|
||||||
These examples are focused on a [IPv6 ULA subnet][wikipedia-ipv6-ula] which is suitable for most users as described in the next section.
|
|
||||||
|
|
||||||
- You may prefer a subnet size smaller than `/64` (eg: `/112`, which still provides over 65k IPv6 addresses), especially if instead configuring for an IPv6 GUA subnet.
|
|
||||||
- The network will also implicitly be assigned an IPv4 subnet (_from the Docker daemon config `default-address-pools`_).
|
|
||||||
|
|
||||||
=== "User-defined Network"
|
|
||||||
|
|
||||||
The preferred approach is with [user-defined networks][docker-docs-ipv6-create-custom] via `compose.yaml` (recommended) or CLI with `docker network create`:
|
|
||||||
|
|
||||||
=== "Compose"
|
|
||||||
|
|
||||||
Create the network in `compose.yaml` and attach a service to it:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
networks:
|
|
||||||
- dms-ipv6
|
|
||||||
|
|
||||||
networks:
|
|
||||||
dms-ipv6:
|
|
||||||
enable_ipv6: true
|
|
||||||
ipam:
|
|
||||||
config:
|
|
||||||
- subnet: fd00:cafe:face:feed::/64
|
|
||||||
```
|
|
||||||
|
|
||||||
??? tip "Override the implicit `default` network"
|
|
||||||
|
|
||||||
You can optionally avoid the service assignment by [overriding the `default` user-defined network that Docker Compose generates][docker-docs-network-compose-default]. Just replace `dms-ipv6` with `default`.
|
|
||||||
|
|
||||||
The Docker Compose `default` bridge is not affected by settings for the default `bridge` (aka `docker0`) in `/etc/docker/daemon.json`.
|
|
||||||
|
|
||||||
??? tip "Using the network outside of this `compose.yaml`"
|
|
||||||
|
|
||||||
To reference this network externally (_from other compose files or `docker run`_), assign the [networks `name` key in `compose.yaml`][docker-docs-network-external].
|
|
||||||
|
|
||||||
=== "CLI"
|
|
||||||
|
|
||||||
Create the network via a CLI command (_which can then be used with `docker run --network dms-ipv6`_):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker network create --ipv6 --subnet fd00:cafe:face:feed::/64 dms-ipv6
|
|
||||||
```
|
|
||||||
|
|
||||||
Optionally reference it from one or more `compose.yaml` files:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
networks:
|
|
||||||
- dms-ipv6
|
|
||||||
|
|
||||||
networks:
|
|
||||||
dms-ipv6:
|
|
||||||
external: true
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Default Bridge (daemon)"
|
|
||||||
|
|
||||||
!!! warning "This approach is discouraged"
|
|
||||||
|
|
||||||
The [`bridge` network is considered legacy][docker-docs-network-bridge-legacy].
|
|
||||||
|
|
||||||
Add these two extra IPv6 settings to your daemon config. They only apply to the [default `bridge` docker network][docker-docs-ipv6-create-default] aka `docker0` (_which containers are attached to by default when using `docker run`_).
|
|
||||||
|
|
||||||
```json title="/etc/docker/daemon.json"
|
|
||||||
{
|
|
||||||
"ipv6": true,
|
|
||||||
"fixed-cidr-v6": "fd00:cafe:face:feed::/64",
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Compose projects can also use this network via `network_mode`:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
network_mode: bridge
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! danger "Do not use `2001:db8:1::/64` for your private subnet"
|
|
||||||
|
|
||||||
The `2001:db8` address prefix is [reserved for documentation][wikipedia-ipv6-reserved]. Avoid creating a subnet with this prefix.
|
|
||||||
|
|
||||||
Presently this is used in examples for Dockers IPv6 docs as a placeholder, while mixed in with private IPv4 addresses which can be misleading.
|
|
||||||
|
|
||||||
### Configuring an IPv6 subnet
|
|
||||||
|
|
||||||
If you've [configured IPv6 address pools in `/etc/docker/daemon.json`][docker-docs-ipv6-supernets], you do not need to specify a subnet explicitly. Otherwise if you're unsure what value to provide, here's a quick guide (_Tip: Prefer IPv6 ULA, it's the least hassle_):
|
|
||||||
|
|
||||||
- `fd00:cafe:face:feed::/64` is an example of a [IPv6 ULA subnet][wikipedia-ipv6-ula]. ULA addresses are akin to the [private IPv4 subnets][wikipedia-ipv4-private] you may already be familiar with. You can use that example, or choose your own ULA address. This is a good choice for getting Docker containers to their have networks support IPv6 via NAT like they already do by default with IPv4.
|
|
||||||
- IPv6 without NAT, using public address space like your server is assigned belongs to an [IPv6 GUA subnet][wikipedia-ipv6-gua].
|
|
||||||
- Typically these will be a `/64` block assigned to your host, but this varies by provider.
|
|
||||||
- These addresses do not need to publish ports of a container to another IP to be publicly reached (_thus `ip6tables: true` is not required_), you will want a firewall configured to manage which ports are accessible instead as no NAT is involved. Note that this may not be desired if the container should also be reachable via the host IPv4 public address.
|
|
||||||
- You may want to subdivide the `/64` into smaller subnets for Docker to use only portions of the `/64`. This can reduce some routing features, and [require additional setup / management via a NDP Proxy][gh-pull-3244-gua] for your public interface to know of IPv6 assignments managed by Docker and accept external traffic.
|
|
||||||
|
|
||||||
### Verify remote IP is correct
|
|
||||||
|
|
||||||
With Docker CLI or Docker Compose, run a `traefik/whoami` container with your IPv6 docker network and port 80 published. You can then send a curl request (or via address in the browser) from another host (as your remote client) with an IPv6 network, the `RemoteAddr` value returned should match your client IPv6 address.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker run --rm -d --network dms-ipv6 -p 80:80 traefik/whoami
|
|
||||||
# On a different host, replace `2001:db8::1` with your DMS host IPv6 address
|
|
||||||
curl --max-time 5 http://[2001:db8::1]:80
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "IPv6 gateway IP"
|
|
||||||
|
|
||||||
If instead of the remote IPv6 address, you may notice the gateway IP for the IPv6 subnet your DMS container belongs to.
|
|
||||||
|
|
||||||
This will happen when DMS has an IPv6 IP address assigned, for the same reason as with IPv4, `userland-proxy: true`. It indicates that your `daemon.json` has not been configured correctly or had the updated config applied for `ip6tables :true` + `experimental: true`. Make sure you used `systemctl restart docker` after updating `daemon.json`.
|
|
||||||
|
|
||||||
!!! info "IPv6 ULA address priority"
|
|
||||||
|
|
||||||
DNS lookups that have records for both IPv4 and IPv6 addresses (_eg: `localhost`_) may prefer IPv4 over IPv6 (ULA) for private addresses, whereas for public addresses IPv6 has priority. This shouldn't be anything to worry about, but can come across as a surprise when testing your IPv6 setup on the same host instead of from a remote client.
|
|
||||||
|
|
||||||
The preference can be controlled with [`/etc/gai.conf`][networking-gai], and appears was configured this way based on [the assumption that IPv6 ULA would never be used with NAT][networking-gai-blog]. It should only affect the destination resolved for outgoing connections, which for IPv6 ULA should only really affect connections between your containers / host. In future [IPv6 ULA may also be prioritized][networking-gai-rfc].
|
|
||||||
|
|
||||||
[docker-subnets]: https://straz.to/2021-09-08-docker-address-pools/#what-are-the-default-address-pools-when-no-configuration-is-given-vanilla-pools
|
|
||||||
[sender-score]: https://senderscore.org/assess/get-your-score/
|
|
||||||
[gh-issue-1438-spf]: https://github.com/docker-mailserver/docker-mailserver/issues/1438
|
|
||||||
[gh-issue-3057-bounce]: https://github.com/docker-mailserver/docker-mailserver/pull/3057#issuecomment-1416700046
|
|
||||||
[wikipedia-openrelay]: https://en.wikipedia.org/wiki/Open_mail_relay
|
|
||||||
|
|
||||||
[docs-compat]: ../debugging.md#compatibility
|
|
||||||
|
|
||||||
[gh-pull-3244-proxy]: https://github.com/docker-mailserver/docker-mailserver/pull/3244#issuecomment-1603436809
|
|
||||||
[docker-docs-enable-ipv6]: https://docs.docker.com/config/daemon/ipv6/
|
|
||||||
[docker-docs-ipv6-create-custom]: https://docs.docker.com/config/daemon/ipv6/#create-an-ipv6-network
|
|
||||||
[docker-docs-ipv6-create-default]: https://docs.docker.com/config/daemon/ipv6/#use-ipv6-for-the-default-bridge-network
|
|
||||||
[docker-docs-ipv6-supernets]: https://docs.docker.com/config/daemon/ipv6/#dynamic-ipv6-subnet-allocation
|
|
||||||
[docker-docs-network-external]: https://docs.docker.com/compose/compose-file/06-networks/#name
|
|
||||||
[docker-docs-network-compose-default]: https://docs.docker.com/compose/networking/#configure-the-default-network
|
|
||||||
[docker-docs-network-bridge-legacy]: https://docs.docker.com/network/drivers/bridge/#use-the-default-bridge-network
|
|
||||||
|
|
||||||
[wikipedia-ipv6-reserved]: https://en.wikipedia.org/wiki/IPv6_address#Documentation
|
|
||||||
[wikipedia-ipv4-private]: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_addresses
|
|
||||||
[wikipedia-ipv6-ula]: https://en.wikipedia.org/wiki/Unique_local_address
|
|
||||||
[wikipedia-ipv6-gua]: https://en.wikipedia.org/wiki/IPv6#Global_addressing
|
|
||||||
[gh-pull-3244-gua]: https://github.com/docker-mailserver/docker-mailserver/pull/3244#issuecomment-1528984894
|
|
||||||
|
|
||||||
[networking-gai]: https://linux.die.net/man/5/gai.conf
|
|
||||||
[networking-gai-blog]: https://thomas-leister.de/en/lxd-prefer-ipv6-outgoing/
|
|
||||||
[networking-gai-rfc]:https://datatracker.ietf.org/doc/html/draft-ietf-v6ops-ula
|
|
||||||
|
|
@ -1,802 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Kubernetes'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
This article describes how to deploy DMS to Kubernetes. We highly recommend everyone to use our community [DMS Helm chart][github-web::docker-mailserver-helm].
|
|
||||||
|
|
||||||
!!! note "Requirements"
|
|
||||||
|
|
||||||
1. Basic knowledge about Kubernetes from the reader.
|
|
||||||
2. A basic understanding of mail servers.
|
|
||||||
3. Ideally, the reader has already deployed DMS before with a simpler setup (_`docker run` or Docker Compose_).
|
|
||||||
|
|
||||||
!!! warning "Limited Support"
|
|
||||||
|
|
||||||
DMS **does not officially support Kubernetes**. This content is entirely community-supported. If you find errors, please open an issue and raise a PR.
|
|
||||||
|
|
||||||
## Manually Writing Manifests
|
|
||||||
|
|
||||||
If using our Helm chart is not viable for you, here is some guidance to start with your own manifests.
|
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
|
||||||
!!! quote ""
|
|
||||||
|
|
||||||
=== "`ConfigMap`"
|
|
||||||
|
|
||||||
Provide the basic configuration via environment variables with a `ConfigMap`.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Below is only an example configuration, adjust the `ConfigMap` to your own needs.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: ConfigMap
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver.environment
|
|
||||||
|
|
||||||
immutable: false
|
|
||||||
|
|
||||||
data:
|
|
||||||
TLS_LEVEL: modern
|
|
||||||
POSTSCREEN_ACTION: drop
|
|
||||||
OVERRIDE_HOSTNAME: mail.example.com
|
|
||||||
FAIL2BAN_BLOCKTYPE: drop
|
|
||||||
POSTMASTER_ADDRESS: postmaster@example.com
|
|
||||||
UPDATE_CHECK_INTERVAL: 10d
|
|
||||||
POSTFIX_INET_PROTOCOLS: ipv4
|
|
||||||
ENABLE_CLAMAV: '1'
|
|
||||||
ENABLE_POSTGREY: '0'
|
|
||||||
ENABLE_FAIL2BAN: '1'
|
|
||||||
AMAVIS_LOGLEVEL: '-1'
|
|
||||||
SPOOF_PROTECTION: '1'
|
|
||||||
MOVE_SPAM_TO_JUNK: '1'
|
|
||||||
ENABLE_UPDATE_CHECK: '1'
|
|
||||||
ENABLE_SPAMASSASSIN: '1'
|
|
||||||
SUPERVISOR_LOGLEVEL: warn
|
|
||||||
SPAMASSASSIN_SPAM_TO_INBOX: '1'
|
|
||||||
|
|
||||||
# here, we provide an example for the SSL configuration
|
|
||||||
SSL_TYPE: manual
|
|
||||||
SSL_CERT_PATH: /secrets/ssl/rsa/tls.crt
|
|
||||||
SSL_KEY_PATH: /secrets/ssl/rsa/tls.key
|
|
||||||
```
|
|
||||||
|
|
||||||
You can also make use of user-provided configuration files (_e.g. `user-patches.sh`, `postfix-accounts.cf`, etc_), to customize DMS to your needs.
|
|
||||||
|
|
||||||
??? example "Providing config files"
|
|
||||||
|
|
||||||
Here is a minimal example that supplies a `postfix-accounts.cf` file inline with two users:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: ConfigMap
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver.files
|
|
||||||
|
|
||||||
data:
|
|
||||||
postfix-accounts.cf: |
|
|
||||||
test@example.com|{SHA512-CRYPT}$6$someHashValueHere
|
|
||||||
other@example.com|{SHA512-CRYPT}$6$someOtherHashValueHere
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "Static Configuration"
|
|
||||||
|
|
||||||
The inline `postfix-accounts.cf` config example above provides file content that is static. It is mounted as read-only at runtime, thus cannot support modifications.
|
|
||||||
|
|
||||||
For production deployments, use persistent volumes instead (via `PersistentVolumeClaim`). That will enable files like `postfix-account.cf` to add and remove accounts, while also persisting those changes externally from the container.
|
|
||||||
|
|
||||||
!!! tip "Modularize your `ConfigMap`"
|
|
||||||
|
|
||||||
[Kustomize][kustomize] can be a useful tool as it supports creating a `ConfigMap` from multiple files.
|
|
||||||
|
|
||||||
=== "`PersistentVolumeClaim`"
|
|
||||||
|
|
||||||
To persist data externally from the DMS container, configure a `PersistentVolumeClaim` (PVC).
|
|
||||||
|
|
||||||
Make sure you have a storage system (like Longhorn, Rook, etc.) and that you choose the correct `storageClassName` (according to your storage system).
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: PersistentVolumeClaim
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: data
|
|
||||||
|
|
||||||
spec:
|
|
||||||
storageClassName: local-path
|
|
||||||
accessModes:
|
|
||||||
- ReadWriteOnce
|
|
||||||
resources:
|
|
||||||
requests:
|
|
||||||
storage: 25Gi
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "`Service`"
|
|
||||||
|
|
||||||
A [`Service`][k8s-docs::config::service] is required for getting the traffic to the pod itself. It configures a load balancer with the ports you'll need.
|
|
||||||
|
|
||||||
The configuration for a `Service` affects if the original IP from a connecting client is preserved (_this is important_). [More about this further down below](#exposing-your-mail-server-to-the-outside-world).
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
labels:
|
|
||||||
app: mailserver
|
|
||||||
|
|
||||||
spec:
|
|
||||||
# `Local` is most likely required, otherwise every incoming request would be identified by the external IP,
|
|
||||||
# which will get banned by Fail2Ban when monitored services are not configured for PROXY protocol
|
|
||||||
externalTrafficPolicy: Local
|
|
||||||
type: LoadBalancer
|
|
||||||
|
|
||||||
selector:
|
|
||||||
app: mailserver
|
|
||||||
|
|
||||||
ports:
|
|
||||||
# smtp
|
|
||||||
- name: smtp
|
|
||||||
port: 25
|
|
||||||
targetPort: smtp
|
|
||||||
protocol: TCP
|
|
||||||
# submissions (ESMTP with implicit TLS)
|
|
||||||
- name: submissions
|
|
||||||
port: 465
|
|
||||||
targetPort: submissions
|
|
||||||
protocol: TCP
|
|
||||||
# submission (ESMTP with explicit TLS)
|
|
||||||
- name: submission
|
|
||||||
port: 587
|
|
||||||
targetPort: submission
|
|
||||||
protocol: TCP
|
|
||||||
# imaps (implicit TLS)
|
|
||||||
- name: imaps
|
|
||||||
port: 993
|
|
||||||
targetPort: imaps
|
|
||||||
protocol: TCP
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "`Certificate`"
|
|
||||||
|
|
||||||
!!! example "Using [`cert-manager`][cert-manager] to supply TLS certificates"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: cert-manager.io/v1
|
|
||||||
kind: Certificate
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mail-tls-certificate-rsa
|
|
||||||
|
|
||||||
spec:
|
|
||||||
secretName: mail-tls-certificate-rsa
|
|
||||||
isCA: false
|
|
||||||
privateKey:
|
|
||||||
algorithm: RSA
|
|
||||||
encoding: PKCS1
|
|
||||||
size: 2048
|
|
||||||
dnsNames: [mail.example.com]
|
|
||||||
issuerRef:
|
|
||||||
name: mail-issuer
|
|
||||||
kind: Issuer
|
|
||||||
```
|
|
||||||
|
|
||||||
The [TLS docs page][docs-tls] provides guidance when it comes to certificates and transport layer security.
|
|
||||||
|
|
||||||
!!! tip "ECDSA + RSA (fallback)"
|
|
||||||
|
|
||||||
You could supply RSA certificates as fallback certificates instead, with ECDSA as the primary. DMS supports dual certificates via the ENV `SSL_ALT_CERT_PATH` and `SSL_ALT_KEY_PATH`.
|
|
||||||
|
|
||||||
!!! warning "Always provide sensitive information via a `Secret`"
|
|
||||||
|
|
||||||
For storing OpenDKIM keys, TLS certificates, or any sort of sensitive data - you should be using `Secret`s.
|
|
||||||
|
|
||||||
A `Secret` is similar to `ConfigMap`, it can be used and mounted as a volume as demonstrated in the [`Deployment` manifest][docs::k8s::config-deployment] tab.
|
|
||||||
|
|
||||||
=== "`Deployment`"
|
|
||||||
|
|
||||||
The [`Deployment`][k8s-docs::config::deployment] config is the most complex component.
|
|
||||||
|
|
||||||
- It instructs Kubernetes how to run the DMS container and how to apply your `ConfigMap`s, persisted storage, etc.
|
|
||||||
- Additional options can be set to enforce runtime security.
|
|
||||||
|
|
||||||
???+ example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: apps/v1
|
|
||||||
kind: Deployment
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
|
|
||||||
annotations:
|
|
||||||
ignore-check.kube-linter.io/run-as-non-root: >-
|
|
||||||
'mailserver' needs to run as root
|
|
||||||
ignore-check.kube-linter.io/privileged-ports: >-
|
|
||||||
'mailserver' needs privileged ports
|
|
||||||
ignore-check.kube-linter.io/no-read-only-root-fs: >-
|
|
||||||
There are too many files written to make the root FS read-only
|
|
||||||
|
|
||||||
spec:
|
|
||||||
replicas: 1
|
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: mailserver
|
|
||||||
|
|
||||||
template:
|
|
||||||
metadata:
|
|
||||||
labels:
|
|
||||||
app: mailserver
|
|
||||||
|
|
||||||
annotations:
|
|
||||||
container.apparmor.security.beta.kubernetes.io/mailserver: runtime/default
|
|
||||||
|
|
||||||
spec:
|
|
||||||
hostname: mail
|
|
||||||
containers:
|
|
||||||
- name: mailserver
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
imagePullPolicy: IfNotPresent
|
|
||||||
|
|
||||||
securityContext:
|
|
||||||
# `allowPrivilegeEscalation: true` is required to support SGID via the `postdrop`
|
|
||||||
# executable in `/var/mail-state` for Postfix (maildrop + public dirs):
|
|
||||||
# https://github.com/docker-mailserver/docker-mailserver/pull/3625
|
|
||||||
allowPrivilegeEscalation: true
|
|
||||||
readOnlyRootFilesystem: false
|
|
||||||
runAsUser: 0
|
|
||||||
runAsGroup: 0
|
|
||||||
runAsNonRoot: false
|
|
||||||
privileged: false
|
|
||||||
capabilities:
|
|
||||||
add:
|
|
||||||
# file permission capabilities
|
|
||||||
- CHOWN
|
|
||||||
- FOWNER
|
|
||||||
- MKNOD
|
|
||||||
- SETGID
|
|
||||||
- SETUID
|
|
||||||
- DAC_OVERRIDE
|
|
||||||
# network capabilities
|
|
||||||
- NET_ADMIN # needed for F2B
|
|
||||||
- NET_RAW # needed for F2B
|
|
||||||
- NET_BIND_SERVICE
|
|
||||||
# miscellaneous capabilities
|
|
||||||
- SYS_CHROOT
|
|
||||||
- KILL
|
|
||||||
drop: [ALL]
|
|
||||||
seccompProfile:
|
|
||||||
type: RuntimeDefault
|
|
||||||
|
|
||||||
# Tune this to your needs.
|
|
||||||
# If you disable ClamAV, you can use less RAM and CPU.
|
|
||||||
# This becomes important in case you're low on resources
|
|
||||||
# and Kubernetes refuses to schedule new pods.
|
|
||||||
resources:
|
|
||||||
limits:
|
|
||||||
memory: 4Gi
|
|
||||||
cpu: 1500m
|
|
||||||
requests:
|
|
||||||
memory: 2Gi
|
|
||||||
cpu: 600m
|
|
||||||
|
|
||||||
volumeMounts:
|
|
||||||
- name: files
|
|
||||||
subPath: postfix-accounts.cf
|
|
||||||
mountPath: /tmp/docker-mailserver/postfix-accounts.cf
|
|
||||||
readOnly: true
|
|
||||||
|
|
||||||
# PVCs
|
|
||||||
- name: data
|
|
||||||
mountPath: /var/mail
|
|
||||||
subPath: data
|
|
||||||
readOnly: false
|
|
||||||
- name: data
|
|
||||||
mountPath: /var/mail-state
|
|
||||||
subPath: state
|
|
||||||
readOnly: false
|
|
||||||
- name: data
|
|
||||||
mountPath: /var/log/mail
|
|
||||||
subPath: log
|
|
||||||
readOnly: false
|
|
||||||
|
|
||||||
# certificates
|
|
||||||
- name: certificates-rsa
|
|
||||||
mountPath: /secrets/ssl/rsa/
|
|
||||||
readOnly: true
|
|
||||||
|
|
||||||
ports:
|
|
||||||
- name: smtp
|
|
||||||
containerPort: 25
|
|
||||||
protocol: TCP
|
|
||||||
- name: submissions
|
|
||||||
containerPort: 465
|
|
||||||
protocol: TCP
|
|
||||||
- name: submission
|
|
||||||
containerPort: 587
|
|
||||||
- name: imaps
|
|
||||||
containerPort: 993
|
|
||||||
protocol: TCP
|
|
||||||
|
|
||||||
envFrom:
|
|
||||||
- configMapRef:
|
|
||||||
name: mailserver.environment
|
|
||||||
|
|
||||||
restartPolicy: Always
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
# configuration files
|
|
||||||
- name: files
|
|
||||||
configMap:
|
|
||||||
name: mailserver.files
|
|
||||||
|
|
||||||
# PVCs
|
|
||||||
- name: data
|
|
||||||
persistentVolumeClaim:
|
|
||||||
claimName: data
|
|
||||||
|
|
||||||
# certificates
|
|
||||||
- name: certificates-rsa
|
|
||||||
secret:
|
|
||||||
secretName: mail-tls-certificate-rsa
|
|
||||||
items:
|
|
||||||
- key: tls.key
|
|
||||||
path: tls.key
|
|
||||||
- key: tls.crt
|
|
||||||
path: tls.crt
|
|
||||||
```
|
|
||||||
|
|
||||||
## Exposing your Mail Server to the Outside World
|
|
||||||
|
|
||||||
The more difficult part with Kubernetes is to expose a deployed DMS instance to the outside world.
|
|
||||||
|
|
||||||
The major problem with exposing DMS to the outside world in Kubernetes is to [preserve the real client IP][k8s-docs::service-source-ip]. The real client IP is required by DMS for performing IP-based DNS and spam checks.
|
|
||||||
|
|
||||||
Kubernetes provides multiple ways to address this; each has its upsides and downsides.
|
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
|
||||||
!!! quote ""
|
|
||||||
|
|
||||||
=== "Configure IP Manually"
|
|
||||||
|
|
||||||
???+ abstract "Advantages / Disadvantages"
|
|
||||||
|
|
||||||
- [x] Simple
|
|
||||||
- [ ] Requires the node to have a dedicated, publicly routable IP address
|
|
||||||
- [ ] Limited to a single node (_associated to the dedicated IP address_)
|
|
||||||
- [ ] Your deployment requires an explicit IP in your configuration (_or an entire Load Balancer_).
|
|
||||||
|
|
||||||
!!! info "Requirements"
|
|
||||||
|
|
||||||
1. You can dedicate a **publicly routable IP** address for the DMS configured `Service`.
|
|
||||||
2. A dedicated IP is required to allow your mail server to have matching `A` and `PTR` records (_which other mail servers will use to verify trust when they receive mail sent from your DMS instance_).
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Assign the DMS `Service` an external IP directly, or delegate an LB to assign the IP on your behalf.
|
|
||||||
|
|
||||||
=== "External-IP Service"
|
|
||||||
|
|
||||||
The DMS `Service` is configured with an "[external IP][k8s-docs::network-external-ip]" manually. Append your externally reachable IP address to `spec.externalIPs`.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
labels:
|
|
||||||
app: mailserver
|
|
||||||
|
|
||||||
spec:
|
|
||||||
selector:
|
|
||||||
app: mailserver
|
|
||||||
ports:
|
|
||||||
- name: smtp
|
|
||||||
port: 25
|
|
||||||
targetPort: smtp
|
|
||||||
# ...
|
|
||||||
|
|
||||||
externalIPs:
|
|
||||||
- 10.20.30.40
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Load-Balancer"
|
|
||||||
|
|
||||||
The config differs depending on your choice of load balancer. This example uses [MetalLB][metallb-web].
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
labels:
|
|
||||||
app: mailserver
|
|
||||||
annotations:
|
|
||||||
metallb.universe.tf/address-pool: mailserver
|
|
||||||
|
|
||||||
# ...
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: metallb.io/v1beta1
|
|
||||||
kind: IPAddressPool
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mail
|
|
||||||
namespace: metallb-system
|
|
||||||
|
|
||||||
spec:
|
|
||||||
addresses: [ <YOUR PUBLIC DEDICATED IP IN CIDR NOTATION> ]
|
|
||||||
autoAssign: true
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: metallb.io/v1beta1
|
|
||||||
kind: L2Advertisement
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mail
|
|
||||||
namespace: metallb-system
|
|
||||||
|
|
||||||
spec:
|
|
||||||
ipAddressPools: [ mailserver ]
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Host network"
|
|
||||||
|
|
||||||
???+ abstract "Advantages / Disadvantages"
|
|
||||||
|
|
||||||
- [x] Simple
|
|
||||||
- [ ] Requires the node to have a dedicated, publicly routable IP address
|
|
||||||
- [ ] Limited to a single node (_associated to the dedicated IP address_)
|
|
||||||
- [ ] It is not possible to access DMS via other cluster nodes, only via the node that DMS was deployed on
|
|
||||||
- [ ] Every port within the container is exposed on the host side
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Using `hostPort` and `hostNetwork: true` is a similar approach to [`network_mode: host` with Docker Compose][docker-docs::compose::network_mode].
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: apps/v1
|
|
||||||
kind: Deployment
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
|
|
||||||
# ...
|
|
||||||
spec:
|
|
||||||
hostNetwork: true
|
|
||||||
# ...
|
|
||||||
containers:
|
|
||||||
# ...
|
|
||||||
ports:
|
|
||||||
- name: smtp
|
|
||||||
containerPort: 25
|
|
||||||
hostPort: 25
|
|
||||||
- name: submissions
|
|
||||||
containerPort: 465
|
|
||||||
hostPort: 465
|
|
||||||
- name: submission
|
|
||||||
containerPort: 587
|
|
||||||
hostPort: 587
|
|
||||||
- name: imaps
|
|
||||||
containerPort: 993
|
|
||||||
hostPort: 993
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Using the PROXY Protocol"
|
|
||||||
|
|
||||||
???+ abstract "Advantages / Disadvantages"
|
|
||||||
|
|
||||||
- [x] Preserves the origin IP address of clients (_which is crucial for DNS related checks_)
|
|
||||||
- [x] Aligns with a best practice for Kubernetes by using a dedicated ingress, routing external traffic to the k8s cluster (_with the benefits of flexible routing rules_)
|
|
||||||
- [x] Avoids the restraint of a single [node][k8s-docs::nodes] (_as a workaround to preserve the original client IP_)
|
|
||||||
- [ ] Introduces complexity by requiring:
|
|
||||||
- A reverse-proxy / ingress controller (_potentially extra setup_)
|
|
||||||
- Kubernetes manifest changes for the DMS configured `Service`
|
|
||||||
- DMS configuration changes for Postfix and Dovecot
|
|
||||||
- [ ] To keep support for direct connections to DMS services internally within cluster, service ports must be "duplicated" to offer an alternative port for connections using PROXY protocol
|
|
||||||
- [ ] Custom Fail2Ban required: Because the traffic to DMS is now coming from the proxy, banning the origin IP address will have no effect; you'll need to implement a [custom solution for your setup][github-web::docker-mailserver::proxy-protocol-fail2ban].
|
|
||||||
|
|
||||||
??? question "What is the PROXY protocol?"
|
|
||||||
|
|
||||||
PROXY protocol is a network protocol for preserving a client’s IP address when the client’s TCP connection passes through a proxy.
|
|
||||||
|
|
||||||
It is a common feature supported among reverse-proxy services (_NGINX, HAProxy, Traefik_), which you may already have handling ingress traffic for your cluster.
|
|
||||||
|
|
||||||
```mermaid
|
|
||||||
flowchart LR
|
|
||||||
A(External Mail Server) -->|Incoming connection| B
|
|
||||||
subgraph cluster
|
|
||||||
B("Ingress Acting as a Proxy") -->|PROXY protocol connection| C(DMS)
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
For more information on the PROXY protocol, refer to [our dedicated docs page][docs-mailserver-behind-proxy] on the topic.
|
|
||||||
|
|
||||||
???+ example "Configure the Ingress Controller"
|
|
||||||
|
|
||||||
=== "Traefik"
|
|
||||||
|
|
||||||
On Traefik's side, the configuration is very simple.
|
|
||||||
|
|
||||||
- Create an entrypoint for each port that you want to expose (_probably 25, 465, 587 and 993_).
|
|
||||||
- Each entrypoint should configure an [`IngressRouteTCP`][traefik-docs::k8s::ingress-route-tcp] that routes to the equivalent internal DMS `Service` port which supports PROXY protocol connections.
|
|
||||||
|
|
||||||
The below snippet demonstrates an example for two entrypoints, `submissions` (port 465) and `imaps` (port 993).
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
apiVersion: v1
|
|
||||||
kind: Service
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
|
|
||||||
spec:
|
|
||||||
# This an optimization to get rid of additional routing steps.
|
|
||||||
# Previously "type: LoadBalancer"
|
|
||||||
type: ClusterIP
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRouteTCP
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: smtp
|
|
||||||
|
|
||||||
spec:
|
|
||||||
entryPoints: [ submissions ]
|
|
||||||
routes:
|
|
||||||
- match: HostSNI(`*`)
|
|
||||||
services:
|
|
||||||
- name: mailserver
|
|
||||||
namespace: mail
|
|
||||||
port: subs-proxy # note the 15 character limit here
|
|
||||||
proxyProtocol:
|
|
||||||
version: 2
|
|
||||||
|
|
||||||
---
|
|
||||||
apiVersion: traefik.io/v1alpha1
|
|
||||||
kind: IngressRouteTCP
|
|
||||||
|
|
||||||
metadata:
|
|
||||||
name: imaps
|
|
||||||
|
|
||||||
spec:
|
|
||||||
entryPoints: [ imaps ]
|
|
||||||
routes:
|
|
||||||
- match: HostSNI(`*`)
|
|
||||||
services:
|
|
||||||
- name: mailserver
|
|
||||||
namespace: mail
|
|
||||||
port: imaps-proxy
|
|
||||||
proxyProtocol:
|
|
||||||
version: 2
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! info "`*-proxy` port name suffix"
|
|
||||||
|
|
||||||
The `IngressRouteTCP` example configs above reference ports with a `*-proxy` suffix.
|
|
||||||
|
|
||||||
- These port variants will be defined in the [`Deployment` manifest][docs::k8s::config-deployment], and are scoped to the `mailserver` service (via `spec.routes.services.name`).
|
|
||||||
- The suffix is used to distinguish that these ports are only compatible with connections using the PROXY protocol, which is what your ingress controller should be managing for you by adding the correct PROXY protocol headers to TCP connections it routes to DMS.
|
|
||||||
|
|
||||||
=== "NGINX"
|
|
||||||
|
|
||||||
With an [NGINX ingress controller][k8s-docs::nginx], add the following to the TCP services config map (_as described [here][k8s-docs::nginx-expose]_):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
25: "mailserver/mailserver:25::PROXY"
|
|
||||||
465: "mailserver/mailserver:465::PROXY"
|
|
||||||
587: "mailserver/mailserver:587::PROXY"
|
|
||||||
993: "mailserver/mailserver:993::PROXY"
|
|
||||||
```
|
|
||||||
|
|
||||||
???+ example "Adjust DMS config for Dovecot + Postfix"
|
|
||||||
|
|
||||||
??? warning "Only ingress should connect to DMS with PROXY protocol"
|
|
||||||
|
|
||||||
While Dovecot will restrict connections via PROXY protocol to only clients trusted configured via `haproxy_trusted_networks`, Postfix does not have an equivalent setting. Public clients should always route through ingress to establish a PROXY protocol connection.
|
|
||||||
|
|
||||||
You are responsible for properly managing traffic inside your cluster and to **ensure that only trustworthy entities** can connect to the designated PROXY protocol ports.
|
|
||||||
|
|
||||||
With Kubernetes, this is usually the task of the CNI (_container network interface_).
|
|
||||||
|
|
||||||
!!! tip "Advised approach"
|
|
||||||
|
|
||||||
The _"Separate PROXY protocol ports"_ tab below introduces a little more complexity, but provides better compatibility for internal connections to DMS.
|
|
||||||
|
|
||||||
=== "Only accept connections with PROXY protocol"
|
|
||||||
|
|
||||||
!!! warning "Connections to DMS within the internal cluster will be rejected"
|
|
||||||
|
|
||||||
The services for these ports can only enable PROXY protocol support by mandating the protocol on all connections for these ports.
|
|
||||||
|
|
||||||
This can be problematic when you also need to support internal cluster traffic directly to DMS (_instead of routing indirectly through the ingress controller_).
|
|
||||||
|
|
||||||
Here is an example configuration for [Postfix][docs-postfix], [Dovecot][docs-dovecot], and the required adjustments for the [`Deployment` manifest][docs::k8s::config-deployment]. The port names are adjusted here only to convey the additional context described earlier.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
kind: ConfigMap
|
|
||||||
apiVersion: v1
|
|
||||||
metadata:
|
|
||||||
name: mailserver-extra-config
|
|
||||||
labels:
|
|
||||||
app: mailserver
|
|
||||||
data:
|
|
||||||
postfix-main.cf: |
|
|
||||||
postscreen_upstream_proxy_protocol = haproxy
|
|
||||||
postfix-master.cf: |
|
|
||||||
smtp/inet/postscreen_upstream_proxy_protocol=haproxy
|
|
||||||
submission/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
submissions/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
dovecot.cf: |
|
|
||||||
haproxy_trusted_networks = <YOUR POD CIDR>
|
|
||||||
service imap-login {
|
|
||||||
inet_listener imap {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
inet_listener imaps {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
# ...
|
|
||||||
|
|
||||||
---
|
|
||||||
kind: Deployment
|
|
||||||
apiVersion: apps/v1
|
|
||||||
metadata:
|
|
||||||
name: mailserver
|
|
||||||
spec:
|
|
||||||
template:
|
|
||||||
spec:
|
|
||||||
containers:
|
|
||||||
- name: docker-mailserver
|
|
||||||
# ...
|
|
||||||
ports:
|
|
||||||
- name: smtp-proxy
|
|
||||||
containerPort: 25
|
|
||||||
protocol: TCP
|
|
||||||
- name: imap-proxy
|
|
||||||
containerPort: 143
|
|
||||||
protocol: TCP
|
|
||||||
- name: subs-proxy
|
|
||||||
containerPort: 465
|
|
||||||
protocol: TCP
|
|
||||||
- name: sub-proxy
|
|
||||||
containerPort: 587
|
|
||||||
protocol: TCP
|
|
||||||
- name: imaps-proxy
|
|
||||||
containerPort: 993
|
|
||||||
protocol: TCP
|
|
||||||
# ...
|
|
||||||
volumeMounts:
|
|
||||||
- name: config
|
|
||||||
subPath: postfix-main.cf
|
|
||||||
mountPath: /tmp/docker-mailserver/postfix-main.cf
|
|
||||||
readOnly: true
|
|
||||||
- name: config
|
|
||||||
subPath: postfix-master.cf
|
|
||||||
mountPath: /tmp/docker-mailserver/postfix-master.cf
|
|
||||||
readOnly: true
|
|
||||||
- name: config
|
|
||||||
subPath: dovecot.cf
|
|
||||||
mountPath: /tmp/docker-mailserver/dovecot.cf
|
|
||||||
readOnly: true
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Separate PROXY protocol ports for ingress"
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
Supporting internal cluster connections to DMS without using PROXY protocol requires both Postfix and Dovecot to be configured with alternative ports for each service port (_which only differ by enforcing PROXY protocol connections_).
|
|
||||||
|
|
||||||
- The ingress controller will route public connections to the internal alternative ports for DMS (`*-proxy` variants).
|
|
||||||
- Internal cluster connections will instead use the original ports configured for the DMS container directly (_which are private to the cluster network_).
|
|
||||||
|
|
||||||
In this example we'll create a copy of the original service ports with PROXY protocol enabled, and increment the port number assigned by `10000`.
|
|
||||||
|
|
||||||
Create a `user-patches.sh` file to apply these config changes during container startup:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# Duplicate the config for the submission(s) service ports (587 / 465) with adjustments for the PROXY ports (10587 / 10465) and `syslog_name` setting:
|
|
||||||
postconf -Mf submission/inet | sed -e s/^submission/10587/ -e 's/submission/submission-proxyprotocol/' >> /etc/postfix/master.cf
|
|
||||||
postconf -Mf submissions/inet | sed -e s/^submissions/10465/ -e 's/submissions/submissions-proxyprotocol/' >> /etc/postfix/master.cf
|
|
||||||
# Enable PROXY Protocol support for these new service variants:
|
|
||||||
postconf -P 10587/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
postconf -P 10465/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
|
|
||||||
# Create a variant for port 25 too (NOTE: Port 10025 is already assigned in DMS to Amavis):
|
|
||||||
postconf -Mf smtp/inet | sed -e s/^smtp/12525/ >> /etc/postfix/master.cf
|
|
||||||
# Enable PROXY Protocol support (different setting as port 25 is handled via postscreen), optionally configure a `syslog_name` to distinguish in logs:
|
|
||||||
postconf -P 12525/inet/postscreen_upstream_proxy_protocol=haproxy 12525/inet/syslog_name=smtp-proxyprotocol
|
|
||||||
```
|
|
||||||
|
|
||||||
For Dovecot, you can configure [`dovecot.cf`][docs-dovecot] to look like this:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
haproxy_trusted_networks = <YOUR POD CIDR>
|
|
||||||
|
|
||||||
service imap-login {
|
|
||||||
inet_listener imap-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10143
|
|
||||||
}
|
|
||||||
|
|
||||||
inet_listener imaps-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10993
|
|
||||||
ssl = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Update the [`Deployment` manifest][docs::k8s::config-deployment] `ports` section by appending these new ports:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
- name: smtp-proxy
|
|
||||||
# not 10025 in this example due to a possible clash with Amavis
|
|
||||||
containerPort: 12525
|
|
||||||
protocol: TCP
|
|
||||||
- name: imap-proxy
|
|
||||||
containerPort: 10143
|
|
||||||
protocol: TCP
|
|
||||||
- name: subs-proxy
|
|
||||||
containerPort: 10465
|
|
||||||
protocol: TCP
|
|
||||||
- name: sub-proxy
|
|
||||||
containerPort: 10587
|
|
||||||
protocol: TCP
|
|
||||||
- name: imaps-proxy
|
|
||||||
containerPort: 10993
|
|
||||||
protocol: TCP
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
If you use other Dovecot ports (110, 995, 4190), you may want to configure those similar to above. The `dovecot.cf` config for these ports is [documented here][docs-mailserver-behind-proxy] (_in the equivalent section of that page_).
|
|
||||||
|
|
||||||
[docs::k8s::config-deployment]: #deployment
|
|
||||||
[docs-tls]: ../security/ssl.md
|
|
||||||
[docs-dovecot]: ./override-defaults/dovecot.md
|
|
||||||
[docs-postfix]: ./override-defaults/postfix.md
|
|
||||||
[docs-mailserver-behind-proxy]: ../../examples/tutorials/mailserver-behind-proxy.md
|
|
||||||
|
|
||||||
[github-web::docker-mailserver-helm]: https://github.com/docker-mailserver/docker-mailserver-helm
|
|
||||||
[docker-docs::compose::network_mode]: https://docs.docker.com/compose/compose-file/compose-file-v3/#network_mode
|
|
||||||
[kustomize]: https://kustomize.io/
|
|
||||||
[cert-manager]: https://cert-manager.io/docs/
|
|
||||||
[metallb-web]: https://metallb.universe.tf/
|
|
||||||
|
|
||||||
[k8s-docs::config::service]: https://kubernetes.io/docs/concepts/services-networking/service
|
|
||||||
[k8s-docs::config::deployment]: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#creating-a-deployment
|
|
||||||
[k8s-docs::nodes]: https://kubernetes.io/docs/concepts/architecture/nodes
|
|
||||||
[k8s-docs::nginx]: https://kubernetes.github.io/ingress-nginx
|
|
||||||
[k8s-docs::nginx-expose]: https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services
|
|
||||||
[k8s-docs::service-source-ip]: https://kubernetes.io/docs/tutorials/services/source-ip
|
|
||||||
[k8s-docs::network-external-ip]: https://kubernetes.io/docs/concepts/services-networking/service/#external-ips
|
|
||||||
|
|
||||||
[traefik-docs::k8s::ingress-route-tcp]: https://doc.traefik.io/traefik/routing/providers/kubernetes-crd/#kind-ingressroutetcp
|
|
||||||
[github-web::docker-mailserver::proxy-protocol-fail2ban]: https://github.com/docker-mailserver/docker-mailserver/issues/1761#issuecomment-2016879319
|
|
||||||
|
|
@ -1,152 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Email Gathering with Fetchmail'
|
|
||||||
---
|
|
||||||
|
|
||||||
To enable the [fetchmail][fetchmail-website] service to retrieve e-mails, set the environment variable `ENABLE_FETCHMAIL` to `1`. Your `compose.yaml` file should look like following snippet:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
environment:
|
|
||||||
- ENABLE_FETCHMAIL=1
|
|
||||||
- FETCHMAIL_POLL=300
|
|
||||||
```
|
|
||||||
|
|
||||||
Generate a file called `fetchmail.cf` and place it in the `docker-data/dms/config/` folder. Your DMS folder should look like this example:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
├── docker-data/dms/config
|
|
||||||
│ ├── dovecot.cf
|
|
||||||
│ ├── fetchmail.cf
|
|
||||||
│ ├── postfix-accounts.cf
|
|
||||||
│ └── postfix-virtual.cf
|
|
||||||
└── compose.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Configuration options for `fetchmail.cf` are covered at the [official fetchmail docs][fetchmail-docs-config] (_see the section "The run control file" and the table with "keyword" column for all settings_).
|
|
||||||
|
|
||||||
!!! example "Basic `fetchmail.cf` configuration"
|
|
||||||
|
|
||||||
Retrieve mail from `remote-user@somewhere.com` and deliver it to `dms-user@example.com`:
|
|
||||||
|
|
||||||
```fetchmailrc
|
|
||||||
poll 'mail.somewhere.com'
|
|
||||||
proto imap
|
|
||||||
user 'remote-user'
|
|
||||||
pass 'secret'
|
|
||||||
is 'dms-user@example.com'
|
|
||||||
```
|
|
||||||
|
|
||||||
- `poll` sets the remote mail server to connect to retrieve mail from.
|
|
||||||
- `proto` lets you connect via IMAP or POP3.
|
|
||||||
- `user` and `pass` provide the login credentials for the remote mail service account to access.
|
|
||||||
- `is` configures where the fetched mail will be sent to (_eg: your local DMS account in `docker-data/dms/config/postfix-accounts.cf`_).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
??? warning "`proto imap` will still delete remote mail once fetched"
|
|
||||||
|
|
||||||
This is due to a separate default setting `no keep`. Adding the setting `keep` to your config on a new line will prevent deleting the remote copy.
|
|
||||||
|
|
||||||
??? example "Multiple users or remote servers"
|
|
||||||
|
|
||||||
The official docs [config examples][fetchmail-config-examples] show a common convention to indent settings on subsequent lines for visually grouping per server.
|
|
||||||
|
|
||||||
=== "Minimal syntax"
|
|
||||||
|
|
||||||
```fetchmailrc
|
|
||||||
poll 'mail.somewhere.com' proto imap
|
|
||||||
user 'john.doe' pass 'secret' is 'johnny@example.com'
|
|
||||||
user 'jane.doe' pass 'secret' is 'jane@example.com'
|
|
||||||
|
|
||||||
poll 'mail.somewhere-else.com' proto pop3
|
|
||||||
user 'john.doe@somewhere-else.com' pass 'secret' is 'johnny@example.com'
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "With optional syntax"
|
|
||||||
|
|
||||||
- `#` for adding comments.
|
|
||||||
- The config file may include "noise" keywords to improve readability.
|
|
||||||
|
|
||||||
```fetchmailrc
|
|
||||||
# Retrieve mail for users `john.doe` and `jane.doe` via IMAP at this remote mail server:
|
|
||||||
poll 'mail.somewhere.com' with proto imap wants:
|
|
||||||
user 'john.doe' with pass 'secret', is 'johnny@example.com' here
|
|
||||||
user 'jane.doe' with pass 'secret', is 'jane@example.com' here
|
|
||||||
|
|
||||||
# Also retrieve mail from this mail server (but via POP3).
|
|
||||||
# NOTE: This could also be all on a single line, or with each key + value as a separate line.
|
|
||||||
# Notice how the remote username includes a full email address,
|
|
||||||
# Some mail servers like DMS use the full email address as the username:
|
|
||||||
poll 'mail.somewhere-else.com' with proto pop3 wants:
|
|
||||||
user 'john.doe@somewhere-else.com' with pass 'secret', is 'johnny@example.com' here
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "`FETCHMAIL_POLL` ENV: Override default polling interval"
|
|
||||||
|
|
||||||
By default the fetchmail service will check every 5 minutes for new mail at the configured mail accounts.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
environment:
|
|
||||||
# The fetchmail polling interval in seconds:
|
|
||||||
FETCHMAIL_POLL: 60
|
|
||||||
```
|
|
||||||
|
|
||||||
## Debugging
|
|
||||||
|
|
||||||
To debug your `fetchmail.cf` configuration run this `setup debug` command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker exec -it dms-container-name setup debug fetchmail
|
|
||||||
```
|
|
||||||
|
|
||||||
??? example "Sample output of `setup debug fetchmail`"
|
|
||||||
|
|
||||||
```log
|
|
||||||
fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:09 2016: poll started
|
|
||||||
Trying to connect to 132.245.48.18/995...connected.
|
|
||||||
fetchmail: Server certificate:
|
|
||||||
fetchmail: Issuer Organization: Microsoft Corporation
|
|
||||||
fetchmail: Issuer CommonName: Microsoft IT SSL SHA2
|
|
||||||
fetchmail: Subject CommonName: outlook.com
|
|
||||||
fetchmail: Subject Alternative Name: outlook.com
|
|
||||||
fetchmail: Subject Alternative Name: *.outlook.com
|
|
||||||
fetchmail: Subject Alternative Name: office365.com
|
|
||||||
fetchmail: Subject Alternative Name: *.office365.com
|
|
||||||
fetchmail: Subject Alternative Name: *.live.com
|
|
||||||
fetchmail: Subject Alternative Name: *.internal.outlook.com
|
|
||||||
fetchmail: Subject Alternative Name: *.outlook.office365.com
|
|
||||||
fetchmail: Subject Alternative Name: outlook.office.com
|
|
||||||
fetchmail: Subject Alternative Name: attachment.outlook.office.net
|
|
||||||
fetchmail: Subject Alternative Name: attachment.outlook.officeppe.net
|
|
||||||
fetchmail: Subject Alternative Name: *.office.com
|
|
||||||
fetchmail: outlook.office365.com key fingerprint: 3A:A4:58:42:56:CD:BD:11:19:5B:CF:1E:85:16:8E:4D
|
|
||||||
fetchmail: POP3< +OK The Microsoft Exchange POP3 service is ready. [SABFADEAUABSADAAMQBDAEEAMAAwADAANwAuAGUAdQByAHAAcgBkADAAMQAuAHAAcgBvAGQALgBlAHgAYwBoAGEAbgBnAGUAbABhAGIAcwAuAGMAbwBtAA==]
|
|
||||||
fetchmail: POP3> CAPA
|
|
||||||
fetchmail: POP3< +OK
|
|
||||||
fetchmail: POP3< TOP
|
|
||||||
fetchmail: POP3< UIDL
|
|
||||||
fetchmail: POP3< SASL PLAIN
|
|
||||||
fetchmail: POP3< USER
|
|
||||||
fetchmail: POP3< .
|
|
||||||
fetchmail: POP3> USER user1@outlook.com
|
|
||||||
fetchmail: POP3< +OK
|
|
||||||
fetchmail: POP3> PASS *
|
|
||||||
fetchmail: POP3< +OK User successfully logged on.
|
|
||||||
fetchmail: POP3> STAT
|
|
||||||
fetchmail: POP3< +OK 0 0
|
|
||||||
fetchmail: No mail for user1@outlook.com at outlook.office365.com
|
|
||||||
fetchmail: POP3> QUIT
|
|
||||||
fetchmail: POP3< +OK Microsoft Exchange Server 2016 POP3 server signing off.
|
|
||||||
fetchmail: 6.3.26 querying outlook.office365.com (protocol POP3) at Mon Aug 29 22:11:11 2016: poll completed
|
|
||||||
fetchmail: normal termination, status 1
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "Troubleshoot with this reference `compose.yaml`"
|
|
||||||
|
|
||||||
[A minimal `compose.yaml` example][fetchmail-compose-example] demonstrates how to run two instances of DMS locally, with one instance configured with `fetchmail.cf` and the other to simulate a remote mail server to fetch from.
|
|
||||||
|
|
||||||
[fetchmail-website]: https://www.fetchmail.info
|
|
||||||
[fetchmail-docs-config]: https://www.fetchmail.info/fetchmail-man.html#the-run-control-file
|
|
||||||
[fetchmail-config-examples]: https://www.fetchmail.info/fetchmail-man.html#configuration-examples
|
|
||||||
[fetchmail-compose-example]: https://github.com/orgs/docker-mailserver/discussions/3994#discussioncomment-9290570
|
|
||||||
|
|
@ -1,47 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Mail Forwarding | AWS SES'
|
|
||||||
---
|
|
||||||
|
|
||||||
[Amazon SES (Simple Email Service)][aws-ses] provides a simple way for cloud based applications to send and receive email.
|
|
||||||
|
|
||||||
!!! example "Configuration via ENV"
|
|
||||||
|
|
||||||
[Configure a relay host in DMS][docs::relay] to forward all your mail through AWS SES:
|
|
||||||
|
|
||||||
- `RELAY_HOST` should match your [AWS SES region][aws-ses::region].
|
|
||||||
- `RELAY_PORT` should be set to [one of the supported AWS SES SMTP ports][aws-ses::smtp-ports] (_eg: 587 for STARTTLS_).
|
|
||||||
- `RELAY_USER` and `RELAY_PASSWORD` should be set to your [Amazon SES SMTP credentials][aws-ses::credentials].
|
|
||||||
|
|
||||||
```env
|
|
||||||
RELAY_HOST=email-smtp.us-west-2.amazonaws.com
|
|
||||||
RELAY_PORT=587
|
|
||||||
# Alternative to RELAY_HOST + RELAY_PORT which is compatible with LDAP:
|
|
||||||
DEFAULT_RELAY_HOST=[email-smtp.us-west-2.amazonaws.com]:587
|
|
||||||
|
|
||||||
RELAY_USER=aws-user
|
|
||||||
RELAY_PASSWORD=secret
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
If you have set up [AWS Easy DKIM][aws-ses::easy-dkim], you can safely skip setting up DKIM as AWS SES will take care of signing your outbound mail.
|
|
||||||
|
|
||||||
!!! note "Verify the relay host is configured correctly"
|
|
||||||
|
|
||||||
To verify proper operation, send an email to some external account of yours and inspect the mail headers.
|
|
||||||
|
|
||||||
You will also see the connection to SES in the mail logs:
|
|
||||||
|
|
||||||
```log
|
|
||||||
postfix/smtp[692]: Trusted TLS connection established to email-smtp.us-west-1.amazonaws.com[107.20.142.169]:25:
|
|
||||||
TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)
|
|
||||||
postfix/smtp[692]: 8C82A7E7: to=<someone@example.com>, relay=email-smtp.us-west-1.amazonaws.com[107.20.142.169]:25,
|
|
||||||
delay=0.35, delays=0/0.02/0.13/0.2, dsn=2.0.0, status=sent (250 Ok 01000154dc729264-93fdd7ea-f039-43d6-91ed-653e8547867c-000000)
|
|
||||||
```
|
|
||||||
|
|
||||||
[docs::relay]: ./relay-hosts.md
|
|
||||||
[aws-ses]: https://aws.amazon.com/ses/
|
|
||||||
[aws-ses::credentials]: https://docs.aws.amazon.com/ses/latest/dg/smtp-credentials.html
|
|
||||||
[aws-ses::smtp-ports]: https://docs.aws.amazon.com/ses/latest/dg/smtp-connect.html
|
|
||||||
[aws-ses::region]: https://docs.aws.amazon.com/general/latest/gr/ses.html
|
|
||||||
[aws-ses::easy-dkim]: https://docs.aws.amazon.com/ses/latest/DeveloperGuide/send-email-authentication-dkim-easy.html
|
|
||||||
|
|
@ -1,50 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Mail Forwarding | Configure Gmail as a relay host'
|
|
||||||
---
|
|
||||||
|
|
||||||
This page provides a guide for configuring DMS to use [GMAIL as an SMTP relay host][gmail-smtp].
|
|
||||||
|
|
||||||
!!! example "Configuration via ENV"
|
|
||||||
|
|
||||||
[Configure a relay host in DMS][docs::relay]. This example shows how the related ENV settings map to the Gmail service config:
|
|
||||||
|
|
||||||
- `RELAY_HOST` should be configured as [advised by Gmail][gmail-smtp::relay-host], there are two SMTP endpoints to choose:
|
|
||||||
- `smtp.gmail.com` (_for a personal Gmail account_)
|
|
||||||
- `smtp-relay.gmail.com` (_when using Google Workspace_)
|
|
||||||
- `RELAY_PORT` should be set to [one of the supported Gmail SMTP ports][gmail-smtp::relay-port] (_eg: 587 for STARTTLS_).
|
|
||||||
- `RELAY_USER` should be your gmail address (`user@gmail.com`).
|
|
||||||
- `RELAY_PASSWORD` should be your [App Password][gmail-smtp::app-password], **not** your personal gmail account password.
|
|
||||||
|
|
||||||
```env
|
|
||||||
RELAY_HOST=smtp.gmail.com
|
|
||||||
RELAY_PORT=587
|
|
||||||
# Alternative to RELAY_HOST + RELAY_PORT which is compatible with LDAP:
|
|
||||||
DEFAULT_RELAY_HOST=[smtp.gmail.com]:587
|
|
||||||
|
|
||||||
RELAY_USER=username@gmail.com
|
|
||||||
RELAY_PASSWORD=secret
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
- As per our main [relay host docs page][docs::relay], you may prefer to configure your credentials via `setup relay add-auth` instead of the `RELAY_USER` + `RELAY_PASSWORD` ENV.
|
|
||||||
- If you configure for `smtp-relay.gmail.com`, the `DEFAULT_RELAY_HOST` ENV should be all you need as shown in the above example. Credentials can be optional when using Google Workspace (`smtp-relay.gmail.com`), which supports restricting connections to trusted IP addresses.
|
|
||||||
|
|
||||||
!!! note "Verify the relay host is configured correctly"
|
|
||||||
|
|
||||||
To verify proper operation, send an email to an external account of yours and inspect the mail headers.
|
|
||||||
|
|
||||||
You will also see the connection to the Gmail relay host (`smtp.gmail.com`) in the mail logs:
|
|
||||||
|
|
||||||
```log
|
|
||||||
postfix/smtp[910]: Trusted TLS connection established to smtp.gmail.com[64.233.188.109]:587:
|
|
||||||
TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
|
|
||||||
postfix/smtp[910]: 4BCB547D9D: to=<username@gmail.com>, relay=smtp.gmail.com[64.233.188.109]:587,
|
|
||||||
delay=2.9, delays=0.01/0.02/1.7/1.2, dsn=2.0.0, status=sent (250 2.0.0 OK 17... - gsmtp)
|
|
||||||
```
|
|
||||||
|
|
||||||
[docs::relay]: ./relay-hosts.md
|
|
||||||
[gmail-smtp]: https://support.google.com/a/answer/2956491
|
|
||||||
[gmail-smtp::relay-host]: https://support.google.com/a/answer/176600
|
|
||||||
[gmail-smtp::relay-port]: https://support.google.com/a/answer/2956491
|
|
||||||
[gmail-smtp::app-password]: https://support.google.com/accounts/answer/185833
|
|
||||||
|
|
@ -1,156 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Mail Forwarding | Relay Hosts'
|
|
||||||
---
|
|
||||||
|
|
||||||
## What is a Relay Host?
|
|
||||||
|
|
||||||
An SMTP relay service (_aka relay host / [smarthost][wikipedia::smarthost]_) is an MTA that relays (_forwards_) mail on behalf of third-parties (_it does not manage the mail domains_).
|
|
||||||
|
|
||||||
- Instead of DMS handling SMTP delivery directly itself (_via Postfix_), it can be configured to delegate delivery by sending all outbound mail through a relay service.
|
|
||||||
- Examples of popular mail relay services: [AWS SES][smarthost::aws-ses], [Mailgun][smarthost::mailgun], [Mailjet][smarthost::mailjet], [SendGrid][smarthost::sendgrid]
|
|
||||||
|
|
||||||
!!! info "When can a relay service can be helpful?"
|
|
||||||
|
|
||||||
- Your network provider has blocked outbound connections on port 25 (_required for direct delivery_).
|
|
||||||
- To improve delivery success via better established reputation (trust) of a relay service.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
All mail sent outbound from DMS (_where the sender address is a DMS account or a virtual alias_) will be relayed through the configured relay host.
|
|
||||||
|
|
||||||
!!! info "Configuration via ENV"
|
|
||||||
|
|
||||||
Configure the default relayhost with either of these ENV:
|
|
||||||
|
|
||||||
- Preferable (_LDAP compatible_): `DEFAULT_RELAY_HOST` (eg: `[mail.relay-service.com]:25`)
|
|
||||||
- `RELAY_HOST` (eg: `mail.relay-service.com`) + `RELAY_PORT` (default: 25)
|
|
||||||
|
|
||||||
Most relay services also require authentication configured:
|
|
||||||
|
|
||||||
- `RELAY_USER` + `RELAY_PASSWORD` provides credentials for authenticating with the default relayhost.
|
|
||||||
|
|
||||||
!!! warning "Providing secrets via ENV"
|
|
||||||
|
|
||||||
While ENV is convenient, the risk of exposing secrets is higher.
|
|
||||||
|
|
||||||
`setup relay add-auth` is a better alternative, which manages the credentials via a config file.
|
|
||||||
|
|
||||||
??? tip "Excluding specific sender domains from relay"
|
|
||||||
|
|
||||||
You can opt-out with: `setup relay exclude-domain <domain>`
|
|
||||||
|
|
||||||
Outbound mail from senders of that domain will be sent normally (_instead of through the configured `RELAY_HOST`_).
|
|
||||||
|
|
||||||
!!! warning "When any relay host credentials are configured"
|
|
||||||
|
|
||||||
It will still be expected that mail is sent over a secure connection with credentials provided.
|
|
||||||
|
|
||||||
Thus this opt-out feature is rarely practical.
|
|
||||||
|
|
||||||
### Advanced Configuration
|
|
||||||
|
|
||||||
When mail is sent, there is support to change the relay service or the credentials configured based on the sender address domain used.
|
|
||||||
|
|
||||||
We provide this support via two config files:
|
|
||||||
|
|
||||||
- Sender-dependent Relay Host: `docker-data/dms/config/postfix-relaymap.cf`
|
|
||||||
- Sender-dependent Authentication: `docker-data/dms/config/postfix-sasl-password.cf`
|
|
||||||
|
|
||||||
!!! tip "Configure with our `setup relay` commands"
|
|
||||||
|
|
||||||
While you can edit those configs directly, DMS provides these helpful config management commands:
|
|
||||||
|
|
||||||
```cli-syntax
|
|
||||||
# Configure a sender domain to use a specific relay host:
|
|
||||||
setup relay add-domain <domain> <host> [<port>]
|
|
||||||
|
|
||||||
# Configure relay host credentials for a sender domain to use:
|
|
||||||
setup relay add-auth <domain> <username> [<password>]
|
|
||||||
|
|
||||||
# Optionally avoid relaying from senders of this domain:
|
|
||||||
# NOTE: Only supported when configured with the `RELAY_HOST` ENV!
|
|
||||||
setup relay exclude-domain <domain>
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! example "Config file: `postfix-sasl-password.cf`"
|
|
||||||
|
|
||||||
```cf-extra title="docker-data/dms/config/postfix-sasl-password.cf"
|
|
||||||
@domain1.com mailgun-user:secret
|
|
||||||
@domain2.com sendgrid-user:secret
|
|
||||||
|
|
||||||
# NOTE: This must have an exact match with the relay host in `postfix-relaymap.cf`,
|
|
||||||
# `/etc/postfix/relayhost_map`, or the `DEFAULT_RELAY_HOST` ENV.
|
|
||||||
# NOTE: Not supported via our setup CLI, but valid config for Postfix.
|
|
||||||
[email-smtp.us-west-2.amazonaws.com]:2587 aws-user:secret
|
|
||||||
```
|
|
||||||
|
|
||||||
When Postfix needs to lookup credentials for mail sent outbound, the above config will:
|
|
||||||
|
|
||||||
- Authenticate as `mailgun-user` for mail sent with a sender belonging to `@domain1.com`
|
|
||||||
- Authenticate as `sendgrid-user` for mail sent with a sender belonging to `@domain2.com`
|
|
||||||
- Authenticate as `aws-user` for mail sent through a configured AWS SES relay host (any sender domain).
|
|
||||||
|
|
||||||
!!! example "Config file: `postfix-relaymap.cf`"
|
|
||||||
|
|
||||||
```cf-extra title="docker-data/dms/config/postfix-relaymap.cf"
|
|
||||||
@domain1.com [smtp.mailgun.org]:587
|
|
||||||
@domain2.com [smtp.sendgrid.net]:2525
|
|
||||||
|
|
||||||
# Opt-out of relaying:
|
|
||||||
@domain3.com
|
|
||||||
```
|
|
||||||
|
|
||||||
When Postfix sends mail outbound from these sender domains, the above config will:
|
|
||||||
|
|
||||||
- Relay mail through `[smtp.mailgun.org]:587` when mail is sent from a sender of `@domain1.com`
|
|
||||||
- Relay mail through `[smtp.sendgrid.net]:2525` when mail is sent from a sender of `@domain1.com`
|
|
||||||
- Mail with a sender from `@domain3.com` is not sent through a relay (_**Only applicable** when using `RELAY_HOST`_)
|
|
||||||
|
|
||||||
### Technical Details
|
|
||||||
|
|
||||||
- Both the supported ENV and config files for this feature have additional details covered in our ENV docs [Relay Host section][docs::env-relay].
|
|
||||||
- For troubleshooting, a [minimal `compose.yaml` config with several DMS instances][dms-gh::relay-example] demonstrates this feature for local testing.
|
|
||||||
- [Subscribe to this tracking issue][dms-gh::pr-3607] for future improvements intended for this feature.
|
|
||||||
|
|
||||||
!!! abstract "Postfix Settings"
|
|
||||||
|
|
||||||
Internally this feature is implemented in DMS by [`relay.sh`][dms-repo::helpers-relay].
|
|
||||||
|
|
||||||
The `relay.sh` script manages configuring these Postfix settings:
|
|
||||||
|
|
||||||
```cf-extra
|
|
||||||
# Send all outbound mail through this relay service:
|
|
||||||
relayhost = [smtp.relay-service.com]:587
|
|
||||||
|
|
||||||
# Credentials to use:
|
|
||||||
smtp_sasl_password_maps = texthash:/etc/postfix/sasl_passwd
|
|
||||||
# Alternative table type examples which do not require a separate file:
|
|
||||||
#smtp_sasl_password_maps = static:john.doe@relay-service.com:secret
|
|
||||||
#smtp_sasl_password_maps = inline:{ [smtp.relay-service.com]:587=john.doe@relay-service.com:secret }
|
|
||||||
|
|
||||||
## Authentication support:
|
|
||||||
# Required to provide credentials to the relay service:
|
|
||||||
smtp_sasl_auth_enable = yes
|
|
||||||
# Enforces requiring credentials when sending mail outbound:
|
|
||||||
smtp_sasl_security_options = noanonymous
|
|
||||||
# Enforces a secure connection (TLS required) to the relay service:
|
|
||||||
smtp_tls_security_level = encrypt
|
|
||||||
|
|
||||||
## Support for advanced requirements:
|
|
||||||
# Relay service(s) to use instead of direct delivery for specific sender domains:
|
|
||||||
sender_dependent_relayhost_maps = texthash:/etc/postfix/relayhost_map
|
|
||||||
# Support credentials to a relay service(s) that vary by relay host used or sender domain:
|
|
||||||
smtp_sender_dependent_authentication = yes
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
[smarthost::mailgun]: https://www.mailgun.com/
|
|
||||||
[smarthost::mailjet]: https://www.mailjet.com
|
|
||||||
[smarthost::sendgrid]: https://sendgrid.com/
|
|
||||||
[smarthost::aws-ses]: https://aws.amazon.com/ses/
|
|
||||||
[wikipedia::smarthost]: https://en.wikipedia.org/wiki/Smart_host
|
|
||||||
|
|
||||||
[docs::env-relay]: ../../environment.md#relay-host
|
|
||||||
[dms-repo::helpers-relay]: https://github.com/docker-mailserver/docker-mailserver/blob/v15.0.0/target/scripts/helpers/relay.sh
|
|
||||||
[dms-gh::pr-3607]: https://github.com/docker-mailserver/docker-mailserver/issues/3607
|
|
||||||
[dms-gh::relay-example]: https://github.com/docker-mailserver/docker-mailserver/issues/3842#issuecomment-1913380639
|
|
||||||
|
|
@ -1,118 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Email Gathering with Getmail'
|
|
||||||
---
|
|
||||||
|
|
||||||
To enable the [getmail][getmail-website] service to retrieve e-mails set the environment variable `ENABLE_GETMAIL` to `1`. Your `compose.yaml` file should include the following:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
environment:
|
|
||||||
- ENABLE_GETMAIL=1
|
|
||||||
- GETMAIL_POLL=5
|
|
||||||
```
|
|
||||||
|
|
||||||
In your DMS config volume (eg: `docker-data/dms/config/`), add a subdirectory `getmail/` for including your getmail config files (eg: `imap-example.cf`) for each remote account that you want to retrieve mail from and deliver to the mailbox of a DMS account.
|
|
||||||
|
|
||||||
The content of these config files is documented in the next section with an IMAP and POP3 example to reference.
|
|
||||||
|
|
||||||
The directory structure should look similar to this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
├── docker-data/dms/config
|
|
||||||
│ ├── dovecot.cf
|
|
||||||
│ ├── getmail
|
|
||||||
│ │ ├── getmailrc_general.cf
|
|
||||||
│ │ ├── remote-account1.cf
|
|
||||||
│ │ ├── remote-account2.cf
|
|
||||||
│ ├── postfix-accounts.cf
|
|
||||||
│ └── postfix-virtual.cf
|
|
||||||
├── docker-compose.yml
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
A detailed description of the configuration options can be found in the [online version of the manual page][getmail-docs].
|
|
||||||
|
|
||||||
### Common Options
|
|
||||||
|
|
||||||
The default options added to each `getmail` config are:
|
|
||||||
|
|
||||||
```getmailrc
|
|
||||||
[options]
|
|
||||||
verbose = 0
|
|
||||||
read_all = false
|
|
||||||
delete = false
|
|
||||||
max_messages_per_session = 500
|
|
||||||
received = false
|
|
||||||
delivered_to = false
|
|
||||||
```
|
|
||||||
|
|
||||||
The DMS integration for Getmail generates a `getmailrc` config that prepends the common options of the base config to each remote account config file (`*.cf`) found in the DMS Config Volume `getmail/` directory.
|
|
||||||
|
|
||||||
!!! tip "Change the base options"
|
|
||||||
|
|
||||||
Add your own base config as `getmail/getmailrc_general.cf` into the DMS Config Volume. It will replace the DMS defaults shown above.
|
|
||||||
|
|
||||||
??? example "IMAP Configuration"
|
|
||||||
|
|
||||||
This example will:
|
|
||||||
|
|
||||||
1. Connect to the remote IMAP server from Gmail.
|
|
||||||
2. Retrieve mail from the gmail account `alice` with password `notsecure`.
|
|
||||||
3. Store any mail retrieved from the remote mail-server into DMS for the `user1@example.com` account that DMS manages.
|
|
||||||
|
|
||||||
```getmailrc
|
|
||||||
[retriever]
|
|
||||||
type = SimpleIMAPSSLRetriever
|
|
||||||
server = imap.gmail.com
|
|
||||||
username = alice
|
|
||||||
password = notsecure
|
|
||||||
[destination]
|
|
||||||
type = MDA_external
|
|
||||||
path = /usr/lib/dovecot/deliver
|
|
||||||
allow_root_commands = true
|
|
||||||
arguments =("-d","user1@example.com")
|
|
||||||
```
|
|
||||||
|
|
||||||
??? example "POP3 Configuration"
|
|
||||||
|
|
||||||
Just like the IMAP example above, but instead via POP3 protocol if you prefer that over IMAP.
|
|
||||||
|
|
||||||
```getmailrc
|
|
||||||
[retriever]
|
|
||||||
type = SimplePOP3SSLRetriever
|
|
||||||
server = pop3.gmail.com
|
|
||||||
username = alice
|
|
||||||
password = notsecure
|
|
||||||
[destination]
|
|
||||||
type = MDA_external
|
|
||||||
path = /usr/lib/dovecot/deliver
|
|
||||||
allow_root_commands = true
|
|
||||||
arguments =("-d","user1@example.com")
|
|
||||||
```
|
|
||||||
|
|
||||||
### Polling Interval
|
|
||||||
|
|
||||||
By default the `getmail` service checks external mail accounts for new mail every 5 minutes. That polling interval is configurable via the `GETMAIL_POLL` ENV variable, with a value in minutes (_default: 5, min: 1_):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
environment:
|
|
||||||
- GETMAIL_POLL=1
|
|
||||||
```
|
|
||||||
|
|
||||||
### XOAUTH2 Authentication
|
|
||||||
|
|
||||||
It is possible to utilize the `getmail-gmail-xoauth-tokens` helper to provide authentication using `xoauth2` for [gmail (example 12)][getmail-docs-xoauth-12] or [Microsoft Office 365 (example 13)][getmail-docs-xoauth-13]
|
|
||||||
|
|
||||||
[getmail-website]: https://www.getmail6.org
|
|
||||||
[getmail-docs]: https://getmail6.org/configuration.html
|
|
||||||
[getmail-docs-xoauth-12]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L286
|
|
||||||
[getmail-docs-xoauth-13]: https://github.com/getmail6/getmail6/blob/1f95606156231f1e074ba62a9baa64f892a92ef8/docs/getmailrc-examples#L351
|
|
||||||
|
|
||||||
## Debugging
|
|
||||||
|
|
||||||
To debug your `getmail` configurations, run this `setup debug` command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker exec -it dms-container-name setup debug getmail
|
|
||||||
```
|
|
||||||
|
|
@ -1,188 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Email Filtering with Sieve'
|
|
||||||
---
|
|
||||||
|
|
||||||
## User-Defined Sieve Filters
|
|
||||||
|
|
||||||
!!! warning "Advice may be outdated"
|
|
||||||
|
|
||||||
This section was contributed by the community some time ago and some configuration examples may be outdated.
|
|
||||||
|
|
||||||
[Sieve][sieve-info] allows to specify filtering rules for incoming emails that allow for example sorting mails into different folders depending on the title of an email.
|
|
||||||
|
|
||||||
!!! info "Global vs User order"
|
|
||||||
|
|
||||||
There are global and user specific filters which are filtering the incoming emails in the following order:
|
|
||||||
|
|
||||||
Global-before -> User specific -> Global-after
|
|
||||||
|
|
||||||
Global filters are applied to EVERY incoming mail for EVERY email address.
|
|
||||||
|
|
||||||
- To specify a global Sieve filter provide a `docker-data/dms/config/before.dovecot.sieve` or a `docker-data/dms/config/after.dovecot.sieve` file with your filter rules.
|
|
||||||
- If any filter in this filtering chain discards an incoming mail, the delivery process will stop as well and the mail will not reach any following filters (e.g. global-before stops an incoming spam mail: The mail will get discarded and a user-specific filter won't get applied.)
|
|
||||||
|
|
||||||
To specify a user-defined Sieve filter place a `.dovecot.sieve` file into a virtual user's mail folder (e.g. `/var/mail/example.com/user1/home/.dovecot.sieve`). If this file exists dovecot will apply the filtering rules.
|
|
||||||
|
|
||||||
It's even possible to install a user provided Sieve filter at startup during users setup: simply include a Sieve file in the `docker-data/dms/config/` path for each user login that needs a filter. The file name provided should be in the form `<user_login>.dovecot.sieve`, so for example for `user1@example.com` you should provide a Sieve file named `docker-data/dms/config/user1@example.com.dovecot.sieve`.
|
|
||||||
|
|
||||||
An example of a sieve filter that moves mails to a folder `INBOX/spam` depending on the sender address:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```sieve
|
|
||||||
require ["fileinto", "reject"];
|
|
||||||
|
|
||||||
if address :contains ["From"] "spam@spam.com" {
|
|
||||||
fileinto "INBOX.spam";
|
|
||||||
} else {
|
|
||||||
keep;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
That folders have to exist beforehand if sieve should move them.
|
|
||||||
|
|
||||||
Another example of a sieve filter that forward mails to a different address:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```sieve
|
|
||||||
require ["copy"];
|
|
||||||
|
|
||||||
redirect :copy "user2@not-example.com";
|
|
||||||
```
|
|
||||||
|
|
||||||
Just forward all incoming emails and do not save them locally:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```sieve
|
|
||||||
redirect "user2@not-example.com";
|
|
||||||
```
|
|
||||||
|
|
||||||
You can also use external programs to filter or pipe (process) messages by adding executable scripts in `docker-data/dms/config/sieve-pipe` or `docker-data/dms/config/sieve-filter`.
|
|
||||||
|
|
||||||
This can be used in lieu of a local alias file, for instance to forward an email to a webservice.
|
|
||||||
|
|
||||||
- These programs can then be referenced by filename, by all users.
|
|
||||||
- Note that the process running the scripts run as a privileged user.
|
|
||||||
- For further information see [Dovecot's docs][dovecot-docs::sieve-pipe].
|
|
||||||
|
|
||||||
```sieve
|
|
||||||
require ["vnd.dovecot.pipe"];
|
|
||||||
pipe "external-program";
|
|
||||||
```
|
|
||||||
|
|
||||||
For more examples or a detailed description of the Sieve language have a look at [the official site][sieve-info::examples]. Other resources are available on the internet where you can find several [examples][third-party::sieve-examples].
|
|
||||||
|
|
||||||
[dovecot-docs::sieve-pipe]: https://doc.dovecot.org/configuration_manual/sieve/plugins/extprograms/#pigeonhole-plugin-extprograms
|
|
||||||
[sieve-info]: http://sieve.info/
|
|
||||||
[sieve-info::examples]: http://sieve.info/examplescripts
|
|
||||||
[third-party::sieve-examples]: https://support.tigertech.net/sieve#sieve-example-rules-jmp
|
|
||||||
|
|
||||||
## Automatic Sorting Based on Sub-addresses { #subaddress-mailbox-routing }
|
|
||||||
|
|
||||||
When mail is delivered to your account, it is possible to organize storing mail into folders by the [subaddress (tag)][docs::accounts-subaddressing] used.
|
|
||||||
|
|
||||||
!!! example "Example: `user+<tag>@example.com` to `INBOX/<Tag>`"
|
|
||||||
|
|
||||||
This example sorts mail into inbox folders by their tag:
|
|
||||||
|
|
||||||
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
|
|
||||||
require ["envelope", "fileinto", "mailbox", "subaddress", "variables"];
|
|
||||||
|
|
||||||
# Check if the mail recipient address has a tag (:detail)
|
|
||||||
if envelope :detail :matches "to" "*" {
|
|
||||||
# Create a variable `tag`, with the the captured `to` value normalized (SoCIAL => Social)
|
|
||||||
set :lower :upperfirst "tag" "${1}";
|
|
||||||
|
|
||||||
# Store the mail into a folder with the tag name, nested under your inbox folder:
|
|
||||||
if mailboxexists "INBOX.${tag}" {
|
|
||||||
fileinto "INBOX.${tag}";
|
|
||||||
} else {
|
|
||||||
fileinto :create "INBOX.${tag}";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
When receiving mail for `user+social@example.com` it would be delivered into the `INBOX/Social` folder.
|
|
||||||
|
|
||||||
??? tip "Only redirect mail for specific tags"
|
|
||||||
|
|
||||||
If you want to only handle specific tags, you could replace the envelope condition and tag assignment from the prior example with:
|
|
||||||
|
|
||||||
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
|
|
||||||
# Instead of `:matches`, use the default comparator `:is` (exact match)
|
|
||||||
if envelope :detail "to" "social" {
|
|
||||||
set "tag" "Social";
|
|
||||||
```
|
|
||||||
|
|
||||||
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
|
|
||||||
# Alternatively you can also provide a list of values to match:
|
|
||||||
if envelope :detail "to" ["azure", "aws"] {
|
|
||||||
set "tag" "Cloud";
|
|
||||||
```
|
|
||||||
|
|
||||||
```sieve title="docker-data/dms/config/user@example.com.dovecot.sieve"
|
|
||||||
# Similar to `:matches`, except `:regex` provides enhanced pattern matching.
|
|
||||||
# NOTE: This example needs you to `require` the "regex" extension
|
|
||||||
if envelope :detail :regex "to" "^cloud-(azure|aws)$" {
|
|
||||||
# Normalize the captured azure/aws tag as the resolved value is no longer fixed:
|
|
||||||
set :lower :upperfirst "vendor" "${1}";
|
|
||||||
# If a `.` exists in the tag, it will create nested folders:
|
|
||||||
set "tag" "Cloud.${vendor}";
|
|
||||||
```
|
|
||||||
|
|
||||||
**NOTE:** There is no need to lowercase the tag in the conditional as the [`to` value is a case-insensitive check][sieve-docs::envelope].
|
|
||||||
|
|
||||||
??? abstract "Technical Details"
|
|
||||||
|
|
||||||
- Dovecot supports this feature via the _Sieve subaddress extension_ ([RFC 5233][rfc::5233::sieve-subaddress]).
|
|
||||||
- Only a single tag per subaddress is supported. Any additional tag delimiters are part of the tag value itself.
|
|
||||||
- The Dovecot setting [`recipient_delimiter`][dovecot-docs::config::recipient_delimiter] (default: `+`) configures the tag delimiter. This is where the `local-part` of the recipient address will split at, providing the `:detail` (tag) value for Sieve.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
`INBOX` is the [default namespace configured by Dovecot][dovecot-docs::namespace].
|
|
||||||
|
|
||||||
- If you omit the `INBOX.` prefix from the sieve script above, the mailbox (folder) for that tag is created at the top-level alongside your Trash and Junk folders.
|
|
||||||
- The `.` between `INBOX` and `${tag}` is important as a [separator to distinguish mailbox names][dovecot-docs::mailbox-names]. This can vary by mailbox format or configuration. DMS uses [`Maildir`][dovecot-docs::mailbox-formats::maildir] by default, which uses `.` as the separator.
|
|
||||||
- [`lmtp_save_to_detail_mailbox = yes`][dovecot-docs::config::lmtp_save_to_detail_mailbox] can be set in `/etc/dovecot/conf.d/20-lmtp.conf`:
|
|
||||||
- This implements the feature globally, except for the tag normalization and `INBOX.` prefix parts of the example script.
|
|
||||||
- However, if the sieve script is also present, the script has precedence and will handle this task instead when the condition is successful, otherwise falling back to the global feature.
|
|
||||||
|
|
||||||
## Manage Sieve
|
|
||||||
|
|
||||||
The [Manage Sieve](https://doc.dovecot.org/admin_manual/pigeonhole_managesieve_server/) extension allows users to modify their Sieve script by themselves. The authentication mechanisms are the same as for the main dovecot service. ManageSieve runs on port `4190` and needs to be enabled using the `ENABLE_MANAGESIEVE=1` environment variable.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
ports:
|
|
||||||
- "4190:4190"
|
|
||||||
environment:
|
|
||||||
- ENABLE_MANAGESIEVE=1
|
|
||||||
```
|
|
||||||
|
|
||||||
All user defined sieve scripts that are managed by ManageSieve are stored in the user's home folder in `/var/mail/example.com/user1/home/sieve`. Just one Sieve script might be active for a user and is sym-linked to `/var/mail/example.com/user1/home/.dovecot.sieve` automatically.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
ManageSieve makes sure to not overwrite an existing `.dovecot.sieve` file. If a user activates a new sieve script the old one is backed up and moved to the `sieve` folder.
|
|
||||||
|
|
||||||
The extension is known to work with the following ManageSieve clients:
|
|
||||||
|
|
||||||
- **[Sieve Editor](https://github.com/thsmi/sieve)** a portable standalone application based on the former Thunderbird plugin.
|
|
||||||
- **[Kmail](https://kontact.kde.org/components/kmail/)** the mail client of [KDE](https://kde.org/)'s Kontact Suite.
|
|
||||||
|
|
||||||
[docs::accounts-subaddressing]: ../account-management/overview.md#sub-addressing
|
|
||||||
|
|
||||||
[dovecot-docs::namespace]: https://doc.dovecot.org/configuration_manual/namespace/
|
|
||||||
[dovecot-docs::mailbox-names]: https://doc.dovecot.org/configuration_manual/sieve/usage/#mailbox-names
|
|
||||||
[dovecot-docs::mailbox-formats::maildir]: https://doc.dovecot.org/admin_manual/mailbox_formats/maildir/#maildir-mbox-format
|
|
||||||
[dovecot-docs::config::lmtp_save_to_detail_mailbox]: https://doc.dovecot.org/settings/core/#core_setting-lmtp_save_to_detail_mailbox
|
|
||||||
[dovecot-docs::config::recipient_delimiter]: https://doc.dovecot.org/settings/core/#core_setting-recipient_delimiter
|
|
||||||
|
|
||||||
[rfc::5233::sieve-subaddress]: https://datatracker.ietf.org/doc/html/rfc5233
|
|
||||||
[sieve-docs::envelope]: https://thsmi.github.io/sieve-reference/en/test/core/envelope.html
|
|
||||||
|
|
@ -1,53 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Maintenance | Update and Cleanup'
|
|
||||||
---
|
|
||||||
|
|
||||||
[`containrrr/watchtower`][watchtower-dockerhub] is a service that monitors Docker images for updates, automatically applying them to running containers.
|
|
||||||
|
|
||||||
!!! example "Automatic image updates + cleanup"
|
|
||||||
|
|
||||||
Run a `watchtower` container with access to `docker.sock`, enabling the service to manage Docker:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
watchtower:
|
|
||||||
image: containrrr/watchtower:latest
|
|
||||||
# Automatic cleanup (removes older image pulls from wasting disk space):
|
|
||||||
environment:
|
|
||||||
- WATCHTOWER_CLEANUP=true
|
|
||||||
volumes:
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "The image tag used for a container is monitored for updates (eg: `:latest`, `:edge`, `:13`)"
|
|
||||||
|
|
||||||
The automatic update support is **only for updates to that specific image tag**.
|
|
||||||
|
|
||||||
- Your container will not update to a new major version tag (_unless using `:latest`_).
|
|
||||||
- Omit the minor or patch portion of the semver tag to receive updates for the omitted portion (_eg: `13` will represent the latest minor + patch release of `v13`_).
|
|
||||||
|
|
||||||
!!! tip "Updating only specific containers"
|
|
||||||
|
|
||||||
By default the `watchtower` service will check every 24 hours for new image updates to pull, based on currently running containers (_**not restricted** to only those running within your `compose.yaml`_).
|
|
||||||
|
|
||||||
Images eligible for updates can configured with a [custom `command`][docker-docs-compose-command] that provides a list of container names, or via other supported options (eg: labels). This configuration is detailed in the [`watchtower` docs][watchtower-docs].
|
|
||||||
|
|
||||||
!!! info "Manual cleanup"
|
|
||||||
|
|
||||||
`watchtower` also supports running on-demand with `docker run` or `compose.yaml` via the `--run-once` option.
|
|
||||||
|
|
||||||
You can alternatively invoke cleanup of Docker storage directly with:
|
|
||||||
|
|
||||||
- [`docker image prune --all`][docker-docs-prune-image]
|
|
||||||
- [`docker system prune --all`][docker-docs-prune-system] (_also removes unused containers, networks, build cache_).
|
|
||||||
|
|
||||||
If you omit the `--all` option, this will instead only remove ["dangling" content][docker-prune-dangling] (_eg: Orphaned images_).
|
|
||||||
|
|
||||||
[watchtower-dockerhub]: https://hub.docker.com/r/containrrr/watchtower
|
|
||||||
[watchtower-cleanup]: https://containrrr.github.io/watchtower/arguments/#cleanup
|
|
||||||
[watchtower-docs]: https://containrrr.dev/watchtower/
|
|
||||||
|
|
||||||
[docker-docs-compose-command]: https://docs.docker.com/compose/compose-file/05-services/#command
|
|
||||||
[docker-docs-prune-image]: https://docs.docker.com/engine/reference/commandline/image_prune/
|
|
||||||
[docker-docs-prune-system]: https://docs.docker.com/engine/reference/commandline/system_prune/
|
|
||||||
[docker-prune-dangling]: https://stackoverflow.com/questions/45142528/what-is-a-dangling-image-and-what-is-an-unused-image/60756668#60756668
|
|
||||||
|
|
@ -1,114 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Optional Configuration'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
## Volumes
|
|
||||||
|
|
||||||
DMS has several locations in the container which may be worth persisting externally via [Docker Volumes][docker-docs::volumes].
|
|
||||||
|
|
||||||
- Often you will want to prefer [bind mount volumes][docker-docs::volumes::bind-mount] for easy access to files at a local location on your filesystem.
|
|
||||||
- As a convention for our docs and example configs, the local location has the common prefix `docker-data/dms/` for grouping these related volumes.
|
|
||||||
|
|
||||||
!!! info "Reference - Volmes for DMS"
|
|
||||||
|
|
||||||
Our docs may refer to these DMS specific volumes only by name, or the host/container path for brevity.
|
|
||||||
|
|
||||||
- [Config](#volumes-config): `docker-data/dms/config/` => `/tmp/docker-mailserver/`
|
|
||||||
- [Mail Storage](#volumes-mail): `docker-data/dms/mail-data/` => `/var/mail/`
|
|
||||||
- [State](#volumes-state): `docker-data/dms/mail-state/` => `/var/mail-state/`
|
|
||||||
- [Logs](#volumes-log): `docker-data/dms/mail-logs/` => `/var/log/mail/`
|
|
||||||
|
|
||||||
### Mail Storage Volume { #volumes-mail }
|
|
||||||
|
|
||||||
This is the location where mail is delivered to your mailboxes.
|
|
||||||
|
|
||||||
### State Volume { #volumes-state }
|
|
||||||
|
|
||||||
Run-time specific state lives here, but so does some data you may want to keep if a failure event occurs (_crash, power loss_).
|
|
||||||
|
|
||||||
!!! example "Examples of relevant data"
|
|
||||||
|
|
||||||
- The Postfix queue (eg: mail pending delivery attempt)
|
|
||||||
- Fail2Ban blocks.
|
|
||||||
- ClamAV signature updates.
|
|
||||||
- Redis storage for Rspamd.
|
|
||||||
|
|
||||||
!!! info "When a volume is mounted to `/var/mail-state/`"
|
|
||||||
|
|
||||||
- Service run-time data is [consolidated into the `/var/mail-state/` directory][mail-state-folders]. Otherwise the original locations vary and would need to be mounted individually.
|
|
||||||
- The original locations are updated with symlinks to redirect to their new path in `/var/mail-state/` (_eg: `/var/lib/redis` => `/var/mail-state/lib-redis/`_).
|
|
||||||
|
|
||||||
Supported services: Postfix, Dovecot, Fail2Ban, Amavis, PostGrey, ClamAV, SpamAssassin, Rspamd & Redis, Fetchmail, Getmail, LogRotate, PostSRSd, MTA-STS.
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
Sometimes it is helpful to disable this volume when troubleshooting to verify if the data stored here is in a bad state (_eg: caused by a failure event_).
|
|
||||||
|
|
||||||
[mail-state-folders]: https://github.com/docker-mailserver/docker-mailserver/blob/v13.3.1/target/scripts/startup/setup.d/mail_state.sh#L13-L33
|
|
||||||
|
|
||||||
### Logs Volume { #volumes-log }
|
|
||||||
|
|
||||||
This can be a useful volume to persist for troubleshooting needs for the full set of log files.
|
|
||||||
|
|
||||||
### Config Volume { #volumes-config }
|
|
||||||
|
|
||||||
Most configuration files for Postfix, Dovecot, etc. are persisted here.
|
|
||||||
|
|
||||||
This is a list of all configuration files and directories which are optional, automatically generated / updated by our `setup` CLI, or other internal scripts.
|
|
||||||
|
|
||||||
#### Directories
|
|
||||||
|
|
||||||
- **sieve-filter:** directory for sieve filter scripts. (Docs: [Sieve][docs-sieve])
|
|
||||||
- **sieve-pipe:** directory for sieve pipe scripts. (Docs: [Sieve][docs-sieve])
|
|
||||||
- **opendkim:** DKIM directory. Auto-configurable via [`setup.sh config dkim`][docs-setupsh]. (Docs: [DKIM][docs-dkim])
|
|
||||||
- **ssl:** SSL Certificate directory if `SSL_TYPE` is set to `self-signed` or `custom`. (Docs: [SSL][docs-ssl])
|
|
||||||
- **rspamd:** Override directory for custom settings when using Rspamd (Docs: [Rspamd][docs-rspamd-override-d])
|
|
||||||
|
|
||||||
#### Files
|
|
||||||
|
|
||||||
- **{user_email_address}.dovecot.sieve:** User specific Sieve filter file. (Docs: [Sieve][docs-sieve])
|
|
||||||
- **before.dovecot.sieve:** Global Sieve filter file, applied prior to the `${login}.dovecot.sieve` filter. (Docs: [Sieve][docs-sieve])
|
|
||||||
- **after.dovecot.sieve**: Global Sieve filter file, applied after the `${login}.dovecot.sieve` filter. (Docs: [Sieve][docs-sieve])
|
|
||||||
- **postfix-main.cf:** Every line will be added to the postfix main configuration. (Docs: [Override Postfix Defaults][docs-override-postfix])
|
|
||||||
- **postfix-master.cf:** Every line will be added to the postfix master configuration. (Docs: [Override Postfix Defaults][docs-override-postfix])
|
|
||||||
- **postfix-accounts.cf:** User accounts file. Modify via the [`setup.sh email`][docs-setupsh] script.
|
|
||||||
- **postfix-send-access.cf:** List of users denied sending. Modify via [`setup.sh email restrict`][docs-setupsh].
|
|
||||||
- **postfix-receive-access.cf:** List of users denied receiving. Modify via [`setup.sh email restrict`][docs-setupsh].
|
|
||||||
- **postfix-virtual.cf:** Alias configuration file. Modify via [`setup.sh alias`][docs-setupsh].
|
|
||||||
- **postfix-sasl-password.cf:** listing of relayed domains with their respective `<username>:<password>`. Modify via `setup.sh relay add-auth <domain> <username> [<password>]`. (Docs: [Relay-Hosts Auth][docs::relay-hosts::advanced])
|
|
||||||
- **postfix-relaymap.cf:** domain-specific relays and exclusions. Modify via `setup.sh relay add-domain` and `setup.sh relay exclude-domain`. (Docs: [Relay-Hosts Senders][docs::relay-hosts::advanced])
|
|
||||||
- **postfix-regexp.cf:** Regular expression alias file. (Docs: [Aliases][docs-aliases-regex])
|
|
||||||
- **ldap-users.cf:** Configuration for the virtual user mapping `virtual_mailbox_maps`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
|
|
||||||
- **ldap-groups.cf:** Configuration for the virtual alias mapping `virtual_alias_maps`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
|
|
||||||
- **ldap-aliases.cf:** Configuration for the virtual alias mapping `virtual_alias_maps`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
|
|
||||||
- **ldap-domains.cf:** Configuration for the virtual domain mapping `virtual_mailbox_domains`. See the [`setup-stack.sh`][github-commit-setup-stack.sh-L411] script.
|
|
||||||
- **whitelist_clients.local:** Whitelisted domains, not considered by postgrey. Enter one host or domain per line.
|
|
||||||
- **spamassassin-rules.cf:** Anti-spam rules for Spamassassin. (Docs: [FAQ - SpamAssassin Rules][docs-faq-spamrules])
|
|
||||||
- **fail2ban-fail2ban.cf:** Additional config options for `fail2ban.cf`. (Docs: [Fail2Ban][docs-fail2ban])
|
|
||||||
- **fail2ban-jail.cf:** Additional config options for fail2ban's jail behavior. (Docs: [Fail2Ban][docs-fail2ban])
|
|
||||||
- **amavis.cf:** replaces the `/etc/amavis/conf.d/50-user` file
|
|
||||||
- **dovecot.cf:** replaces `/etc/dovecot/local.conf`. (Docs: [Override Dovecot Defaults][docs-override-dovecot])
|
|
||||||
- **dovecot-quotas.cf:** list of custom quotas per mailbox. (Docs: [Accounts][docs-accounts-quota])
|
|
||||||
- **user-patches.sh:** this file will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started. (Docs: [FAQ - How to adjust settings with the `user-patches.sh` script][docs-faq-userpatches])
|
|
||||||
- **rspamd/custom-commands.conf:** list of simple commands to adjust Rspamd modules in an easy way (Docs: [Rspamd][docs-rspamd-commands])
|
|
||||||
|
|
||||||
[docker-docs::volumes]: https://docs.docker.com/storage/volumes/
|
|
||||||
[docker-docs::volumes::bind-mount]: https://docs.docker.com/storage/bind-mounts/
|
|
||||||
|
|
||||||
[docs-accounts-quota]: ../../config/account-management/provisioner/file.md#quotas
|
|
||||||
[docs-aliases-regex]: ../../config/account-management/provisioner/file.md#configuring-regex-aliases
|
|
||||||
[docs-dkim]: ../../config/best-practices/dkim_dmarc_spf.md#dkim
|
|
||||||
[docs-fail2ban]: ../../config/security/fail2ban.md
|
|
||||||
[docs-faq-spamrules]: ../../faq.md#how-can-i-manage-my-custom-spamassassin-rules
|
|
||||||
[docs-faq-userpatches]: ../../faq.md#how-to-adjust-settings-with-the-user-patchessh-script
|
|
||||||
[docs-override-postfix]: ./override-defaults/postfix.md
|
|
||||||
[docs-override-dovecot]: ./override-defaults/dovecot.md
|
|
||||||
[docs::relay-hosts::advanced]: ./mail-forwarding/relay-hosts.md#advanced-configuration
|
|
||||||
[docs-sieve]: ./mail-sieve.md
|
|
||||||
[docs-setupsh]: ../../config/setup.sh.md
|
|
||||||
[docs-ssl]: ../../config/security/ssl.md
|
|
||||||
[docs-rspamd-override-d]: ../security/rspamd.md#manually
|
|
||||||
[docs-rspamd-commands]: ../security/rspamd.md#with-the-help-of-a-custom-file
|
|
||||||
[github-commit-setup-stack.sh-L411]: https://github.com/docker-mailserver/docker-mailserver/blob/941e7acdaebe271eaf3d296b36d4d81df4c54b90/target/scripts/startup/setup-stack.sh#L411
|
|
||||||
|
|
@ -1,66 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Override the Default Configs | Dovecot'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Add Configuration
|
|
||||||
|
|
||||||
The Dovecot default configuration can easily be extended providing a `docker-data/dms/config/dovecot.cf` file.
|
|
||||||
[Dovecot documentation](https://doc.dovecot.org/configuration_manual/) remains the best place to find configuration options.
|
|
||||||
|
|
||||||
Your DMS folder structure should look like this example:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
├── docker-data/dms/config
|
|
||||||
│ ├── dovecot.cf
|
|
||||||
│ ├── postfix-accounts.cf
|
|
||||||
│ └── postfix-virtual.cf
|
|
||||||
├── compose.yaml
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
One common option to change is the maximum number of connections per user:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
mail_max_userip_connections = 100
|
|
||||||
```
|
|
||||||
|
|
||||||
Another important option is the `default_process_limit` (defaults to `100`). If high-security mode is enabled you'll need to make sure this count is higher than the maximum number of users that can be logged in simultaneously.
|
|
||||||
|
|
||||||
This limit is quickly reached if users connect to DMS with multiple end devices.
|
|
||||||
|
|
||||||
## Override Configuration
|
|
||||||
|
|
||||||
For major configuration changes it’s best to override the dovecot configuration files. For each configuration file you want to override, add a list entry under the `volumes` key.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/config/dovecot/10-master.conf:/etc/dovecot/conf.d/10-master.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
You will first need to obtain the configuration from the running container (_where `mailserver` is the container name_):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
mkdir -p ./docker-data/dms/config/dovecot
|
|
||||||
docker cp mailserver:/etc/dovecot/conf.d/10-master.conf ./docker-data/dms/config/dovecot/10-master.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
## Debugging
|
|
||||||
|
|
||||||
To debug your dovecot configuration you can use:
|
|
||||||
|
|
||||||
- This command: `./setup.sh debug login doveconf | grep <some-keyword>`
|
|
||||||
- Or: `docker exec -it mailserver doveconf | grep <some-keyword>`
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
[`setup.sh`][github-file-setupsh] is included in the DMS repository. Make sure to use the one matching your image version release.
|
|
||||||
|
|
||||||
The file `docker-data/dms/config/dovecot.cf` is copied internally to `/etc/dovecot/local.conf`. To verify the file content, run:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker exec -it mailserver cat /etc/dovecot/local.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh
|
|
||||||
|
|
@ -1,35 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Override the Default Configs | Postfix'
|
|
||||||
---
|
|
||||||
|
|
||||||
[Our default Postfix configuration](https://github.com/docker-mailserver/docker-mailserver/blob/master/target/postfix/main.cf) can easily be extended to add parameters or modify existing ones by providing a `docker-data/dms/config/postfix-main.cf`. This file uses the same format as Postfix `main.cf` does ([See official docs](http://www.postfix.org/postconf.5.html) for all parameters and syntax rules).
|
|
||||||
|
|
||||||
!!! example "Example"
|
|
||||||
|
|
||||||
One can easily increase the [backwards-compatibility level](http://www.postfix.org/postconf.5.html#compatibility_level) and set new Postscreen options:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
# increase the compatibility level from 2 (default) to 3
|
|
||||||
compatibility_level = 3
|
|
||||||
# set a threshold value for Spam detection
|
|
||||||
postscreen_dnsbl_threshold = 4
|
|
||||||
```
|
|
||||||
|
|
||||||
|
|
||||||
!!! help "How are your changes applied?"
|
|
||||||
|
|
||||||
The custom configuration you supply is appended to the default configuration located at `/etc/postfix/main.cf`, and then `postconf -nf` is run to remove earlier duplicate entries that have since been replaced. This happens early during container startup before Postfix is started.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Similarly, it is possible to add a custom `docker-data/dms/config/postfix-master.cf` file that will override the standard `master.cf`. **Note**: Each line in this file will be passed to `postconf -P`, i.e. **the file is not appended as a whole** to `/etc/postfix/master.cf` like `docker-data/dms/config/postfix-main.cf`! The expected format is `<service_name>/<type>/<parameter>`, for example:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
# adjust the submission "reject_unlisted_recipient" option
|
|
||||||
submission/inet/smtpd_reject_unlisted_recipient=no
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! attention
|
|
||||||
There should be no space between the parameter and the value.
|
|
||||||
|
|
||||||
Run `postconf -Mf` in the container without arguments to see the active master options.
|
|
||||||
|
|
@ -1,43 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Custom User Changes & Patches | Scripting'
|
|
||||||
---
|
|
||||||
|
|
||||||
If you'd like to change, patch or alter files or behavior of DMS, you can use a script.
|
|
||||||
|
|
||||||
In case you cloned this repository, you can copy the file [`user-patches.sh.dist` (_under `config/`_)][github-file-userpatches] with `#!sh cp config/user-patches.sh.dist docker-data/dms/config/user-patches.sh` in order to create the `user-patches.sh` script.
|
|
||||||
|
|
||||||
If you are managing your directory structure yourself, create a `docker-data/dms/config/` directory and add the `user-patches.sh` file yourself.
|
|
||||||
|
|
||||||
``` sh
|
|
||||||
# 1. Either create the docker-data/dms/config/ directory yourself
|
|
||||||
# or let docker-mailserver create it on initial startup
|
|
||||||
/tmp $ mkdir -p docker-data/dms/config/ && cd docker-data/dms/config/
|
|
||||||
|
|
||||||
# 2. Create the user-patches.sh file and edit it
|
|
||||||
/tmp/docker-data/dms/config $ touch user-patches.sh
|
|
||||||
/tmp/docker-data/dms/config $ nano user-patches.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
The contents could look like this:
|
|
||||||
|
|
||||||
``` sh
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
cat >/etc/amavis/conf.d/50-user << "END"
|
|
||||||
use strict;
|
|
||||||
|
|
||||||
$undecipherable_subject_tag = undef;
|
|
||||||
$admin_maps_by_ccat{+CC_UNCHECKED} = undef;
|
|
||||||
|
|
||||||
#------------ Do not modify anything below this line -------------
|
|
||||||
1; # ensure a defined return
|
|
||||||
END
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
And you're done. The user patches script runs right before starting daemons. That means, all the other configuration is in place, so the script can make final adjustments.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
Many "patches" can already be done with the Docker Compose-/Stack-file. Adding hostnames to `/etc/hosts` is done with the `#!yaml extra_hosts:` section, `sysctl` commands can be managed with the `#!yaml sysctls:` section, etc.
|
|
||||||
|
|
||||||
[github-file-userpatches]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/user-patches.sh
|
|
||||||
|
|
@ -1,177 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | Podman'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
Podman is a daemonless container engine for developing, managing, and running OCI Containers on your Linux System.
|
|
||||||
|
|
||||||
!!! warning "About Support for Podman"
|
|
||||||
|
|
||||||
Please note that Podman **is not** officially supported as DMS is built and verified on top of the _Docker Engine_. This content is entirely community supported. If you find errors, please open an issue and provide a PR.
|
|
||||||
|
|
||||||
!!! warning "About this Guide"
|
|
||||||
|
|
||||||
This guide was tested with Fedora 34 using `systemd` and `firewalld`. Moreover, it requires Podman version >= 3.2. You may be able to substitute `dnf` - Fedora's package manager - with others such as `apt`.
|
|
||||||
|
|
||||||
!!! warning "About Security"
|
|
||||||
|
|
||||||
Running podman in rootless mode requires additional modifications in order to keep your mailserver secure.
|
|
||||||
Make sure to read the related documentation.
|
|
||||||
|
|
||||||
## Installation in Rootfull Mode
|
|
||||||
|
|
||||||
While using Podman, you can just manage docker-mailserver as what you did with Docker. Your best friend `setup.sh` includes the minimum code in order to support Podman since it's 100% compatible with the Docker CLI.
|
|
||||||
|
|
||||||
The installation is basically the same. Podman v3.2 introduced a RESTful API that is 100% compatible with the Docker API, so you can use Docker Compose with Podman easily. Install Podman and Docker Compose with your package manager first.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
sudo dnf install podman docker-compose
|
|
||||||
```
|
|
||||||
|
|
||||||
Then enable `podman.socket` using `systemctl`.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
systemctl enable --now podman.socket
|
|
||||||
```
|
|
||||||
|
|
||||||
This will create a unix socket locate under `/run/podman/podman.sock`, which is the entrypoint of Podman's API. Now, configure docker-mailserver and start it.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export DOCKER_HOST="unix:///run/podman/podman.sock"
|
|
||||||
docker compose up -d mailserver
|
|
||||||
docker compose ps
|
|
||||||
```
|
|
||||||
|
|
||||||
You should see that docker-mailserver is running now.
|
|
||||||
|
|
||||||
### Self-start in Rootfull Mode
|
|
||||||
|
|
||||||
Podman is daemonless, that means if you want docker-mailserver self-start while boot up the system, you have to generate a systemd file with Podman CLI.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
podman generate systemd mailserver > /etc/systemd/system/mailserver.service
|
|
||||||
systemctl daemon-reload
|
|
||||||
systemctl enable --now mailserver.service
|
|
||||||
```
|
|
||||||
|
|
||||||
## Installation in Rootless Mode
|
|
||||||
|
|
||||||
Running rootless containers is one of Podman's major features. But due to some restrictions, deploying docker-mailserver in rootless mode is not as easy compared to rootfull mode.
|
|
||||||
|
|
||||||
- a rootless container is running in a user namespace so you cannot bind ports lower than 1024
|
|
||||||
- a rootless container's systemd file can only be placed in folder under `~/.config`
|
|
||||||
- a rootless container can result in an open relay, make sure to read the [security section](#security-in-rootless-mode).
|
|
||||||
|
|
||||||
Also notice that Podman's rootless mode is not about running as a non-root user inside the container, but about the mapping of (normal, non-root) host users to root inside the container.
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
In order to make rootless DMS work we must modify some settings in the Linux system, it requires some basic linux server knowledge so don't follow this guide if you not sure what this guide is talking about. Podman rootfull mode and Docker are still good and security enough for normal daily usage.
|
|
||||||
|
|
||||||
First, enable `podman.socket` in systemd's userspace with a non-root user.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
systemctl enable --now --user podman.socket
|
|
||||||
```
|
|
||||||
|
|
||||||
The socket file should be located at `/var/run/user/$(id -u)/podman/podman.sock`. Then, modify `compose.yaml` to make sure all ports are bindings are on non-privileged ports.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
ports:
|
|
||||||
- "10025:25" # SMTP (explicit TLS => STARTTLS)
|
|
||||||
- "10143:143" # IMAP4 (explicit TLS => STARTTLS)
|
|
||||||
- "10465:465" # ESMTP (implicit TLS)
|
|
||||||
- "10587:587" # ESMTP (explicit TLS => STARTTLS)
|
|
||||||
- "10993:993" # IMAP4 (implicit TLS)
|
|
||||||
```
|
|
||||||
|
|
||||||
Then, setup your `mailserver.env` file follow the documentation and use Docker Compose to start the container.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
export DOCKER_HOST="unix:///var/run/user/$(id -u)/podman/podman.sock"
|
|
||||||
docker compose up -d mailserver
|
|
||||||
docker compose ps
|
|
||||||
```
|
|
||||||
|
|
||||||
### Security in Rootless Mode
|
|
||||||
|
|
||||||
In rootless mode, podman resolves all incoming IPs as localhost, which results in an open gateway in the default configuration. There are two workarounds to fix this problem, both of which have their own drawbacks.
|
|
||||||
|
|
||||||
#### Enforce authentication from localhost
|
|
||||||
|
|
||||||
The `PERMIT_DOCKER` variable in the `mailserver.env` file allows to specify trusted networks that do not need to authenticate. If the variable is left empty, only requests from localhost and the container IP are allowed, but in the case of rootless podman any IP will be resolved as localhost. Setting `PERMIT_DOCKER=none` enforces authentication also from localhost, which prevents sending unauthenticated emails.
|
|
||||||
|
|
||||||
#### Use the slip4netns network driver
|
|
||||||
|
|
||||||
The second workaround is slightly more complicated because the `compose.yaml` has to be modified.
|
|
||||||
As shown in the [fail2ban section][docs::fail2ban::rootless] the `slirp4netns` network driver has to be enabled.
|
|
||||||
This network driver enables podman to correctly resolve IP addresses but it is not compatible with
|
|
||||||
user defined networks which might be a problem depending on your setup.
|
|
||||||
|
|
||||||
[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yaml`.
|
|
||||||
|
|
||||||
You must also add the ENV `NETWORK_INTERFACE=tap0`, because Podman uses a [hard-coded interface name][rootless::podman::interface] for `slirp4netns`.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
network_mode: "slirp4netns:port_handler=slirp4netns"
|
|
||||||
environment:
|
|
||||||
- NETWORK_INTERFACE=tap0
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
`podman-compose` is not compatible with this configuration.
|
|
||||||
|
|
||||||
### Self-start in Rootless Mode
|
|
||||||
|
|
||||||
Generate a systemd file with the Podman CLI.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
podman generate systemd mailserver > ~/.config/systemd/user/mailserver.service
|
|
||||||
systemctl --user daemon-reload
|
|
||||||
systemctl enable --user --now mailserver.service
|
|
||||||
```
|
|
||||||
|
|
||||||
Systemd's user space service is only started when a specific user logs in and stops when you log out. In order to make it to start with the system, we need to enable linger with `loginctl`
|
|
||||||
|
|
||||||
```bash
|
|
||||||
loginctl enable-linger <username>
|
|
||||||
```
|
|
||||||
|
|
||||||
Remember to run this command as root user.
|
|
||||||
|
|
||||||
### Port Forwarding
|
|
||||||
|
|
||||||
When it comes to forwarding ports using `firewalld`, see [these port forwarding docs][firewalld-port-forwarding] for more information.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
firewall-cmd --permanent --add-forward-port=port=<25|143|465|587|993>:proto=<tcp>:toport=<10025|10143|10465|10587|10993>
|
|
||||||
...
|
|
||||||
|
|
||||||
# After you set all ports up.
|
|
||||||
firewall-cmd --reload
|
|
||||||
```
|
|
||||||
|
|
||||||
Notice that this will only open the access to the external client. If you want to access privileges port in your server, do this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
firewall-cmd --permanent --direct --add-rule <ipv4|ipv6> nat OUTPUT 0 -p <tcp|udp> -o lo --dport <25|143|465|587|993> -j REDIRECT --to-ports <10025|10143|10465|10587|10993>
|
|
||||||
...
|
|
||||||
# After you set all ports up.
|
|
||||||
firewall-cmd --reload
|
|
||||||
```
|
|
||||||
|
|
||||||
Just map all the privilege port with non-privilege port you set in compose.yaml before as root user.
|
|
||||||
|
|
||||||
[docs::fail2ban::rootless]: ../security/fail2ban.md#rootless-container
|
|
||||||
[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
|
|
||||||
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264
|
|
||||||
[firewalld-port-forwarding]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/securing_networks/using-and-configuring-firewalld_securing-networks#port-forwarding_using-and-configuring-firewalld
|
|
||||||
|
|
@ -1,13 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Best Practices | Auto-discovery'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
# Auto-Discovery of Services
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
@ -1,385 +0,0 @@
|
||||||
# DKIM, DMARC & SPF
|
|
||||||
|
|
||||||
Cloudflare has written an [article about DKIM, DMARC and SPF][cloudflare-dkim-dmarc-spf] that we highly recommend you to read to get acquainted with the topic.
|
|
||||||
|
|
||||||
!!! note "Rspamd vs Individual validators"
|
|
||||||
|
|
||||||
With v12.0.0, Rspamd was integrated into DMS. It can perform validations for DKIM, DMARC and SPF as part of the `spam-score-calculation` for an email. DMS provides individual alternatives for each validation that can be used instead of deferring to Rspamd:
|
|
||||||
|
|
||||||
- DKIM: `opendkim` is used as a milter (like Rspamd)
|
|
||||||
- DMARC: `opendmarc` is used as a milter (like Rspamd)
|
|
||||||
- SPF: `policyd-spf` is used in Postfix's `smtpd_recipient_restrictions`
|
|
||||||
|
|
||||||
In a future release Rspamd will become the default for these validations, with a deprecation notice issued prior to the removal of the above alternatives.
|
|
||||||
|
|
||||||
We encourage everyone to prefer Rspamd via `ENABLE_RSPAMD=1`.
|
|
||||||
|
|
||||||
!!! warning "DNS Caches & Propagation"
|
|
||||||
|
|
||||||
While modern DNS providers are quick, it may take minutes or even hours for new DNS records to become available / propagate.
|
|
||||||
|
|
||||||
## DKIM
|
|
||||||
|
|
||||||
!!! quote "What is DKIM"
|
|
||||||
|
|
||||||
DomainKeys Identified Mail (DKIM) is an email authentication method designed to detect forged sender addresses in email (email spoofing), a technique often used in phishing and email spam.
|
|
||||||
|
|
||||||
[Source][wikipedia-dkim]
|
|
||||||
|
|
||||||
When DKIM is enabled:
|
|
||||||
|
|
||||||
1. Inbound mail will verify any included DKIM signatures
|
|
||||||
2. Outbound mail is signed (_when your sending domain has a configured DKIM key_)
|
|
||||||
|
|
||||||
DKIM requires a public/private key pair to enable **signing (_via private key_)** your outgoing mail, while the receiving end must query DNS to **verify (_via public key_)** that the signature is trustworthy.
|
|
||||||
|
|
||||||
??? info "Verification expiry"
|
|
||||||
|
|
||||||
Unlike your TLS certificate, your DKIM keypair does not have a fixed expiry associated to it.
|
|
||||||
|
|
||||||
|
|
||||||
Instead, an expiry may be included in your DKIM signature for each mail sent, where a receiver will [refuse to validate the signature for an email after that expiry date][dkim-verification-expiry-refusal]. This is an added precaution to mitigate malicious activity like "DKIM replay attacks", where an already delivered email from a third-party with a trustworthy DKIM signature is leveraged by a spammer when sending mail to an MTA which verifies the DKIM signature successfully, enabling the spammer to bypass spam protections.
|
|
||||||
|
|
||||||
Unlike a TLS handshake where you are authenticating trust with future communications, with DKIM once the mail has been received and trust of the signature has been verified, the value of verifying the signature again at a later date is less meaningful since the signature was to ensure no tampering had occurred during delivery through the network.
|
|
||||||
|
|
||||||
??? tip "DKIM key rotation"
|
|
||||||
|
|
||||||
You can rotate your DKIM keypair by switching to a new DKIM selector (_and DNS updates_), while the previous key and selector remains valid for verification until the last mail signed with that key reaches it's expiry.
|
|
||||||
|
|
||||||
DMS does not provide any automation or support for key rotation, [nor is it likely to provide a notable security benefit][gh-discussion::dkim-key-rotation-expiry] to the typical small scale DMS deployment.
|
|
||||||
|
|
||||||
### Generating Keys
|
|
||||||
|
|
||||||
You'll need to repeat this process if you add any new domains.
|
|
||||||
|
|
||||||
You should have:
|
|
||||||
|
|
||||||
- At least one [email account setup][docs-accounts]
|
|
||||||
- Attached a [volume for config][docs-volumes-config] to persist the generated files to local storage
|
|
||||||
|
|
||||||
!!! example "Creating DKIM Keys"
|
|
||||||
|
|
||||||
DKIM keys can be generated with good defaults by running:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec -it <CONTAINER NAME> setup config dkim
|
|
||||||
```
|
|
||||||
|
|
||||||
If you need to generate your keys with different settings, check the `help` output for supported config options and examples:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec -it <CONTAINER NAME> setup config dkim help
|
|
||||||
```
|
|
||||||
|
|
||||||
As described by the help output, you may need to use the `domain` option explicitly when you're using LDAP or Rspamd.
|
|
||||||
|
|
||||||
??? info "Changing the key size"
|
|
||||||
|
|
||||||
The keypair generated for using with DKIM presently defaults to RSA-2048. This is a good size but you can lower the security to `1024-bit`, or increase it to `4096-bit` (_discouraged as that is excessive_).
|
|
||||||
|
|
||||||
To generate a key with different size (_for RSA 1024-bit_) run:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
setup config dkim keysize 1024
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "RSA Key Sizes >= 4096 Bit"
|
|
||||||
|
|
||||||
According to [RFC 8301][rfc-8301], keys are preferably between 1024 and 2048 bits. Keys of size 4096-bit or larger may not be compatible to all systems your mail is intended for.
|
|
||||||
|
|
||||||
You [should not need a key length beyond 2048-bit][gh-issue::dkim-length]. If 2048-bit does not meet your security needs, you may want to instead consider adopting key rotation or switching from RSA to ECC keys for DKIM.
|
|
||||||
|
|
||||||
??? note "You may need to specify mail domains explicitly"
|
|
||||||
|
|
||||||
Required when using LDAP and Rspamd.
|
|
||||||
|
|
||||||
`setup config dkim` will generate DKIM keys for what is assumed as the primary mail domain (_derived from the FQDN assigned to DMS, minus any subdomain_).
|
|
||||||
|
|
||||||
When the DMS FQDN is `mail.example.com` or `example.com`, by default this command will generate DKIM keys for `example.com` as the primary domain for your users mail accounts (eg: `hello@example.com`).
|
|
||||||
|
|
||||||
The DKIM generation does not have support to query LDAP for additional mail domains it should know about. If the primary mail domain is not sufficient, then you must explicitly specify any extra domains via the `domain` option:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# ENABLE_OPENDKIM=1 (default):
|
|
||||||
setup config dkim domain 'example.com,another-example.com'
|
|
||||||
|
|
||||||
# ENABLE_RSPAMD=1 + ENABLE_OPENDKIM=0:
|
|
||||||
setup config dkim domain example.com
|
|
||||||
setup config dkim domain another-example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! info "OpenDKIM with `ACCOUNT_PROVISIONER=FILE`"
|
|
||||||
|
|
||||||
When DMS uses this configuration, it will by default also detect mail domains (_from accounts added via `setup email add`_), generating additional DKIM keys.
|
|
||||||
|
|
||||||
DKIM is currently supported by either OpenDKIM or Rspamd:
|
|
||||||
|
|
||||||
=== "OpenDKIM"
|
|
||||||
|
|
||||||
OpenDKIM is currently [enabled by default][docs-env-opendkim].
|
|
||||||
|
|
||||||
After running `setup config dkim`, your new DKIM key files (_and OpenDKIM config_) have been added to `/tmp/docker-mailserver/opendkim/`.
|
|
||||||
|
|
||||||
!!! info "Restart required"
|
|
||||||
|
|
||||||
After restarting DMS, outgoing mail will now be signed with your new DKIM key(s) :tada:
|
|
||||||
|
|
||||||
=== "Rspamd"
|
|
||||||
|
|
||||||
Requires opt-in via [`ENABLE_RSPAMD=1`][docs-env-rspamd] (_and disable the default OpenDKIM: `ENABLE_OPENDKIM=0`_).
|
|
||||||
|
|
||||||
Rspamd provides DKIM support through two separate modules:
|
|
||||||
|
|
||||||
1. [Verifying DKIM signatures from inbound mail][rspamd-docs-dkim-checks] is enabled by default.
|
|
||||||
2. [Signing outbound mail with your DKIM key][rspamd-docs-dkim-signing] needs additional setup (key + dns + config).
|
|
||||||
|
|
||||||
??? warning "Using Multiple Domains"
|
|
||||||
|
|
||||||
If you have multiple domains, you need to:
|
|
||||||
|
|
||||||
- Create a key wth `docker exec -it <CONTAINER NAME> setup config dkim domain <DOMAIN>` for each domain DMS should sign outgoing mail for.
|
|
||||||
- Provide a custom `dkim_signing.conf` (for which an example is shown below), as the default config only supports one domain.
|
|
||||||
|
|
||||||
!!! info "About the Helper Script"
|
|
||||||
|
|
||||||
The script will persist the keys in `/tmp/docker-mailserver/rspamd/dkim/`. Hence, if you are already using the default volume mounts, the keys are persisted in a volume. The script also restarts Rspamd directly, so changes take effect without restarting DMS.
|
|
||||||
|
|
||||||
The script provides you with log messages along the way of creating keys. In case you want to read the complete log, use `-v` (verbose) or `-vv` (very verbose).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
In case you have not already provided a default DKIM signing configuration, the script will create one and write it to `/etc/rspamd/override.d/dkim_signing.conf`. If this file already exists, it will not be overwritten.
|
|
||||||
|
|
||||||
When you're already using [the `rspamd/override.d/` directory][docs-rspamd-config-dropin], the file is created inside your volume and therefore persisted correctly. If you are not using `rspamd/override.d/`, you will need to persist the file yourself (otherwise it is lost on container restart).
|
|
||||||
|
|
||||||
An example of what a default configuration file for DKIM signing looks like can be found by expanding the example below.
|
|
||||||
|
|
||||||
??? example "DKIM Signing Module Configuration Examples"
|
|
||||||
|
|
||||||
A simple configuration could look like this:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
# documentation: https://rspamd.com/doc/modules/dkim_signing.html
|
|
||||||
|
|
||||||
enabled = true;
|
|
||||||
|
|
||||||
sign_authenticated = true;
|
|
||||||
sign_local = true;
|
|
||||||
|
|
||||||
use_domain = "header";
|
|
||||||
use_redis = false; # don't change unless Redis also provides the DKIM keys
|
|
||||||
use_esld = true;
|
|
||||||
check_pubkey = true; # you want to use this in the beginning
|
|
||||||
|
|
||||||
selector = "mail";
|
|
||||||
# The path location is searched for a DKIM key with these variables:
|
|
||||||
# - `$domain` is sourced from the MIME mail message `From` header
|
|
||||||
# - `$selector` is configured for `mail` (as a default fallback)
|
|
||||||
path = "/tmp/docker-mailserver/dkim/keys/$domain/$selector.private";
|
|
||||||
|
|
||||||
# domain specific configurations can be provided below:
|
|
||||||
domain {
|
|
||||||
example.com {
|
|
||||||
path = "/tmp/docker-mailserver/rspamd/dkim/mail.private";
|
|
||||||
selector = "mail";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
As shown next:
|
|
||||||
|
|
||||||
- You can add more domains into the `domain { ... }` section (in the following example: `example.com` and `example.org`).
|
|
||||||
- A domain can also be configured with multiple selectors and keys within a `selectors [ ... ]` array (in the following example, this is done for `example.org`).
|
|
||||||
|
|
||||||
```cf
|
|
||||||
# ...
|
|
||||||
|
|
||||||
domain {
|
|
||||||
example.com {
|
|
||||||
path = /tmp/docker-mailserver/rspamd/example.com/ed25519.private";
|
|
||||||
selector = "dkim-ed25519";
|
|
||||||
}
|
|
||||||
example.org {
|
|
||||||
selectors [
|
|
||||||
{
|
|
||||||
path = "/tmp/docker-mailserver/rspamd/dkim/example.org/rsa.private";
|
|
||||||
selector = "dkim-rsa";
|
|
||||||
},
|
|
||||||
{
|
|
||||||
path = "/tmp/docker-mailserver/rspamd/dkim/example.org/ed25519.private";
|
|
||||||
selector = "dkim-ed25519";
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
??? warning "Support for DKIM Keys using ED25519"
|
|
||||||
|
|
||||||
This modern elliptic curve is supported by Rspamd, but support by third-parties for [verifying Ed25519 DKIM signatures is unreliable][dkim-ed25519-support].
|
|
||||||
|
|
||||||
If you sign your mail with this key type, you should include RSA as a fallback, like shown in the above example.
|
|
||||||
|
|
||||||
??? tip "Let Rspamd Check Your Keys"
|
|
||||||
|
|
||||||
When `check_pubkey = true;` is set, Rspamd will query the DNS record for each DKIM selector, verifying each public key matches the private key configured.
|
|
||||||
|
|
||||||
If there is a mismatch, a warning will be emitted to the Rspamd log `/var/log/mail/rspamd.log`.
|
|
||||||
|
|
||||||
### DNS Record { #dkim-dns }
|
|
||||||
|
|
||||||
When mail signed with your DKIM key is sent from your mail server, the receiver needs to check a DNS `TXT` record to verify the DKIM signature is trustworthy.
|
|
||||||
|
|
||||||
!!! example "Configuring DNS - DKIM record"
|
|
||||||
|
|
||||||
When you generated your key in the previous step, the DNS data was saved into a file `<selector>.txt` (default: `mail.txt`). Use this content to update your [DNS via Web Interface][dns::example-webui] or directly edit your [DNS Zone file][dns::wikipedia-zonefile]:
|
|
||||||
|
|
||||||
=== "Web Interface"
|
|
||||||
|
|
||||||
Create a new record:
|
|
||||||
|
|
||||||
| Field | Value |
|
|
||||||
| ----- | ------------------------------------------------------------------------------ |
|
|
||||||
| Type | `TXT` |
|
|
||||||
| Name | `<selector>._domainkey` (_default: `mail._domainkey`_) |
|
|
||||||
| TTL | Use the default (_otherwise [3600 seconds is appropriate][dns::digicert-ttl]_) |
|
|
||||||
| Data | File content within `( ... )` (_formatted as advised below_) |
|
|
||||||
|
|
||||||
When using Rspamd, the helper script has already provided you with the contents (the "Data" field) of the DNS record you need to create - you can just copy-paste this text.
|
|
||||||
|
|
||||||
=== "DNS Zone file"
|
|
||||||
|
|
||||||
`<selector>.txt` is already formatted as a snippet for adding to your [DNS Zone file][dns::wikipedia-zonefile].
|
|
||||||
|
|
||||||
Just copy/paste the file contents into your existing DNS zone. The `TXT` value has been split into separate strings every 255 characters for compatibility.
|
|
||||||
|
|
||||||
??? info "`<selector>.txt` - Formatting the `TXT` record value correctly"
|
|
||||||
|
|
||||||
This file was generated for use within a [DNS zone file][dns::wikipedia-zonefile]. The file name uses the DKIM selector it was generated with (default DKIM selector is `mail`, which creates `mail.txt`_).
|
|
||||||
|
|
||||||
For your DNS setup, DKIM support needs to create a `TXT` record to store the public key for mail clients to use. `TXT` records with values that are longer than 255 characters need to be split into multiple parts. This is why the generated `<selector>.txt` file (_containing your public key for use with DKIM_) has multiple value parts wrapped within double-quotes between `(` and `)`.
|
|
||||||
|
|
||||||
A DNS web-interface may handle this separation internally instead, and [could expect the value provided all as a single line][dns::webui-dkim] instead of split. When that is required, you'll need to manually format the value as described below.
|
|
||||||
|
|
||||||
Your generated DNS record file (`<selector>.txt`) should look similar to this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
mail._domainkey IN TXT ( "v=DKIM1; k=rsa; "
|
|
||||||
"p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ"
|
|
||||||
"5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB"
|
|
||||||
) ;
|
|
||||||
```
|
|
||||||
|
|
||||||
Take the content between `( ... )`, and combine all the quote wrapped content and remove the double-quotes including the white-space between them. That is your `TXT` record value, the above example would become this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB
|
|
||||||
```
|
|
||||||
|
|
||||||
To test that your new DKIM record is correct, query it with the `dig` command. The `TXT` value response should be a single line split into multiple parts wrapped in double-quotes:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ dig +short TXT mail._domainkey.example.com
|
|
||||||
"v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqQMMqhb1S52Rg7VFS3EC6JQIMxNDdiBmOKZvY5fiVtD3Z+yd9ZV+V8e4IARVoMXWcJWSR6xkloitzfrRtJRwOYvmrcgugOalkmM0V4Gy/2aXeamuiBuUc4esDQEI3egmtAsHcVY1XCoYfs+9VqoHEq3vdr3UQ8zP/l+FP5UfcaJFCK/ZllqcO2P1GjIDVSHLdPpRHbMP/tU1a9mNZ5QMZBJ/JuJK/s+2bp8gpxKn8rh1akSQjlynlV9NI+7J3CC7CUf3bGvoXIrb37C/lpJehS39" "KNtcGdaRufKauSfqx/7SxA0zyZC+r13f7ASbMaQFzm+/RRusTqozY/p/MsWx8QIDAQAB"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Troubleshooting { #dkim-debug }
|
|
||||||
|
|
||||||
[MxToolbox has a DKIM Verifier][mxtoolbox-dkim-verifier] that you can use to check your DKIM DNS record(s).
|
|
||||||
|
|
||||||
When using Rspamd, we recommend you turn on `check_pubkey = true;` in `dkim_signing.conf`. Rspamd will then check whether your private key matches your public key, and you can check possible mismatches by looking at `/var/log/mail/rspamd.log`.
|
|
||||||
|
|
||||||
## DMARC
|
|
||||||
|
|
||||||
With DMS, DMARC is pre-configured out of the box. You may disable extra and excessive DMARC checks when using Rspamd via `ENABLE_OPENDMARC=0`.
|
|
||||||
|
|
||||||
The only thing you need to do in order to enable DMARC on a "DNS-level" is to add new `TXT`. In contrast to [DKIM](#dkim), DMARC DNS entries do 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:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
_dmarc.example.com. IN TXT "v=DMARC1; p=none; sp=none; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
Or a bit more strict policies (_mind `p=quarantine` and `sp=quarantine`_):
|
|
||||||
|
|
||||||
```txt
|
|
||||||
_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; sp=quarantine; fo=0; adkim=r; aspf=r; pct=100; rf=afrf; ri=86400; rua=mailto:dmarc.report@example.com; ruf=mailto:dmarc.report@example.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
The DMARC status may not be displayed instantly due to delays in DNS (caches). Dmarcian has [a few tools][dmarcian-tools] you can use to verify your DNS records.
|
|
||||||
|
|
||||||
## SPF
|
|
||||||
|
|
||||||
!!! quote "What is SPF"
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
[Source][wikipedia-spf]
|
|
||||||
|
|
||||||
!!! tip "Disabling the default SPF service `policy-spf`"
|
|
||||||
|
|
||||||
Set [`ENABLE_POLICYD_SPF=0`][docs-env-spf-policyd] to opt-out of the default SPF service. Advised when Rspamd is configured to handle SPF instead.
|
|
||||||
|
|
||||||
### Adding an SPF Record
|
|
||||||
|
|
||||||
To add a SPF record in your DNS, insert the following line in your DNS zone:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
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. _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.
|
|
||||||
|
|
||||||
In any case, increment the SPF record's TTL to its final value.
|
|
||||||
|
|
||||||
### Backup MX & Secondary MX for `policyd-spf`
|
|
||||||
|
|
||||||
For whitelisting an 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 at `docker-data/dms/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
|
|
||||||
|
|
||||||
# Preferably use IP-Addresses for whitelist lookups:
|
|
||||||
Whitelist = 192.168.0.0/31,192.168.1.0/30
|
|
||||||
# Domain_Whitelist = mx1.not-example.com,mx2.not-example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
Then add this line to `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/config/postfix-policyd-spf.conf:/etc/postfix-policyd-spf-python/policyd-spf.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
[docs-accounts]: ../account-management/overview.md#accounts
|
|
||||||
[docs-volumes-config]: ../advanced/optional-config.md#volumes-config
|
|
||||||
[docs-env-opendkim]: ../environment.md#enable_opendkim
|
|
||||||
[docs-env-rspamd]: ../environment.md#enable_rspamd
|
|
||||||
[docs-env-spf-policyd]: ../environment.md#enable_policyd_spf
|
|
||||||
[docs-rspamd-config-dropin]: ../security/rspamd.md#manually
|
|
||||||
[cloudflare-dkim-dmarc-spf]: https://www.cloudflare.com/learning/email-security/dmarc-dkim-spf/
|
|
||||||
[rfc-8301]: https://datatracker.ietf.org/doc/html/rfc8301#section-3.2
|
|
||||||
[gh-discussion::dkim-key-rotation-expiry]: https://github.com/orgs/docker-mailserver/discussions/4068#discussioncomment-9784263
|
|
||||||
[gh-issue::dkim-length]: https://github.com/docker-mailserver/docker-mailserver/issues/1854#issuecomment-806280929
|
|
||||||
[rspamd-docs-dkim-checks]: https://www.rspamd.com/doc/modules/dkim.html
|
|
||||||
[rspamd-docs-dkim-signing]: https://www.rspamd.com/doc/modules/dkim_signing.html
|
|
||||||
[dns::example-webui]: https://www.vultr.com/docs/introduction-to-vultr-dns/
|
|
||||||
[dns::digicert-ttl]: https://www.digicert.com/faq/dns/what-is-ttl
|
|
||||||
[dns::wikipedia-zonefile]: https://en.wikipedia.org/wiki/Zone_file
|
|
||||||
[dns::webui-dkim]: https://serverfault.com/questions/763815/route-53-doesnt-allow-adding-dkim-keys-because-length-is-too-long
|
|
||||||
[dkim-ed25519-support]: https://serverfault.com/questions/1023674/is-ed25519-well-supported-for-the-dkim-validation/1074545#1074545
|
|
||||||
[dkim-verification-expiry-refusal]: https://mxtoolbox.com/problem/dkim/dkim-signature-expiration
|
|
||||||
[mxtoolbox-dkim-verifier]: https://mxtoolbox.com/dkim.aspx
|
|
||||||
[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
|
|
||||||
[dmarcian-tools]: https://dmarcian.com/dmarc-tools/
|
|
||||||
[wikipedia-dkim]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail
|
|
||||||
[wikipedia-spf]: https://en.wikipedia.org/wiki/Sender_Policy_Framework
|
|
||||||
|
|
@ -1,30 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Best practices | MTA-STS'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
MTA-STS is an optional mechanism for a domain to signal support for STARTTLS.
|
|
||||||
|
|
||||||
- It can be used to prevent man-in-the-middle-attacks from hiding STARTTLS support that would force DMS to send outbound mail through an insecure connection.
|
|
||||||
- MTA-STS is an alternative to DANE without the need of DNSSEC.
|
|
||||||
- MTA-STS is supported by some of the biggest mail providers like Google Mail and Outlook.
|
|
||||||
|
|
||||||
## Supporting MTA-STS for outbound mail
|
|
||||||
|
|
||||||
Enable this feature via the ENV setting [`ENABLE_MTA_STS=1`](../environment.md#enable_mta_sts).
|
|
||||||
|
|
||||||
!!! warning "If you have configured DANE"
|
|
||||||
|
|
||||||
Enabling MTA-STS will by default override DANE if both are configured for a domain.
|
|
||||||
|
|
||||||
This can be partially addressed by configuring a dane-only policy resolver before the MTA-STS entry in `smtp_tls_policy_maps`. See the [`postfix-mta-sts-resolver` documentation][postfix-mta-sts-resolver::dane] for further details.
|
|
||||||
|
|
||||||
[postfix-mta-sts-resolver::dane]: https://github.com/Snawoot/postfix-mta-sts-resolver#warning-mta-sts-policy-overrides-dane-tls-authentication
|
|
||||||
|
|
||||||
## Supporting MTA-STS for inbound mail
|
|
||||||
|
|
||||||
While this feature in DMS supports ensuring STARTTLS is used when mail is sent to another mail server, you may setup similar for mail servers sending mail to DMS.
|
|
||||||
|
|
||||||
This requires configuring your DNS and hosting the MTA-STS policy file via a webserver. A good introduction can be found on [dmarcian.com](https://dmarcian.com/mta-sts/).
|
|
||||||
|
|
||||||
|
|
@ -1,137 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Debugging'
|
|
||||||
hide:
|
|
||||||
- toc
|
|
||||||
---
|
|
||||||
|
|
||||||
This page contains valuable information when it comes to resolving issues you encounter.
|
|
||||||
|
|
||||||
!!! info "Contributions Welcome!"
|
|
||||||
|
|
||||||
Please consider contributing solutions to the [FAQ][docs-faq] :heart:
|
|
||||||
|
|
||||||
## Preliminary Checks
|
|
||||||
|
|
||||||
- Check that all published DMS ports are actually open and not blocked by your ISP / hosting provider.
|
|
||||||
- SSL errors are likely the result of a wrong setup on the user side and not caused by DMS itself.
|
|
||||||
- Ensure that you have correctly started DMS. Many problems related to configuration are due to this.
|
|
||||||
|
|
||||||
!!! danger "Correctly starting DMS"
|
|
||||||
|
|
||||||
Use the [`--force-recreate`][docker-docs::force-recreate] option to avoid configuration mishaps: `docker compose up --force-recreate`
|
|
||||||
|
|
||||||
Alternatively, always use `docker compose down` to stop DMS. **Do not** rely on `CTRL + C`, `docker compose stop`, or `docker compose restart`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
DMS setup scripts are run when a container starts, but may fail to work properly if you do the following:
|
|
||||||
|
|
||||||
- Stopping a container with commands like: `docker stop` or `docker compose up` stopped via `CTRL + C` instead of `docker compose down`.
|
|
||||||
- Restarting a container.
|
|
||||||
|
|
||||||
Volumes persist data across container instances, however the same container instance will keep internal changes not stored in a volume until the container is removed.
|
|
||||||
|
|
||||||
Due to this, DMS setup scripts may modify configuration it has already modified in the past.
|
|
||||||
|
|
||||||
- This is brittle as some changes are naive by assuming they are applied to the original configs from the image.
|
|
||||||
- Volumes in `compose.yaml` are expected to persist any important data. Thus it should be safe to throwaway the container created each time, avoiding this config problem.
|
|
||||||
|
|
||||||
### Mail sent from DMS does not arrive at destination
|
|
||||||
|
|
||||||
Some service providers block outbound traffic on port 25. Common hosting providers known to have this issue:
|
|
||||||
|
|
||||||
- [Azure](https://docs.microsoft.com/en-us/azure/virtual-network/troubleshoot-outbound-smtp-connectivity)
|
|
||||||
- [AWS EC2](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-port-25-throttle/)
|
|
||||||
- [Vultr](https://www.vultr.com/docs/what-ports-are-blocked/)
|
|
||||||
|
|
||||||
These links may advise how the provider can unblock the port through additional services offered, or via a support ticket request.
|
|
||||||
|
|
||||||
### Mail sent to DMS does not get delivered to user
|
|
||||||
|
|
||||||
Common logs related to this are:
|
|
||||||
|
|
||||||
- `warning: do not list domain domain.fr in BOTH mydestination and virtual_mailbox_domains`
|
|
||||||
- `Recipient address rejected: User unknown in local recipient table`
|
|
||||||
|
|
||||||
If your logs look like this, you likely have [assigned the same FQDN to the DMS `hostname` and your mail accounts][gh-issues::dms-fqdn-misconfigured] which is not supported by default. You can either adjust your DMS `hostname` or follow [this FAQ advice][docs::faq-bare-domain]
|
|
||||||
|
|
||||||
It is also possible that [DMS services are temporarily unavailable][gh-issues::dms-services-unavailable] when configuration changes are detected, producing the 2nd error. Certificate updates may be a less obvious trigger.
|
|
||||||
|
|
||||||
## Steps for Debugging DMS
|
|
||||||
|
|
||||||
1. **Increase log verbosity**: Very helpful for troubleshooting problems during container startup. Set the environment variable [`LOG_LEVEL`][docs-environment-log-level] to `debug` or `trace`.
|
|
||||||
2. **Use error logs as a search query**: Try [finding an _existing issue_][gh-issues] or _search engine result_ from any errors in your container log output. Often you'll find answers or more insights. If you still need to open an issue, sharing links from your search may help us assist you. The mail server log can be acquired by running `docker log <CONTAINER NAME>` (_or `docker logs -f <CONTAINER NAME>` if you want to follow the log_).
|
|
||||||
3. **Inspect the logs of the service that is failing**: We provide a dedicated paragraph on this topic [further down below](#logs).
|
|
||||||
4. **Understand the basics of mail servers**: Especially for beginners, make sure you read our [Introduction][docs-introduction] and [Usage][docs-usage] articles.
|
|
||||||
5. **Search the whole FAQ**: Our [FAQ][docs-faq] contains answers for common problems. Make sure you go through the list.
|
|
||||||
6. **Reduce the scope**: Ensure that you can run a basic setup of DMS first. Then incrementally restore parts of your original configuration until the problem is reproduced again. If you're new to DMS, it is common to find the cause is misunderstanding how to configure a minimal setup.
|
|
||||||
|
|
||||||
### Debug a running container
|
|
||||||
|
|
||||||
#### General
|
|
||||||
|
|
||||||
To get a shell inside the container run: `docker exec -it <CONTAINER NAME> bash`. To install additional software, run:
|
|
||||||
|
|
||||||
1. `apt-get update` to update repository metadata.
|
|
||||||
2. `apt-get install <PACKAGE>` to install a package, e.g., `apt-get install neovim` if you want to use NeoVim instead of `nano` (which is shipped by default).
|
|
||||||
|
|
||||||
#### Logs
|
|
||||||
|
|
||||||
If you need more flexibility than what the `docker logs` command offers, then the most useful locations to get relevant DMS logs within the container are:
|
|
||||||
|
|
||||||
- `/var/log/mail/<SERVICE>.log`
|
|
||||||
- `/var/log/supervisor/<SERVICE>.log`
|
|
||||||
|
|
||||||
You may use `nano` (a text editor) to edit files, while `less` (a file viewer) and `tail`/`cat` are useful tools to inspect the contents of logs.
|
|
||||||
|
|
||||||
## Compatibility
|
|
||||||
|
|
||||||
It's possible that the issue you're experiencing is due to a compatibility conflict.
|
|
||||||
|
|
||||||
This could be from outdated software, or running a system that isn't able to provide you newer software and kernels. You may want to verify if you can reproduce the issue on a system that is not affected by these concerns.
|
|
||||||
|
|
||||||
### Network
|
|
||||||
|
|
||||||
- Misconfigured network connections can cause the client IP address to be proxied through a docker network gateway IP, or a [service that acts on behalf of connecting clients for logins][gh-discuss-roundcube-fail2ban] where the connections client IP appears to be only from that service (eg: Container IP) instead. This can relay the wrong information to other services (eg: monitoring like Fail2Ban, SPF verification) causing unexpected failures.
|
|
||||||
- **`userland-proxy`:** Prior to Docker `v23`, [changing the `userland-proxy` setting did not reliably remove NAT rules][network::docker-userlandproxy].
|
|
||||||
- **UFW / firewalld:** Some users expect only their firewall frontend to manage the firewall rules, but these will be bypassed when Docker publishes a container port (_as there is no integration between the two_).
|
|
||||||
- **`iptables` / `nftables`:**
|
|
||||||
- Docker [only manages the NAT rules via `iptables`][network::docker-nftables], relying on compatibility shims for supporting the successor `nftables`. Internally DMS expects `nftables` support on the host kernel for services like Fail2Ban to function correctly.
|
|
||||||
- [Kernels older than 5.2 may affect management of NAT rules via `nftables`][network::kernel-nftables]. Other software outside of DMS may also manipulate these rules, such as firewall frontends.
|
|
||||||
- **IPv6:**
|
|
||||||
- Requires [additional configuration][docs-ipv6] to prevent or properly support IPv6 connections (eg: Preserving the Client IP).
|
|
||||||
- Support in 2023 is still considered experimental. You are advised to use at least Docker Engine `v23` (2023Q1).
|
|
||||||
- Various networking bug fixes have been addressed since the initial IPv6 support arrived in Docker Engine `v20.10.0` (2020Q4).
|
|
||||||
|
|
||||||
### System
|
|
||||||
|
|
||||||
- **macOS:** DMS has limited support for macOS. Often an issue encountered is due to permissions related to the `volumes` config in `compose.yaml`. You may have luck [trying `gRPC FUSE`][gh-macos-support] as the file sharing implementation; [`VirtioFS` is the successor][docker-macos-virtiofs] but presently appears incompatible with DMS.
|
|
||||||
- **Kernel:** Some systems provide [kernels with modifications (_replacing defaults and backporting patches_)][network::kernels-modified] to support running legacy software or kernels, complicating compatibility. This can be commonly experienced with products like NAS.
|
|
||||||
- **CGroups v2:** Hosts running older kernels (prior to 5.2) and systemd (prior to v244) are not likely to leverage cgroup v2, or have not defaulted to the cgroup v2 `unified` hierarchy. Not meeting this baseline may influence the behavior of your DMS container, even with the latest Docker Engine installed.
|
|
||||||
- **Container runtime:** Docker and Podman for example have subtle differences. DMS docs are primarily focused on Docker, but we try to document known issues where relevant.
|
|
||||||
- **Rootless containers:** Introduces additional differences in behavior or requirements:
|
|
||||||
- cgroup v2 is required for supporting rootless containers.
|
|
||||||
- Differences such as for container networking which may further affect support for IPv6 and preserving the client IP (Remote address). Example with Docker rootless are [binding a port to a specific interface][docker-rootless-interface] and the choice of [port forwarding driver][docs::fail2ban::rootless-portdriver].
|
|
||||||
|
|
||||||
[network::docker-userlandproxy]: https://github.com/moby/moby/issues/44721
|
|
||||||
[network::docker-nftables]: https://github.com/moby/moby/issues/26824
|
|
||||||
[network::kernels-modified]: https://github.com/docker-mailserver/docker-mailserver/pull/2662#issuecomment-1168435970
|
|
||||||
[network::kernel-nftables]: https://unix.stackexchange.com/questions/596493/can-nftables-and-iptables-ip6tables-rules-be-applied-at-the-same-time-if-so-wh/596497#596497
|
|
||||||
|
|
||||||
[docs-environment-log-level]: ./environment.md#log_level
|
|
||||||
[docs-faq]: ../faq.md
|
|
||||||
[docs::faq-bare-domain]: ../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname
|
|
||||||
[docs-ipv6]: ./advanced/ipv6.md
|
|
||||||
[docs-introduction]: ../introduction.md
|
|
||||||
[docs::fail2ban::rootless-portdriver]: ./security/fail2ban.md#rootless-container
|
|
||||||
[docs-usage]: ../usage.md
|
|
||||||
|
|
||||||
[gh-issues]: https://github.com/docker-mailserver/docker-mailserver/issues
|
|
||||||
[gh-issues::dms-fqdn-misconfigured]: https://github.com/docker-mailserver/docker-mailserver/issues/3679#issuecomment-1837609043
|
|
||||||
[gh-issues::dms-services-unavailable]: https://github.com/docker-mailserver/docker-mailserver/issues/3679#issuecomment-1848083358
|
|
||||||
[gh-macos-support]: https://github.com/docker-mailserver/docker-mailserver/issues/3648#issuecomment-1822774080
|
|
||||||
[gh-discuss-roundcube-fail2ban]: https://github.com/orgs/docker-mailserver/discussions/3273#discussioncomment-5654603
|
|
||||||
|
|
||||||
[docker-rootless-interface]: https://github.com/moby/moby/issues/45742
|
|
||||||
[docker-macos-virtiofs]: https://www.docker.com/blog/speed-boost-achievement-unlocked-on-docker-desktop-4-6-for-mac/
|
|
||||||
[docker-docs::force-recreate]: https://docs.docker.com/compose/reference/up/
|
|
||||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,21 +0,0 @@
|
||||||
---
|
|
||||||
title: Mail Delivery with POP3
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
If you want to use POP3(S), you have to add the ports 110 and/or 995 (TLS secured) and the environment variable `ENABLE_POP3` to your `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
mailserver:
|
|
||||||
ports:
|
|
||||||
- "25:25" # SMTP (explicit TLS => STARTTLS)
|
|
||||||
- "143:143" # IMAP4 (explicit TLS => STARTTLS)
|
|
||||||
- "465:465" # ESMTP (implicit TLS)
|
|
||||||
- "587:587" # ESMTP (explicit TLS => STARTTLS)
|
|
||||||
- "993:993" # IMAP4 (implicit TLS)
|
|
||||||
- "110:110" # POP3
|
|
||||||
- "995:995" # POP3 (with TLS)
|
|
||||||
environment:
|
|
||||||
- ENABLE_POP3=1
|
|
||||||
```
|
|
||||||
|
|
@ -1,162 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Security | Fail2Ban'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! quote "What is Fail2Ban (F2B)?"
|
|
||||||
|
|
||||||
Fail2ban is an intrusion prevention software framework. Written in the Python programming language, it is designed to prevent against brute-force attacks. It is able to run on POSIX systems that have an interface to a packet-control system or firewall installed locally, such as \[NFTables\] or TCP Wrapper.
|
|
||||||
|
|
||||||
[Source][wikipedia-fail2ban]
|
|
||||||
|
|
||||||
[wikipedia-fail2ban]: https://en.wikipedia.org/wiki/Fail2ban
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Enabling Fail2Ban support can be done via ENV, but also requires granting at least the `NET_ADMIN` capability to interact with the kernel and ban IP addresses.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
=== "Docker Compose"
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
environment:
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Docker CLI"
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker run --rm -it \
|
|
||||||
--cap-add=NET_ADMIN \
|
|
||||||
--env ENABLE_FAIL2BAN=1
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "Security risk of adding non-default capabilties"
|
|
||||||
|
|
||||||
DMS bundles F2B into the image for convenience to simplify integration and deployment.
|
|
||||||
|
|
||||||
The [`NET_ADMIN`][security::cap-net-admin] and [`NET_RAW`][security::cap-net-raw] capabilities are not granted by default to the container root user, as they can be used to compromise security.
|
|
||||||
|
|
||||||
If this risk concerns you, it may be wiser to instead prefer only granting these capabilities to a dedicated Fail2Ban container ([example][lsio:f2b-image]).
|
|
||||||
|
|
||||||
!!! bug "Running Fail2Ban on Older Kernels"
|
|
||||||
|
|
||||||
DMS configures F2B to use [NFTables][network::nftables], not [IPTables (legacy)][network::iptables-legacy].
|
|
||||||
|
|
||||||
We have observed that older systems (for example NAS systems), do not support the modern NFTables rules. You will need to configure F2B to use legacy IPTables again, for example with the [`fail2ban-jail.cf`][github-file-f2bjail], see the [section on configuration further down below](#custom-files).
|
|
||||||
|
|
||||||
[security::cap-net-admin]: https://0xn3va.gitbook.io/cheat-sheets/container/escaping/excessive-capabilities#cap_net_admin
|
|
||||||
[security::cap-net-raw]: https://0xn3va.gitbook.io/cheat-sheets/container/escaping/excessive-capabilities#cap_net_raw
|
|
||||||
[lsio:f2b-image]: https://docs.linuxserver.io/images/docker-fail2ban
|
|
||||||
[network::nftables]: https://en.wikipedia.org/wiki/Nftables
|
|
||||||
[network::iptables-legacy]: https://developers.redhat.com/blog/2020/08/18/iptables-the-two-variants-and-their-relationship-with-nftables#two_variants_of_the_iptables_command
|
|
||||||
|
|
||||||
### DMS Defaults
|
|
||||||
|
|
||||||
DMS will automatically ban IP addresses of hosts that have generated 6 failed attempts over the course of the last week. The bans themselves last for one week. The Postfix jail is configured to use `mode = extra` in DMS.
|
|
||||||
|
|
||||||
### Custom Files
|
|
||||||
|
|
||||||
!!! question "What is [`docker-data/dms/config/`][docs::dms-volumes-config]?"
|
|
||||||
|
|
||||||
This following configuration files inside the `docker-data/dms/config/` volume will be copied inside the container during startup
|
|
||||||
|
|
||||||
1. `fail2ban-jail.cf` is copied to `/etc/fail2ban/jail.d/user-jail.local`
|
|
||||||
- with this file, you can adjust the configuration of individual jails and their defaults
|
|
||||||
- there is an example provided [in our repository on GitHub][github-file-f2bjail]
|
|
||||||
2. `fail2ban-fail2ban.cf` is copied to `/etc/fail2ban/fail2ban.local`
|
|
||||||
- with this file, you can adjust F2B behavior in general
|
|
||||||
- there is an example provided [in our repository on GitHub][github-file-f2bconfig]
|
|
||||||
|
|
||||||
[docs::dms-volumes-config]: ../advanced/optional-config.md#volumes-config
|
|
||||||
[github-file-f2bjail]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-jail.cf
|
|
||||||
[github-file-f2bconfig]: https://github.com/docker-mailserver/docker-mailserver/blob/master/config-examples/fail2ban-fail2ban.cf
|
|
||||||
|
|
||||||
### Viewing All Bans
|
|
||||||
|
|
||||||
When just running
|
|
||||||
|
|
||||||
```bash
|
|
||||||
setup fail2ban
|
|
||||||
```
|
|
||||||
|
|
||||||
the script will show all banned IP addresses.
|
|
||||||
|
|
||||||
To get a more detailed `status` view, run
|
|
||||||
|
|
||||||
```bash
|
|
||||||
setup fail2ban status
|
|
||||||
```
|
|
||||||
|
|
||||||
### Managing Bans
|
|
||||||
|
|
||||||
You can manage F2B with the `setup` script. The usage looks like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec <CONTAINER NAME> setup fail2ban [<ban|unban> <IP>]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Viewing the Log File
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec <CONTAINER NAME> setup fail2ban log
|
|
||||||
```
|
|
||||||
|
|
||||||
## Running Inside A Rootless Container { #rootless-container }
|
|
||||||
|
|
||||||
[`RootlessKit`][rootless::rootless-kit] is the _fakeroot_ implementation for supporting _rootless mode_ in Docker and Podman. By default, RootlessKit uses the [`builtin` port forwarding driver][rootless::port-drivers], which does not propagate source IP addresses.
|
|
||||||
|
|
||||||
It is necessary for F2B to have access to the real source IP addresses in order to correctly identify clients. This is achieved by changing the port forwarding driver to [`slirp4netns`][rootless::slirp4netns], which is slower than the builtin driver but does preserve the real source IPs.
|
|
||||||
|
|
||||||
[rootless::rootless-kit]: https://github.com/rootless-containers/rootlesskit
|
|
||||||
[rootless::port-drivers]: https://github.com/rootless-containers/rootlesskit/blob/v0.14.5/docs/port.md#port-drivers
|
|
||||||
[rootless::slirp4netns]: https://github.com/rootless-containers/slirp4netns
|
|
||||||
|
|
||||||
=== "Docker"
|
|
||||||
|
|
||||||
For [rootless mode][rootless::docker] in Docker, create `~/.config/systemd/user/docker.service.d/override.conf` with the following content:
|
|
||||||
|
|
||||||
!!! danger inline end
|
|
||||||
|
|
||||||
This changes the port driver for all rootless containers managed by Docker. Per container configuration is not supported, if you need that consider Podman instead.
|
|
||||||
|
|
||||||
```cf
|
|
||||||
[Service]
|
|
||||||
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_PORT_DRIVER=slirp4netns"
|
|
||||||
```
|
|
||||||
|
|
||||||
And then restart the daemon:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ systemctl --user daemon-reload
|
|
||||||
$ systemctl --user restart docker
|
|
||||||
```
|
|
||||||
|
|
||||||
[rootless::docker]: https://docs.docker.com/engine/security/rootless
|
|
||||||
|
|
||||||
=== "Podman"
|
|
||||||
|
|
||||||
[Rootless Podman][rootless::podman] requires adding the value `slirp4netns:port_handler=slirp4netns` to the `--network` CLI option, or `network_mode` setting in your `compose.yaml`:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
network_mode: "slirp4netns:port_handler=slirp4netns"
|
|
||||||
environment:
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
- NETWORK_INTERFACE=tap0
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
You must also add the ENV `NETWORK_INTERFACE=tap0`, because Podman uses a [hard-coded interface name][rootless::podman::interface] for `slirp4netns`. `slirp4netns` is not compatible with user-defined networks!
|
|
||||||
|
|
||||||
[rootless::podman]: https://github.com/containers/podman/blob/v3.4.1/docs/source/markdown/podman-run.1.md#--networkmode---net
|
|
||||||
[rootless::podman::interface]: https://github.com/containers/podman/blob/v3.4.1/libpod/networking_slirp4netns.go#L264
|
|
||||||
|
|
@ -1,66 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Security | mail_crypt (email/storage encryption)'
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
The Mail crypt plugin is used to secure email messages stored in a Dovecot system. Messages are encrypted before written to storage and decrypted after reading. Both operations are transparent to the user.
|
|
||||||
|
|
||||||
In case of unauthorized access to the storage backend, the messages will, without access to the decryption keys, be unreadable to the offending party.
|
|
||||||
|
|
||||||
There can be a single encryption key for the whole system or each user can have a key of their own. The used cryptographical methods are widely used standards and keys are stored in portable formats, when possible.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Official Dovecot documentation: https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Single Encryption Key / Global Method
|
|
||||||
|
|
||||||
1. Create `10-custom.conf` and populate it with the following:
|
|
||||||
|
|
||||||
```
|
|
||||||
# Enables mail_crypt for all services (imap, pop3, etc)
|
|
||||||
mail_plugins = $mail_plugins mail_crypt
|
|
||||||
plugin {
|
|
||||||
mail_crypt_global_private_key = </certs/ecprivkey.pem
|
|
||||||
mail_crypt_global_public_key = </certs/ecpubkey.pem
|
|
||||||
mail_crypt_save_version = 2
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Shutdown your mailserver (`docker compose down`)
|
|
||||||
|
|
||||||
3. You then need to [generate your global EC key](https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/#ec-key). We named them `/certs/ecprivkey.pem` and `/certs/ecpubkey.pem` in step #1.
|
|
||||||
|
|
||||||
4. The EC key needs to be available in the container. I prefer to mount a /certs directory into the container:
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
volumes:
|
|
||||||
. . .
|
|
||||||
- ./certs/:/certs
|
|
||||||
. . .
|
|
||||||
```
|
|
||||||
|
|
||||||
5. While you're editing the `compose.yaml`, add the configuration file:
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
volumes:
|
|
||||||
. . .
|
|
||||||
- ./config/dovecot/10-custom.conf:/etc/dovecot/conf.d/10-custom.conf
|
|
||||||
- ./certs/:/certs
|
|
||||||
. . .
|
|
||||||
```
|
|
||||||
|
|
||||||
6. Start the container, monitor the logs for any errors, send yourself a message, and then confirm the file on disk is encrypted:
|
|
||||||
```
|
|
||||||
[root@ip-XXXXXXXXXX ~]# cat -A /mnt/efs-us-west-2/maildata/awesomesite.com/me/cur/1623989305.M6v<36>z<EFBFBD>@<40><> m}<7D><>,<2C><>9<EFBFBD><39><EFBFBD><EFBFBD>B*<2A>247.us-west-2.compute.inE<6E><45>\Ck*<2A>@7795,W=7947:2,
|
|
||||||
T<>9<EFBFBD>8t<38>6<EFBFBD><36> t<><74><EFBFBD>e<EFBFBD>W<EFBFBD><57>S `<60>H<EFBFBD><48>C<EFBFBD>ڤ <20>yeY<65><59>XZ<58><5A>^<5E>d<EFBFBD>/<2F><>+<2B>A
|
|
||||||
```
|
|
||||||
|
|
||||||
This should be the minimum required for encryption of the mail while in storage.
|
|
||||||
|
|
@ -1,369 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Security | Rspamd'
|
|
||||||
---
|
|
||||||
|
|
||||||
## About
|
|
||||||
|
|
||||||
Rspamd is a ["fast, free and open-source spam filtering system"][rspamd-web]. DMS integrates Rspamd like any other service. We provide a basic but easy to maintain setup of Rspamd.
|
|
||||||
|
|
||||||
If you want to take a look at the default configuration files for Rspamd that DMS adds, navigate to [`target/rspamd/` inside the repository][dms-repo::default-rspamd-configuration]. Please consult the [section "The Default Configuration"](#the-default-configuration) section down below for a written overview.
|
|
||||||
|
|
||||||
### Enable Rspamd
|
|
||||||
|
|
||||||
Rspamd is presently opt-in for DMS, but intended to become the default anti-spam service in a future release.
|
|
||||||
|
|
||||||
DMS offers two anti-spam solutions:
|
|
||||||
|
|
||||||
- Legacy (_Amavis, SpamAssassin, OpenDKIM, OpenDMARC_)
|
|
||||||
- Rspamd (_Provides equivalent features of software from the legacy solution_)
|
|
||||||
|
|
||||||
While you could configure Rspamd to only replace some of the legacy services, it is advised to only use Rspamd with the legacy services disabled.
|
|
||||||
|
|
||||||
!!! example "Switch to Rspamd"
|
|
||||||
|
|
||||||
To use Rspamd add the following ENV config changes:
|
|
||||||
|
|
||||||
```env
|
|
||||||
ENABLE_RSPAMD=1
|
|
||||||
|
|
||||||
# Rspamd replaces the functionality of all these anti-spam services, disable them:
|
|
||||||
ENABLE_OPENDKIM=0
|
|
||||||
ENABLE_OPENDMARC=0
|
|
||||||
ENABLE_POLICYD_SPF=0
|
|
||||||
ENABLE_AMAVIS=0
|
|
||||||
ENABLE_SPAMASSASSIN=0
|
|
||||||
# Greylisting is opt-in, if you had enabled Postgrey switch to the Rspamd equivalent:
|
|
||||||
ENABLE_POSTGREY=0
|
|
||||||
RSPAMD_GREYLISTING=1
|
|
||||||
|
|
||||||
# Optional: Add anti-virus support with ClamAV (compatible with Rspamd):
|
|
||||||
ENABLE_CLAMAV=1
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! info "Relevant Environment Variables"
|
|
||||||
|
|
||||||
The following environment variables are related to Rspamd:
|
|
||||||
|
|
||||||
1. [`ENABLE_RSPAMD`](../environment.md#enable_rspamd)
|
|
||||||
2. [`ENABLE_RSPAMD_REDIS`](../environment.md#enable_rspamd_redis)
|
|
||||||
3. [`RSPAMD_CHECK_AUTHENTICATED`](../environment.md#rspamd_check_authenticated)
|
|
||||||
4. [`RSPAMD_GREYLISTING`](../environment.md#rspamd_greylisting)
|
|
||||||
5. [`RSPAMD_HFILTER`](../environment.md#rspamd_hfilter)
|
|
||||||
6. [`RSPAMD_HFILTER_HOSTNAME_UNKNOWN_SCORE`](../environment.md#rspamd_hfilter_hostname_unknown_score)
|
|
||||||
7. [`RSPAMD_LEARN`](../environment.md#rspamd_learn)
|
|
||||||
8. [`SPAM_SUBJECT`](../environment.md#spam_subject)
|
|
||||||
9. [`MOVE_SPAM_TO_JUNK`][docs::spam-to-junk]
|
|
||||||
10. [`MARK_SPAM_AS_READ`](../environment.md#mark_spam_as_read)
|
|
||||||
|
|
||||||
## Overview of Rspamd support
|
|
||||||
|
|
||||||
### Mode of Operation
|
|
||||||
|
|
||||||
!!! note "Attention"
|
|
||||||
|
|
||||||
Read this section carefully if you want to understand how Rspamd is integrated into DMS and how it works (on a surface level).
|
|
||||||
|
|
||||||
Rspamd is integrated as a milter into DMS. When enabled, Postfix's `main.cf` configuration file includes the parameter `rspamd_milter = inet:localhost:11332`, which is added to `smtpd_milters`. As a milter, Rspamd can inspect incoming and outgoing e-mails.
|
|
||||||
|
|
||||||
Each mail is assigned what Rspamd calls symbols: when an e-mail matches a specific criterion, the e-mail receives a symbol. Afterward, Rspamd applies a _spam score_ (as usual with anti-spam software) to the e-mail.
|
|
||||||
|
|
||||||
- The score itself is calculated by adding the values of the individual symbols applied earlier. The higher the spam score is, the more likely the e-mail is spam.
|
|
||||||
- Symbol values can be negative (i.e., these symbols indicate the mail is legitimate, maybe because [SPF and DKIM][docs::dkim-dmarc-spf] are verified successfully). On the other hand, symbol scores can be positive (i.e., these symbols indicate the e-mail is spam, perhaps because the e-mail contains numerous links).
|
|
||||||
|
|
||||||
Rspamd then adds (a few) headers to the e-mail based on the spam score. Most important is `X-Spamd-Result`, which contains an overview of which symbols were applied. It could look like this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
X-Spamd-Result default: False [-2.80 / 11.00]; R_SPF_NA(1.50)[no SPF record]; R_DKIM_ALLOW(-1.00)[example.com:s=dtag1]; DWL_DNSWL_LOW(-1.00)[example.com:dkim]; RWL_AMI_LASTHOP(-1.00)[192.0.2.42:from]; DMARC_POLICY_ALLOW(-1.00)[example.com,none]; RWL_MAILSPIKE_EXCELLENT(-0.40)[192.0.2.42:from]; FORGED_SENDER(0.30)[noreply@example.com,some-reply-address@bounce.example.com]; RCVD_IN_DNSWL_LOW(-0.10)[192.0.2.42:from]; MIME_GOOD(-0.10)[multipart/mixed,multipart/related,multipart/alternative,text/plain]; MIME_TRACE(0.00)[0:+,1:+,2:+,3:+,4:~,5:~,6:~]; RCVD_COUNT_THREE(0.00)[3]; RCPT_COUNT_ONE(0.00)[1]; REPLYTO_DN_EQ_FROM_DN(0.00)[]; ARC_NA(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; RCVD_TLS_LAST(0.00)[]; DKIM_TRACE(0.00)[example.com:+]; HAS_ATTACHMENT(0.00)[]; TO_DN_NONE(0.00)[]; FROM_NEQ_ENVFROM(0.00)[noreply@example.com,some-reply-address@bounce.example.com]; FROM_HAS_DN(0.00)[]; REPLYTO_DOM_NEQ_FROM_DOM(0.00)[]; PREVIOUSLY_DELIVERED(0.00)[receiver@anotherexample.com]; ASN(0.00)[asn:3320, ipnet:192.0.2.0/24, country:DE]; MID_RHS_MATCH_FROM(0.00)[]; MISSING_XM_UA(0.00)[]; HAS_REPLYTO(0.00)[some-reply-address@dms-reply.example.com]
|
|
||||||
```
|
|
||||||
|
|
||||||
And then there is a corresponding `X-Rspamd-Action` header, which shows the overall result and the action that is taken. In our example, it would be:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
X-Rspamd-Action no action
|
|
||||||
```
|
|
||||||
|
|
||||||
Since the score is `-2.80`, nothing will happen and the e-mail is not classified as spam. Our custom [`actions.conf`][dms-repo::rspamd-actions-config] defines what to do at certain scores:
|
|
||||||
|
|
||||||
1. At a score of 4, the e-mail is to be _greylisted_;
|
|
||||||
2. At a score of 6, the e-mail is _marked with a header_ (`X-Spam: Yes`);
|
|
||||||
3. At a score of 11, the e-mail is outright _rejected_.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
There is more to spam analysis than meets the eye: we have not covered the [Bayes training and filters][rspamd-docs::bayes] here, nor have we discussed [Sieve rules for e-mails that are marked as spam][docs::spam-to-junk].
|
|
||||||
|
|
||||||
Even the calculation of the score with the individual symbols has been presented to you in a simplified manner. But with the knowledge from above, you're equipped to read on and use Rspamd confidently. Keep on reading to understand the integration even better - you will want to know about your anti-spam software, not only to keep the bad e-mail out, but also to make sure the good e-mail arrive properly!
|
|
||||||
|
|
||||||
### Workers
|
|
||||||
|
|
||||||
The proxy worker operates in [self-scan mode][rspamd-docs::proxy-self-scan-mode]. This simplifies the setup as we do not require a normal worker. You can easily change this though by [overriding the configuration by DMS](#providing-custom-settings-overriding-settings).
|
|
||||||
|
|
||||||
DMS does not set a default password for the controller worker. You may want to do that yourself. In setups where you already have an authentication provider in front of the Rspamd webpage, you may want to [set the `secure_ip ` option to `"0.0.0.0/0"` for the controller worker](#with-the-help-of-a-custom-file) to disable password authentication inside Rspamd completely.
|
|
||||||
|
|
||||||
### Persistence with Redis
|
|
||||||
|
|
||||||
When Rspamd is enabled, we implicitly also start an instance of Redis in the container:
|
|
||||||
|
|
||||||
- Redis is configured to persist its data via RDB snapshots to disk in the directory `/var/lib/redis` (_or the [`/var/mail-state/`][docs::dms-volumes-state] volume when present_).
|
|
||||||
- With the volume mount, the snapshot will restore the Redis data across container updates, and provide a way to keep a backup.
|
|
||||||
- Without a volume mount a containers internal state will persist across restarts until the container is recreated due to changes like ENV or upgrading the image for the container.
|
|
||||||
|
|
||||||
Redis uses `/etc/redis/redis.conf` for configuration:
|
|
||||||
|
|
||||||
- We adjust this file when enabling the internal Redis service.
|
|
||||||
- If you have an external instance of Redis to use, the internal Redis service can be opt-out via setting the ENV [`ENABLE_RSPAMD_REDIS=0`][docs::env::enable-redis] (_link also details required changes to the DMS Rspamd config_).
|
|
||||||
|
|
||||||
If you are interested in using Valkey instead of Redis, please refer to [this guidance][gh-dms::guide::valkey].
|
|
||||||
|
|
||||||
### Web Interface
|
|
||||||
|
|
||||||
Rspamd provides a [web interface][rspamd-docs::web-ui], which contains statistics and data Rspamd collects. The interface is enabled by default and reachable on port 11334.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
To use the web interface you will need to configure a password, [otherwise you won't be able to log in][rspamd-docs::web-ui::password].
|
|
||||||
|
|
||||||
??? example "Set a custom password"
|
|
||||||
|
|
||||||
Add this line to [your Rspamd `custom-commands.conf` config](#with-the-help-of-a-custom-file) which sets the `password` option of the _controller worker_:
|
|
||||||
|
|
||||||
```
|
|
||||||
set-option-for-controller password "your hashed password here"
|
|
||||||
```
|
|
||||||
|
|
||||||
The password hash can be generated via the `rspamadm pw` command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec -it <CONTAINER_NAME> rspamadm pw
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Related:** A minimal Rspamd `compose.yaml` [example with a reverse-proxy for web access][gh-dms::guide::rspamd-web].
|
|
||||||
|
|
||||||
### DNS
|
|
||||||
|
|
||||||
DMS does not supply custom values for DNS servers (to Rspamd). If you need to use custom DNS servers, which could be required when using [DNS-based deny/allowlists](#rbls-real-time-blacklists-dnsbls-dns-based-blacklists), you need to adjust [`options.inc`][rspamd-docs::config::global] yourself. Make sure to also read our [FAQ page on DNS servers][docs::faq::dns-servers].
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Rspamd heavily relies on a properly working DNS server that it can use to resolve DNS queries. If your DNS server is misconfigured, you will encounter issues when Rspamd queries DNS to assess if mail is spam. Legitimate mail is then unintentionally marked as spam or worse, rejected entirely.
|
|
||||||
|
|
||||||
When Rspamd is deciding if mail is spam, it will check DNS records for SPF, DKIM and DMARC. Each of those has an associated symbol for DNS temporary errors with a non-zero weight assigned. That weight contributes towards the spam score assessed by Rspamd which is normally desirable - provided your network DNS is functioning correctly, otherwise when DNS is broken all mail is biased towards spam due to these failed DNS lookups.
|
|
||||||
|
|
||||||
!!! danger
|
|
||||||
|
|
||||||
While we do not provide values for custom DNS servers by default, we set `soft_reject_on_timeout = true;` by default. This setting will cause a soft reject if a task (presumably a DNS request) timeout takes place.
|
|
||||||
|
|
||||||
This setting is enabled to not allow spam to proceed just because DNS requests did not succeed. It could deny legitimate e-mails to pass though too in case your DNS setup is incorrect or not functioning properly.
|
|
||||||
|
|
||||||
### Logs
|
|
||||||
|
|
||||||
You can find the Rspamd logs at `/var/log/mail/rspamd.log`, and the corresponding logs for [Redis](#persistence-with-redis), if it is enabled, at `/var/log/supervisor/rspamd-redis.log`. We recommend inspecting these logs (with `docker exec -it <CONTAINER NAME> less /var/log/mail/rspamd.log`) in case Rspamd does not work as expected.
|
|
||||||
|
|
||||||
### Modules
|
|
||||||
|
|
||||||
You can find a list of all Rspamd modules [on their website][rspamd-docs::modules].
|
|
||||||
|
|
||||||
#### Disabled By Default
|
|
||||||
|
|
||||||
DMS disables certain modules (`clickhouse`, `elastic`, `neural`, `reputation`, `spamassassin`, `url_redirector`, `metric_exporter`) by default. We believe these are not required in a standard setup, and they would otherwise needlessly use system resources.
|
|
||||||
|
|
||||||
#### Anti-Virus (ClamAV)
|
|
||||||
|
|
||||||
You can choose to enable ClamAV, and Rspamd will then use it to check for viruses. Just set the environment variable `ENABLE_CLAMAV=1`.
|
|
||||||
|
|
||||||
#### RBLs (Real-time Blacklists) / DNSBLs (DNS-based Blacklists)
|
|
||||||
|
|
||||||
The [RBL module][rspamd-docs::modules::rbl] is enabled by default. As a consequence, Rspamd will perform DNS lookups to various blacklists. Whether an RBL or a DNSBL is queried depends on where the domain name was obtained: RBL servers are queried with IP addresses extracted from message headers, DNSBL server are queried with domains and IP addresses extracted from the message body ([source][www::rbl-vs-dnsbl]).
|
|
||||||
|
|
||||||
!!! danger "Rspamd and DNS Block Lists"
|
|
||||||
|
|
||||||
When the RBL module is enabled, Rspamd will do a variety of DNS requests to (amongst other things) DNSBLs. There are a variety of issues involved when using DNSBLs. Rspamd will try to mitigate some of them by properly evaluating all return codes. This evaluation is a best effort though, so if the DNSBL operators change or add return codes, it may take a while for Rspamd to adjust as well.
|
|
||||||
|
|
||||||
If you want to use DNSBLs, **try to use your own DNS resolver** and make sure it is set up correctly, i.e. it should be a non-public & **recursive** resolver. Otherwise, you might not be able ([see this Spamhaus post][spamhaus::faq::dnsbl-usage]) to make use of the block lists.
|
|
||||||
|
|
||||||
## Providing Custom Settings & Overriding Settings
|
|
||||||
|
|
||||||
!!! info "Rspamd config overriding precedence"
|
|
||||||
|
|
||||||
Rspamd has a layered approach for configuration with [`local.d` and `override.d` config directories][rspamd-docs::config-directories].
|
|
||||||
|
|
||||||
- DMS [extends the Rspamd default configs via `/etc/rspamd/local.d/`][dms-repo::default-rspamd-configuration].
|
|
||||||
- User config changes should be handled separately as overrides via the [DMS Config Volume][docs::dms-volumes-config] (`docker-data/dms/config/`) with either:
|
|
||||||
- `./rspamd/override.d/` - Config files placed here are copied to `/etc/rspamd/override.d/` during container startup.
|
|
||||||
- [`./rspamd/custom-commands.conf`](#with-the-help-of-a-custom-file) - Applied after copying any provided configs from `rspamd/override.d/` (DMS Config volume) to `/etc/rspamd/override.d/`.
|
|
||||||
|
|
||||||
!!! abstract "Reference docs for Rspamd config"
|
|
||||||
|
|
||||||
- [Config Overview][rspamd-docs::config::overview], [Quickstart guide][rspamd-docs::config::quickstart], and [Config Syntax (UCL)][rspamd-docs::config::ucl-syntax]
|
|
||||||
- Global Options ([`options.inc`][rspamd-docs::config::global])
|
|
||||||
- [Workers][rspamd-docs::config::workers] ([`worker-controller.inc`][rspamd-docs::config::worker-controller], [`worker-proxy.inc`][rspamd-docs::config::worker-proxy])
|
|
||||||
- [Modules][rspamd-docs::modules] (_view each module page for their specific config options_)
|
|
||||||
|
|
||||||
!!! tip "View rendered config"
|
|
||||||
|
|
||||||
`rspamadm configdump` will output the full rspamd configuration that is used should you need it for troubleshooting / inspection.
|
|
||||||
|
|
||||||
- You can also see which modules are enabled / disabled via `rspamadm configdump --modules-state`
|
|
||||||
- Specific config sections like `dkim` or `worker` can also be used to filter the output to just those sections: `rspamadm configdump dkim worker`
|
|
||||||
- Use `--show-help` to include inline documentation for many settings.
|
|
||||||
|
|
||||||
### Using `custom-commands.conf` { #with-the-help-of-a-custom-file }
|
|
||||||
|
|
||||||
For convenience DMS provides a single config file that will directly create or modify multiple configs at `/etc/rspamd/override.d/`. This is handled as the final rspamd configuration step during container startup.
|
|
||||||
|
|
||||||
DMS will apply this config when you provide `rspamd/custom-commands.conf` in your DMS Config volume. Configure it with directive lines as documented below.
|
|
||||||
|
|
||||||
!!! note "Only use this feature for `option = value` changes"
|
|
||||||
|
|
||||||
`custom-commands.conf` is only suitable for adding or replacing simple `option = value` settings for configs at `/etc/rspamd/override.d/`.
|
|
||||||
|
|
||||||
- New settings are appended to the associated config file.
|
|
||||||
- When replacing an existing setting in an override config, that setting may be any matching line (_allowing for nested scopes, instead of only top-level keys_).
|
|
||||||
|
|
||||||
Any changes involving more advanced [UCL config syntax][rspamd-docs::config::ucl-syntax] should instead add UCL config files directly to `rspamd/override.d/` (_in the DMS Config volume_).
|
|
||||||
|
|
||||||
!!! info "`custom-commands.conf` syntax"
|
|
||||||
|
|
||||||
There are 7 directives available to manage custom Rspamd configurations. Add these directive lines into `custom-commands.conf`, they will be processed sequentially.
|
|
||||||
|
|
||||||
**Directives:**
|
|
||||||
|
|
||||||
```txt
|
|
||||||
# For /etc/rspamd/override.d/{options.inc,worker-controller.inc,worker-proxy}.inc
|
|
||||||
set-common-option <OPTION NAME> <OPTION VALUE>
|
|
||||||
set-option-for-controller <OPTION NAME> <OPTION VALUE>
|
|
||||||
set-option-for-proxy <OPTION NAME> <OPTION VALUE>
|
|
||||||
|
|
||||||
# For /etc/rspamd/override.d/<MODULE NAME>.conf
|
|
||||||
enable-module <MODULE NAME>
|
|
||||||
disable-module <MODULE NAME>
|
|
||||||
set-option-for-module <MODULE NAME> <OPTION NAME> <OPTION VALUE>
|
|
||||||
|
|
||||||
# For /etc/rspamd/override.d/<FILENAME>
|
|
||||||
add-line <FILENAME> <CONTENT>
|
|
||||||
```
|
|
||||||
|
|
||||||
**Syntax:**
|
|
||||||
|
|
||||||
- Blank lines are ok.
|
|
||||||
- `#` at the start of a line represents a comment for adding notes.
|
|
||||||
- `<OPTION VALUE>` and `<CONTENT>` will contain the remaining content of their line, any preceding inputs are delimited by white-space.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
??? note "`<MODULE NAME>` can also target non-module configs"
|
|
||||||
|
|
||||||
An example is the `statistics` module, which has config to import a separate file (`classifier-bayes.conf`) for easier overrides to this section of the module config.
|
|
||||||
|
|
||||||
??? example
|
|
||||||
|
|
||||||
```conf title="rspamd/custom-commands.conf"
|
|
||||||
# If you're confident you've properly secured access to the rspamd web service/API (Default port: 11334)
|
|
||||||
# with your own auth layer (eg: reverse-proxy) you can bypass rspamd requiring credentials:
|
|
||||||
# https://rspamd.com/doc/workers/controller.html#controller-configuration
|
|
||||||
set-option-for-controller secure_ip "0.0.0.0/0"
|
|
||||||
|
|
||||||
# Some settings aren't documented well, you may find them in snippets or Rspamds default config files:
|
|
||||||
# https://rspamd.com/doc/tutorials/quickstart.html#using-of-milter-protocol-for-rspamd--16
|
|
||||||
# /etc/rspamd/worker-proxy.inc
|
|
||||||
set-option-for-proxy reject_message "Rejected - Detected as spam"
|
|
||||||
|
|
||||||
# Equivalent to the previous example, but `add-line` is more verbose:
|
|
||||||
add-line worker-proxy.inc reject_message = "Rejected - Detected as spam"
|
|
||||||
|
|
||||||
# Enable Bayes auto-learning feature to classify spam based on Rspamd action/score results:
|
|
||||||
# NOTE: The statistics module imports a separate file for classifier-bayes config
|
|
||||||
# https://rspamd.com/doc/configuration/statistic.html#autolearning
|
|
||||||
set-option-for-module classifier-bayes autolearn true
|
|
||||||
|
|
||||||
# Disable the `chartable` module:
|
|
||||||
# https://rspamd.com/doc/modules/chartable.html
|
|
||||||
disable-module chartable
|
|
||||||
```
|
|
||||||
|
|
||||||
## Advanced Configuration
|
|
||||||
|
|
||||||
### DKIM Signing
|
|
||||||
|
|
||||||
There is a dedicated [section for setting up DKIM with Rspamd in our documentation][docs::dkim-with-rspamd].
|
|
||||||
|
|
||||||
### ARC (Authenticated Received Chain)
|
|
||||||
|
|
||||||
[ARC][wikipedia::arc] support in DMS is opt-in via config file. [Enable the ARC Rspamd module][rspamd-docs::arc] by creating a config file at `docker-data/dms/config/rspamd/override.d/arc.conf`.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
For each mail domain you have DMS manage, add the equivalent `example.com` sub-section to `domain` and adjust the `path` + `selector` fields as necessary.
|
|
||||||
|
|
||||||
```conf title="rspamd/override.d/arc.conf"
|
|
||||||
sign_local = true;
|
|
||||||
sign_authenticated = true;
|
|
||||||
|
|
||||||
domain {
|
|
||||||
example.com {
|
|
||||||
path = "/tmp/docker-mailserver/rspamd/dkim/rsa-2048-mail-example.private.txt";
|
|
||||||
selector = "mail";
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "Using a common keypair"
|
|
||||||
|
|
||||||
As with DKIM, the keypair can be shared across your configured domains.
|
|
||||||
|
|
||||||
Your ARC config can share the same DKIM private key + selector (_with associated DNS record for the public key_).
|
|
||||||
|
|
||||||
### _Abusix_ Integration
|
|
||||||
|
|
||||||
This subsection provides information about the integration of [Abusix][abusix-web], "a set of blocklists that work as an additional email security layer for your existing mail environment". The setup is straight-forward and well documented:
|
|
||||||
|
|
||||||
1. [Create an account][abusix-web::register]
|
|
||||||
2. Retrieve your API key
|
|
||||||
3. Navigate to the ["Getting Started" documentation for Rspamd][abusix-docs::rspamd-integration] and follow the steps described there
|
|
||||||
4. Make sure to change `<APIKEY>` to your private API key
|
|
||||||
|
|
||||||
We recommend mounting the files directly into the container, as they are rather big and not manageable with our [`custom-command.conf` script](#with-the-help-of-a-custom-file). If mounted to the correct location, Rspamd will automatically pick them up.
|
|
||||||
|
|
||||||
While _Abusix_ can be integrated into Postfix, Postscreen and a multitude of other software, we recommend integrating _Abusix_ only into a single piece of software running in your mail server - everything else would be excessive and wasting queries. Moreover, we recommend the integration into suitable filtering software and not Postfix itself, as software like Postscreen or Rspamd can properly evaluate the return codes and other configuration.
|
|
||||||
|
|
||||||
[rspamd-web]: https://rspamd.com/
|
|
||||||
[rspamd-docs::bayes]: https://rspamd.com/doc/configuration/statistic.html
|
|
||||||
[rspamd-docs::proxy-self-scan-mode]: https://rspamd.com/doc/workers/rspamd_proxy.html#self-scan-mode
|
|
||||||
[rspamd-docs::web-ui]: https://rspamd.com/webui/
|
|
||||||
[rspamd-docs::web-ui::password]: https://www.rspamd.com/doc/tutorials/quickstart.html#setting-the-controller-password
|
|
||||||
[rspamd-docs::modules]: https://rspamd.com/doc/modules/
|
|
||||||
[rspamd-docs::modules::rbl]: https://rspamd.com/doc/modules/rbl.html
|
|
||||||
[rspamd-docs::config-directories]: https://rspamd.com/doc/faq.html#what-are-the-locald-and-overrided-directories
|
|
||||||
[rspamd-docs::config::ucl-syntax]: https://rspamd.com/doc/configuration/ucl.html
|
|
||||||
[rspamd-docs::config::overview]: https://rspamd.com/doc/configuration/index.html
|
|
||||||
[rspamd-docs::config::quickstart]: https://rspamd.com/doc/tutorials/quickstart.html#configuring-rspamd
|
|
||||||
[rspamd-docs::config::global]: https://rspamd.com/doc/configuration/options.html
|
|
||||||
[rspamd-docs::config::workers]: https://rspamd.com/doc/workers/
|
|
||||||
[rspamd-docs::config::worker-controller]: https://rspamd.com/doc/workers/controller.html
|
|
||||||
[rspamd-docs::config::worker-proxy]: https://rspamd.com/doc/workers/rspamd_proxy.html
|
|
||||||
|
|
||||||
[wikipedia::arc]: https://en.wikipedia.org/wiki/Authenticated_Received_Chain
|
|
||||||
[rspamd-docs::arc]: https://rspamd.com/doc/modules/arc.html
|
|
||||||
|
|
||||||
[www::rbl-vs-dnsbl]: https://forum.eset.com/topic/25277-dnsbl-vs-rbl-mail-security/#comment-119818
|
|
||||||
[abusix-web]: https://abusix.com/
|
|
||||||
[abusix-web::register]: https://app.abusix.com/
|
|
||||||
[abusix-docs::rspamd-integration]: https://abusix.com/docs/rspamd/
|
|
||||||
[spamhaus::faq::dnsbl-usage]: https://www.spamhaus.org/faq/section/DNSBL%20Usage#365
|
|
||||||
|
|
||||||
[dms-repo::rspamd-actions-config]: https://github.com/docker-mailserver/docker-mailserver/tree/v15.0.0/target/rspamd/local.d/actions.conf
|
|
||||||
[dms-repo::default-rspamd-configuration]: https://github.com/docker-mailserver/docker-mailserver/tree/v15.0.0/target/rspamd
|
|
||||||
[gh-dms::guide::valkey]: https://github.com/docker-mailserver/docker-mailserver/issues/4001#issuecomment-2652596692
|
|
||||||
[gh-dms::guide::rspamd-web]: https://github.com/orgs/docker-mailserver/discussions/4269#discussioncomment-11329588
|
|
||||||
|
|
||||||
[docs::env::enable-redis]: ../environment.md#enable_rspamd_redis
|
|
||||||
[docs::spam-to-junk]: ../environment.md#move_spam_to_junk
|
|
||||||
[docs::dkim-dmarc-spf]: ../best-practices/dkim_dmarc_spf.md
|
|
||||||
[docs::dkim-with-rspamd]: ../best-practices/dkim_dmarc_spf.md#dkim
|
|
||||||
|
|
||||||
[docs::dms-volumes-config]: ../advanced/optional-config.md#volumes-config
|
|
||||||
[docs::dms-volumes-state]: ../advanced/optional-config.md#volumes-state
|
|
||||||
|
|
||||||
[docs::faq::dns-servers]: ../../faq.md#what-about-dns-servers
|
|
||||||
|
|
@ -1,966 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Security | TLS (aka SSL)'
|
|
||||||
---
|
|
||||||
|
|
||||||
There are multiple options to enable SSL (via [`SSL_TYPE`][docs-env::ssl-type]):
|
|
||||||
|
|
||||||
- Using [letsencrypt](#lets-encrypt-recommended) (recommended)
|
|
||||||
- Using [Caddy](#caddy)
|
|
||||||
- Using [Traefik](#traefik)
|
|
||||||
- Using [self-signed certificates](#self-signed-certificates)
|
|
||||||
- Using [your own certificates](#bring-your-own-certificates)
|
|
||||||
|
|
||||||
After installation, you can test your setup with:
|
|
||||||
|
|
||||||
- [`checktls.com`](https://www.checktls.com/TestReceiver)
|
|
||||||
- [`testssl.sh`](https://github.com/drwetter/testssl.sh)
|
|
||||||
|
|
||||||
!!! warning "Exposure of DNS labels through Certificate Transparency"
|
|
||||||
|
|
||||||
All public Certificate Authorities (CAs) are required to log certificates they issue publicly via [Certificate Transparency][certificate-transparency]. This helps to better establish trust.
|
|
||||||
|
|
||||||
When using a public CA for certificates used in private networks, be aware that the associated DNS labels in the certificate are logged publicly and [easily searchable][ct-search]. These logs are _append only_, you **cannot** redact this information.
|
|
||||||
|
|
||||||
You could use a [wildcard certificate][wildcard-cert]. This avoids accidentally leaking information to the internet, but keep in mind the [potential security risks][security::wildcard-cert] of wildcard certs.
|
|
||||||
|
|
||||||
## 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 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 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 DMS.
|
|
||||||
|
|
||||||
!!! example "Setting the hostname correctly"
|
|
||||||
|
|
||||||
Change `mail.example.com` below to your own FQDN.
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# CLI:
|
|
||||||
docker run --hostname mail.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
or
|
|
||||||
|
|
||||||
```yml
|
|
||||||
# compose.yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
hostname: mail.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
## Provisioning methods
|
|
||||||
|
|
||||||
### Let's Encrypt (Recommended)
|
|
||||||
|
|
||||||
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 DMS container:
|
|
||||||
|
|
||||||
- Add the environment variable `SSL_TYPE=letsencrypt`.
|
|
||||||
- Mount [your local `letsencrypt` folder][certbot::certs-storage] as a volume to `/etc/letsencrypt`.
|
|
||||||
|
|
||||||
You don't have to do anything else. Enjoy!
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
`/etc/letsencrypt/live` stores provisioned certificates in individual folders named by their FQDN.
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Add these additions to the `mailserver` service in your [`compose.yaml`][github-file-compose]:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
hostname: mail.example.com
|
|
||||||
environment:
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
volumes:
|
|
||||||
- /etc/letsencrypt:/etc/letsencrypt
|
|
||||||
```
|
|
||||||
|
|
||||||
#### 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 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]_):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# Requires access to port 80 from the internet, adjust your firewall if needed.
|
|
||||||
docker run --rm -it \
|
|
||||||
-v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
|
|
||||||
-v "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
|
|
||||||
-p 80:80 \
|
|
||||||
certbot/certbot certonly --standalone -d mail.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Add a volume for DMS that maps the _local `certbot/certs/` folder_ to the container path `/etc/letsencrypt/`.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Add these additions to the `mailserver` service in your [`compose.yaml`][github-file-compose]:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
hostname: mail.example.com
|
|
||||||
environment:
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/certbot/certs/:/etc/letsencrypt
|
|
||||||
```
|
|
||||||
|
|
||||||
3. The certificate setup is complete, but remember _it will expire_. Consider automating renewals.
|
|
||||||
|
|
||||||
!!! tip "Renewing Certificates"
|
|
||||||
|
|
||||||
When running the above `certonly --standalone` snippet again, the existing certificate is renewed if it would expire within 30 days.
|
|
||||||
|
|
||||||
Alternatively, Certbot can look at all the certificates it manages, and only renew those nearing their expiry via the [`renew` command][certbot::renew]:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# This will need access to port 443 from the internet, adjust your firewall if needed.
|
|
||||||
docker run --rm -it \
|
|
||||||
-v "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
|
|
||||||
-v "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
|
|
||||||
-p 80:80 \
|
|
||||||
-p 443:443 \
|
|
||||||
certbot/certbot renew
|
|
||||||
```
|
|
||||||
|
|
||||||
This process can also be [automated via _cron_ or _systemd timers_][certbot::automated-renewal].
|
|
||||||
|
|
||||||
- [Example with a systemd timer][certbot::automated-renewal::example-systemd-timer]
|
|
||||||
|
|
||||||
!!! note "Using a different ACME CA"
|
|
||||||
|
|
||||||
Certbot does support [alternative certificate providers via the `--server`][certbot::custom-ca] option. In most cases you'll want to use the default _Let's Encrypt_.
|
|
||||||
|
|
||||||
#### Example using `certbot-dns-cloudflare` with Docker { data-toc-label='certbot-dns-cloudflare with Docker' }
|
|
||||||
|
|
||||||
If you are unable get a certificate via the `HTTP-01` (port 80) or `TLS-ALPN-01` (port 443) [challenge types](https://letsencrypt.org/docs/challenge-types/), the `DNS-01` challenge can be useful (_this challenge can additionally issue wildcard certificates_). This guide shows how to use the `DNS-01` challenge with Cloudflare as your DNS provider.
|
|
||||||
|
|
||||||
Obtain a Cloudflare API token:
|
|
||||||
|
|
||||||
1. Login into your Cloudflare dashboard.
|
|
||||||
2. Navigate to the [API Tokens page](https://dash.cloudflare.com/profile/api-tokens).
|
|
||||||
3. Click "Create Token", and choose the `Edit zone DNS` template (_Certbot [requires the `ZONE:DNS:Edit` permission](https://certbot-dns-cloudflare.readthedocs.io/en/stable/#credentials)_).
|
|
||||||
|
|
||||||
!!! warning "Only include the necessary Zone resource configuration"
|
|
||||||
|
|
||||||
Be sure to configure "Zone Resources" section on this page to `Include -> Specific zone -> <your zone here>`.
|
|
||||||
|
|
||||||
This restricts the API token to only this zone (domain) which is an important security measure.
|
|
||||||
|
|
||||||
4. Store the _API token_ you received in a file `cloudflare.ini` with content:
|
|
||||||
|
|
||||||
```dosini
|
|
||||||
dns_cloudflare_api_token = YOUR_CLOUDFLARE_TOKEN_HERE
|
|
||||||
```
|
|
||||||
|
|
||||||
- As this is sensitive data, you should restrict access to it with `chmod 600` and `chown 0:0`.
|
|
||||||
- Store the file in a folder if you like, such as `docker-data/certbot/secrets/`.
|
|
||||||
|
|
||||||
5. Your `compose.yaml` should include the following:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
environments:
|
|
||||||
# Set SSL certificate type.
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
volumes:
|
|
||||||
# Mount the cert folder generated by Certbot:
|
|
||||||
- ./docker-data/certbot/certs/:/etc/letsencrypt/:ro
|
|
||||||
|
|
||||||
certbot-cloudflare:
|
|
||||||
image: certbot/dns-cloudflare:latest
|
|
||||||
command: certonly --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token -d mail.example.com
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/certbot/certs/:/etc/letsencrypt/
|
|
||||||
- ./docker-data/certbot/logs/:/var/log/letsencrypt/
|
|
||||||
secrets:
|
|
||||||
- cloudflare-api-token
|
|
||||||
|
|
||||||
# Docs: https://docs.docker.com/engine/swarm/secrets/#use-secrets-in-compose
|
|
||||||
# WARNING: In compose configs without swarm, the long syntax options have no effect,
|
|
||||||
# Ensure that you properly `chmod 600` and `chown 0:0` the file on disk. Effectively treated as a bind mount.
|
|
||||||
secrets:
|
|
||||||
cloudflare-api-token:
|
|
||||||
file: ./docker-data/certbot/secrets/cloudflare.ini
|
|
||||||
```
|
|
||||||
|
|
||||||
Alternative using the `docker run` command (`secrets` feature is not available):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker run \
|
|
||||||
--volume "${PWD}/docker-data/certbot/certs/:/etc/letsencrypt/" \
|
|
||||||
--volume "${PWD}/docker-data/certbot/logs/:/var/log/letsencrypt/" \
|
|
||||||
--volume "${PWD}/docker-data/certbot/secrets/:/tmp/secrets/certbot/"
|
|
||||||
certbot/dns-cloudflare \
|
|
||||||
certonly --dns-cloudflare --dns-cloudflare-credentials /tmp/secrets/certbot/cloudflare.ini -d mail.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
6. Run the service to provision a certificate:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker compose run certbot-cloudflare
|
|
||||||
```
|
|
||||||
|
|
||||||
7. You should see the following log output:
|
|
||||||
|
|
||||||
```log
|
|
||||||
Saving debug log to /var/log/letsencrypt/letsencrypt. log | Requesting a certificate for mail.example.com
|
|
||||||
Waiting 10 seconds for DNS changes to propagate
|
|
||||||
Successfully received certificate.
|
|
||||||
Certificate is saved at: /etc/letsencrypt/live/mail.example.com/fullchain.pem
|
|
||||||
Key is saved at: /etc/letsencrypt/live/mail.example.com/privkey.pem
|
|
||||||
This certificate expires on YYYY-MM-DD.
|
|
||||||
These files will be updated when the certificate renews.
|
|
||||||
NEXT STEPS:
|
|
||||||
- The certificate will need to be renewed before it expires. Certbot can automatically renew the certificate in background, but you may need to take steps to enable that functionality. See https://certbot.org/renewal instructions.
|
|
||||||
```
|
|
||||||
|
|
||||||
After completing the steps above, your certificate should be ready to use.
|
|
||||||
|
|
||||||
??? tip "Renewing a certificate (Optional)"
|
|
||||||
|
|
||||||
We've only demonstrated how to provision a certificate, but it will expire in 90 days and need to be renewed before then.
|
|
||||||
|
|
||||||
In the following example, add a new service (`certbot-cloudflare-renew`) into `compose.yaml` that will handle certificate renewals:
|
|
||||||
|
|
||||||
```yml
|
|
||||||
services:
|
|
||||||
certbot-cloudflare-renew:
|
|
||||||
image: certbot/dns-cloudflare:latest
|
|
||||||
command: renew --dns-cloudflare --dns-cloudflare-credentials /run/secrets/cloudflare-api-token
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/certbot/certs/:/etc/letsencrypt/
|
|
||||||
- ./docker-data/certbot/logs/:/var/log/letsencrypt/
|
|
||||||
secrets:
|
|
||||||
- cloudflare-api-token
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
You can manually run this service to renew the cert within 90 days:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker compose run certbot-cloudflare-renew
|
|
||||||
```
|
|
||||||
|
|
||||||
You should see the following output
|
|
||||||
(The following log was generated with `--dry-run` options)
|
|
||||||
|
|
||||||
```log
|
|
||||||
Saving debug log to /var/log/letsencrypt/letsencrypt.log
|
|
||||||
|
|
||||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
||||||
Processing /etc/letsencrypt/renewal/mail.example.com.conf
|
|
||||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
||||||
Account registered.
|
|
||||||
Simulating renewal of an existing certificate for mail.example.com
|
|
||||||
Waiting 10 seconds for DNS changes to propagate
|
|
||||||
|
|
||||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
||||||
Congratulations, all simulated renewals succeeded:
|
|
||||||
/etc/letsencrypt/live/mail.example.com/fullchain.pem (success)
|
|
||||||
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
|
|
||||||
```
|
|
||||||
|
|
||||||
It is recommended to automate this renewal via a task scheduler like a _systemd timer_ or in `crontab`
|
|
||||||
(`crontab` example: Checks every day if the certificate should be renewed)
|
|
||||||
|
|
||||||
```sh
|
|
||||||
0 0 * * * docker compose -f PATH_TO_YOUR_DOCKER_COMPOSE_YML up certbot-cloudflare-renew
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Example using `nginx-proxy` and `acme-companion` with Docker { data-toc-label='nginx-proxy with Docker' }
|
|
||||||
|
|
||||||
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 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`):
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker run --detach \
|
|
||||||
--name nginx-proxy \
|
|
||||||
--restart always \
|
|
||||||
--publish 80:80 \
|
|
||||||
--publish 443:443 \
|
|
||||||
--volume "${PWD}/docker-data/nginx-proxy/html/:/usr/share/nginx/html/" \
|
|
||||||
--volume "${PWD}/docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/" \
|
|
||||||
--volume "${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:ro" \
|
|
||||||
--volume '/var/run/docker.sock:/tmp/docker.sock:ro' \
|
|
||||||
nginxproxy/nginx-proxy
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Then start the _certificate provisioner_ (`acme-companion`), which will provide certificates to `nginx-proxy`:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# Inherit `nginx-proxy` volumes via `--volumes-from`, but make `certs/` writeable:
|
|
||||||
docker run --detach \
|
|
||||||
--name nginx-proxy-acme \
|
|
||||||
--restart always \
|
|
||||||
--volumes-from nginx-proxy \
|
|
||||||
--volume "${PWD}/docker-data/acme-companion/certs/:/etc/nginx/certs/:rw" \
|
|
||||||
--volume "${PWD}/docker-data/acme-companion/acme-state/:/etc/acme.sh/" \
|
|
||||||
--volume '/var/run/docker.sock:/var/run/docker.sock:ro' \
|
|
||||||
--env 'DEFAULT_EMAIL=admin@example.com' \
|
|
||||||
nginxproxy/acme-companion
|
|
||||||
```
|
|
||||||
|
|
||||||
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 DMS:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker run --detach \
|
|
||||||
--name webmail \
|
|
||||||
--env 'VIRTUAL_HOST=mail.example.com' \
|
|
||||||
--env 'LETSENCRYPT_HOST=mail.example.com' \
|
|
||||||
--env 'LETSENCRYPT_EMAIL=admin@example.com' \
|
|
||||||
nginx
|
|
||||||
```
|
|
||||||
|
|
||||||
You may want to add `--env LETSENCRYPT_TEST=true` to the above while testing, to avoid the _Let's Encrypt_ certificate generation rate limits.
|
|
||||||
|
|
||||||
5. Make sure your mount path to the `letsencrypt` certificates directory is correct. Edit your `compose.yaml` for the `mailserver` service to have volumes added like below:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
6. Then from the `compose.yaml` project directory, run: `docker compose up -d mailserver`.
|
|
||||||
|
|
||||||
#### 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 DMS (_Referencing: [`acme-companion` documentation][acme-companion::docs]_):
|
|
||||||
|
|
||||||
???+ example "Example: `compose.yaml`"
|
|
||||||
|
|
||||||
You should have an existing `compose.yaml` with a `mailserver` service. Below are the modifications to add for integrating with `nginx-proxy` and `acme-companion` services:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
# Add the following `environment` and `volumes` to your existing `mailserver` service:
|
|
||||||
mailserver:
|
|
||||||
environment:
|
|
||||||
# SSL_TYPE: Uses the `letsencrypt` method to find mounted certificates.
|
|
||||||
# VIRTUAL_HOST: The FQDN that `nginx-proxy` will configure itself to handle for HTTP[S] connections.
|
|
||||||
# LETSENCRYPT_HOST: The FQDN for a certificate that `acme-companion` will provision and renew.
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
- VIRTUAL_HOST=mail.example.com
|
|
||||||
- LETSENCRYPT_HOST=mail.example.com
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/acme-companion/certs/:/etc/letsencrypt/live/:ro
|
|
||||||
|
|
||||||
# If you don't yet have your own `nginx-proxy` and `acme-companion` setup,
|
|
||||||
# here is an example you can use:
|
|
||||||
reverse-proxy:
|
|
||||||
image: nginxproxy/nginx-proxy
|
|
||||||
container_name: nginx-proxy
|
|
||||||
restart: always
|
|
||||||
ports:
|
|
||||||
# Port 80: Required for HTTP-01 challenges to `acme-companion`.
|
|
||||||
# Port 443: Only required for containers that need access over HTTPS. TLS-ALPN-01 challenge not supported.
|
|
||||||
- "80:80"
|
|
||||||
- "443:443"
|
|
||||||
volumes:
|
|
||||||
# `certs/`: Managed by the `acme-companion` container (_read-only_).
|
|
||||||
# `docker.sock`: Required to interact with containers via the Docker API.
|
|
||||||
- ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
|
|
||||||
- ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
|
|
||||||
- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:ro
|
|
||||||
- /var/run/docker.sock:/tmp/docker.sock:ro
|
|
||||||
|
|
||||||
acme-companion:
|
|
||||||
image: nginxproxy/acme-companion
|
|
||||||
container_name: nginx-proxy-acme
|
|
||||||
restart: always
|
|
||||||
environment:
|
|
||||||
# When `volumes_from: [nginx-proxy]` is not supported,
|
|
||||||
# reference the _reverse-proxy_ `container_name` here:
|
|
||||||
- NGINX_PROXY_CONTAINER=nginx-proxy
|
|
||||||
volumes:
|
|
||||||
# `html/`: Write ACME HTTP-01 challenge files that `nginx-proxy` will serve.
|
|
||||||
# `vhost.d/`: To enable web access via `nginx-proxy` to HTTP-01 challenge files.
|
|
||||||
# `certs/`: To store certificates and private keys.
|
|
||||||
# `acme-state/`: To persist config and state for the ACME provisioner (`acme.sh`).
|
|
||||||
# `docker.sock`: Required to interact with containers via the Docker API.
|
|
||||||
- ./docker-data/nginx-proxy/html/:/usr/share/nginx/html/
|
|
||||||
- ./docker-data/nginx-proxy/vhost.d/:/etc/nginx/vhost.d/
|
|
||||||
- ./docker-data/acme-companion/certs/:/etc/nginx/certs/:rw
|
|
||||||
- ./docker-data/acme-companion/acme-state/:/etc/acme.sh/
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "Optional ENV vars worth knowing about"
|
|
||||||
|
|
||||||
[Per container ENV][acme-companion::env-container] that `acme-companion` will detect to override default provisioning settings:
|
|
||||||
|
|
||||||
- `LETSENCRYPT_TEST=true`: _Recommended during initial setup_. Otherwise the default production endpoint has a [rate limit of 5 duplicate certificates per week][letsencrypt::limits]. Overrides `ACME_CA_URI` to use the _Let's Encrypt_ staging endpoint.
|
|
||||||
- `LETSENCRYPT_EMAIL`: For when you don't use `DEFAULT_EMAIL` on `acme-companion`, or want to assign a different email contact for this container.
|
|
||||||
- `LETSENCRYPT_KEYSIZE`: Allows you to configure the type (RSA or ECDSA) and size of the private key for your certificate. Default is RSA 4096, but RSA 2048 is recommended.
|
|
||||||
- `LETSENCRYPT_RESTART_CONTAINER=true`: When the certificate is renewed, the entire container will be restarted to ensure the new certificate is used.
|
|
||||||
|
|
||||||
[`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.
|
|
||||||
- `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`.
|
|
||||||
- `CA_BUNDLE`: If you want to use a private CA instead of _Let's Encrypt_.
|
|
||||||
|
|
||||||
!!! tip "Alternative to required ENV on `mailserver` service"
|
|
||||||
|
|
||||||
While you will still need both `nginx-proxy` and `acme-companion` containers, you can manage certificates without adding ENV vars to containers. Instead the ENV is moved into a file and uses the `acme-companion` feature [Standalone certificates][acme-companion::standalone].
|
|
||||||
|
|
||||||
This requires adding another shared volume between `nginx-proxy` and `acme-companion`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
reverse-proxy:
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/
|
|
||||||
|
|
||||||
acme-companion:
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/nginx-proxy/conf.d/:/etc/nginx/conf.d/
|
|
||||||
- ./docker-data/acme-companion/standalone.sh:/app/letsencrypt_user_data:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
`acme-companion` mounts a shell script (`standalone.sh`), which defines variables to customize certificate provisioning:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# A list IDs for certificates to provision:
|
|
||||||
LETSENCRYPT_STANDALONE_CERTS=('mail')
|
|
||||||
|
|
||||||
# Each ID inserts itself into the standard `acme-companion` supported container ENV vars below.
|
|
||||||
# The LETSENCRYPT_<ID>_HOST var is a list of FQDNs to provision a certificate for as the SAN field:
|
|
||||||
LETSENCRYPT_mail_HOST=('mail.example.com')
|
|
||||||
|
|
||||||
# Optional variables:
|
|
||||||
LETSENCRYPT_mail_TEST=true
|
|
||||||
LETSENCRYPT_mail_EMAIL='admin@example.com'
|
|
||||||
# Supported values are `2048`, `3072` and `4096` for RSA keys, and `ec-256` or `ec-384` for elliptic curve keys.
|
|
||||||
LETSENCRYPT_mail_KEYSIZE=2048
|
|
||||||
```
|
|
||||||
|
|
||||||
Unlike with the equivalent ENV for containers, [changes to this file will **not** be detected automatically][acme-companion::standalone-changes]. You would need to wait until the next renewal check by `acme-companion` (_every hour by default_), restart `acme-companion`, or [manually invoke the _service loop_][acme-companion::service-loop]:
|
|
||||||
|
|
||||||
`#!bash docker exec nginx-proxy-acme /app/signal_le_service`
|
|
||||||
|
|
||||||
#### Example using _Let's Encrypt_ Certificates with a _Synology NAS_ { data-toc-label='Synology NAS' }
|
|
||||||
|
|
||||||
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/`.
|
|
||||||
|
|
||||||
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 `compose.yaml` declaration file:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- /usr/syno/etc/certificate/_archive/<your-folder>/:/tmp/dms/custom-certs/
|
|
||||||
environment:
|
|
||||||
- SSL_TYPE=manual
|
|
||||||
- SSL_CERT_PATH=/tmp/dms/custom-certs/fullchain.pem
|
|
||||||
- SSL_KEY_PATH=/tmp/dms/custom-certs/privkey.pem
|
|
||||||
```
|
|
||||||
|
|
||||||
DSM-generated letsencrypt certificates get auto-renewed every three months.
|
|
||||||
|
|
||||||
### Caddy
|
|
||||||
|
|
||||||
[Caddy][web::caddy] is an open-source web server with built-in TLS certificate generation. You can use the [official Docker image][dockerhub::caddy] and write your own `Caddyfile`.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
While DMS does not need a webserver to work, this workaround will provision a TLS certificate for DMS to use by adding a dummy site block to trigger cert provisioning.
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
# Basic Caddy service to provision certs:
|
|
||||||
reverse-proxy:
|
|
||||||
image: caddy:2.7
|
|
||||||
ports:
|
|
||||||
- 80:80
|
|
||||||
- 443:443
|
|
||||||
volumes:
|
|
||||||
- ./Caddyfile:/etc/caddy/Caddyfile:ro
|
|
||||||
- ${CADDY_DATA_DIR}:/data
|
|
||||||
|
|
||||||
# Share the Caddy data volume for certs and configure SSL_TYPE to `letsencrypt`
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
hostname: mail.example.com
|
|
||||||
environment:
|
|
||||||
SSL_TYPE: letsencrypt
|
|
||||||
# While you could use a named data volume instead of a bind mount volume, it would require the long-syntax to rename cert files:
|
|
||||||
# https://docs.docker.com/compose/compose-file/05-services/#volumes
|
|
||||||
volumes:
|
|
||||||
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
|
|
||||||
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
|
|
||||||
```
|
|
||||||
|
|
||||||
An explicit entry in your `Caddyfile` config will have Caddy provision and renew a certificate for your DMS FQDN:
|
|
||||||
|
|
||||||
```caddyfile title="Caddyfile"
|
|
||||||
mail.example.com {
|
|
||||||
# Optionally provision RSA 2048-bit certificate instead of ECDSA P-256:
|
|
||||||
tls {
|
|
||||||
key_type rsa2048
|
|
||||||
}
|
|
||||||
|
|
||||||
# Optional, can be useful for troubleshooting
|
|
||||||
# connection to Caddy with correct certificate:
|
|
||||||
respond "Hello DMS"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
An explicit `tls` directive affects only the site-address block it's used in:
|
|
||||||
|
|
||||||
- Use [`tls internal { ... }`][caddy-docs::tls-internal] if wanting to create a local self-signed cert, which may be useful for testing. This allows opt-in to use self-signed certs unlike the global `local_certs` option.
|
|
||||||
- [`key_type`][caddy-docs::key-type] can be used in the `tls` block if you need to enforce RSA as the key type for certificates provisioned. The default is currently ECDSA (P-256). This may improve compatibility with legacy clients.
|
|
||||||
|
|
||||||
??? example "With `caddy-docker-proxy`"
|
|
||||||
|
|
||||||
Using [`lucaslorentz/caddy-docker-proxy`][github::caddy-docker-proxy] allows you to generate a `Caddyfile` by adding labels to your services in `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
reverse-proxy:
|
|
||||||
image: lucaslorentz/caddy-docker-proxy:2.8
|
|
||||||
ports:
|
|
||||||
- 80:80
|
|
||||||
- 443:443
|
|
||||||
volumes:
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
- ${CADDY_DATA_DIR}:/data
|
|
||||||
labels:
|
|
||||||
# Set global config here, this option has an empty value to enable self-signed certs for local testing:
|
|
||||||
# NOTE: Remove this label when going to production.
|
|
||||||
caddy.local_certs: ""
|
|
||||||
|
|
||||||
# Use labels to configure Caddy to provision DMS certs
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
hostname: mail.example.com
|
|
||||||
environment:
|
|
||||||
SSL_TYPE: letsencrypt
|
|
||||||
volumes:
|
|
||||||
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.crt:/etc/letsencrypt/live/mail.example.com/fullchain.pem
|
|
||||||
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/mail.example.com.key:/etc/letsencrypt/live/mail.example.com/privkey.pem
|
|
||||||
labels:
|
|
||||||
# Set your DMS FQDN here to add the site-address into the generated Caddyfile:
|
|
||||||
caddy_0: mail.example.com
|
|
||||||
# Adding a dummy directive is required:
|
|
||||||
caddy_0.respond: "Hello DMS"
|
|
||||||
# Uncomment to make a proxy for Rspamd:
|
|
||||||
# caddy_1: rspamd.example.com
|
|
||||||
# caddy_1.reverse_proxy: "{{upstreams 11334}}"
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "Caddy certificate location varies"
|
|
||||||
|
|
||||||
The path contains the certificate provisioner used. This path may be different from the example above for you and may change over time when [multiple ACME provisioner services are used][dms-pr-feedback::caddy-provisioning-gotcha].
|
|
||||||
|
|
||||||
This can make the volume mounting for DMS to find the certificates non-deterministic, but you can [restrict provisioning to single service via the `acme_ca` setting][caddy::restrict-acme-provisioner].
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**NOTE:** Bind mounting a file directly instead of a directory will mount by inode. If the file is updated at renewal and this modifies the inode on the host system, then the container will still point to the old certificate.
|
|
||||||
|
|
||||||
If this happens, consider using our manual TLS type instead:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
environment:
|
|
||||||
SSL_TYPE: manual
|
|
||||||
SSL_CERT_PATH: /srv/tls/mail.example.com/mail.example.com.crt
|
|
||||||
SSL_KEY_PATH: /srv/tls/mail.example.com/mail.example.com.key
|
|
||||||
volumes:
|
|
||||||
- ${CADDY_DATA_DIR}/certificates/acme-v02.api.letsencrypt.org-directory/mail.example.com/:/srv/tls/mail.example.com/:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
### Traefik
|
|
||||||
|
|
||||||
[Traefik][traefik::github] is an open-source application proxy using the [ACME protocol][ietf::rfc::acme]. Traefik can request certificates for domains and subdomains, and it will take care of renewals, challenge negotiations, etc.
|
|
||||||
|
|
||||||
Traefik's storage format is natively supported if the `acme.json` store is mounted into the container at `/etc/letsencrypt/acme.json`. The file is also monitored for changes and will trigger a reload of the mail services (Postfix and Dovecot).
|
|
||||||
|
|
||||||
DMS will select it's certificate from `acme.json` prioritizing a match for the DMS FQDN (hostname), while also checking one DNS level up (_eg: `mail.example.com` => `example.com`_). Wildcard certificates are supported.
|
|
||||||
|
|
||||||
This setup only comes with one caveat - The domain has to be configured on another service for Traefik to actually request it from _Let's Encrypt_ (_i.e. Traefik will not issue a certificate without a service / router demanding it_).
|
|
||||||
|
|
||||||
???+ example "Example Code"
|
|
||||||
|
|
||||||
Here is an example setup for [`Docker Compose`](https://docs.docker.com/compose/):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
hostname: mail.example.com
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/traefik/acme.json:/etc/letsencrypt/acme.json:ro
|
|
||||||
environment:
|
|
||||||
SSL_TYPE: letsencrypt
|
|
||||||
SSL_DOMAIN: mail.example.com
|
|
||||||
# for a wildcard certificate, use
|
|
||||||
# SSL_DOMAIN: example.com
|
|
||||||
|
|
||||||
reverse-proxy:
|
|
||||||
image: docker.io/traefik:latest #v2.5
|
|
||||||
container_name: docker-traefik
|
|
||||||
ports:
|
|
||||||
- "80:80"
|
|
||||||
- "443:443"
|
|
||||||
command:
|
|
||||||
- --providers.docker
|
|
||||||
- --entrypoints.http.address=:80
|
|
||||||
- --entrypoints.http.http.redirections.entryPoint.to=https
|
|
||||||
- --entrypoints.http.http.redirections.entryPoint.scheme=https
|
|
||||||
- --entrypoints.https.address=:443
|
|
||||||
- --entrypoints.https.http.tls.certResolver=letsencrypt
|
|
||||||
- --certificatesresolvers.letsencrypt.acme.email=admin@example.com
|
|
||||||
- --certificatesresolvers.letsencrypt.acme.storage=/acme.json
|
|
||||||
- --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=http
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/traefik/acme.json:/acme.json
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
||||||
|
|
||||||
whoami:
|
|
||||||
image: docker.io/traefik/whoami:latest
|
|
||||||
labels:
|
|
||||||
- "traefik.http.routers.whoami.rule=Host(`mail.example.com`)"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Self-Signed Certificates
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Use self-signed certificates only for testing purposes!
|
|
||||||
|
|
||||||
This feature requires you to provide the following files into your [`docker-data/dms/config/ssl/` directory][docs::dms-volumes-config] (_internal location: `/tmp/docker-mailserver/ssl/`_):
|
|
||||||
|
|
||||||
- `<FQDN>-key.pem`
|
|
||||||
- `<FQDN>-cert.pem`
|
|
||||||
- `demoCA/cacert.pem`
|
|
||||||
|
|
||||||
Where `<FQDN>` is the FQDN you've configured for your DMS container.
|
|
||||||
|
|
||||||
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 [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:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
#! /bin/sh
|
|
||||||
mkdir -p demoCA
|
|
||||||
|
|
||||||
step certificate create "Smallstep Root CA" "demoCA/cacert.pem" "demoCA/cakey.pem" \
|
|
||||||
--no-password --insecure \
|
|
||||||
--profile root-ca \
|
|
||||||
--not-before "2021-01-01T00:00:00+00:00" \
|
|
||||||
--not-after "2031-01-01T00:00:00+00:00" \
|
|
||||||
--san "example.test" \
|
|
||||||
--san "mail.example.test" \
|
|
||||||
--kty RSA --size 2048
|
|
||||||
|
|
||||||
step certificate create "Smallstep Leaf" mail.example.test-cert.pem mail.example.test-key.pem \
|
|
||||||
--no-password --insecure \
|
|
||||||
--profile leaf \
|
|
||||||
--ca "demoCA/cacert.pem" \
|
|
||||||
--ca-key "demoCA/cakey.pem" \
|
|
||||||
--not-before "2021-01-01T00:00:00+00:00" \
|
|
||||||
--not-after "2031-01-01T00:00:00+00:00" \
|
|
||||||
--san "example.test" \
|
|
||||||
--san "mail.example.test" \
|
|
||||||
--kty RSA --size 2048
|
|
||||||
```
|
|
||||||
|
|
||||||
If you'd rather not install the CLI tool locally to run the `step` commands above; you can save the script above to a file such as `generate-certs.sh` (_and make it executable `chmod +x generate-certs.sh`_) in a directory that you want the certs to be placed (eg: `docker-data/dms/custom-certs/`), then use docker to run that script in a container:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# '--user' is to keep ownership of the files written to
|
|
||||||
# the local volume to use your systems User and Group ID values.
|
|
||||||
docker run --rm -it \
|
|
||||||
--user "$(id -u):$(id -g)" \
|
|
||||||
--volume "${PWD}/docker-data/dms/custom-certs/:/tmp/step-ca/" \
|
|
||||||
--workdir "/tmp/step-ca/" \
|
|
||||||
--entrypoint "/tmp/step-ca/generate-certs.sh" \
|
|
||||||
smallstep/step-ca
|
|
||||||
```
|
|
||||||
|
|
||||||
### Bring Your Own Certificates
|
|
||||||
|
|
||||||
You can also provide your own certificate files. Add these entries to your `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/custom-certs/:/tmp/dms/custom-certs/:ro
|
|
||||||
environment:
|
|
||||||
- SSL_TYPE=manual
|
|
||||||
# Values should match the file paths inside the container:
|
|
||||||
- SSL_CERT_PATH=/tmp/dms/custom-certs/public.crt
|
|
||||||
- SSL_KEY_PATH=/tmp/dms/custom-certs/private.key
|
|
||||||
```
|
|
||||||
|
|
||||||
This will mount the path where your certificate files reside locally into the _read-only_ container folder: `/tmp/dms/custom-certs`.
|
|
||||||
|
|
||||||
The local and internal paths may be whatever you prefer, so long as both `SSL_CERT_PATH` and `SSL_KEY_PATH` point to the correct internal file paths. The certificate files may also be named to your preference, but should be PEM encoded.
|
|
||||||
|
|
||||||
`SSL_ALT_CERT_PATH` and `SSL_ALT_KEY_PATH` are additional ENV vars to support a 2nd certificate as a fallback. Commonly known as hybrid or dual certificate support. This is useful for using a modern ECDSA as your primary certificate, and RSA as your fallback for older connections. They work in the same manner as the non-`ALT` versions.
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
You may have to restart DMS once the certificates change.
|
|
||||||
|
|
||||||
## Testing a Certificate is Valid
|
|
||||||
|
|
||||||
!!! example "Connect to DMS on port 25"
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker exec mailserver openssl s_client \
|
|
||||||
-connect 0.0.0.0:25 \
|
|
||||||
-starttls smtp \
|
|
||||||
-CApath /etc/ssl/certs/
|
|
||||||
```
|
|
||||||
|
|
||||||
The response should show the certificate chain with a line further down: `Verify return code: 0 (ok)`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
This example runs within the DMS container itself to verify the cert is working locally.
|
|
||||||
|
|
||||||
- Adjust the `-connect` IP if testing externally from another system. Additionally testing for port 143 (Dovecot IMAP) is encouraged (_change the protocol for `-starttls` from `smtp` to `imap`_).
|
|
||||||
- `-CApath` will help verify the certificate chain, provided the location contains the root CA that signed your TLS cert for DMS.
|
|
||||||
|
|
||||||
??? example "Verify certificate dates"
|
|
||||||
|
|
||||||
```sh
|
|
||||||
docker exec mailserver openssl s_client \
|
|
||||||
-connect 0.0.0.0:25 \
|
|
||||||
-starttls smtp \
|
|
||||||
-CApath /etc/ssl/certs/ \
|
|
||||||
2>/dev/null | openssl x509 -noout -dates
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip "Testing and troubleshooting"
|
|
||||||
|
|
||||||
If you need to test a connection without resolving DNS, `curl` can connect with `--resolve` option to map an FQDN + Port to an IP address, instead of the request address provided.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# NOTE: You may want to use `--insecure` if the cert was provisioned with a private CA not present on the curl client:
|
|
||||||
# Use `--verbose` for additional insights on the connection.
|
|
||||||
curl --resolve mail.example.com:443:127.0.0.1 https://mail.example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
Similarly with `openssl` you can connect to an IP as shown previously, but provide an explicit SNI if necessary with `-servername mail.example.com`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Both `curl` and `openssl` also support `-4` and `-6` for enforcing IPv4 or IPv6 lookup.
|
|
||||||
|
|
||||||
This can be useful, such as when [DNS resolves the IP to different servers leading to different certificates returned][dms-discussion::gotcha-fqdn-bad-dns]. As shown in that link, `step certificate inspect` is also handy for viewing details of the cert returned or on disk.
|
|
||||||
|
|
||||||
## Plain-Text Access
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Not recommended for purposes other than testing.
|
|
||||||
|
|
||||||
Add this to `docker-data/dms/config/dovecot.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
ssl = yes
|
|
||||||
disable_plaintext_auth=no
|
|
||||||
```
|
|
||||||
|
|
||||||
These options in conjunction mean:
|
|
||||||
|
|
||||||
- SSL/TLS is offered to the client, but the client isn't required to use it.
|
|
||||||
- The client is allowed to login with plaintext authentication even when SSL/TLS isn't enabled on the connection.
|
|
||||||
- **This is insecure**, because the plaintext password is exposed to the internet.
|
|
||||||
|
|
||||||
## Importing Certificates Obtained via Another Source
|
|
||||||
|
|
||||||
If you have another source for SSL/TLS certificates you can import them into the server via an external script. The external script can be found here: [external certificate import script][hanscees-renewcerts].
|
|
||||||
|
|
||||||
This is a community contributed script, and in most cases you will have better support via our _Change Detection_ service (_automatic for `SSL_TYPE` of `manual` and `letsencrypt`_) - Unless you're using LDAP which disables the service.
|
|
||||||
|
|
||||||
!!! warning "Script Compatibility"
|
|
||||||
|
|
||||||
- Relies on private filepaths `/etc/dms/tls/cert` and `/etc/dms/tls/key` intended for internal use only.
|
|
||||||
- Only supports hard-coded `fullchain.key` + `privkey.pem` as your mounted file names. That may not align with your provisioning method.
|
|
||||||
- No support for `ALT` fallback certificates (_for supporting dual/hybrid, RSA + ECDSA_).
|
|
||||||
|
|
||||||
The steps to follow are these:
|
|
||||||
|
|
||||||
1. Transfer the new certificates to `./docker-data/dms/custom-certs/` (volume mounted to: `/tmp/ssl/`)
|
|
||||||
2. You should provide `fullchain.key` and `privkey.pem`
|
|
||||||
3. Place the script in `./docker-data/dms/config/` (volume mounted to: `/tmp/docker-mailserver/`)
|
|
||||||
4. Make the script executable (`chmod +x tomav-renew-certs.sh`)
|
|
||||||
5. Run the script: `docker exec mailserver /tmp/docker-mailserver/tomav-renew-certs.sh`
|
|
||||||
|
|
||||||
If an error occurs the script will inform you. If not you will see both postfix and dovecot restart.
|
|
||||||
|
|
||||||
After the certificates have been loaded you can check the certificate:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
openssl s_client \
|
|
||||||
-servername mail.example.com \
|
|
||||||
-connect 192.168.0.72:465 \
|
|
||||||
2>/dev/null | openssl x509
|
|
||||||
|
|
||||||
# or
|
|
||||||
|
|
||||||
openssl s_client \
|
|
||||||
-servername mail.example.com \
|
|
||||||
-connect mail.example.com:465 \
|
|
||||||
2>/dev/null | openssl x509
|
|
||||||
```
|
|
||||||
|
|
||||||
Or you can check how long the new certificate is valid with commands like:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
export SITE_URL="mail.example.com"
|
|
||||||
export SITE_IP_URL="192.168.0.72" # can also use `mail.example.com`
|
|
||||||
export SITE_SSL_PORT="993" # imap port dovecot
|
|
||||||
|
|
||||||
##works: check if certificate will expire in two weeks
|
|
||||||
#2 weeks is 1209600 seconds
|
|
||||||
#3 weeks is 1814400
|
|
||||||
#12 weeks is 7257600
|
|
||||||
#15 weeks is 9072000
|
|
||||||
|
|
||||||
certcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \
|
|
||||||
-servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`
|
|
||||||
|
|
||||||
####################################
|
|
||||||
#notes: output could be either:
|
|
||||||
#Certificate will not expire
|
|
||||||
#Certificate will expire
|
|
||||||
####################
|
|
||||||
```
|
|
||||||
|
|
||||||
What does the script that imports the certificates do:
|
|
||||||
|
|
||||||
1. Check if there are new certs in the internal container folder: `/tmp/ssl`.
|
|
||||||
2. Check with the ssl cert fingerprint if they differ from the current certificates.
|
|
||||||
3. If so it will copy the certs to the right places.
|
|
||||||
4. And restart postfix and dovecot.
|
|
||||||
|
|
||||||
You can of course run the script by cron once a week or something. In that way you could automate cert renewal. If you do so it is probably wise to run an automated check on certificate expiry as well. Such a check could look something like this:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# This script is run inside docker-mailserver via 'docker exec ...', using the 'mail' command to send alerts.
|
|
||||||
## code below will alert if certificate expires in less than two weeks
|
|
||||||
## please adjust variables!
|
|
||||||
## make sure the 'mail -s' command works! Test!
|
|
||||||
|
|
||||||
export SITE_URL="mail.example.com"
|
|
||||||
export SITE_IP_URL="192.168.2.72" # can also use `mail.example.com`
|
|
||||||
export SITE_SSL_PORT="993" # imap port dovecot
|
|
||||||
# Below can be from a different domain; like your personal email, not handled by this docker-mailserver:
|
|
||||||
export ALERT_EMAIL_ADDR="external-account@gmail.com"
|
|
||||||
|
|
||||||
certcheck_2weeks=`openssl s_client -connect ${SITE_IP_URL}:${SITE_SSL_PORT} \
|
|
||||||
-servername ${SITE_URL} 2> /dev/null | openssl x509 -noout -checkend 1209600`
|
|
||||||
|
|
||||||
####################################
|
|
||||||
#notes: output can be
|
|
||||||
#Certificate will not expire
|
|
||||||
#Certificate will expire
|
|
||||||
####################
|
|
||||||
|
|
||||||
#echo "certcheck 2 weeks gives $certcheck_2weeks"
|
|
||||||
|
|
||||||
##automated check you might run by cron or something
|
|
||||||
## does the certificate expire within two weeks?
|
|
||||||
|
|
||||||
if [ "$certcheck_2weeks" = "Certificate will not expire" ]; then
|
|
||||||
echo "all is well, certwatch 2 weeks says $certcheck_2weeks"
|
|
||||||
else
|
|
||||||
echo "Cert seems to be expiring pretty soon, within two weeks: $certcheck_2weeks"
|
|
||||||
echo "we will send an alert email and log as well"
|
|
||||||
logger Certwatch: cert $SITE_URL will expire in two weeks
|
|
||||||
echo "Certwatch: cert $SITE_URL will expire in two weeks" | mail -s "cert $SITE_URL expires in two weeks " $ALERT_EMAIL_ADDR
|
|
||||||
fi
|
|
||||||
```
|
|
||||||
|
|
||||||
## Custom DH Parameters
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
[docs-env::ssl-type]: ../environment.md#ssl_type
|
|
||||||
[docs::dms-volumes-config]: ../advanced/optional-config.md#volumes-config
|
|
||||||
[docs-faq-baredomain]: ../../faq.md#can-i-use-a-nakedbare-domain-ie-no-hostname
|
|
||||||
|
|
||||||
[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml
|
|
||||||
[github-file::tls-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/3b8059f2daca80d967635e04d8d81e9abb755a4d/test/test-files/ssl/example.test/README.md
|
|
||||||
[hanscees-renewcerts]: https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-renew-certs
|
|
||||||
|
|
||||||
[traefik::github]: https://github.com/containous/traefik
|
|
||||||
[ietf::rfc::acme]: https://datatracker.ietf.org/doc/html/rfc8555
|
|
||||||
|
|
||||||
[ietf::rfc::ffdhe]: https://datatracker.ietf.org/doc/html/rfc7919
|
|
||||||
[ffdhe4096-src]: https://github.com/internetstandards/dhe_groups
|
|
||||||
[dh-avoid-selfgenerated]: https://crypto.stackexchange.com/questions/29926/what-diffie-hellman-parameters-should-i-use
|
|
||||||
|
|
||||||
[certificate-transparency]: https://certificate.transparency.dev/
|
|
||||||
[ct-search]: https://crt.sh/
|
|
||||||
[wildcard-cert]: https://en.wikipedia.org/wiki/Wildcard_certificate#Examples
|
|
||||||
[security::wildcard-cert]: https://gist.github.com/joepie91/7e5cad8c0726fd6a5e90360a754fc568
|
|
||||||
[letsencrypt::limits]: https://letsencrypt.org/docs/rate-limits/
|
|
||||||
|
|
||||||
[certbot::github]: https://github.com/certbot/certbot
|
|
||||||
[certbot::certs-storage]: https://certbot.eff.org/docs/using.html#where-are-my-certificates
|
|
||||||
[certbot::log-rotation]: https://certbot.eff.org/docs/using.html#log-rotation
|
|
||||||
[certbot::docker]: https://certbot.eff.org/docs/install.html#running-with-docker
|
|
||||||
[certbot::standalone]: https://certbot.eff.org/docs/using.html#standalone
|
|
||||||
[certbot::renew]: https://certbot.eff.org/docs/using.html#renewing-certificates
|
|
||||||
[certbot::automated-renewal]: https://certbot.eff.org/docs/using.html#automated-renewals
|
|
||||||
[certbot::automated-renewal::example-systemd-timer]: https://github.com/orgs/docker-mailserver/discussions/3917#discussioncomment-8661690
|
|
||||||
[certbot::custom-ca]: https://certbot.eff.org/docs/using.htmlchanging-the-acme-server
|
|
||||||
[certbot::webroot]: https://certbot.eff.org/docs/using.html#webroot
|
|
||||||
|
|
||||||
[nginx-proxy::github]: https://github.com/nginx-proxy/nginx-proxy
|
|
||||||
[acme-companion::github]: https://github.com/nginx-proxy/acme-companion
|
|
||||||
[acme-companion::docs]: https://github.com/nginx-proxy/acme-companion/blob/main/docs
|
|
||||||
[acme-companion::basic-setup]: https://github.com/nginx-proxy/acme-companion#basic-usage-with-the-nginx-proxy-container
|
|
||||||
[acme-companion::env-container]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md
|
|
||||||
[acme-companion::env-config]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Container-configuration.md
|
|
||||||
[acme-companion::troubleshooting]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Invalid-authorizations.md
|
|
||||||
[acme-companion::standalone]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Standalone-certificates.md
|
|
||||||
[acme-companion::standalone-changes]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Standalone-certificates.md#picking-up-changes-to-letsencrypt_user_data
|
|
||||||
[acme-companion::service-loop]: https://github.com/nginx-proxy/acme-companion/blob/main/docs/Container-utilities.md
|
|
||||||
|
|
||||||
[web::caddy]: https://caddyserver.com
|
|
||||||
[dockerhub::caddy]: https://hub.docker.com/_/caddy
|
|
||||||
[github::caddy-docker-proxy]: https://github.com/lucaslorentz/caddy-docker-proxy
|
|
||||||
[dms-pr-feedback::caddy-provisioning-gotcha]: https://github.com/docker-mailserver/docker-mailserver/pull/3485/files#r1297512818
|
|
||||||
[caddy-docs::tls-internal]: https://caddyserver.com/docs/caddyfile/directives/tls#syntax
|
|
||||||
[caddy-docs::key-type]: https://caddyserver.com/docs/caddyfile/options#key-type
|
|
||||||
[caddy::restrict-acme-provisioner]: https://caddy.community/t/is-there-a-way-on-a-caddyfile-to-force-a-specific-acme-ca/14506
|
|
||||||
|
|
||||||
[dms-discussion::gotcha-fqdn-bad-dns]: https://github.com/docker-mailserver/docker-mailserver/issues/3955#issuecomment-2027882633
|
|
||||||
|
|
@ -1,162 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Security | Understanding the Ports'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Reference
|
|
||||||
|
|
||||||
Prefer ports with Implicit [TLS][wikipedia-tls] ports, they're more secure than ports using Explicit TLS, and if you use a Reverse Proxy should be less hassle.
|
|
||||||
|
|
||||||
## Overview of Email Ports
|
|
||||||
|
|
||||||
| Protocol | Explicit TLS<sup>1</sup> | Implicit TLS | Purpose | Enabled by Default |
|
|
||||||
|--------------------------|--------------------------|-----------------|----------------------|--------------------|
|
|
||||||
| [ESMTP][wikipedia-esmtp] | 25 | N/A | Transfer<sup>2</sup> | Yes |
|
|
||||||
| ESMTP | 587 | 465<sup>3</sup> | Submission | Yes |
|
|
||||||
| 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, 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"
|
|
||||||
|
|
||||||
There is a common misconception of this port due to it's history detailed by various communities and blogs articles on the topic (_including by popular mail relay services_).
|
|
||||||
|
|
||||||
Port 465 was [briefly assigned the role of SMTPS in 1997][wikipedia-smtps] as an secure alternative to Port 25 between MTA exchanges. Then RFC 2487 (`STARTTLS`) [while still in a draft status in late 1998 had IANA revoke the SMTPS assignment][history-465-revoked]. The [draft history was modified to exclude all mention of port 465 and SMTPS][history-465-politics].
|
|
||||||
|
|
||||||
In 2018 [RFC 8314][rfc-8314] was published which revives Port 465 as an Implicit TLS alternative to Port 587 for mail submission. It details very clearly that gaining adoption of 465 as the preferred port will take time. IANA reassigned [port 465 as the `submissions` service][iana-services-465]. Any unofficial usage as **SMTPS is legacy and has been for over two decades**.
|
|
||||||
|
|
||||||
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
|
|
||||||
flowchart LR
|
|
||||||
subgraph your-server ["Your Server"]
|
|
||||||
in_25(25) --> server
|
|
||||||
in_465(465) --> server
|
|
||||||
server(("docker-mailserver<br/>hello@world.com"))
|
|
||||||
server --- out_25(25)
|
|
||||||
server --- out_465(465)
|
|
||||||
end
|
|
||||||
|
|
||||||
third-party("Third-party<br/>(sending you email)") ---|"Receive email for<br/>hello@world.com"| in_25
|
|
||||||
|
|
||||||
subgraph clients ["Clients (MUA)"]
|
|
||||||
mua-client(Thunderbird,<br/>Webmail,<br/>Mutt,<br/>etc)
|
|
||||||
mua-service(Backend software<br/>on another server)
|
|
||||||
end
|
|
||||||
clients ---|"Send email as<br/>hello@world.com"| in_465
|
|
||||||
|
|
||||||
out_25(25) -->|"Direct<br/>Delivery"| tin_25
|
|
||||||
out_465(465) --> relay("MTA<br/>Relay Server") --> tin_25(25)
|
|
||||||
|
|
||||||
subgraph third-party-server["Third-party Server"]
|
|
||||||
third-party-mta("MTA<br/>friend@example.com")
|
|
||||||
tin_25(25) --> third-party-mta
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
#### Inbound Traffic (On the left)
|
|
||||||
|
|
||||||
Mail arriving at your server will be processed and stored in a mailbox, or sent outbound to another mail server.
|
|
||||||
|
|
||||||
- **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.
|
|
||||||
- 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 (_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 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 DMS is not involved in, and thus unable to ensure encrypted transit throughout delivery.
|
|
||||||
|
|
||||||
#### Outbound Traffic (On the Right)
|
|
||||||
|
|
||||||
Mail being sent from your server is either being relayed through another MTA (eg: SendGrid), or direct to an MTA responsible for an email address (eg: Gmail).
|
|
||||||
|
|
||||||
- **Port 25:**
|
|
||||||
- As most MTA use port 25 to receive inbound mail, when no authenticated relay is involved this is the outbound port used.
|
|
||||||
- Outbound traffic on this port is often blocked by service providers (eg: VPS, ISP) to prevent abuse by spammers. If the port cannot be unblocked, you will need to relay outbound mail through a service to send on your behalf.
|
|
||||||
- **Port 465 and 587:**
|
|
||||||
- Submission ports for outbound traffic establish trust to forward mail through a third-party relay service. This requires [authenticating to an account on the relay service][docs-relays]. The relay will then deliver the mail through port 25 on your behalf.
|
|
||||||
- These are the two typical ports used, but smart hosts like SendGrid often document support for additional non-standard ports as alternatives if necessary.
|
|
||||||
- Usually you'll only use these outbound ports for relaying. It is possible to deliver directly to the relevant MTA for email address, but requires having credentials for each MTA.
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
At best, you can only ensure a secure connection between the MTA you directly connect to. The receiving MTA may relay that mail to another MTA (_and so forth_), each connection may not be enforcing TLS.
|
|
||||||
|
|
||||||
|
|
||||||
### Explicit vs Implicit TLS
|
|
||||||
|
|
||||||
#### Explicit TLS (aka Opportunistic TLS) - Opt-in Encryption
|
|
||||||
|
|
||||||
Communication on these ports begin in [cleartext][ref-clear-vs-plain]. Upgrading to an encrypted connection must be requested explicitly through the `STARTTLS` protocol **and** successfully negotiated.
|
|
||||||
|
|
||||||
Sometimes a reverse-proxy is involved, but is misconfigured or lacks support for the `STARTTLS` negotiation to succeed.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
- 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
|
|
||||||
|
|
||||||
`STARTTLS` [continues to have vulnerabilities found][starttls-vulnerabilities] (Nov 2021 article), as per [RFC 8314 (Section 4.1)][rfc-8314-s41] you are encouraged to **prefer Implicit TLS where possible**.
|
|
||||||
|
|
||||||
Support for `STARTTLS` is not always implemented correctly, which can lead to leaking credentials (like a client sending too early) prior to a TLS connection being established. Third-parties such as some ISPs have also been known to intercept the `STARTTLS` exchange, modifying network traffic to prevent establishing a secure connection.
|
|
||||||
|
|
||||||
|
|
||||||
#### Implicit TLS - Enforced Encryption
|
|
||||||
|
|
||||||
Communication on these ports are always encrypted (_enforced, thus implicit_), avoiding the potential risks with `STARTTLS` (Explicit TLS).
|
|
||||||
|
|
||||||
While Explicit TLS can provide the same benefit (_when `STARTTLS` is successfully negotiated_), Implicit TLS more reliably avoids concerns with connection manipulation and compatibility.
|
|
||||||
|
|
||||||
|
|
||||||
## Security
|
|
||||||
|
|
||||||
!!! todo
|
|
||||||
|
|
||||||
This section should provide any related configuration advice, and probably expand on and link to resources about DANE, DNSSEC, MTA-STS and STARTTLS Policy list, with advice on how to configure/setup these added security layers.
|
|
||||||
|
|
||||||
!!! todo
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Other machines that facilitate a connection that generally aren't taken into account can exist between a client and server, such as those where your connection passes through your ISP provider are capable of compromising a `cleartext` connection through interception.
|
|
||||||
|
|
||||||
[docs-accounts]: ../account-management/overview.md#accounts
|
|
||||||
[docs-relays]: ../advanced/mail-forwarding/relay-hosts.md
|
|
||||||
[iana-services-465]: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=465
|
|
||||||
[starttls-policy-list]: https://github.com/EFForg/starttls-everywhere#email-security-database-starttls-policy-list
|
|
||||||
[starttls-vulnerabilities]: https://blog.apnic.net/2021/11/18/vulnerabilities-show-why-starttls-should-be-avoided-if-possible/
|
|
||||||
[ref-clear-vs-plain]: https://www.denimgroup.com/resources/blog/2007/10/cleartext-vs-pl
|
|
||||||
[ref-port25-mandatory]: https://serverfault.com/questions/623692/is-it-still-wrong-to-require-starttls-on-incoming-smtp-messages
|
|
||||||
[rfc-8314]: https://tools.ietf.org/html/rfc8314
|
|
||||||
[rfc-8314-s41]: https://tools.ietf.org/html/rfc8314#section-4.1
|
|
||||||
[history-465-revoked]: https://web.archive.org/web/20150603202057/http://www.imc.org/ietf-apps-tls/mail-archive/msg00204.html
|
|
||||||
[history-465-politics]: https://mailing.postfix.users.narkive.com/F3ACwg2F/which-port-to-use-for-ssl-tls#post21
|
|
||||||
[postfix-upstream-config-mastercf]: https://github.com/vdukhovni/postfix/blob/62931e5b1f9f1e80d02a496c7fd0062a5aae1d25/postfix/conf/master.cf#L38-L41
|
|
||||||
[wikipedia-smtps]: https://en.wikipedia.org/wiki/SMTPS#History
|
|
||||||
[wikipedia-esmtp]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol#Modern_SMTP
|
|
||||||
[wikipedia-tls]: https://en.wikipedia.org/wiki/Transport_Layer_Security
|
|
||||||
|
|
@ -1,28 +0,0 @@
|
||||||
---
|
|
||||||
title: About setup.sh
|
|
||||||
hide:
|
|
||||||
- toc
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
`setup.sh` is not required. We encourage you to use `docker exec -ti <CONTAINER NAME> setup` instead.
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
This script assumes Docker or Podman is used. You will not be able to use `setup.sh` with other container orchestration tools.
|
|
||||||
|
|
||||||
[`setup.sh`][github-file-setupsh] is a script that is complimentary to the internal `setup` command in DMS.
|
|
||||||
|
|
||||||
It mostly provides the convenience of aliasing `docker exec -ti <CONTAINER NAME> setup`, inferring the container name of a running DMS instance or running a new instance and bind mounting necessary volumes implicitly.
|
|
||||||
|
|
||||||
It is intended to be run from the host machine, _not_ from inside your running container. The latest version of the script is included in the DMS repository. You may retrieve it at any time by running this command in your console:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
wget https://raw.githubusercontent.com/docker-mailserver/docker-mailserver/master/setup.sh
|
|
||||||
chmod a+x ./setup.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
For more information on using the script run: `./setup.sh help`.
|
|
||||||
|
|
||||||
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh
|
|
||||||
|
|
@ -1,34 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Contributing | General Information'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Coding Style
|
|
||||||
|
|
||||||
When refactoring, writing or altering scripts or other files, adhere to these rules:
|
|
||||||
|
|
||||||
1. **Adjust your style of coding to the style that is already present**! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all scripts consistent.
|
|
||||||
2. **Use `shellcheck` to check your scripts**! Your contributions are checked by GitHub Actions too, so you will need to do this. You can **lint your work with `make lint`** to check against all targets.
|
|
||||||
3. **Use the provided `.editorconfig`** file.
|
|
||||||
4. Use `/bin/bash` instead of `/bin/sh` in scripts
|
|
||||||
|
|
||||||
## Documentation
|
|
||||||
|
|
||||||
Make sure to select `edge` in the dropdown menu at the top. Navigate to the page you would like to edit and click the edit button in the top right. This allows you to make changes and create a pull-request.
|
|
||||||
|
|
||||||
Alternatively you can make the changes locally. For that you'll need to have Docker installed and run:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# From the root directory of the git clone:
|
|
||||||
docker run --rm -it -p 8000:8000 -v "./docs:/docs" squidfunk/mkdocs-material
|
|
||||||
```
|
|
||||||
|
|
||||||
This serves the documentation on your local machine on port `8000`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result.
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
The container logs will inform you of invalid links detected, but a [few are false-positives][gh-dms::mkdocs-link-error-false-positives] due to our usage of linking to specific [content tabs][mkdocs::content-tabs].
|
|
||||||
|
|
||||||
[get-docker]: https://docs.docker.com/get-docker/
|
|
||||||
[docs-bats-parallel]: https://bats-core.readthedocs.io/en/v1.8.2/usage.html#parallel-execution
|
|
||||||
[gh-dms::mkdocs-link-error-false-positives]: https://github.com/docker-mailserver/docker-mailserver/pull/4366
|
|
||||||
[mkdocs::content-tabs]: https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#anchor-links
|
|
||||||
|
|
@ -1,59 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Contributing | Issues and Pull Requests'
|
|
||||||
---
|
|
||||||
|
|
||||||
This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation.
|
|
||||||
|
|
||||||
## Opening an Issue
|
|
||||||
|
|
||||||
!!! attention
|
|
||||||
|
|
||||||
**Before opening an issue**, read the [`README`][github-file-readme] carefully, study the docs for your version (maybe [latest][docs-latest]), the Postfix/Dovecot documentation and your search engine you trust. The issue tracker is not meant to be used for unrelated questions!
|
|
||||||
|
|
||||||
When opening an issue, please provide details use case to let the community reproduce your problem. Please start DMS with the environment variable `LOG_LEVEL` set to `debug` or `trace` and paste the output into the issue.
|
|
||||||
|
|
||||||
!!! attention
|
|
||||||
|
|
||||||
**Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed.
|
|
||||||
|
|
||||||
By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.
|
|
||||||
|
|
||||||
Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and **comply with the rules**.
|
|
||||||
|
|
||||||
### Filing a Bug Report
|
|
||||||
|
|
||||||
Thank you for participating in this project and reporting a bug. Docker Mail Server (DMS) is a community-driven project, and each contribution counts!
|
|
||||||
|
|
||||||
Maintainers and moderators are volunteers. We greatly appreciate reports that take the time to provide detailed information via the template, enabling us to help you in the best and quickest way. Ignoring the template provided may seem easier, but discourages receiving any support (_via assignment of the label `meta/no template - no support`_).
|
|
||||||
|
|
||||||
Markdown formatting can be used in almost all text fields (_unless stated otherwise in the description_).
|
|
||||||
|
|
||||||
Be as precise as possible, and if in doubt, it's best to add more information that too few.
|
|
||||||
|
|
||||||
When an option is marked with "not officially supported" / "unsupported", then support is dependent on availability from specific maintainers.
|
|
||||||
|
|
||||||
## Pull Requests
|
|
||||||
|
|
||||||
!!! question "Motivation"
|
|
||||||
|
|
||||||
You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results.
|
|
||||||
|
|
||||||
### Submit a Pull-Request
|
|
||||||
|
|
||||||
The development workflow is the following:
|
|
||||||
|
|
||||||
1. Fork the project and clone your fork with `git clone --recurse-submodules ...` or run `git submodule update --init --recursive` after you cloned your fork
|
|
||||||
2. Write the code that is needed :D
|
|
||||||
3. Add integration tests if necessary
|
|
||||||
4. [Prepare your environment and run linting and tests][docs::contributing::tests]
|
|
||||||
5. Document your improvements if necessary (e.g. if you introduced new environment variables, describe those in the [ENV documentation][docs::env]) and add your changes the changelog under the "Unreleased" section
|
|
||||||
6. [Commit][commit] (and [sign your commit][gpg]), push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist.
|
|
||||||
|
|
||||||
Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new `:edge` image immediately and your changes will be includes in the next version release.
|
|
||||||
|
|
||||||
[docs-latest]: https://docker-mailserver.github.io/docker-mailserver/latest
|
|
||||||
[github-file-readme]: https://github.com/docker-mailserver/docker-mailserver/blob/master/README.md
|
|
||||||
[docs::env]: ../config/environment.md
|
|
||||||
[docs::contributing::tests]: ./tests.md
|
|
||||||
[commit]: https://help.github.com/articles/closing-issues-via-commit-messages/
|
|
||||||
[gpg]: https://docs.github.com/en/github/authenticating-to-github/generating-a-new-gpg-key
|
|
||||||
|
|
@ -1,143 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tests'
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! quote "_Program testing can be used to show the presence of bugs, but never to show their absence!_"
|
|
||||||
|
|
||||||
– Edsger Wybe Dijkstra
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
DMS employs a variety of unit and integration tests. All tests and associated configuration is stored in the `test/` directory. If you want to change existing functionality or integrate a new feature into DMS, you will probably need to work with our test suite.
|
|
||||||
|
|
||||||
!!! question "Can I use macOS?"
|
|
||||||
|
|
||||||
We do not support running linting, tests, etc. on macOS at this time. Please use a Linux VM, Debian/Ubuntu is recommended.
|
|
||||||
|
|
||||||
### About
|
|
||||||
|
|
||||||
We use [BATS] (_Bash Automated Testing System_) and additional support libraries. BATS is very similar to Bash, and one can easily and quickly get an understanding of how tests in a single file are run. A [test file template][template-test] provides a minimal working example for newcomers to look at.
|
|
||||||
|
|
||||||
### Structure
|
|
||||||
|
|
||||||
The `test/` directory contains multiple directories. Among them is the `bats/` directory (_which is the [BATS] git submodule_) and the `helper/` directory. The latter is especially interesting because it contains common support functionality used in almost every test. Actual tests are located in `test/tests/`.
|
|
||||||
|
|
||||||
!!! warning "Test suite undergoing refactoring"
|
|
||||||
|
|
||||||
We are currently in the process of restructuring all of our tests. Tests will be moved into `test/tests/parallel/` and new tests should be placed there as well.
|
|
||||||
|
|
||||||
### Using Our Helper Functions
|
|
||||||
|
|
||||||
There are many functions that aid in writing tests. **We urge you to use them!** They will not only ease writing a test but they will also do their best to ensure there are no race conditions or other unwanted side effects. To learn about the functions we provide, you can:
|
|
||||||
|
|
||||||
1. look into existing tests for helper functions we already used
|
|
||||||
2. look into the `test/helper/` directory which contains all files that can (and will) be loaded in test files
|
|
||||||
|
|
||||||
We encourage you to try both of the approaches mentioned above. To make understanding and using the helper functions easy, every function contains detailed documentation comments. Read them carefully!
|
|
||||||
|
|
||||||
### How Are Tests Run?
|
|
||||||
|
|
||||||
Tests are split into two categories:
|
|
||||||
|
|
||||||
- **`test/tests/parallel/`:** Multiple test files are run concurrently to reduce the required time to complete the test suite. A test file will presently run it's own defined test-cases in a sequential order.
|
|
||||||
- **`test/tests/serial/`:** Each test file is queued up to run sequentially. Tests that are unable to support running concurrently belong here.
|
|
||||||
|
|
||||||
Parallel tests are further partitioned into smaller sets. If your system has the resources to support running more than one of those sets at a time this is perfectly ok (_our CI runs tests by distributing the sets across multiple test runners_). Care must be taken not to mix running the serial tests while a parallel set is also running; this is handled for you when using `make tests`.
|
|
||||||
|
|
||||||
## Running Tests
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
To run the test suite, you will need to:
|
|
||||||
|
|
||||||
1. [Install Docker][get-docker]
|
|
||||||
2. Install `jq` , (GNU) `parallel` and `file` (under Ubuntu, use `sudo apt-get -y install jq parallel file`)
|
|
||||||
3. Execute `git submodule update --init --recursive` if you haven't already initialized the git submodules
|
|
||||||
|
|
||||||
### Executing Test(s)
|
|
||||||
|
|
||||||
We use `make` to run commands.
|
|
||||||
|
|
||||||
1. Run `make build` to create or update the local `mailserver-testing:ci` Docker image (_using the projects `Dockerfile`_)
|
|
||||||
2. Run all tests: `make clean tests`
|
|
||||||
3. Run a single test: `make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>`
|
|
||||||
4. Run multiple unrelated tests: `make clean generate-accounts test/<TEST NAME WITHOUT .bats SUFFIX>,<TEST NAME WITHOUT .bats SUFFIX>` (just add a `,` and then immediately write the new test name)
|
|
||||||
5. Run a whole set or all serial tests: `make clean generate-accounts tests/parallel/setX` where `X` is the number of the set or `make clean generate-accounts tests/serial`
|
|
||||||
|
|
||||||
??? tip "Setting the Degree of Parallelization for Tests"
|
|
||||||
|
|
||||||
If your machine is capable, you can increase the amount of tests that are run simultaneously by prepending the `make clean all` command with `BATS_PARALLEL_JOBS=X` (i.e. `BATS_PARALLEL_JOBS=X make clean all`). This wil speed up the test procedure. You can also run all tests in serial by setting `BATS_PARALLEL_JOBS=1` this way.
|
|
||||||
|
|
||||||
The default value of `BATS_PARALLEL_JOBS` is 2. This can be increased if your system has the resources spare to support running more jobs at once to complete the test suite sooner.
|
|
||||||
|
|
||||||
!!! warning "Test Output when Running in Parallel"
|
|
||||||
|
|
||||||
[When running tests in parallel][docs-bats-parallel] (_with `make clean generate-accounts tests/parallel/setX`_), BATS will delay outputting the results until completing all test cases within a file.
|
|
||||||
|
|
||||||
This likewise delays the reporting of test-case failures. When troubleshooting parallel set tests, you may prefer to run specific tests you're working on serially (_as demonstrated in the example below_).
|
|
||||||
|
|
||||||
When writing tests, ensure that parallel set tests still pass when run in parallel. You need to account for other tests running in parallel that may interfere with your own tests logic.
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
You may use `make run-local-instance` to run a version of the image built locally to test and edit your changes in a running DMS instance.
|
|
||||||
|
|
||||||
### An Example
|
|
||||||
|
|
||||||
In this example, you've made a change to the Rspamd feature support (_or adjusted it's tests_). First verify no regressions have been introduced by running it's specific test file:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ make clean generate-accounts test/rspamd
|
|
||||||
rspamd.bats
|
|
||||||
✓ [Rspamd] Postfix's main.cf was adjusted [12]
|
|
||||||
✓ [Rspamd] normal mail passes fine [44]
|
|
||||||
✓ [Rspamd] detects and rejects spam [122]
|
|
||||||
✓ [Rspamd] detects and rejects virus [189]
|
|
||||||
```
|
|
||||||
|
|
||||||
As your feature work progresses your change for Rspamd also affects ClamAV. As your change now spans more than just the Rspamd test file, you could run multiple test files serially:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ make clean generate-accounts test/rspamd,clamav
|
|
||||||
rspamd.bats
|
|
||||||
✓ [Rspamd] Postfix's main.cf was adjusted [12]
|
|
||||||
✓ [Rspamd] normal mail passes fine [44]
|
|
||||||
✓ [Rspamd] detects and rejects spam [122]
|
|
||||||
✓ [Rspamd] detects and rejects virus [189]
|
|
||||||
|
|
||||||
clamav.bats
|
|
||||||
✓ [ClamAV] log files exist at /var/log/mail directory [68]
|
|
||||||
✓ [ClamAV] should be identified by Amavis [67]
|
|
||||||
✓ [ClamAV] freshclam cron is enabled [76]
|
|
||||||
✓ [ClamAV] env CLAMAV_MESSAGE_SIZE_LIMIT is set correctly [63]
|
|
||||||
✓ [ClamAV] rejects virus [60]
|
|
||||||
```
|
|
||||||
|
|
||||||
You're almost finished with your change before submitting it as a PR. It's a good idea to run the full parallel set those individual tests belong to (_especially if you've modified any tests_):
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ make clean generate-accounts tests/parallel/set1
|
|
||||||
default_relay_host.bats
|
|
||||||
✓ [Relay] (ENV) 'DEFAULT_RELAY_HOST' should configure 'main.cf:relayhost' [88]
|
|
||||||
|
|
||||||
spam_virus/amavis.bats
|
|
||||||
✓ [Amavis] SpamAssassin integration should be active [1165]
|
|
||||||
|
|
||||||
spam_virus/clamav.bats
|
|
||||||
✓ [ClamAV] log files exist at /var/log/mail directory [73]
|
|
||||||
✓ [ClamAV] should be identified by Amavis [67]
|
|
||||||
✓ [ClamAV] freshclam cron is enabled [76]
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
Even better, before opening a PR run the full test suite:
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ make clean tests
|
|
||||||
```
|
|
||||||
|
|
||||||
[BATS]: https://github.com/bats-core/bats-core
|
|
||||||
[template-test]: https://github.com/docker-mailserver/docker-mailserver/blob/master/test/tests/parallel/set2/template.bats
|
|
||||||
[testing-prs]: https://github.com/docker-mailserver/docker-mailserver/blob/master/.github/workflows/test_merge_requests.yml
|
|
||||||
[get-docker]: https://docs.docker.com/get-docker/
|
|
||||||
[docs-bats-parallel]: https://bats-core.readthedocs.io/en/v1.8.2/usage.html#parallel-execution
|
|
||||||
|
|
@ -1,226 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tutorials | Basic Installation'
|
|
||||||
---
|
|
||||||
|
|
||||||
## A Basic Example With Relevant Environmental Variables
|
|
||||||
|
|
||||||
This example provides you only with a basic example of what a minimal setup could look like. We **strongly recommend** that you go through the configuration file yourself and adjust everything to your needs. The default [compose.yaml](https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml) can be used for the purpose out-of-the-box, see the [_Usage_ chapter](../../usage.md).
|
|
||||||
|
|
||||||
``` YAML
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
|
|
||||||
hostname: mail.example.com
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "465:465"
|
|
||||||
- "587:587"
|
|
||||||
- "993:993"
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
environment:
|
|
||||||
- ENABLE_RSPAMD=1
|
|
||||||
- ENABLE_CLAMAV=1
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN # For Fail2Ban to work
|
|
||||||
restart: always
|
|
||||||
```
|
|
||||||
|
|
||||||
## A Basic LDAP Setup
|
|
||||||
|
|
||||||
**Note** There are currently no LDAP maintainers. If you encounter issues, please raise them in the issue tracker, but be aware that the core maintainers team will most likely not be able to help you. **We would appreciate and we encourage everyone to actively participate in maintaining LDAP-related code by becoming a maintainer!**
|
|
||||||
|
|
||||||
``` YAML
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
|
|
||||||
hostname: mail.example.com
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "465:465"
|
|
||||||
- "587:587"
|
|
||||||
- "993:993"
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
environment:
|
|
||||||
- ACCOUNT_PROVISIONER=LDAP
|
|
||||||
- LDAP_SERVER_HOST=ldap # your ldap container/IP/ServerName
|
|
||||||
- LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
|
|
||||||
- LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
|
|
||||||
- LDAP_BIND_PW=admin
|
|
||||||
- LDAP_QUERY_FILTER_USER=(&(mail=%s)(mailEnabled=TRUE))
|
|
||||||
- LDAP_QUERY_FILTER_GROUP=(&(mailGroupMember=%s)(mailEnabled=TRUE))
|
|
||||||
- LDAP_QUERY_FILTER_ALIAS=(|(&(mailAlias=%s)(objectClass=PostfixBookMailForward))(&(mailAlias=%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE)))
|
|
||||||
- LDAP_QUERY_FILTER_DOMAIN=(|(&(mail=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailGroupMember=*@%s)(objectClass=PostfixBookMailAccount)(mailEnabled=TRUE))(&(mailalias=*@%s)(objectClass=PostfixBookMailForward)))
|
|
||||||
- DOVECOT_PASS_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
|
|
||||||
- DOVECOT_USER_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%n))
|
|
||||||
- ENABLE_SASLAUTHD=1
|
|
||||||
- SASLAUTHD_MECHANISMS=ldap
|
|
||||||
- SASLAUTHD_LDAP_SERVER=ldap
|
|
||||||
- SASLAUTHD_LDAP_BIND_DN=cn=admin,dc=localhost,dc=localdomain
|
|
||||||
- SASLAUTHD_LDAP_PASSWORD=admin
|
|
||||||
- SASLAUTHD_LDAP_SEARCH_BASE=ou=people,dc=localhost,dc=localdomain
|
|
||||||
- SASLAUTHD_LDAP_FILTER=(&(objectClass=PostfixBookMailAccount)(uniqueIdentifier=%U))
|
|
||||||
- POSTMASTER_ADDRESS=postmaster@localhost.localdomain
|
|
||||||
restart: always
|
|
||||||
```
|
|
||||||
|
|
||||||
## Using DMS as a local mail relay for containers
|
|
||||||
|
|
||||||
!!! info
|
|
||||||
|
|
||||||
This was originally a community contributed guide. Please let us know via a Github Issue if you're having any difficulty following the guide so that we can update it.
|
|
||||||
|
|
||||||
This guide is focused on only using [SMTP ports (not POP3 and IMAP)][docs-ports] with the intent to relay mail received from another service to an external email address (eg: `user@gmail.com`). It is not intended for mailbox storage of real users.
|
|
||||||
|
|
||||||
In this setup DMS is not intended to receive email from the outside world, so no anti-spam or anti-virus software is needed, making the service lighter to run.
|
|
||||||
|
|
||||||
!!! tip "`setup`"
|
|
||||||
|
|
||||||
The `setup` command used below is to be [run inside the container][docs-usage].
|
|
||||||
|
|
||||||
!!! warning "Open Relays"
|
|
||||||
|
|
||||||
Adding the docker network's gateway to the list of trusted hosts (_eg: using the `network` or `connected-networks` option_), can create an [**open relay**](https://en.wikipedia.org/wiki/Open_mail_relay). For instance [if IPv6 is enabled on the host machine, but not in Docker][github-issue-1405-comment].
|
|
||||||
|
|
||||||
1. Create the file `compose.yaml` with a content like this:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
container_name: mailserver
|
|
||||||
# Provide the FQDN of your mail server here (Your DNS MX record should point to this value)
|
|
||||||
hostname: mail.example.com
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "587:587"
|
|
||||||
- "465:465"
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/mail-data/:/var/mail/
|
|
||||||
- ./docker-data/dms/mail-state/:/var/mail-state/
|
|
||||||
- ./docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
- ./docker-data/dms/config/:/tmp/docker-mailserver/
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
environment:
|
|
||||||
- ENABLE_FAIL2BAN=1
|
|
||||||
# Using letsencrypt for SSL/TLS certificates:
|
|
||||||
- SSL_TYPE=letsencrypt
|
|
||||||
# Allow sending emails from other docker containers:
|
|
||||||
# Beware creating an Open Relay: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#permit_docker
|
|
||||||
- PERMIT_DOCKER=network
|
|
||||||
# You may want to enable this: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#spoof_protection
|
|
||||||
# See step 6 below, which demonstrates setup with enabled/disabled SPOOF_PROTECTION:
|
|
||||||
- SPOOF_PROTECTION=0
|
|
||||||
cap_add:
|
|
||||||
- NET_ADMIN # For Fail2Ban to work
|
|
||||||
restart: always
|
|
||||||
```
|
|
||||||
|
|
||||||
The docs have a detailed page on [Environment Variables][docs-environment] for reference.
|
|
||||||
|
|
||||||
??? tip "Firewalled ports"
|
|
||||||
|
|
||||||
If you have a firewall running, you may need to open ports `25`, `587` and `465`.
|
|
||||||
|
|
||||||
For example, with the firewall `ufw`, run:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
ufw allow 25
|
|
||||||
ufw allow 587
|
|
||||||
ufw allow 465
|
|
||||||
```
|
|
||||||
|
|
||||||
**Caution:** This may [not be sound advice][github-issue-ufw].
|
|
||||||
|
|
||||||
2. Configure your DNS service to use an MX record for the _hostname_ (eg: `mail`) you configured in the previous step and add the [SPF][docs-spf] TXT record.
|
|
||||||
|
|
||||||
!!! tip "If you manually manage the DNS zone file for the domain"
|
|
||||||
|
|
||||||
It would look something like this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
$ORIGIN example.com
|
|
||||||
@ IN A 10.11.12.13
|
|
||||||
mail IN A 10.11.12.13
|
|
||||||
|
|
||||||
; mail server for example.com
|
|
||||||
@ IN MX 10 mail.example.com.
|
|
||||||
|
|
||||||
; Add SPF record
|
|
||||||
@ IN TXT "v=spf1 mx -all"
|
|
||||||
```
|
|
||||||
|
|
||||||
Then don't forget to change the `SOA` serial number, and to restart the service.
|
|
||||||
|
|
||||||
3. [Generate DKIM keys][docs-dkim] for your domain via `setup config dkim`.
|
|
||||||
|
|
||||||
Copy the content of the file `docker-data/dms/config/opendkim/keys/example.com/mail.txt` and add it to your DNS records as a TXT like SPF was handled above.
|
|
||||||
|
|
||||||
I use [bind9](https://github.com/docker-scripts/bind9) for managing my domains, so I just paste it on `example.com.db`:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
mail._domainkey IN TXT ( "v=DKIM1; h=sha256; k=rsa; "
|
|
||||||
"p=MIIBIjANBgkqhkiG9w0BAQEFACAQ8AMIIBCgKCAQEAaH5KuPYPSF3Ppkt466BDMAFGOA4mgqn4oPjZ5BbFlYA9l5jU3bgzRj3l6/Q1n5a9lQs5fNZ7A/HtY0aMvs3nGE4oi+LTejt1jblMhV/OfJyRCunQBIGp0s8G9kIUBzyKJpDayk2+KJSJt/lxL9Iiy0DE5hIv62ZPP6AaTdHBAsJosLFeAzuLFHQ6USyQRojefqFQtgYqWQ2JiZQ3"
|
|
||||||
"iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB" ) ; ----- DKIM key mail for example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Get an SSL certificate, [we have a guide for you here][docs-ssl] (_Let's Encrypt_ is a popular service to get free SSL certificates).
|
|
||||||
|
|
||||||
5. Start DMS and check the terminal output for any errors: `docker compose up`.
|
|
||||||
|
|
||||||
6. Create email accounts and aliases:
|
|
||||||
|
|
||||||
!!! example "With `SPOOF_PROTECTION=0`"
|
|
||||||
|
|
||||||
```sh
|
|
||||||
setup email add admin@example.com passwd123
|
|
||||||
setup email add info@example.com passwd123
|
|
||||||
setup alias add admin@example.com external-account@gmail.com
|
|
||||||
setup alias add info@example.com external-account@gmail.com
|
|
||||||
setup email list
|
|
||||||
setup alias list
|
|
||||||
```
|
|
||||||
|
|
||||||
Aliases make sure that any email that comes to these accounts is forwarded to your third-party email address (`external-account@gmail.com`), where they are retrieved (_eg: via third-party web or mobile app_), instead of connecting directly to `docker-mailserer` with POP3 / IMAP.
|
|
||||||
|
|
||||||
!!! example "With `SPOOF_PROTECTION=1`"
|
|
||||||
|
|
||||||
```sh
|
|
||||||
setup email add admin.gmail@example.com passwd123
|
|
||||||
setup email add info.gmail@example.com passwd123
|
|
||||||
setup alias add admin@example.com admin.gmail@example.com
|
|
||||||
setup alias add info@example.com info.gmail@example.com
|
|
||||||
setup alias add admin.gmail@example.com external-account@gmail.com
|
|
||||||
setup alias add info.gmail@example.com external-account@gmail.com
|
|
||||||
setup email list
|
|
||||||
setup alias list
|
|
||||||
```
|
|
||||||
|
|
||||||
This extra step is required to avoid the `553 5.7.1 Sender address rejected: not owned by user` error (_the accounts used for submitting mail to Gmail are `admin.gmail@example.com` and `info.gmail@example.com`_)
|
|
||||||
|
|
||||||
7. Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with `ctrl+c` and start it again as a daemon: `docker compose up -d`.
|
|
||||||
|
|
||||||
[docs-ports]: ../../config/security/understanding-the-ports.md
|
|
||||||
[docs-environment]: ../../config/environment.md
|
|
||||||
[docs-spf]: ../../config/best-practices/dkim_dmarc_spf.md#spf
|
|
||||||
[docs-dkim]: ../../config/best-practices/dkim_dmarc_spf.md#dkim
|
|
||||||
[docs-ssl]: ../../config/security/ssl.md#lets-encrypt-recommended
|
|
||||||
[docs-usage]: ../../usage.md#get-up-and-running
|
|
||||||
[github-issue-ufw]: https://github.com/docker-mailserver/docker-mailserver/issues/3151
|
|
||||||
[github-issue-1405-comment]: https://github.com/docker-mailserver/docker-mailserver/issues/1405#issuecomment-590106498
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tutorials | Blog Posts'
|
|
||||||
---
|
|
||||||
|
|
||||||
This site lists blog entries that write about the project. If you blogged about DMS let us know so we can add it here!
|
|
||||||
|
|
||||||
- [Installing docker-mailserver](https://lowtek.ca/roo/2021/installing-docker-mailserver/) by [@andrewlow](https://github.com/andrewlow)
|
|
||||||
- [Self hosted mail-server](https://www.ifthenel.se/self-hosted-mail-server/) by [@matrixes](https://github.com/matrixes)
|
|
||||||
- [Docker-mailserver on kubernetes](https://brakkee.org/site/index.php/mailserver-on-kubernetes/) by [@ErikEngerd](https://github.com/ErikEngerd)
|
|
||||||
|
|
@ -1,74 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tutorials | Crowdsec'
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! quote "What is Crowdsec?"
|
|
||||||
|
|
||||||
Crowdsec is an open source software that detects and blocks attackers using log analysis.
|
|
||||||
It has access to a global community-wide IP reputation database.
|
|
||||||
|
|
||||||
[Source](https://www.crowdsec.net)
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
Crowdsec supports multiple [installation methods][crowdsec-installation-docs], however this page will use the docker installation.
|
|
||||||
|
|
||||||
|
|
||||||
### Docker mailserver
|
|
||||||
|
|
||||||
In your `compose.yaml` for the DMS service, add a bind mount volume for `/var/log/mail`. This is to share the DMS logs to a separate crowdsec container.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
- /docker-data/dms/mail-logs/:/var/log/mail/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Crowdsec
|
|
||||||
|
|
||||||
The crowdsec container should also bind mount the same host path for the DMS logs that was added in the DMS example above.
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
image: crowdsecurity/crowdsec
|
|
||||||
restart: unless-stopped
|
|
||||||
ports:
|
|
||||||
- "8080:8080"
|
|
||||||
- "6060:6060"
|
|
||||||
volumes:
|
|
||||||
- /docker-data/dms/mail-logs/:/var/log/dms:ro
|
|
||||||
- ./acquis.d:/etc/crowdsec/acquis.d
|
|
||||||
- crowdsec-db:/var/lib/crowdsec/data/
|
|
||||||
environment:
|
|
||||||
# These collection contains parsers and scenarios for postfix and dovecot
|
|
||||||
COLLECTIONS: crowdsecurity/postfix crowdsecurity/dovecot
|
|
||||||
TZ: Europe/Paris
|
|
||||||
volumes:
|
|
||||||
crowdsec-db:
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Configure crowdsec to read and parse DMS logs file.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
Create the file `dms.yml` in `./acquis.d/`
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
source: file
|
|
||||||
filenames:
|
|
||||||
- /var/log/dms/mail.log
|
|
||||||
labels:
|
|
||||||
type: syslog
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning Bouncers
|
|
||||||
|
|
||||||
Crowdsec on its own is just a detection software, the remediation is done by components called bouncers.
|
|
||||||
This page does not explain how to install or configure a bouncer. It can be found in [crowdsec documentation][crowdsec-bouncer-docs].
|
|
||||||
|
|
||||||
[crowdsec-installation-docs]: https://doc.crowdsec.net/docs/getting_started/install_crowdsec
|
|
||||||
[crowdsec-bouncer-docs]: https://doc.crowdsec.net/docs/bouncers/intro
|
|
||||||
|
|
@ -1,46 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tutorials | Docker Build'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Building your own Docker image
|
|
||||||
|
|
||||||
### Submodules
|
|
||||||
|
|
||||||
You'll need to retrieve the git submodules prior to building your own Docker image. From within your copy of the git repo run the following to retrieve the submodules and build the Docker image:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
git submodule update --init --recursive
|
|
||||||
docker build --tag <YOUR CUSTOM IMAGE NAME> .
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, you can clone and retrieve the submodules in one command:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
git clone --recurse-submodules https://github.com/docker-mailserver/docker-mailserver
|
|
||||||
```
|
|
||||||
|
|
||||||
### About Docker
|
|
||||||
|
|
||||||
#### Minimum supported version
|
|
||||||
|
|
||||||
We make use of build features that require a recent version of Docker. v23.0 or newer is advised, but earlier releases may work.
|
|
||||||
|
|
||||||
- To get the latest version for your distribution, please have a look at [the official installation documentation for Docker](https://docs.docker.com/engine/install/).
|
|
||||||
- If you are using a version of Docker prior to v23.0, you will need to enable BuildKit via the ENV [`DOCKER_BUILDKIT=1`](https://docs.docker.com/build/buildkit/#getting-started).
|
|
||||||
|
|
||||||
#### Build Arguments (Optional)
|
|
||||||
|
|
||||||
The `Dockerfile` includes several build [`ARG`][docker-docs::builder-arg] instructions that can be configured:
|
|
||||||
|
|
||||||
- `DOVECOT_COMMUNITY_REPO`: Install Dovecot from the community repo instead of from Debian (default = 0)
|
|
||||||
- `DMS_RELEASE`: The image version (default = edge)
|
|
||||||
- `VCS_REVISION`: The git commit hash used for the build (default = unknown)
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
- `DMS_RELEASE` (_when not `edge`_) will be used to check for updates from our GH releases page at runtime due to the default feature [`ENABLE_UPDATE_CHECK=1`][docs::env-update-check].
|
|
||||||
- Both `DMS_RELEASE` and `VCS_REVISION` are also used with `opencontainers` metadata [`LABEL`][docker-docs::builder-label] instructions.
|
|
||||||
|
|
||||||
[docs::env-update-check]: https://docker-mailserver.github.io/docker-mailserver/latest/config/environment/#enable_update_check
|
|
||||||
[docker-docs::builder-arg]: https://docs.docker.com/engine/reference/builder/#using-arg-variables
|
|
||||||
[docker-docs::builder-label]: https://docs.docker.com/engine/reference/builder/#label
|
|
||||||
|
|
@ -1,178 +0,0 @@
|
||||||
# Dovecot Full Text Search (FTS) using the Solr Backend
|
|
||||||
|
|
||||||
Dovecot supports several FTS backends for providing fast and efficient full text searching of e-mails directly from the IMAP server.
|
|
||||||
|
|
||||||
As the size of your mail storage grows, the benefits of FTS are especially notable:
|
|
||||||
|
|
||||||
- Without FTS, Dovecot would perform a search query by checking each individual email stored for a match, and then repeat this process again from scratch for the exact same query in future.
|
|
||||||
- Some mail clients (_like Thunderbird_) may provide their own indexing and search features when all mail to search is stored locally, otherwise Dovecot needs to handle the search query (_for example webmail and mobile clients, like Gmail_).
|
|
||||||
- FTS indexes each mail into a database for querying instead, where it can skip the cost of inspecting irrelevant emails for a query.
|
|
||||||
|
|
||||||
!!! warning "This is a community contributed guide"
|
|
||||||
|
|
||||||
It extends [our official docs for Dovecot FTS][docs::dovecot::full-text-search] with a focus on Apache Solr. DMS does not officially support this integration.
|
|
||||||
|
|
||||||
## Setup Solr for DMS
|
|
||||||
|
|
||||||
An FTS backend supported by Dovecot is [Apache Solr][github-solr], a fast and efficient multi-purpose search indexer.
|
|
||||||
|
|
||||||
### Add the required `dovecot-solr` package
|
|
||||||
|
|
||||||
As the official DMS image does not provide `dovecot-solr`, you'll need to include the package in your own image (_extending a DMS release as a base image_), or via our [`user-patches.sh` feature][docs::user-patches]:
|
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
|
||||||
!!! quote ""
|
|
||||||
|
|
||||||
=== "`user-patches.sh`"
|
|
||||||
|
|
||||||
If you'd prefer to avoid a custom image build. This approach is simpler but with the caveat that any time the container is restarted, you'll have a delay as the package is installed each time.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
apt-get update && apt-get install dovecot-solr
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "`compose.yaml`"
|
|
||||||
|
|
||||||
A custom DMS image does not add much friction. You do not need a separate `Dockerfile` as Docker Compose supports building from an inline `Dockerfile` in your `compose.yaml`.
|
|
||||||
|
|
||||||
The `image` key of the service is swapped for the `build` key instead, as shown below:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
hostname: mail.example.com
|
|
||||||
# The `image` setting now represents the tag for the local build configured below:
|
|
||||||
image: local/dms:${DMS_TAG?Must set DMS image tag}
|
|
||||||
# Local build (no need to try pull `image` remotely):
|
|
||||||
pull_policy: build
|
|
||||||
# Add this `build` section to your real `compose.yaml` for your DMS service:
|
|
||||||
build:
|
|
||||||
dockerfile_inline: |
|
|
||||||
FROM docker.io/mailserver/docker-mailserver:${DMS_TAG?Must set DMS image tag}
|
|
||||||
RUN apt-get update && apt-get install dovecot-solr
|
|
||||||
```
|
|
||||||
|
|
||||||
This approach only needs to install the package once with the image build itself which minimizes the delay of container startup.
|
|
||||||
|
|
||||||
- Just run `DMS_TAG='14.0' docker compose up` and it will pull the DMS image, then build your custom DMS image to run a new container instance.
|
|
||||||
- Updating to a new DMS release is straight-forward, just adjust the `DMS_TAG` ENV value or change the image tag directly in `compose.yaml` as you normally would to upgrade an image.
|
|
||||||
- If you make future changes to the `dockerfile_inline` that don't seem to be applied, you may need to force a rebuild with `DMS_TAG='14.0' docker compose up --build`.
|
|
||||||
|
|
||||||
!!! note "Why doesn't DMS include `dovecot-solr`?"
|
|
||||||
|
|
||||||
This integration is not officially supported in DMS as no maintainer is able to provide troubleshooting support.
|
|
||||||
|
|
||||||
Prior to v14, the package was included but the community contributed guide had been outdated for several years that it was non-functional. It was decided that it was better to drop support and docs, however some DMS users voiced active use of Solr and it's benefits over Xapian for FTS which led to these revised docs.
|
|
||||||
|
|
||||||
**ARM64 builds do not have support for `dovecot-solr`**. Additionally the [user demand for including `dovecot-solr` is presently too low][gh-dms::feature-request::dovecot-solr-package] to justify vs the minimal effort to add additional packages as shown above.
|
|
||||||
|
|
||||||
### `compose.yaml` config
|
|
||||||
|
|
||||||
Firstly you need a working Solr container, for this the [official docker image][dockerhub-solr] will do:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
solr:
|
|
||||||
image: solr:latest
|
|
||||||
container_name: dms-solr
|
|
||||||
environment:
|
|
||||||
# As Solr can be quite resource hungry, raise the memory limit to 2GB.
|
|
||||||
# The default is 512MB, which may be exhausted quickly.
|
|
||||||
SOLR_JAVA_MEM: "-Xms2g -Xmx2g"
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/solr:/var/solr
|
|
||||||
restart: always
|
|
||||||
```
|
|
||||||
|
|
||||||
DMS will connect internally to the `solr` service above. Either have both services in the same `compose.yaml` file, or ensure that the containers are connected to the same docker network.
|
|
||||||
|
|
||||||
### Configure Solr for Dovecot
|
|
||||||
|
|
||||||
1. Once the Solr container is started, you need to configure a "Solr core" for Dovecot:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec -it dms-solr /bin/sh
|
|
||||||
solr create -c dovecot
|
|
||||||
cp -R /opt/solr/contrib/analysis-extras/lib /var/solr/data/dovecot
|
|
||||||
```
|
|
||||||
|
|
||||||
Stop the `dms-solr` container and you should now have a `./data/dovecot` folder in the local bind mount volume.
|
|
||||||
|
|
||||||
2. Solr needs a schema that is specifically tailored for Dovecot FTS.
|
|
||||||
|
|
||||||
As of writing of this guide, Solr 9 is the current release. [Dovecot provides the required schema configs][github-dovecot::core-docs] for Solr, copy the following two v9 config files to `./data/dovecot` and rename them accordingly:
|
|
||||||
|
|
||||||
- `solr-config-9.xml` (_rename to `solrconfig.xml`_)
|
|
||||||
- `solr-schema-9.xml` (_rename to `schema.xml`_)
|
|
||||||
|
|
||||||
Additionally, remove the `managed-schema.xml` file from `./data/dovecot` and ensure the two files you copied have a [UID and GID of `8983`][dockerfile-solr-uidgid] assigned.
|
|
||||||
|
|
||||||
Start the Solr container once again, you should now have a working Solr core specifically for Dovecot FTS.
|
|
||||||
|
|
||||||
3. Configure Dovecot in DMS to connect to this Solr core:
|
|
||||||
|
|
||||||
Create a `10-plugin.conf` file in your `./config/dovecot` folder with this contents:
|
|
||||||
|
|
||||||
```config
|
|
||||||
mail_plugins = $mail_plugins fts fts_solr
|
|
||||||
|
|
||||||
plugin {
|
|
||||||
fts = solr
|
|
||||||
fts_autoindex = yes
|
|
||||||
fts_solr = url=http://dms-solr:8983/solr/dovecot/
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Add a volume mount for that config to your DMS service in `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/config/dovecot/10-plugin.conf:/etc/dovecot/conf.d/10-plugin.conf:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
### Trigger Dovecot FTS indexing
|
|
||||||
|
|
||||||
After following the previous steps, restart DMS and run this command to have Dovecot re-index all mail:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker compose exec mailserver doveadm fts rescan -A
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! info "Indexing will take a while depending on how large your mail folders"
|
|
||||||
|
|
||||||
Usually within 15 minutes or so, you should be able to search your mail using the Dovecot FTS feature! :tada:
|
|
||||||
|
|
||||||
### Compatibility
|
|
||||||
|
|
||||||
Since Solr 9.8.0 was released (Jan 2025), a breaking change [deprecates support for `<lib>` directives][solr::9.8::lib-directive] which is presently used by the Dovecot supplied Solr config (`solr-config-9.xml`) to automatically load additional jars required.
|
|
||||||
|
|
||||||
To enable support for `<lib>` directives, add the following ENV to your `solr` container:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
solr:
|
|
||||||
environment:
|
|
||||||
SOLR_CONFIG_LIB_ENABLED: true
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! warning "Solr 10"
|
|
||||||
|
|
||||||
From the Solr 10 release onwards, this opt-in ENV will no longer be available.
|
|
||||||
|
|
||||||
If Dovecot has not updated their example Solr config ([upstream PR][dovecot::pr::solr-config-lib]), you will need to manually modify the Solr XML config to remove the `<lib>` directives and replace the suggested ENV `SOLR_CONFIG_LIB_ENABLED=true` with `SOLR_MODULES=analysis-extras`.
|
|
||||||
|
|
||||||
[docs::user-patches]: ../../config/advanced/override-defaults/user-patches.md
|
|
||||||
[docs::dovecot::full-text-search]: ../../config/advanced/full-text-search.md
|
|
||||||
[gh-dms::feature-request::dovecot-solr-package]: https://github.com/docker-mailserver/docker-mailserver/issues/4052
|
|
||||||
|
|
||||||
[dockerhub-solr]: https://hub.docker.com/_/solr
|
|
||||||
[dockerfile-solr-uidgid]: https://github.com/apache/solr-docker/blob/9cd850b72309de05169544395c83a85b329d6b86/9.6/Dockerfile#L89-L92
|
|
||||||
[github-solr]: https://github.com/apache/solr
|
|
||||||
[github-dovecot::core-docs]: https://github.com/dovecot/core/tree/main/doc
|
|
||||||
|
|
||||||
[solr::9.8::lib-directive]: https://issues.apache.org/jira/browse/SOLR-16781
|
|
||||||
[dovecot::pr::solr-config-lib]: https://github.com/dovecot/core/pull/238
|
|
||||||
|
|
@ -1,422 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Tutorials | Mail Server behind a Proxy'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Using a Reverse Proxy
|
|
||||||
|
|
||||||
Guidance is provided via a Traefik config example, however if you're only familiar with configuring a reverse proxy for web services there are some differences to keep in mind.
|
|
||||||
|
|
||||||
- A security concern where preserving the client IP is important but needs to be handled at Layer 4 (TCP).
|
|
||||||
- TLS will be handled differently due protocols like STARTTLS and the need to comply with standards for interoperability with other MTAs.
|
|
||||||
- The ability to route the same port to different containers by FQDN can be limited.
|
|
||||||
|
|
||||||
This reduces many of the benefits for why you might use a reverse proxy, but they can still be useful.
|
|
||||||
|
|
||||||
Some deployments may require a service to route traffic (kubernetes) when deploying, in which case the below advice is important to understand well.
|
|
||||||
|
|
||||||
The guide here has also been adapted for [our Kubernetes docs][docs::kubernetes].
|
|
||||||
|
|
||||||
## What can go wrong?
|
|
||||||
|
|
||||||
Without a reverse proxy involved, a service is typically aware of the client IP for a connection.
|
|
||||||
|
|
||||||
However when a reverse proxy routes the connection this information can be lost, and the proxied service mistakenly treats the client IP as the reverse proxy handling the connection.
|
|
||||||
|
|
||||||
- That can be problematic when the client IP is meaningful information for the proxied service to act upon, especially when it [impacts security](#security-concerns).
|
|
||||||
- The [PROXY protocol][networking::spec:proxy-protocol] is a well established solution to preserve the client IP when both the proxy and service have enabled the support.
|
|
||||||
|
|
||||||
??? abstract "Technical Details - HTTP vs TCP proxying"
|
|
||||||
|
|
||||||
A key difference for how the network is proxied relates to the [OSI Model][networking::osi-model]:
|
|
||||||
|
|
||||||
- Layer 7 (_Application layer protocols: SMTP / IMAP / HTTP / etc_)
|
|
||||||
- Layer 4 (_Transport layer protocols: TCP / UDP_)
|
|
||||||
|
|
||||||
When working with Layer 7 and a protocol like HTTP, it is possible to inspect a protocol header like [`Forwarded`][networking::http-header::forwarded] (_or it's predecessor: [`X-Forwarded-For`][networking::http-header::x-forwarded-for]_). At a lower level with Layer 4, that information is not available and we are routing traffic agnostic to the application protocol being proxied.
|
|
||||||
|
|
||||||
A proxy can prepend the [PROXY protocol][networking::spec:proxy-protocol] header to the TCP/UDP connection as it is routed to the service, which must be configured to be compatible with PROXY protocol (_often this adds a restriction that connections must provide the header, otherwise they're rejected_).
|
|
||||||
|
|
||||||
Beyond your own proxy, traffic may be routed in the network by other means that would also rewrite this information such as Docker's own network management via `iptables` and `userland-proxy` (NAT). The PROXY header ensures the original source and destination IP addresses, along with their ports is preserved across transit.
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
### Reverse Proxy
|
|
||||||
|
|
||||||
The below guidance is focused on configuring [Traefik][traefik-web], but the advice should be roughly applicable elsewhere (_eg: [NGINX][nginx-docs::proxyprotocol], [Caddy][caddy::plugin::l4]_).
|
|
||||||
|
|
||||||
- Support requires the capability to proxy TCP (Layer 4) connections with PROXY protocol enabled for the upstream (DMS). The upstream must also support enabling PROXY protocol (_which for DMS services rejects any connection not using the protocol_).
|
|
||||||
- TLS should not be terminated at the proxy, that should be delegated to DMS (_which should be configured with the TLS certs_). Reasoning is covered under the [ports section](#ports).
|
|
||||||
|
|
||||||
???+ example "Traefik service"
|
|
||||||
|
|
||||||
The Traefik service config is fairly standard, just define the necessary entrypoints:
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
reverse-proxy:
|
|
||||||
image: docker.io/traefik:latest # 2.10 / 3.0
|
|
||||||
# CAUTION: In production you should configure the Docker API endpoint securely:
|
|
||||||
# https://doc.traefik.io/traefik/providers/docker/#docker-api-access
|
|
||||||
volumes:
|
|
||||||
- /var/run/docker.sock:/var/run/docker.sock
|
|
||||||
command:
|
|
||||||
# Docker provider config:
|
|
||||||
- --providers.docker=true
|
|
||||||
- --providers.docker.exposedbydefault=false
|
|
||||||
# DMS ports you want to proxy:
|
|
||||||
- --entryPoints.mail-smtp.address=:25
|
|
||||||
- --entryPoints.mail-submission.address=:587
|
|
||||||
- --entryPoints.mail-submissions.address=:465
|
|
||||||
- --entryPoints.mail-imap.address=:143
|
|
||||||
- --entryPoints.mail-imaps.address=:993
|
|
||||||
- --entryPoints.mail-pop3.address=:110
|
|
||||||
- --entryPoints.mail-pop3s.address=:995
|
|
||||||
- --entryPoints.mail-managesieve.address=:4190
|
|
||||||
# Publish external access ports mapped to traefik entrypoint ports:
|
|
||||||
ports:
|
|
||||||
- "25:25"
|
|
||||||
- "587:587"
|
|
||||||
- "465:465"
|
|
||||||
- "143:143"
|
|
||||||
- "993:993"
|
|
||||||
- "110:110"
|
|
||||||
- "995:995"
|
|
||||||
- "4190:4190"
|
|
||||||
# An IP is assigned here for other services (Dovecot) to trust for PROXY protocol:
|
|
||||||
networks:
|
|
||||||
default:
|
|
||||||
ipv4_address: 172.16.42.2
|
|
||||||
|
|
||||||
# Specifying a subnet to assign a fixed container IP to the reverse proxy:
|
|
||||||
networks:
|
|
||||||
default:
|
|
||||||
name: my-network
|
|
||||||
ipam:
|
|
||||||
config:
|
|
||||||
- subnet: "172.16.42.0/24"
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note "Extra considerations"
|
|
||||||
|
|
||||||
- [`--providers.docker.network=my-network`][traefik-docs::provider-docker::network] is useful when there is more than one network to consider.
|
|
||||||
- If your deployment has any other hops (an edge proxy, load balancer, etc) between the reverse proxy and the client, you'll need PROXY protocol support throughout that chain. For Traefik this additionally requires [enabling PROXY protocol on your entry points][traefik-docs::entrypoint::proxyprotocol].
|
|
||||||
|
|
||||||
???+ example "Traefik labels for DMS"
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
services:
|
|
||||||
dms:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
hostname: mail.example.com
|
|
||||||
labels:
|
|
||||||
- traefik.enable=true
|
|
||||||
|
|
||||||
# These are examples, configure the equivalent for any additional ports you proxy.
|
|
||||||
# Explicit TLS (STARTTLS):
|
|
||||||
- traefik.tcp.routers.mail-smtp.rule=HostSNI(`*`)
|
|
||||||
- traefik.tcp.routers.mail-smtp.entrypoints=smtp
|
|
||||||
- traefik.tcp.routers.mail-smtp.service=smtp
|
|
||||||
- traefik.tcp.services.mail-smtp.loadbalancer.server.port=25
|
|
||||||
- traefik.tcp.services.mail-smtp.loadbalancer.proxyProtocol.version=2
|
|
||||||
|
|
||||||
# Implicit TLS is no different, except for optional HostSNI support:
|
|
||||||
- traefik.tcp.routers.mail-submissions.rule=HostSNI(`*`)
|
|
||||||
- traefik.tcp.routers.mail-submissions.entrypoints=smtp-submissions
|
|
||||||
- traefik.tcp.routers.mail-submissions.service=smtp-submissions
|
|
||||||
- traefik.tcp.services.mail-submissions.loadbalancer.server.port=465
|
|
||||||
- traefik.tcp.services.mail-submissions.loadbalancer.proxyProtocol.version=2
|
|
||||||
# NOTE: Optionally match by SNI rule, this requires TLS passthrough (not compatible with STARTTLS):
|
|
||||||
#- traefik.tcp.routers.mail-submissions.rule=HostSNI(`mail.example.com`)
|
|
||||||
#- traefik.tcp.routers.mail-submissions.tls.passthrough=true
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note "PROXY protocol compatibility"
|
|
||||||
|
|
||||||
Only TCP routers support enabling PROXY Protocol (via [`proxyProtocol.version=2`][traefik-docs::service-tcp::proxyprotocol])
|
|
||||||
|
|
||||||
Postfix and Dovecot are both compatible with PROXY protocol v1 and v2.
|
|
||||||
|
|
||||||
#### Ports
|
|
||||||
|
|
||||||
??? abstract "Technical Details - Ports (Traefik config)"
|
|
||||||
|
|
||||||
!!! info "Explicit TLS (STARTTLS)"
|
|
||||||
|
|
||||||
**Service Ports:** `mail-smtp` (25), `mail-submission` (587), `mail-imap` (143), `mail-pop3` (110), `mail-managesieve` (4190)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
- [Traefik expects the TCP router to not enable TLS][traefik-docs::router-tcp::server-first-protocols] (_see "Server First protocols"_) for these connections. They begin in plaintext and potentially upgrade the connection to TLS, Traefik has no involvement in STARTTLS.
|
|
||||||
- Without an initial TLS connection, the [`HostSNI` router rule is not usable][traefik-docs::router-tcp::host-sni] (_see "HostSNI & TLS"_). This limits routing flexibility for these ports (_eg: routing these ports by the FQDN to different DMS containers_).
|
|
||||||
|
|
||||||
!!! info "Implicit TLS"
|
|
||||||
|
|
||||||
**Service Ports:** `mail-submissions` (465), `mail-imaps` (993), `mail-pop3s` (995)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
The `HostSNI` router rule could specify the DMS FQDN instead of `*`:
|
|
||||||
|
|
||||||
- This requires the router to have TLS enabled, so that Traefik can inspect the server name sent by the client.
|
|
||||||
- Traefik can only match the SNI to `*` when the client does not provide a server name. Some clients must explicitly opt-in, such as CLI clients `openssl` (`-servername`) and `swaks` (`--tls-sni`).
|
|
||||||
- Add [`tls.passthrough=true` to the router][traefik-docs::router-tcp::passthrough] (_this implicitly enables TLS_).
|
|
||||||
- Traefik should not terminate TLS, decryption should occur within DMS instead when proxying to the same implicit TLS ports.
|
|
||||||
- Passthrough ignores any certificates configured for Traefik; DMS must be configured with the certificates instead (_[DMS can use `acme.json` from Traefik][docs::tls::traefik]_).
|
|
||||||
|
|
||||||
Unlike proxying HTTPS (port 443) to a container via HTTP (port 80), the equivalent for DMS service ports is not supported:
|
|
||||||
|
|
||||||
- Port 25 must secure the connection via STARTTLS to be reached publicly.
|
|
||||||
- STARTTLS ports requiring authentication for Postfix (587) and Dovecot (110, 143, 4190) are configured to only permit authentication over an encrypted connection.
|
|
||||||
- Support would require routing the implicit TLS ports to their explicit TLS equivalent ports with auth restrictions removed. `tls.passthrough.true` would not be required, additionally port 25 would always be unencrypted (_if the proxy exclusively manages TLS/certs_), or unreachable by public MTAs attempting delivery if the proxy enables implicit TLS for this port.
|
|
||||||
|
|
||||||
### DMS (Postfix + Dovecot)
|
|
||||||
|
|
||||||
???+ example "Enable PROXY protocol on existing service ports"
|
|
||||||
|
|
||||||
This can be handled via our config override support.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Postfix via [`postfix-master.cf`][docs::overrides::postfix]:
|
|
||||||
|
|
||||||
```cf title="docker-data/dms/config/postfix-master.cf"
|
|
||||||
smtp/inet/postscreen_upstream_proxy_protocol=haproxy
|
|
||||||
submission/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
submissions/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
```
|
|
||||||
|
|
||||||
[`postscreen_upstream_proxy_protocol`][postfix-docs::settings::postscreen_upstream_proxy_protocol] and [`smtpd_upstream_proxy_protocol`][postfix-docs::settings::smtpd_upstream_proxy_protocol] both specify the protocol type used by a proxy. `haproxy` represents the PROXY protocol.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Dovecot via [`dovecot.cf`][docs::overrides::dovecot]:
|
|
||||||
|
|
||||||
```cf title="docker-data/dms/config/dovecot.cf"
|
|
||||||
haproxy_trusted_networks = 172.16.42.2
|
|
||||||
|
|
||||||
service imap-login {
|
|
||||||
inet_listener imap {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
|
|
||||||
inet_listener imaps {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
service pop3-login {
|
|
||||||
inet_listener pop3 {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
|
|
||||||
inet_listener pop3s {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
service managesieve-login {
|
|
||||||
inet_listener sieve {
|
|
||||||
haproxy = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [`haproxy_trusted_networks`][dovecot-docs::settings::haproxy-trusted-networks] must reference the reverse proxy IP, or a wider subnet using CIDR notation.
|
|
||||||
- [`haproxy = yes`][dovecot-docs::service-config::haproxy] for the TCP listeners of each login service.
|
|
||||||
|
|
||||||
!!! warning "Internal traffic (_within the network or DMS itself_)"
|
|
||||||
|
|
||||||
- Direct connections to DMS from other containers within the internal network will be rejected when they don't provide the required PROXY header.
|
|
||||||
- This can also affect services running within the DMS container itself if they attempt to make a connection and aren't PROXY protocol capable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
A solution is to configure alternative service ports that offer PROXY protocol support (as shown next).
|
|
||||||
|
|
||||||
Alternatively routing connections to DMS through the local reverse proxy via [DNS query rewriting][gh-dms::dns-rewrite-example] can work too.
|
|
||||||
|
|
||||||
??? example "Configuring services with separate ports for PROXY protocol"
|
|
||||||
|
|
||||||
In this example we'll take the original service ports and add `10000` for the new PROXY protocol service ports.
|
|
||||||
|
|
||||||
Traefik labels will need to update their service ports accordingly (eg: `.loadbalancer.server.port=10465`).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Postfix config now requires [our `user-patches.sh` support][docs::overrides::user-patches] to add new services in `/etc/postfix/master.cf`:
|
|
||||||
|
|
||||||
```bash title="docker-data/dms/config/user-patches.sh"
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# Duplicate the config for the submission(s) service ports (587 / 465) with adjustments for the PROXY ports (10587 / 10465) and `syslog_name` setting:
|
|
||||||
postconf -Mf submission/inet | sed -e s/^submission/10587/ -e 's/submission/submission-proxyprotocol/' >> /etc/postfix/master.cf
|
|
||||||
postconf -Mf submissions/inet | sed -e s/^submissions/10465/ -e 's/submissions/submissions-proxyprotocol/' >> /etc/postfix/master.cf
|
|
||||||
# Enable PROXY Protocol support for these new service variants:
|
|
||||||
postconf -P 10587/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
postconf -P 10465/inet/smtpd_upstream_proxy_protocol=haproxy
|
|
||||||
|
|
||||||
# Create a variant for port 25 too (NOTE: Port 10025 is already assigned in DMS to Amavis):
|
|
||||||
postconf -Mf smtp/inet | sed -e s/^smtp/12525/ >> /etc/postfix/master.cf
|
|
||||||
# Enable PROXY Protocol support (different setting as port 25 is handled via postscreen), optionally configure a `syslog_name` to distinguish in logs:
|
|
||||||
postconf -P 12525/inet/postscreen_upstream_proxy_protocol=haproxy 12525/inet/syslog_name=smtp-proxyprotocol
|
|
||||||
```
|
|
||||||
|
|
||||||
Supporting port 25 with an additional PROXY protocol port will also require a `postfix-main.cf` override line for `postscreen` to work correctly:
|
|
||||||
|
|
||||||
```cf title="docker-data/dms/config/postfix-main.cf"
|
|
||||||
postscreen_cache_map = proxy:btree:$data_directory/postscreen_cache
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Dovecot is mostly the same as before:
|
|
||||||
|
|
||||||
- A new service name instead of targeting one to modify.
|
|
||||||
- Add the new port assignment.
|
|
||||||
- Set [`ssl = yes`][dovecot-docs::service-config::ssl] when implicit TLS is needed.
|
|
||||||
|
|
||||||
```cf title="docker-data/dms/config/dovecot.cf"
|
|
||||||
haproxy_trusted_networks = 172.16.42.2
|
|
||||||
|
|
||||||
service imap-login {
|
|
||||||
inet_listener imap-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10143
|
|
||||||
}
|
|
||||||
|
|
||||||
inet_listener imaps-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10993
|
|
||||||
ssl = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
service pop3-login {
|
|
||||||
inet_listener pop3-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10110
|
|
||||||
}
|
|
||||||
|
|
||||||
inet_listener pop3s-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 10995
|
|
||||||
ssl = yes
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
service managesieve-login {
|
|
||||||
inet_listener sieve-proxied {
|
|
||||||
haproxy = yes
|
|
||||||
port = 14190
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Verification
|
|
||||||
|
|
||||||
Send an email through the reverse proxy. If you do not use the DNS query rewriting approach, you'll need to do this from an external client.
|
|
||||||
|
|
||||||
??? example "Sending a generic test mail through `swaks` CLI"
|
|
||||||
|
|
||||||
Run a `swaks` command and then check your DMS logs for the expected client IP, it should no longer be using the reverse proxy IP.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# NOTE: It is common to find port 25 is blocked from outbound connections, you may only be able to test the submission(s) ports.
|
|
||||||
swaks --helo not-relevant.test --server mail.example.com --port 25 -tls --from hello@not-relevant.test --to user@example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
- You can specify the `--server` as the DMS FQDN or an IP address, where either should connect to the reverse proxy service.
|
|
||||||
- `not-relevant.test` technically may be subject to some tests, at least for port 25. With the submission(s) ports those should be exempt.
|
|
||||||
- `-tls` will use STARTTLS on port 25, you can exclude it to send unencrypted, but it would still go through the same port/route being tested.
|
|
||||||
- To test the submission ports use `--port 587 -tls` or `--port 465 -tlsc` with your credentials `--auth-user user@example.com --auth-password secret`
|
|
||||||
- Add `--tls-sni mail.example.com` if you have configured `HostSNI` in Traefik router rules (_SNI routing is only valid for implicit TLS ports_).
|
|
||||||
|
|
||||||
??? warning "Do not rely on local testing alone"
|
|
||||||
|
|
||||||
Testing from the Docker host technically works, however the IP is likely subject to more manipulation via `iptables` than an external client.
|
|
||||||
|
|
||||||
The IP will likely appear as from the gateway IP of the Docker network associated to the reverse proxy, where that gateway IP then becomes the client IP when writing the PROXY protocol header.
|
|
||||||
|
|
||||||
## Security concerns
|
|
||||||
|
|
||||||
### Forgery
|
|
||||||
|
|
||||||
Since the PROXY protocol sends a header with the client IP rewritten for software to use instead, this could be abused by bad actors.
|
|
||||||
|
|
||||||
Software on the receiving end of the connection often supports configuring an IP or CIDR range of clients to trust receiving the PROXY protocol header from.
|
|
||||||
|
|
||||||
??? warning "Risk exposure"
|
|
||||||
|
|
||||||
If you trust more than the reverse proxy IP, you must consider the risk exposure:
|
|
||||||
|
|
||||||
- Any container within the network that is compromised could impersonate another IP (_container or external client_) which may have been configured to have additional access/exceptions granted.
|
|
||||||
- If the reverse proxy is on a separate network/host than DMS, exposure of the PROXY protocol enabled ports outside the network increases the importance of narrowing trust. For example with the [known IPv6 to subnet Gateway IP routing gotcha][docs::ipv6::security-risks] in Docker, trusting the entire subnet DMS belongs to would wrongly trust external clients that have the subnet Gateway IP to impersonate any client IP.
|
|
||||||
- There is a [known risk with Layer 2 switching][docker::networking::l2-switch-gotcha] (_applicable to VPC networks, impact varies by cloud vendor_):
|
|
||||||
- Neighbouring hosts can indirectly route to ports published on the interfaces of a separate host system that shouldn't be reachable (_eg: localhost `127.0.0.1`, or a private subnet `172.16.0.0/12`_).
|
|
||||||
- The scope of this in Docker is limited to published ports only when Docker uses `iptables` with the kernel tunable `sysctl net.ipv4.ip_forward=1` (enabled implicitly). Port access is via `HOST:CONTAINER` ports published to their respective interface(s), that includes the container IP + port.
|
|
||||||
|
|
||||||
While some concerns raised above are rather specific, these type of issues aren't exclusive to Docker and difficult to keep on top of as software is constantly changing. Limit the trusted networks where possible.
|
|
||||||
|
|
||||||
??? warning "Postfix has no concept of trusted proxies"
|
|
||||||
|
|
||||||
Postfix does not appear to have a way to configure trusted proxies like Dovecot does (`haproxy_trusted_networks`).
|
|
||||||
|
|
||||||
[`postscreen_access_list`][postfix-docs::settings::postscreen_access_list] (_or [`smtpd_client_restrictions`][postfix-docs::settings::smtpd_client_restrictions] with [`check_client_access`][postfix-docs::settings::check_client_access] for ports 587/465_) can both restrict access by IP via a [CIDR lookup table][postfix-docs::config-table::cidr], however the client IP is already rewritten at this point via PROXY protocol.
|
|
||||||
|
|
||||||
Thus those settings cannot be used for restricting access to only trusted proxies, only to the actual clients.
|
|
||||||
|
|
||||||
A similar setting [`mynetworks`][postfix-docs::settings::mynetworks] / [`PERMIT_DOCKER`][docs::env::permit_docker] manages elevated trust for bypassing security restrictions. While it is intended for trusted clients, it has no relevance to trusting proxies for the same reasons.
|
|
||||||
|
|
||||||
### Monitoring
|
|
||||||
|
|
||||||
While PROXY protocol works well with the reverse proxy, you may have some containers internally that interact with DMS on behalf of multiple clients.
|
|
||||||
|
|
||||||
??? example "Roundcube + Fail2Ban"
|
|
||||||
|
|
||||||
You may have other services with functionality like an API to send mail through DMS that likewise delegates credentials through DMS.
|
|
||||||
|
|
||||||
Roundcube is an example of this where authentication is delegated to DMS, which introduces the same concern with loss of client IP.
|
|
||||||
|
|
||||||
- While this service does implement some support for preserving the client IP, it is limited.
|
|
||||||
- This may be problematic when monitoring services like Fail2Ban are enabled that scan logs for multiple failed authentication attempts which triggers a ban on the shared IP address.
|
|
||||||
|
|
||||||
You should adjust configuration of these monitoring services to monitor for auth failures from those services directly instead, adding an exclusion for that service IP from any DMS logs monitored (_but be mindful of PROXY header forgery risks_).
|
|
||||||
|
|
||||||
[docs::kubernetes]: ../../config/advanced/kubernetes.md#using-the-proxy-protocol
|
|
||||||
|
|
||||||
[docs::overrides::dovecot]: ../../config/advanced/override-defaults/dovecot.md
|
|
||||||
[docs::overrides::postfix]: ../../config/advanced/override-defaults/postfix.md
|
|
||||||
[docs::overrides::user-patches]: ../../config/advanced/override-defaults/user-patches.md
|
|
||||||
[docs::ipv6::security-risks]: ../../config/advanced/ipv6.md#what-can-go-wrong
|
|
||||||
[docs::tls::traefik]: ../../config/security/ssl.md#traefik
|
|
||||||
[docs::env::permit_docker]: ../../config/environment.md#permit_docker
|
|
||||||
[gh-dms::dns-rewrite-example]: https://github.com/docker-mailserver/docker-mailserver/issues/3866#issuecomment-1928877236
|
|
||||||
|
|
||||||
[nginx-docs::proxyprotocol]: https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol
|
|
||||||
[caddy::plugin::l4]: https://github.com/mholt/caddy-l4
|
|
||||||
|
|
||||||
[traefik-web]: https://traefik.io
|
|
||||||
[traefik-docs::entrypoint::proxyprotocol]: https://doc.traefik.io/traefik/routing/entrypoints/#proxyprotocol
|
|
||||||
[traefik-docs::provider-docker::network]: https://doc.traefik.io/traefik/providers/docker/#network
|
|
||||||
[traefik-docs::router-tcp::server-first-protocols]: https://doc.traefik.io/traefik/routing/routers/#entrypoints_1
|
|
||||||
[traefik-docs::router-tcp::host-sni]: https://doc.traefik.io/traefik/routing/routers/#rule_1
|
|
||||||
[traefik-docs::router-tcp::passthrough]: https://doc.traefik.io/traefik/routing/routers/#passthrough
|
|
||||||
[traefik-docs::service-tcp::proxyprotocol]:https://doc.traefik.io/traefik/routing/services/#proxy-protocol
|
|
||||||
|
|
||||||
[dovecot-docs::settings::haproxy-trusted-networks]: https://doc.dovecot.org/settings/core/#core_setting-haproxy_trusted_networks
|
|
||||||
[dovecot-docs::service-config::haproxy]: https://doc.dovecot.org/configuration_manual/service_configuration/#haproxy-v2-2-19
|
|
||||||
[dovecot-docs::service-config::ssl]: https://doc.dovecot.org/configuration_manual/service_configuration/#ssl
|
|
||||||
|
|
||||||
[postfix-docs::config-table::cidr]: https://www.postfix.org/cidr_table.5.html
|
|
||||||
[postfix-docs::settings::check_client_access]: https://www.postfix.org/postconf.5.html#check_client_access
|
|
||||||
[postfix-docs::settings::mynetworks]: https://www.postfix.org/postconf.5.html#mynetworks
|
|
||||||
[postfix-docs::settings::postscreen_access_list]: https://www.postfix.org/postconf.5.html#postscreen_access_list
|
|
||||||
[postfix-docs::settings::postscreen_upstream_proxy_protocol]: https://www.postfix.org/postconf.5.html#postscreen_upstream_proxy_protocol
|
|
||||||
[postfix-docs::settings::smtpd_client_restrictions]: https://www.postfix.org/postconf.5.html#smtpd_client_restrictions
|
|
||||||
[postfix-docs::settings::smtpd_upstream_proxy_protocol]: https://www.postfix.org/postconf.5.html#smtpd_upstream_proxy_protocol
|
|
||||||
|
|
||||||
[docker::networking::l2-switch-gotcha]: https://github.com/moby/moby/issues/45610
|
|
||||||
[networking::spec:proxy-protocol]: https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt
|
|
||||||
[networking::http-header::x-forwarded-for]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For
|
|
||||||
[networking::http-header::forwarded]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded
|
|
||||||
[networking::osi-model]: https://www.cloudflare.com/learning/ddos/glossary/open-systems-interconnection-model-osi/
|
|
||||||
|
|
@ -1,162 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Examples | Use Cases | Lua Authentication'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
Dovecot has the ability to let users create their own custom user provisioning and authentication providers in [Lua](https://en.wikipedia.org/wiki/Lua_(programming_language)#Syntax). This allows any data source that can be approached from Lua to be used for authentication, including web servers. It is possible to do more with Dovecot and Lua, but other use cases fall outside of the scope of this documentation page.
|
|
||||||
|
|
||||||
!!! warning "Community contributed guide"
|
|
||||||
Dovecot authentication via Lua scripting is not officially supported in DMS. No assistance will be provided should you encounter any issues.
|
|
||||||
|
|
||||||
DMS provides the required packages to support this guide. Note that these packages will be removed should they introduce any future maintenance burden.
|
|
||||||
|
|
||||||
The example in this guide relies on the current way in which DMS works with Dovecot configuration files. Changes to this to accommodate new authentication methods such as OpenID Connect will likely break this example in the future. This guide is updated on a best-effort base.
|
|
||||||
|
|
||||||
Dovecot's Lua support can be used for user provisioning (userdb functionality) and/or password verification (passdb functionality). Consider using other userdb and passdb options before considering Lua, since Lua does require the use of additional (unsupported) program code that might require maintenance when updating DMS.
|
|
||||||
|
|
||||||
Each implementation of Lua-based authentication is custom. Therefore it is impossible to write documentation that covers every scenario. Instead, this page describes a single example scenario. If that scenario is followed, you will learn vital aspects that are necessary to kickstart your own Lua development:
|
|
||||||
|
|
||||||
- How to override Dovecot's default configuration to disable parts that conflict with your scenario.
|
|
||||||
- How to make Dovecot use your Lua script.
|
|
||||||
- How to add your own Lua script and any libraries it uses.
|
|
||||||
- How to debug your Lua script.
|
|
||||||
|
|
||||||
## The example scenario
|
|
||||||
|
|
||||||
This scenario starts with [DMS being configured to use LDAP][docs::auth-ldap] for mailbox identification, user authorization and user authentication. In this scenario, [Nextcloud](https://nextcloud.com/) is also a service that uses the same LDAP server for user identification, authorization and authentication.
|
|
||||||
|
|
||||||
The goal of this scenario is to have Dovecot not authenticate the user against LDAP, but against Nextcloud using an [application password](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html#managing-devices). The idea behind this is that a compromised mailbox password does not compromise the user's account entirely. To make this work, Nextcloud is configured to [deny the use of account passwords by clients](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#token-auth-enforced) and to [disable account password reset through mail verification](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#lost-password-link).
|
|
||||||
|
|
||||||
If the application password is configured correctly, an adversary can only use it to access the user's mailbox on DMS, and CalDAV and CardDAV data on Nextcloud. File access through WebDAV can be disabled for the application password used to access mail. Having CalDAV and CardDAV compromised by the same password is a minor setback. If an adversary gets access to a Nextcloud application password through a device of the user, it is likely that the adversary also gets access to the user's calendars and contact lists anyway (locally or through the same account settings used for mail and CalDAV/CardDAV synchronization). The user's stored files in Nextcloud, the LDAP account password and any other services that rely on it would still be protected. A bonus is that a user is able to revoke and renew the mailbox password in Nextcloud for whatever reason, through a friendly user interface with all the security measures with which the Nextcloud instance is configured (e.g. verification of the current account password).
|
|
||||||
|
|
||||||
A drawback of this method is that any (compromised) Nextcloud application password can be used to access the user's mailbox. This introduces a risk that a Nextcloud application password used for something else (e.g. WebDAV file access) is compromised and used to access the user's mailbox. Discussion of that risk and possible mitigations fall outside of the scope of this scenario.
|
|
||||||
|
|
||||||
To answer the questions asked earlier for this specific scenario:
|
|
||||||
|
|
||||||
1. Do I want to use Lua to identify mailboxes and verify that users are authorized to use mail services? **No. Provisioning is done through LDAP.**
|
|
||||||
1. Do I want to use Lua to verify passwords that users authenticate with for IMAP/POP3/SMTP in their mail clients? **Yes. Password authentication is done through Lua against Nextcloud.**
|
|
||||||
1. If the answer is 'yes' to question 1 or 2: are there other methods that better facilitate my use case instead of custom scripts which rely on me being a developer and not just a user? **No. Only HTTP can be used to authenticate against Nextcloud, which is not supported natively by Dovecot or DMS.**
|
|
||||||
|
|
||||||
While it is possible to extend the authentication methods which Nextcloud can facilitate with [Nextcloud apps](https://apps.nextcloud.com/), there is currently a mismatch between what DMS supports and what Nextcloud applications can provide. This might change in the future. For now, Lua will be used to bridge the gap between DMS and Nextcloud for authentication only (Dovecot passdb), while LDAP will still be used to identify mailboxes and verify authorization (Dovecot userdb).
|
|
||||||
|
|
||||||
## Modify Dovecot's configuration
|
|
||||||
|
|
||||||
???+ example "Add to DMS volumes in `compose.yaml`"
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# All new volumes are marked :ro to configure them as read-only, since their contents are not changed from inside the container
|
|
||||||
volumes:
|
|
||||||
# Configuration override to disable LDAP authentication
|
|
||||||
- ./docker-data/dms/config/dovecot/auth-ldap.conf.ext:/etc/dovecot/conf.d/auth-ldap.conf.ext:ro
|
|
||||||
# Configuration addition to enable Lua authentication
|
|
||||||
- ./docker-data/dms/config/dovecot/auth-lua-httpbasic.conf:/etc/dovecot/conf.d/auth-lua-httpbasic.conf:ro
|
|
||||||
# Directory containing Lua scripts
|
|
||||||
- ./docker-data/dms/config/dovecot/lua/:/etc/dovecot/lua/:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
Create a directory for Lua scripts:
|
|
||||||
```bash
|
|
||||||
mkdir -p ./docker-data/dms/config/dovecot/lua
|
|
||||||
```
|
|
||||||
|
|
||||||
Create configuration file `./docker-data/dms/config/dovecot/auth-ldap.conf.ext` for LDAP user provisioning:
|
|
||||||
```
|
|
||||||
userdb {
|
|
||||||
driver = ldap
|
|
||||||
args = /etc/dovecot/dovecot-ldap.conf.ext
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Create configuration file `./docker-data/dms/config/dovecot/auth-lua-httpbasic.conf` for Lua user authentication:
|
|
||||||
```
|
|
||||||
passdb {
|
|
||||||
driver = lua
|
|
||||||
args = file=/etc/dovecot/lua/auth-httpbasic.lua blocking=yes
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
That is all for configuring Dovecot.
|
|
||||||
|
|
||||||
## Create the Lua script
|
|
||||||
|
|
||||||
Create Lua file `./docker-data/dms/config/dovecot/lua/auth-httpbasic.lua` with contents:
|
|
||||||
|
|
||||||
```lua
|
|
||||||
local http_url = "https://nextcloud.example.com/remote.php/dav/"
|
|
||||||
local http_method = "PROPFIND"
|
|
||||||
local http_status_ok = 207
|
|
||||||
local http_status_failure = 401
|
|
||||||
local http_header_forwarded_for = "X-Forwarded-For"
|
|
||||||
|
|
||||||
package.path = package.path .. ";/etc/dovecot/lua/?.lua"
|
|
||||||
local base64 = require("base64")
|
|
||||||
|
|
||||||
local http_client = dovecot.http.client {
|
|
||||||
timeout = 1000;
|
|
||||||
max_attempts = 1;
|
|
||||||
debug = false;
|
|
||||||
}
|
|
||||||
|
|
||||||
function script_init()
|
|
||||||
return 0
|
|
||||||
end
|
|
||||||
|
|
||||||
function script_deinit()
|
|
||||||
end
|
|
||||||
|
|
||||||
function auth_passdb_lookup(req)
|
|
||||||
local auth_request = http_client:request {
|
|
||||||
url = http_url;
|
|
||||||
method = http_method;
|
|
||||||
}
|
|
||||||
auth_request:add_header("Authorization", "Basic " .. (base64.encode(req.user .. ":" .. req.password)))
|
|
||||||
auth_request:add_header(http_header_forwarded_for, req.remote_ip)
|
|
||||||
local auth_response = auth_request:submit()
|
|
||||||
local resp_status = auth_response:status()
|
|
||||||
local reason = auth_response:reason()
|
|
||||||
|
|
||||||
local returnStatus = dovecot.auth.PASSDB_RESULT_INTERNAL_FAILURE
|
|
||||||
local returnDesc = http_method .. " - " .. http_url .. " - " .. resp_status .. " " .. reason
|
|
||||||
if resp_status == http_status_ok
|
|
||||||
then
|
|
||||||
returnStatus = dovecot.auth.PASSDB_RESULT_OK
|
|
||||||
returnDesc = "nopassword=y"
|
|
||||||
elseif resp_status == http_status_failure
|
|
||||||
then
|
|
||||||
returnStatus = dovecot.auth.PASSDB_RESULT_PASSWORD_MISMATCH
|
|
||||||
returnDesc = ""
|
|
||||||
end
|
|
||||||
return returnStatus, returnDesc
|
|
||||||
end
|
|
||||||
```
|
|
||||||
|
|
||||||
Replace the hostname in the URL to the actual hostname of Nextcloud.
|
|
||||||
|
|
||||||
Dovecot [provides an HTTP client for use in Lua](https://doc.dovecot.org/admin_manual/lua/#dovecot.http.client). Aside of that, Lua by itself is pretty barebones. It chooses library compactness over included functionality. You can see that in that a separate library is referenced to add support for Base64 encoding, which is required for [HTTP basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). This library (also a Lua script) is not included. It must be downloaded and stored in the same directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd ./docker-data/dms/config/dovecot/lua
|
|
||||||
curl -JLO https://raw.githubusercontent.com/iskolbin/lbase64/master/base64.lua
|
|
||||||
```
|
|
||||||
|
|
||||||
Only use native (pure Lua) libraries as dependencies if possible, such as `base64.lua` from the example. This ensures maximum compatibility. Performance is less of an issue since Lua scripts written for Dovecot probably won't be long or complex, and there won't be a lot of data processing by Lua itself.
|
|
||||||
|
|
||||||
## Debugging a Lua script
|
|
||||||
|
|
||||||
To see which Lua version is used by Dovecot if you plan to do something that is version dependent, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec CONTAINER_NAME strings /usr/lib/dovecot/libdovecot-lua.so|grep '^LUA_'
|
|
||||||
```
|
|
||||||
|
|
||||||
While Dovecot logs the status of authentication attempts for any passdb backend, Dovecot will also log Lua scripting errors and messages sent to Dovecot's [Lua API log functions](https://doc.dovecot.org/admin_manual/lua/#dovecot.i_debug). The combined DMS log (including that of Dovecot) can be viewed using `docker logs CONTAINER_NAME`. If the log is too noisy (_due to other processes in the container also logging to it_), `docker exec CONTAINER_NAME cat /var/log/mail/mail.log` can be used to view the log of Dovecot and Postfix specifically.
|
|
||||||
|
|
||||||
If working with HTTP in Lua, setting `debug = true;` when initiating `dovecot.http.client` will create debug log messages for every HTTP request and response.
|
|
||||||
|
|
||||||
Note that Lua runs compiled bytecode, and that scripts will be compiled when they are initially started. Once compiled, the bytecode is cached and changes in the Lua script will not be processed automatically. Dovecot will reload its configuration and clear its cached Lua bytecode when running `docker exec CONTAINER_NAME dovecot reload`. A (changed) Lua script will be compiled to bytecode the next time it is executed after running the Dovecot reload command.
|
|
||||||
|
|
||||||
[docs::auth-ldap]: ../../config/account-management/provisioner/ldap.md
|
|
||||||
[docs::dovecot-override-configuration]: ../../config/advanced/override-defaults/dovecot.md#override-configuration
|
|
||||||
[docs::dovecot-add-configuration]: ../../config/advanced/override-defaults/dovecot.md#add-configuration
|
|
||||||
[docs::faq-alter-running-dms-instance-without-container-relaunch]: ../../faq.md#how-to-alter-a-running-dms-instance-without-relaunching-the-container
|
|
||||||
|
|
@ -1,106 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Use Cases | Binding outbound SMTP to a specific network'
|
|
||||||
hide:
|
|
||||||
- toc
|
|
||||||
---
|
|
||||||
|
|
||||||
!!! warning "Advice not extensively tested"
|
|
||||||
|
|
||||||
This configuration advice is a community contribution which has only been verified as a solution when using `network: host`, where you have direct access to the host interfaces.
|
|
||||||
|
|
||||||
It may be applicable in other network modes if the container has control of the outbound IPs to bind to. This is not the case with bridge networks that typically bind to a private range network for containers which are bridged to a public interface via Docker.
|
|
||||||
|
|
||||||
If your Docker host is running multiple IPv4 and IPv6 IP-addresses, it may be beneficial to bind outgoing SMTP connections to specific IP-address / interface.
|
|
||||||
|
|
||||||
- When a mail is sent outbound from DMS, it greets the MTA it is connecting to with a EHLO (DMS FQDN) which might be verified against the IP resolved, and that a `PTR` record for that IP resolves an address back to the same IP.
|
|
||||||
- A similar check with SPF can be against the envelope-sender address which may verify a DNS record like MX / A is valid (_or a similar restriction check from an MTA like [Postfix has with `reject_unknown_sender`][gh-pr::3465::comment-restrictions]_).
|
|
||||||
- If the IP address is inconsistent for those connections from DMS, these DNS checks are likely to fail.
|
|
||||||
|
|
||||||
This can be configured by [overriding the default Postfix configurations][docs::overrides-postfix] DMS provides. Create `postfix-master.cf` and `postfix-main.cf` files for your config volume (`docker-data/dms/config`).
|
|
||||||
|
|
||||||
In `postfix-main.cf` you'll have to set the [`smtp_bind_address`][postfix-docs::smtp-bind-address-ipv4] and [`smtp_bind_address6`][postfix-docs::smtp-bind-address-ipv6]
|
|
||||||
to the respective IP-address on the server you want to use.
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
=== "Contributed solution"
|
|
||||||
|
|
||||||
```title="postfix-main.cf"
|
|
||||||
smtp_bind_address = 198.51.100.42
|
|
||||||
smtp_bind_address6 = 2001:DB8::42
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! bug "Inheriting the bind from `main.cf` can misconfigure services"
|
|
||||||
|
|
||||||
One problem when setting `smtp_bind_address` in `main.cf` is that it will be inherited by any services in `master.cf` that extend the `smtp` transport. One of these is `smtp-amavis`, which is explicitly configured to listen / connect via loopback (localhost / `127.0.0.1`).
|
|
||||||
|
|
||||||
A `postfix-master.cf` override can workaround that issue by ensuring `smtp-amavis` binds to the expected internal IP:
|
|
||||||
|
|
||||||
```title="postfix-master.cf"
|
|
||||||
smtp-amavis/unix/smtp_bind_address=127.0.0.1
|
|
||||||
smtp-amavis/unix/smtp_bind_address6=::1
|
|
||||||
```
|
|
||||||
|
|
||||||
=== "Alternative (unverified)"
|
|
||||||
|
|
||||||
A potentially better solution might be to instead [explicitly set the `smtp_bind_address` override on the `smtp` transport service][gh-pr::3465::alternative-solution]:
|
|
||||||
|
|
||||||
```title="postfix-master.cf"
|
|
||||||
smtp/inet/smtp_bind_address = 198.51.100.42
|
|
||||||
smtp/inet/smtp_bind_address6 = 2001:DB8::42
|
|
||||||
```
|
|
||||||
|
|
||||||
If that avoids the concern with `smtp-amavis`, you may still need to additionally override for the [`relay` transport][gh-src::postfix-master-cf::relay-transport] as well if you have configured DMS to relay mail.
|
|
||||||
|
|
||||||
=== "Bridged Networks"
|
|
||||||
|
|
||||||
When your DMS container is using a bridge network, you'll instead need to restrict which IP address inbound and outbound traffic is routed through via the bridged interface.
|
|
||||||
|
|
||||||
For **inbound** traffic, you may configure this at whatever scope is most appropriate for you:
|
|
||||||
|
|
||||||
- **Daemon:** Change the [default bind address][inbound-ip::docker-docs::daemon] configured in `/etc/docker/daemon.json` (default `0.0.0.0`)
|
|
||||||
- **Network:** Assign the [`host_binding_ipv4` bridge driver option][inbound-ip::docker-docs::network] as shown in the below `compose.yaml` snippet.
|
|
||||||
- **Container:** Provide an explicit host IP address when [publishing a port][inbound-ip::docker-docs::container].
|
|
||||||
|
|
||||||
For **outbound** traffic, the bridge network will use the default route. You can change this by either:
|
|
||||||
|
|
||||||
- [Manually routing networks][outbound-ip::route-manually] on the host.
|
|
||||||
- Use the [`host_ipv4` driver option][outbind-ip::host-ipv4] for Docker networks to force the SNAT (source IP) that the bridged network will route outbound traffic through.
|
|
||||||
- This IP address must belong to a network interface to be routed through it.
|
|
||||||
- IPv6 support via `host_ipv6` [requires at least Docker v25][outbind-ip::host-ipv6].
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Here is a `compose.yaml` snippet that applies the inbound + outbound settings to the default bridge network Docker Compose creates (_if it already exists, you will need to ensure it's re-created to apply the updated settings_):
|
|
||||||
|
|
||||||
```yaml title="compose.yaml"
|
|
||||||
networks:
|
|
||||||
default:
|
|
||||||
driver_opts:
|
|
||||||
# Inbound IP (sets the host IP that published ports receive traffic from):
|
|
||||||
com.docker.network.bridge.host_binding_ipv4: 198.51.100.42
|
|
||||||
# Outbound IP (sets the host IP that external hosts will receive connections from):
|
|
||||||
com.docker.network.host_ipv4: 198.51.100.42
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! note "IP addresses for documentation"
|
|
||||||
|
|
||||||
IP addresses shown in above examples (`198.51.100.42` + `2001:DB8::42`) are placeholders, they are IP addresses reserved for documentation by IANA (_[RFC-5737 (IPv4)][rfc-5737] and [RFC-3849 (IPv6)][rfc-3849]_). Replace them with the IP addresses you want DMS to send mail through.
|
|
||||||
|
|
||||||
[docs::overrides-postfix]: ../../config/advanced/override-defaults/postfix.md
|
|
||||||
[postfix-docs::smtp-bind-address-ipv4]: https://www.postfix.org/postconf.5.html#smtp_bind_address
|
|
||||||
[postfix-docs::smtp-bind-address-ipv6]: https://www.postfix.org/postconf.5.html#smtp_bind_address6
|
|
||||||
|
|
||||||
[rfc-5737]: https://datatracker.ietf.org/doc/html/rfc5737
|
|
||||||
[rfc-3849]: https://datatracker.ietf.org/doc/html/rfc3849
|
|
||||||
|
|
||||||
[gh-pr::3465::comment-restrictions]: https://github.com/docker-mailserver/docker-mailserver/pull/3465#discussion_r1458114528
|
|
||||||
[gh-pr::3465::alternative-solution]: https://github.com/docker-mailserver/docker-mailserver/pull/3465#issuecomment-1678107233
|
|
||||||
[gh-src::postfix-master-cf::relay-transport]: https://github.com/docker-mailserver/docker-mailserver/blob/9cdbef2b369fb4fb0f1b4e534da8703daf92abc9/target/postfix/master.cf#L65
|
|
||||||
|
|
||||||
[inbound-ip::docker-docs::daemon]: https://docs.docker.com/reference/cli/dockerd/#default-network-options
|
|
||||||
[inbound-ip::docker-docs::network]: https://docs.docker.com/engine/network/drivers/bridge/#default-host-binding-address
|
|
||||||
[inbound-ip::docker-docs::container]: https://docs.docker.com/reference/compose-file/services/#ports
|
|
||||||
[outbound-ip::route-manually]: https://github.com/moby/moby/issues/30053#issuecomment-1077041045
|
|
||||||
[outbind-ip::host-ipv4]: https://github.com/moby/libnetwork/pull/2454
|
|
||||||
[outbind-ip::host-ipv6]: https://github.com/moby/moby/issues/46469
|
|
||||||
|
|
@ -1,233 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Use Cases | Relay inbound and outbound mail for an internal DMS'
|
|
||||||
hide:
|
|
||||||
- toc
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
!!! info "Community contributed guide"
|
|
||||||
|
|
||||||
Adapted into a guide from [this discussion](https://github.com/orgs/docker-mailserver/discussions/3965).
|
|
||||||
|
|
||||||
**Requirements:**
|
|
||||||
|
|
||||||
- A _public server_ with a static IP, like many VPS providers offer. It will only relay mail to DMS, no mail is stored on this system.
|
|
||||||
- A _private server_ (e.g.: a local system at home) that will run DMS.
|
|
||||||
- Both servers are connected to the same network via a VPN (_optional convenience for trust via the `mynetworks` setting_).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
The guide below will assume the VPN is setup on `192.168.2.0/24` with:
|
|
||||||
|
|
||||||
- The _public server_ is using `192.168.2.2`
|
|
||||||
- The _private server_ is using `192.168.2.3`
|
|
||||||
|
|
||||||
The goal of this guide is to configure a _public server_ that can receive inbound mail and relay that over to DMS on a _private server_, which can likewise submit mail outbound through a _public server_ or service.
|
|
||||||
|
|
||||||
The primary motivation is to keep your mail storage private instead of storing it to disk unencrypted on a VPS host.
|
|
||||||
|
|
||||||
## DNS setup
|
|
||||||
|
|
||||||
Follow our [standard guidance][docs::usage-dns-setup] for DNS setup.
|
|
||||||
|
|
||||||
Set your A, MX and PTR records for the _public server_ as if it were running DMS.
|
|
||||||
|
|
||||||
!!! example "DNS Zone file example"
|
|
||||||
|
|
||||||
For this guide, we assume DNS is configured with:
|
|
||||||
|
|
||||||
- A public reachable IP address of `11.22.33.44`
|
|
||||||
- Mail for `@example.com` addresses must have an MX record pointing to `mail.example.com`.
|
|
||||||
- An A record for `mail.example.com` pointing to the IP address of your _public server_.
|
|
||||||
|
|
||||||
```txt
|
|
||||||
$ORIGIN example.com
|
|
||||||
@ IN A 11.22.33.44
|
|
||||||
mail IN A 11.22.33.44
|
|
||||||
|
|
||||||
; mail server for example.com
|
|
||||||
@ IN MX 10 mail.example.com.
|
|
||||||
```
|
|
||||||
|
|
||||||
SPF records should also be set up as you normally would for `mail.example.com`.
|
|
||||||
|
|
||||||
## Public Server (Basic Postfix setup)
|
|
||||||
|
|
||||||
You will need to install Postfix on your _public server_. The functionality that is needed for this setup is not yet implemented in DMS, so a vanilla Postfix will probably be easier to work with, especially since this server will only be used as an inbound and outbound relay.
|
|
||||||
|
|
||||||
It's necessary to adjust some settings afterwards.
|
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
|
||||||
!!! quote ""
|
|
||||||
|
|
||||||
=== "Postfix main config"
|
|
||||||
|
|
||||||
??? example "Create or replace `/etc/postfix/main.cf`"
|
|
||||||
|
|
||||||
```cf
|
|
||||||
# See /usr/share/postfix/main.cf.dist for a commented, more complete version
|
|
||||||
|
|
||||||
smtpd_banner = $myhostname ESMTP $mail_name (Debian/GNU)
|
|
||||||
biff = no
|
|
||||||
|
|
||||||
# appending .domain is the MUA's job.
|
|
||||||
append_dot_mydomain = no
|
|
||||||
|
|
||||||
# Uncomment the next line to generate "delayed mail" warnings
|
|
||||||
#delay_warning_time = 4h
|
|
||||||
|
|
||||||
# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 3.6 on
|
|
||||||
# fresh installs.
|
|
||||||
compatibility_level = 3.6
|
|
||||||
|
|
||||||
# TLS parameters
|
|
||||||
smtpd_tls_cert_file=/etc/postfix/certificates/mail.example.com.crt
|
|
||||||
smtpd_tls_key_file=/etc/postfix/certificates/mail.example.com.key
|
|
||||||
smtpd_tls_security_level=may
|
|
||||||
smtp_tls_CApath=/etc/ssl/certs
|
|
||||||
smtp_tls_security_level=may
|
|
||||||
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache
|
|
||||||
|
|
||||||
alias_database = hash:/etc/aliases
|
|
||||||
alias_maps = hash:/etc/aliases
|
|
||||||
maillog_file = /var/log/postfix.log
|
|
||||||
mailbox_size_limit = 0
|
|
||||||
inet_interfaces = all
|
|
||||||
inet_protocols = ipv4
|
|
||||||
readme_directory = no
|
|
||||||
recipient_delimiter = +
|
|
||||||
|
|
||||||
# Customizations relevant to this guide:
|
|
||||||
myhostname = mail.example.com
|
|
||||||
myorigin = example.com
|
|
||||||
mydestination = localhost
|
|
||||||
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128 192.168.2.0/24
|
|
||||||
smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
|
|
||||||
transport_maps = hash:/etc/postfix/transport
|
|
||||||
relay_domains = $mydestination, hash:/etc/postfix/relay
|
|
||||||
|
|
||||||
# Disable local system accounts and delivery:
|
|
||||||
local_recipient_maps =
|
|
||||||
local_transport = error:local mail delivery is disabled
|
|
||||||
```
|
|
||||||
|
|
||||||
Let's highlight some of the important parts:
|
|
||||||
|
|
||||||
- Avoid including `mail.example.com` in `mydestination`, in fact you can just set `localhost` or nothing at all here as we want all mail to be relayed to our _private server_ (DMS).
|
|
||||||
- `mynetworks` should contain your VPN network (_eg: `192.168.2.0/24` subnet_).
|
|
||||||
- Important are `transport_maps = hash:/etc/postfix/transport` and `relay_domains = $mydestination, hash:/etc/postfix/relay`, with their file contents covered below.
|
|
||||||
- For good measure, also disable `local_recipient_maps`.
|
|
||||||
- You should have a valid certificate configured for `mail.example.com`.
|
|
||||||
|
|
||||||
!!! warning "Open relay"
|
|
||||||
|
|
||||||
Please be aware that setting `mynetworks` to a public CIDR will leave you with an open relay. **Only** set it to the CIDR of your VPN beyond the localhost ranges.
|
|
||||||
|
|
||||||
=== "Route outbound mail through a separate transport"
|
|
||||||
|
|
||||||
When mail arrives to the _public server_ for an `@example.com` address, we want to send it via the `relay` transport to our _private server_ over port 25 for delivery to DMS.
|
|
||||||
|
|
||||||
[`transport_maps`][postfix-docs::transport_maps] is configured with a [`transport` table][postfix-docs::transport_table] file that matches recipient addresses and assigns a non-default transport. This setting has priority over [`relay_transport`][postfix-docs::relay_transport].
|
|
||||||
|
|
||||||
!!! example "Create `/etc/postfix/transport`"
|
|
||||||
|
|
||||||
```txt
|
|
||||||
example.com relay:[192.168.2.3]:25
|
|
||||||
```
|
|
||||||
|
|
||||||
**Other considerations:**
|
|
||||||
|
|
||||||
- If you have multiple domains, you can add them here too (on separate lines).
|
|
||||||
- If you use a smarthost add `* relay:[X.X.X.X]:port` to the bottom (eg: `* relay:[relay1.org]:587`), which will relay everything outbound via this relay host.
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
Instead of a file, you could alternatively configure `main.cf` with `transport_maps = inline:{ example.com=relay:[192.168.2.3]:25 }`
|
|
||||||
|
|
||||||
=== "Configure recipient domains to relay mail"
|
|
||||||
|
|
||||||
We want `example.com` to be relayed inbound and everything else relayed outbound.
|
|
||||||
|
|
||||||
[`relay_domains`][postfix-docs::relay_domains] is configured with a file with a list of domains that should be relayed (one per line), the 2nd value is required but can be anything.
|
|
||||||
|
|
||||||
!!! example "Create `/etc/postfix/relay`"
|
|
||||||
|
|
||||||
```txt
|
|
||||||
example.com OK
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
Instead of a file, you could alternatively configure `main.cf` with `relay_domains = example.com`.
|
|
||||||
|
|
||||||
!!! note "Files configured with `hash:` table type must run `postmap` to apply changes"
|
|
||||||
|
|
||||||
Run `postmap /etc/postfix/transport` and `postmap /etc/postfix/relay` after creating or updating either of these files, this processes them into a separate file for Postfix to use.
|
|
||||||
|
|
||||||
## Private Server (Running DMS)
|
|
||||||
|
|
||||||
You can set up your DMS instance as you normally would.
|
|
||||||
|
|
||||||
- Be careful not to give it a hostname of `mail.example.com`. Instead, use `internal-mail.example.com` or something similar.
|
|
||||||
- DKIM can be setup as usual since it considers checks whether the message body has been tampered with, which our public relay doesn't do. Set DKIM up for `mail.example.com`.
|
|
||||||
|
|
||||||
Next, we need to configure our _private server_ to relay all outbound mail through the _public server_ (or a separate smarthost service). The setup is [similar to the default relay setup][docs::relay-host-details].
|
|
||||||
|
|
||||||
<!-- This empty quote block is purely for a visual border -->
|
|
||||||
!!! quote ""
|
|
||||||
|
|
||||||
=== "Configure the relay host"
|
|
||||||
|
|
||||||
!!! example "Create `postfix-relaymap.cf`"
|
|
||||||
|
|
||||||
```txt
|
|
||||||
@example.com [192.168.2.2]:25
|
|
||||||
```
|
|
||||||
|
|
||||||
Meaning all mail sent outbound from `@example.com` addresses will be relayed through the _public server_ at that VPN IP.
|
|
||||||
|
|
||||||
The _public server_ `mynetworks` setting from earlier trusts any mail received on port 25 from the VPN network, which is what allows the mail to be sent outbound when it'd otherwise be denied.
|
|
||||||
|
|
||||||
=== "Trust the _public server_"
|
|
||||||
|
|
||||||
!!! example "Create `postfix-main.cf`"
|
|
||||||
|
|
||||||
```txt
|
|
||||||
mynetworks = 192.168.2.0/24
|
|
||||||
```
|
|
||||||
|
|
||||||
This will trust any connection from the VPN network to DMS, such as from the _public server_ when relaying mail over to DMS at the _private server_.
|
|
||||||
|
|
||||||
This step is necessary to skip some security measures that DMS normally checks for, like verifying DNS records like SPF are valid. As the mail is being relayed, those checks would fail otherwise as the IP of your _public server_ would not be authorized to send mail on behalf of the sender address in mail being relayed.
|
|
||||||
|
|
||||||
??? tip "Alternative to `mynetworks` setting"
|
|
||||||
|
|
||||||
Instead of trusting connections by their IP with the `mynetworks` setting, those same security measures can be skipped for any authenticated deliveries to DMS over port 587 instead.
|
|
||||||
|
|
||||||
This is a bit more work. `mynetworks` on the _public server_ `main.cf` Postfix config is for trusting DMS when it sends mail from the _private server_, thus you'll need to have that public Postfix service configured with a login account that DMS can use.
|
|
||||||
|
|
||||||
On the _private server_, DMS needs to know the credentials for that login account, that is handled with `postfix-sasl-password.cf`:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
@example.com user:secret
|
|
||||||
```
|
|
||||||
|
|
||||||
You could also relay mail through SendGrid, AWS SES or similar instead of the _public server_ you're running to receive mail from. Login credentials for those relay services are provided via the same `postfix-sasl-password.cf` file.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
Likewise for the _public server_ to send mail to DMS, it would need to be configured to relay mail with credentials too, removing the need for `mynetworks` on the DMS `postfix-main.cf` config.
|
|
||||||
|
|
||||||
The extra effort to require authentication instead of blind trust of your private subnet can be beneficial at reducing the impact of a compromised system or service on that network that wasn't expected to be permitted to send mail.
|
|
||||||
|
|
||||||
## IMAP / POP3
|
|
||||||
|
|
||||||
IMAP and POP3 need to point towards your _private server_, since that is where the mailboxes are located, which means you need to have a way for your MUA to connect to it.
|
|
||||||
|
|
||||||
[docs::usage-dns-setup]: ../../usage.md#minimal-dns-setup
|
|
||||||
[docs::relay-host-details]: ../../config/advanced/mail-forwarding/relay-hosts.md#technical-details
|
|
||||||
[postfix-docs::relay_domains]: https://www.postfix.org/postconf.5.html#relay_domains
|
|
||||||
[postfix-docs::relay_transport]: https://www.postfix.org/postconf.5.html#relay_transport
|
|
||||||
[postfix-docs::transport_maps]: https://www.postfix.org/postconf.5.html#transport_maps
|
|
||||||
[postfix-docs::transport_table]: https://www.postfix.org/transport.5.html
|
|
||||||
|
|
@ -1,108 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Use Cases | Forward-Only Mail Server with LDAP'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Building a Forward-Only Mail Server
|
|
||||||
|
|
||||||
A **forward-only** mail server does not have any local mailboxes. Instead, it has only aliases that forward emails to external email accounts (for example to a Gmail account). You can also send email from the localhost (the computer where DMS is installed), using as sender any of the alias addresses.
|
|
||||||
|
|
||||||
The important settings for this setup (on `mailserver.env`) are these:
|
|
||||||
|
|
||||||
```env
|
|
||||||
PERMIT_DOCKER=host
|
|
||||||
ENABLE_POP3=
|
|
||||||
ENABLE_CLAMAV=0
|
|
||||||
SMTP_ONLY=1
|
|
||||||
ENABLE_SPAMASSASSIN=0
|
|
||||||
ENABLE_FETCHMAIL=0
|
|
||||||
```
|
|
||||||
|
|
||||||
Since there are no local mailboxes, we use `SMTP_ONLY=1` to disable `dovecot`. We disable as well the other services that are related to local mailboxes (`POP3`, `ClamAV`, `SpamAssassin`, etc.)
|
|
||||||
|
|
||||||
We can create aliases with `./setup.sh`, like this:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
./setup.sh alias add <alias-address> <external-email-account>
|
|
||||||
```
|
|
||||||
|
|
||||||
## Authenticating with LDAP
|
|
||||||
|
|
||||||
If you want to send emails from outside the mail server you have to authenticate somehow (with a username and password). One way of doing it is described in [this discussion][github-issue-1247]. However if there are many user accounts, it is better to use authentication with LDAP. The settings for this on `mailserver.env` are:
|
|
||||||
|
|
||||||
```env
|
|
||||||
ACCOUNT_PROVISIONER=LDAP
|
|
||||||
LDAP_START_TLS=yes
|
|
||||||
LDAP_SERVER_HOST=ldap.example.org
|
|
||||||
LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
|
|
||||||
LDAP_BIND_DN=cn=mailserver,dc=example,dc=org
|
|
||||||
LDAP_BIND_PW=pass1234
|
|
||||||
|
|
||||||
ENABLE_SASLAUTHD=1
|
|
||||||
SASLAUTHD_MECHANISMS=ldap
|
|
||||||
SASLAUTHD_LDAP_SERVER=ldap.example.org
|
|
||||||
SASLAUTHD_LDAP_START_TLS=yes
|
|
||||||
SASLAUTHD_LDAP_BIND_DN=cn=mailserver,dc=example,dc=org
|
|
||||||
SASLAUTHD_LDAP_PASSWORD=pass1234
|
|
||||||
SASLAUTHD_LDAP_SEARCH_BASE=ou=users,dc=example,dc=org
|
|
||||||
SASLAUTHD_LDAP_FILTER=(&(uid=%U)(objectClass=inetOrgPerson))
|
|
||||||
```
|
|
||||||
|
|
||||||
My LDAP data structure is very basic, containing only the username, password, and the external email address where to forward emails for this user. An entry looks like this:
|
|
||||||
|
|
||||||
```properties
|
|
||||||
add uid=username,ou=users,dc=example,dc=org
|
|
||||||
uid: username
|
|
||||||
objectClass: inetOrgPerson
|
|
||||||
sn: username
|
|
||||||
cn: username
|
|
||||||
userPassword: {SSHA}abcdefghi123456789
|
|
||||||
email: external-account@gmail.com
|
|
||||||
```
|
|
||||||
|
|
||||||
This structure is different from what is expected/assumed from the configuration scripts of DMS, so it doesn't work just by using the `LDAP_QUERY_FILTER_...` settings. Instead, I had to use a custom configuration ([via `user-patches.sh`][docs-userpatches]). I created the script `docker-data/dms/config/user-patches.sh`, with content like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
rm -f /etc/postfix/{ldap-groups.cf,ldap-domains.cf}
|
|
||||||
|
|
||||||
postconf \
|
|
||||||
"virtual_mailbox_domains = /etc/postfix/vhost" \
|
|
||||||
"virtual_alias_maps = ldap:/etc/postfix/ldap-aliases.cf texthash:/etc/postfix/virtual" \
|
|
||||||
"smtpd_sender_login_maps = ldap:/etc/postfix/ldap-users.cf"
|
|
||||||
|
|
||||||
sed -i /etc/postfix/ldap-users.cf \
|
|
||||||
-e '/query_filter/d' \
|
|
||||||
-e '/result_attribute/d' \
|
|
||||||
-e '/result_format/d'
|
|
||||||
cat <<EOF >> /etc/postfix/ldap-users.cf
|
|
||||||
query_filter = (uid=%u)
|
|
||||||
result_attribute = uid
|
|
||||||
result_format = %s@example.org
|
|
||||||
EOF
|
|
||||||
|
|
||||||
sed -i /etc/postfix/ldap-aliases.cf \
|
|
||||||
-e '/domain/d' \
|
|
||||||
-e '/query_filter/d' \
|
|
||||||
-e '/result_attribute/d'
|
|
||||||
cat <<EOF >> /etc/postfix/ldap-aliases.cf
|
|
||||||
domain = example.org
|
|
||||||
query_filter = (uid=%u)
|
|
||||||
result_attribute = mail
|
|
||||||
EOF
|
|
||||||
|
|
||||||
postfix reload
|
|
||||||
```
|
|
||||||
|
|
||||||
You see that besides `query_filter`, I had to customize as well `result_attribute` and `result_format`.
|
|
||||||
|
|
||||||
!!! note "See also"
|
|
||||||
|
|
||||||
For more details about using LDAP see: [LDAP managed mail server with Postfix and Dovecot for multiple domains](https://www.vennedey.net/resources/2-LDAP-managed-mail-server-with-Postfix-and-Dovecot-for-multiple-domains)
|
|
||||||
|
|
||||||
!!! note
|
|
||||||
|
|
||||||
Another solution that serves as a forward-only mail server is [this](https://gitlab.com/docker-scripts/postfix).
|
|
||||||
|
|
||||||
[docs-userpatches]: ../../config/advanced/override-defaults/user-patches.md
|
|
||||||
[github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247
|
|
||||||
|
|
@ -1,72 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Use Cases | Customize Mailbox Folders'
|
|
||||||
hide:
|
|
||||||
- toc # Hide Table of Contents for this page
|
|
||||||
---
|
|
||||||
|
|
||||||
# Mailboxes (_aka IMAP Folders_)
|
|
||||||
|
|
||||||
`INBOX` is setup as the private [`inbox` namespace][dovecot-docs-namespaces]. By default [`target/dovecot/15-mailboxes.conf`][github-config-dovecot-mailboxes] configures the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash` to be automatically created and subscribed. They are all assigned to the private [`inbox` namespace][dovecot-docs-namespaces] (_which implicitly provides the `INBOX` folder_).
|
|
||||||
|
|
||||||
These IMAP folders are considered special because they add a [_"SPECIAL-USE"_ attribute][rfc-6154], which is a standardized way to communicate to mail clients that the folder serves a purpose like storing spam/junk mail (`\Junk`) or deleted mail (`\Trash`). This differentiates them from regular mail folders that you may use for organizing.
|
|
||||||
|
|
||||||
## Adding a mailbox folder
|
|
||||||
|
|
||||||
See [`target/dovecot/15-mailboxes.conf`][github-config-dovecot-mailboxes] for existing mailbox folders which you can modify or uncomment to enable some other common mailboxes. For more information try the [official Dovecot documentation][dovecot-docs-mailboxes].
|
|
||||||
|
|
||||||
The `Archive` special IMAP folder may be useful to enable. To do so, make a copy of [`target/dovecot/15-mailboxes.conf`][github-config-dovecot-mailboxes] and uncomment the `Archive` mailbox definition. Mail clients should understand that this folder is intended for archiving mail due to the [`\Archive` _"SPECIAL-USE"_ attribute][rfc-6154].
|
|
||||||
|
|
||||||
With the provided [compose.yaml][github-config-dockercompose] example, a volume bind mounts the host directory `docker-data/dms/config/` to the container location `/tmp/docker-mailserver/`. Config file overrides should instead be mounted to a different location as described in [Overriding Configuration for Dovecot][docs-config-overrides-dovecot]:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/config/dovecot/15-mailboxes.conf:/etc/dovecot/conf.d/15-mailboxes.conf:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
## Caution
|
|
||||||
|
|
||||||
### Adding folders to an existing setup
|
|
||||||
|
|
||||||
Handling of newly added mailbox folders can be inconsistent across mail clients:
|
|
||||||
|
|
||||||
- Users may experience issues such as archived emails only being available locally.
|
|
||||||
- Users may need to migrate emails manually between two folders.
|
|
||||||
|
|
||||||
### Support for `SPECIAL-USE` attributes
|
|
||||||
|
|
||||||
Not all mail clients support the `SPECIAL-USE` attribute for mailboxes (_defined in [RFC 6154][rfc-6154]_). These clients will treat the mailbox folder as any other, using the name assigned to it instead.
|
|
||||||
|
|
||||||
Some clients may still know to treat these folders for their intended purpose if the mailbox name matches the common names that the `SPECIAL-USE` attributes represent (_eg `Sent` as the mailbox name for `\Sent`_).
|
|
||||||
|
|
||||||
### Internationalization (i18n)
|
|
||||||
|
|
||||||
Usually the mail client will know via context such as the `SPECIAL-USE` attribute or common English mailbox names, to provide a localized label for the users preferred language.
|
|
||||||
|
|
||||||
Take care to test localized names work well as well.
|
|
||||||
|
|
||||||
### Email Clients Support
|
|
||||||
|
|
||||||
- If a new mail account is added without the `SPECIAL-USE` attribute enabled for archives:
|
|
||||||
- **Thunderbird** suggests and may create an `Archives` folder on the server.
|
|
||||||
- **Outlook for Android** archives to a local folder.
|
|
||||||
- **Spark for Android** archives to server folder named `Archive`.
|
|
||||||
- If a new mail account is added after the `SPECIAL-USE` attribute is enabled for archives:
|
|
||||||
- **Thunderbird**, **Outlook for Android** and **Spark for Android** will use the mailbox folder name assigned.
|
|
||||||
|
|
||||||
!!! caution "Windows Mail"
|
|
||||||
|
|
||||||
**Windows Mail** has been said to ignore `SPECIAL-USE` attribute and look only at the mailbox folder name assigned.
|
|
||||||
|
|
||||||
!!! note "Needs citation"
|
|
||||||
|
|
||||||
This information is provided by the community.
|
|
||||||
|
|
||||||
It presently lacks references to confirm the behavior. If any information is incorrect please let us know! :smile:
|
|
||||||
|
|
||||||
|
|
||||||
[docs-config-overrides-dovecot]: ../../config/advanced/override-defaults/dovecot.md#override-configuration
|
|
||||||
[github-config-dockercompose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml
|
|
||||||
[github-config-dovecot-mailboxes]: https://github.com/docker-mailserver/docker-mailserver/blob/master/target/dovecot/15-mailboxes.conf
|
|
||||||
[dovecot-docs-namespaces]: https://doc.dovecot.org/configuration_manual/namespace/#namespace-inbox
|
|
||||||
[dovecot-docs-mailboxes]: https://doc.dovecot.org/configuration_manual/namespace/#mailbox-settings
|
|
||||||
[rfc-6154]: https://datatracker.ietf.org/doc/html/rfc6154
|
|
||||||
|
|
@ -1,232 +0,0 @@
|
||||||
---
|
|
||||||
title: 'Advanced | iOS Mail Push Support'
|
|
||||||
---
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
iOS Mail currently does not support the IMAP idle extension. Therefore users can only either check manually or configure intervals for fetching mails in their mail account preferences when using the default configuration.
|
|
||||||
|
|
||||||
To support mail push Dovecot needs to advertise the `XAPPLEPUSHSERVICE` IMAP extension as well as sending the actual push notifications to the Apple Push Notification service (APNs) which will forward them to the device.
|
|
||||||
|
|
||||||
This can be done with two components:
|
|
||||||
|
|
||||||
- A Dovecot plugin (`dovecot-xaps-plugin`) which is triggered whenever a mail is created or moved from/to a mail folder.
|
|
||||||
- A daemon service (`dovecot-xaps-daemon`) that manages both the device registrations as well as sending notifications to the APNs.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
- An Apple developer account to create the required Apple Push Notification service certificate.
|
|
||||||
- Knowledge creating Docker images, using the command-line, and creating shell scripts.
|
|
||||||
|
|
||||||
## Limitations
|
|
||||||
|
|
||||||
- You need to maintain a custom `docker-mailserver` image.
|
|
||||||
- Push support is limited to the INBOX folder. Changes to other folders will not be pushed to the device regardless of the configuration settings.
|
|
||||||
- You currently cannot use the same account UUID on multiple devices. This means that if you use the same backup on multiple devices (e.g. old phone / new phone) only one of them will get the notification. Use different backups or recreate the mail account.
|
|
||||||
|
|
||||||
## Privacy concerns
|
|
||||||
|
|
||||||
- The service does not send any part of the actual message to Apple.
|
|
||||||
- The information sent contains the device UUID to notify and the (on-device) account UUID which was generated by the iOS mail application when creating the account.
|
|
||||||
- Upon receiving the notification, the iOS mail application will connect to the IMAP server given by the provided account UUID and fetch the mail to notify the user.
|
|
||||||
- Apple therefore does not know the mail address for which the mail was received, only that a specific account on a specific device should be notified that a new mail or that a mail was moved to the INBOX folder.
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
Both components will be built using Docker and included into a custom `docker-mailserver` image. Afterwards the required configuration is added to `docker-data/dms/config`. The registration data is stored in `/var/mail-state/lib-xapsd`.
|
|
||||||
|
|
||||||
1. Create a Dockerfile to build a `docker-mailserver` image that includes the [`dovecot-xaps-plugin`](https://github.com/freswa/dovecot-xaps-plugin) as well as the [`dovecot-xaps-daemon`](https://github.com/freswa/dovecot-xaps-daemon). This is required to ensure that the Dovecot plugin is built against the same Dovecot version. The `:edge` tag is used here, but you might want to use a released version instead.
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
FROM mailserver/docker-mailserver:edge AS dovecot-plugin-xaps
|
|
||||||
WORKDIR /tmp/dovecot-xaps-plugin
|
|
||||||
RUN <<EOF
|
|
||||||
apt-get update
|
|
||||||
apt-get -y --no-install-recommends install git cmake make build-essential dovecot-dev
|
|
||||||
git clone --single-branch --depth=1 https://github.com/freswa/dovecot-xaps-plugin.git .
|
|
||||||
mkdir build && cd build
|
|
||||||
cmake .. -DCMAKE_BUILD_TYPE=Release
|
|
||||||
make install
|
|
||||||
EOF
|
|
||||||
|
|
||||||
# Use an older Go version as Go >= 1.20 causes this issue: https://github.com/freswa/dovecot-xaps-daemon/issues/24#issuecomment-1483876081
|
|
||||||
# Note that the underlying issue are non-standard-compliant Apple http servers which might get fixed at some point
|
|
||||||
FROM golang:1.19-alpine AS dovecot-xaps-daemon
|
|
||||||
ENV GOPROXY=https://proxy.golang.org,direct
|
|
||||||
ENV CGO_ENABLED=0
|
|
||||||
WORKDIR /go/dovecot-xaps-daemon
|
|
||||||
RUN <<EOF
|
|
||||||
apk add --no-cache --virtual build-dependencies git
|
|
||||||
git clone --single-branch --depth=1 https://github.com/freswa/dovecot-xaps-daemon .
|
|
||||||
go build ./cmd/xapsd
|
|
||||||
EOF
|
|
||||||
|
|
||||||
FROM mailserver/docker-mailserver:edge
|
|
||||||
COPY --from=dovecot-plugin-xaps /usr/lib/dovecot/modules/*_xaps_* /usr/lib/dovecot/modules/
|
|
||||||
COPY --from=dovecot-xaps-daemon /go/dovecot-xaps-daemon/xapsd /usr/bin/xapsd
|
|
||||||
|
|
||||||
# create a non-root user for the daemon process as well as configuration and run state directories
|
|
||||||
RUN <<EOF
|
|
||||||
adduser --quiet --system --group --disabled-password --home /var/mail-state/lib-xapsd --no-create-home xapsd
|
|
||||||
mkdir -p /var/run/xapsd /etc/xapsd
|
|
||||||
EOF
|
|
||||||
```
|
|
||||||
|
|
||||||
2. Build the new image:
|
|
||||||
```sh
|
|
||||||
docker build -t yourname/docker-mailserver .
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Modify your `compose.yaml` to use the newly created image:
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: yourname/docker-mailserver:latest
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Recreate the container:
|
|
||||||
```sh
|
|
||||||
docker compose down
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
5. Create a hash of your Apple developer account password using the provided `xapsd -pass` command:
|
|
||||||
```sh
|
|
||||||
docker exec -it mailserver xapsd -pass
|
|
||||||
```
|
|
||||||
|
|
||||||
6. Add configuration for both components:
|
|
||||||
- Create a folder named `xaps` in `docker-data/dms/config`.
|
|
||||||
|
|
||||||
- Create a file named `xapsd.yaml` in `docker-data/dms/config/xaps`.
|
|
||||||
- Replace `appleId` and `appleIdHashedPassword` with your actual credentials. For reference see also [here](https://github.com/freswa/dovecot-xaps-daemon/blob/master/configs/xapsd/xapsd.yaml).
|
|
||||||
- The service will use the provided username/hash combination to automatically request a new certificate from Apple as well as renewing an older certificate if needed.
|
|
||||||
|
|
||||||
```yaml title="xapsd.yaml"
|
|
||||||
|
|
||||||
# set the loglevel to either
|
|
||||||
# trace, debug, error, fatal, info, panic or warn
|
|
||||||
# Default: info
|
|
||||||
loglevel: info
|
|
||||||
|
|
||||||
# xapsd creates a json file to store the registration persistent on disk.
|
|
||||||
# This sets the location of the file.
|
|
||||||
databaseFile: /var/mail-state/lib-xapsd/database.json
|
|
||||||
|
|
||||||
# xapsd listens on a socket for http/https requests from the dovecot plugin.
|
|
||||||
# This sets the address and port number of the listen socket.
|
|
||||||
listenAddr: '127.0.0.1'
|
|
||||||
port: 11619
|
|
||||||
|
|
||||||
# xapsd is able to listen on a HTTPS Socket to allow HTTP/2 to be used
|
|
||||||
# SSL is enabled implicitly when certfile and keyfile exist
|
|
||||||
# !!! only use HTTPS for connection pooling with a proxy e.g. nginx or HaProxy
|
|
||||||
# !!! direct usage with the plugin is discouraged and unsupported
|
|
||||||
tlsCertfile:
|
|
||||||
tlsKeyfile:
|
|
||||||
tlsListenAddr:
|
|
||||||
tlsPort: 11620
|
|
||||||
|
|
||||||
# Notifications that are not initiated by new messages are not sent immediately for two reasons:
|
|
||||||
# 1. When you move/copy/delete messages you most likely move/copy/delete more messages within a short period of time.
|
|
||||||
# 2. You don't need your mailboxes to synchronize immediately since they are automatically synchronized when opening
|
|
||||||
# the app
|
|
||||||
# If a new message comes and the move/copy/delete notification is still on hold it will be sent with the notification
|
|
||||||
# for the new message.
|
|
||||||
# This sets the interval to check for delayed messages.
|
|
||||||
checkInterval: 20
|
|
||||||
|
|
||||||
# Set the time how long notifications for not-new messages should be delayed until they are sent.
|
|
||||||
# Whenever checkInterval runs, it checks if "delay" <= "waiting time" and sends the notification if the expression is
|
|
||||||
# true.
|
|
||||||
delay: 30
|
|
||||||
|
|
||||||
# To retrieve certificates from Apple, we need to login with a valid Apple ID
|
|
||||||
# The accounts email must be given in cleartext, but the password has to
|
|
||||||
# be hashed before sending it. To not leak working credentials on running servers,
|
|
||||||
# we do not accept the cleartext password here.
|
|
||||||
appleId: foo@example.com
|
|
||||||
|
|
||||||
# use `xaps -pass` to calculate the hash of the apple id password
|
|
||||||
appleIdHashedPassword: bar
|
|
||||||
```
|
|
||||||
|
|
||||||
- Create a file named `95-xaps.conf` in `docker-data/dms/config/xaps`. For reference see also [here](https://github.com/freswa/dovecot-xaps-plugin/blob/master/xaps.conf).
|
|
||||||
```txt title="95-xaps.conf"
|
|
||||||
|
|
||||||
protocol imap {
|
|
||||||
mail_plugins = $mail_plugins notify push_notification xaps_push_notification xaps_imap
|
|
||||||
}
|
|
||||||
|
|
||||||
protocol lda {
|
|
||||||
mail_plugins = $mail_plugins notify push_notification xaps_push_notification
|
|
||||||
}
|
|
||||||
|
|
||||||
protocol lmtp {
|
|
||||||
mail_plugins = $mail_plugins notify push_notification xaps_push_notification
|
|
||||||
}
|
|
||||||
|
|
||||||
plugin {
|
|
||||||
# xaps_config contains xaps specific configuration parameters
|
|
||||||
# url: protocol, hostname and port under which xapsd listens
|
|
||||||
# user_lookup: Use if you want to determine the username used for PNs from environment variables provided by
|
|
||||||
# login mechanism. Value is variable name to look up.
|
|
||||||
# max_retries: maximum num of retries the http client connects to the xaps daemon
|
|
||||||
# timeout_msecs http timeout of the http connection
|
|
||||||
xaps_config = url=http://127.0.0.1:11619 user_lookup=theattribute max_retries=6 timeout_msecs=5000
|
|
||||||
push_notification_driver = xaps
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- Create a supervisord file named `xapsd.conf` in `docker-data/dms/config/xaps` with the following content:
|
|
||||||
```txt title="xapsd.conf"
|
|
||||||
|
|
||||||
[program:xapsd]
|
|
||||||
startsecs=0
|
|
||||||
autostart=false
|
|
||||||
autorestart=true
|
|
||||||
stdout_logfile=/var/log/supervisor/%(program_name)s.log
|
|
||||||
stderr_logfile=/var/log/supervisor/%(program_name)s.log
|
|
||||||
user=xapsd
|
|
||||||
command=/usr/bin/xapsd
|
|
||||||
pidfile=/var/run/xapsd/xapsd.pid
|
|
||||||
```
|
|
||||||
|
|
||||||
- Create or update your `user-patches.sh` in `docker-data/dms/config` to move the files to their final location as well as starting the daemon service:
|
|
||||||
```sh title="user-patches.sh"
|
|
||||||
#!/bin/bash
|
|
||||||
|
|
||||||
# Copy the configs to internal locations:
|
|
||||||
cp /tmp/docker-mailserver/xaps/95-xaps.conf /etc/dovecot/conf.d/95-xaps.conf
|
|
||||||
cp /tmp/docker-mailserver/xaps/xapsd.yaml /etc/xapsd/xapsd.yaml
|
|
||||||
cp /tmp/docker-mailserver/xaps/xapsd.conf /etc/supervisor/conf.d/xapsd.conf
|
|
||||||
|
|
||||||
# Setup data persistence and ensure ownership is always for xapsd:
|
|
||||||
mkdir -p /var/mail-state/lib-xapsd
|
|
||||||
chown -R xapsd:xapsd /var/mail-state/lib-xapsd
|
|
||||||
|
|
||||||
# Start the xaps daemon:
|
|
||||||
supervisorctl update
|
|
||||||
supervisorctl start xapsd
|
|
||||||
```
|
|
||||||
|
|
||||||
7. Recreate the container again to apply the new configuration:
|
|
||||||
```sh
|
|
||||||
docker compose down
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
8. Recreate your mail account on your iOS device and check the logs in `/var/log/supervisor/dovecot.log` and `/var/log/supervisor/xapsd.log` for any errors.
|
|
||||||
|
|
||||||
|
|
||||||
## Other configuration options
|
|
||||||
|
|
||||||
Both device registration and notifications send a username to the daemon to lookup the device. While the registration and other IMAP operations in Dovecot will send the Dovecot username, LMTP will send the provided authentication username.
|
|
||||||
|
|
||||||
The format of that username is specified by the `auth_username_format` Dovecot setting. If you are not using mail addresses as Dovecot usernames - e.g. when using LDAP - you can either change the `auth_username_format` or add the mail address as property to the user account and use the lookup feature (see below).
|
|
||||||
|
|
||||||
```sh title="user-patches.sh"
|
|
||||||
sed -i -r "s|^#?(auth_username_format =).*|\1 %Ln|" /etc/dovecot/conf.d/10-auth.conf
|
|
||||||
```
|
|
||||||
|
|
||||||
You can also use notifications for Dovecot alias mailboxes. Depending on your server configuration, this might require to add the original Dovecot username as [Dovecot attribute](https://doc.dovecot.org/configuration_manual/authentication/user_database_extra_fields/) to the login user as well as changing the `user_lookup=theattribute` in `95-xaps.conf` to perform the lookup of that attribute.
|
|
||||||
|
|
@ -1,517 +0,0 @@
|
||||||
---
|
|
||||||
title: 'FAQ'
|
|
||||||
---
|
|
||||||
|
|
||||||
### What kind of database are you using?
|
|
||||||
|
|
||||||
None! No database is required. The filesystem is the database. This image is based on config files that can be persisted using bind mounts (default) or Docker volumes, and as such versioned, backed up and so forth.
|
|
||||||
|
|
||||||
### Where are emails stored?
|
|
||||||
|
|
||||||
Mails are stored in `/var/mail/${domain}/${username}`. Since `v9.0.0` it is possible to add custom `user_attributes` for each accounts to have a different mailbox configuration (See [#1792][github-issue-1792]).
|
|
||||||
|
|
||||||
### How are IMAP mailboxes (_aka IMAP Folders_) set up?
|
|
||||||
|
|
||||||
`INBOX` is setup by default with the special IMAP folders `Drafts`, `Sent`, `Junk` and `Trash`. You can learn how to modify or add your own folders (_including additional special folders like `Archive`_) by visiting our docs page [_Customizing IMAP Folders_](./examples/use-cases/imap-folders.md) for more information.
|
|
||||||
|
|
||||||
### How do I update DMS?
|
|
||||||
|
|
||||||
**Make sure to read the [CHANGELOG](https://github.com/docker-mailserver/docker-mailserver/blob/master/CHANGELOG.md)** before updating to new versions, to be prepared for possible breaking changes.
|
|
||||||
|
|
||||||
Then, run the following commands:
|
|
||||||
|
|
||||||
``` BASH
|
|
||||||
docker compose pull
|
|
||||||
docker compose down
|
|
||||||
docker compose up -d
|
|
||||||
```
|
|
||||||
|
|
||||||
You should see the new version number on startup, for example: `[ INF ] Welcome to docker-mailserver 11.3.1`. And you're done! Don't forget to have a look at the remaining functions of the `setup.sh` script with `./setup.sh help`.
|
|
||||||
|
|
||||||
### Which operating systems are supported?
|
|
||||||
|
|
||||||
- Linux is officially supported.
|
|
||||||
- Windows and macOS are _not_ supported and users and have reported various issues running the image on these hosts.
|
|
||||||
|
|
||||||
As you'll realistically be deploying to production on a Linux host, if you are on Windows or macOS and want to run the image locally first, it's advised to do so via a VM guest running Linux if you have issues running DMS on your host system.
|
|
||||||
|
|
||||||
### What are the system requirements?
|
|
||||||
|
|
||||||
#### Recommended
|
|
||||||
|
|
||||||
- 1 vCore
|
|
||||||
- 2GB RAM
|
|
||||||
- Swap enabled for the container
|
|
||||||
|
|
||||||
#### Minimum
|
|
||||||
|
|
||||||
- 1 vCore
|
|
||||||
- 512MB RAM
|
|
||||||
- You'll need to avoid running some services like ClamAV (_disabled by default_) to be able to run on a host with 512MB of RAM.
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
ClamAV can consume a lot of memory, as it reads the entire signature database into RAM.
|
|
||||||
|
|
||||||
Current figure is about 850M and growing. If you get errors about ClamAV or amavis failing to allocate memory you need more RAM or more swap and of course docker must be allowed to use swap (not always the case). If you can't use swap at all you may need 3G RAM.
|
|
||||||
|
|
||||||
### How to alter a running DMS instance _without_ relaunching the container?
|
|
||||||
|
|
||||||
DMS aggregates multiple "sub-services", such as Postfix, Dovecot, Fail2ban, SpamAssassin, etc. In many cases, one may edit a sub-service's config and reload that very sub-service, without stopping and relaunching the whole mail server.
|
|
||||||
|
|
||||||
In order to do so, you'll probably want to push your config updates to your server through a Docker volume (these docs use: `./docker-data/dms/config/:/tmp/docker-mailserver/`), then restart the sub-service to apply your changes, using `supervisorctl`. For instance, after editing fail2ban's config: `supervisorctl restart fail2ban`.
|
|
||||||
|
|
||||||
See the [documentation for `supervisorctl`](http://supervisord.org/running.html#running-supervisorctl).
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
To add, update or delete an email account; there is no need to restart postfix / dovecot service inside the container after using `setup.sh` script.
|
|
||||||
|
|
||||||
For more information, see [#1639][github-issue-1639].
|
|
||||||
|
|
||||||
### How can I sync the container and host date/time?
|
|
||||||
|
|
||||||
Share the host's [`/etc/localtime`](https://www.freedesktop.org/software/systemd/man/localtime.html) with the container, e.g. by using a bind mount:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
volumes:
|
|
||||||
- /etc/localtime:/etc/localtime:ro
|
|
||||||
```
|
|
||||||
|
|
||||||
Optionally, you can set the `TZ` ENV variable; e.g. `TZ=Europe/Berlin`. Check [this list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for which values are allowed.
|
|
||||||
|
|
||||||
### What About DNS Servers?
|
|
||||||
|
|
||||||
Properly working DNS servers are crucial for differentiating spam from legitimate e-mails. Records like `SPF`, `DKIM` and `DMARC` records, as well as working name (resolving `A` records) and reverse name (resolving `PTR` records) resolution ensures legitimate e-mails arrive while e-mails that are more likely phishing and spam do not.
|
|
||||||
|
|
||||||
Anti-spam measures (like SpamAssassin or Rspamd) make use of DNS block lists. To learn more check out our [Rspamd documentation on this topic][docs::rspamd-rbl-dnsbl]. In case you want to utilize RBL/DNSBLs, you need a recursive DNS resolver (_not big custom resolvers like Cloudflare, Quad9, Google, etc._).
|
|
||||||
|
|
||||||
DMS does not integrate support for an internal DNS service as this is a [responsibility that is sensitive to the host environment][gh-discussion::dms-avoid-maintaining-internal-dns]. You can configure internal services within DMS to use your own managed DNS server, or configure for such at the host or container level (_such as with [`compose.yaml`][docker-compose::docs::config-dns]_).
|
|
||||||
|
|
||||||
### What is the file format?
|
|
||||||
|
|
||||||
All files are using the Unix format with `LF` line endings. Please do not use `CRLF`.
|
|
||||||
|
|
||||||
### Do you support multiple domains?
|
|
||||||
|
|
||||||
DMS supports multiple domains out of the box, so you can do this:
|
|
||||||
|
|
||||||
``` BASH
|
|
||||||
./setup.sh email add user1@example.com
|
|
||||||
./setup.sh email add user1@example.de
|
|
||||||
./setup.sh email add user1@server.example.org
|
|
||||||
```
|
|
||||||
|
|
||||||
### What about backups?
|
|
||||||
|
|
||||||
#### Bind mounts (default)
|
|
||||||
|
|
||||||
From the location of your `compose.yaml`, create a compressed archive of your `docker-data/dms/config/` and `docker-data/dms/mail-*` folders:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tar --gzip -cf "backup-$(date +%F).tar.gz" ./docker-data/dms
|
|
||||||
```
|
|
||||||
|
|
||||||
Then to restore `docker-data/dms/config/` and `docker-data/dms/mail-*` folders from your backup file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
tar --gzip -xf backup-date.tar.gz
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Volumes
|
|
||||||
|
|
||||||
Assuming that you use `docker-compose` and data volumes, you can backup the configuration, emails and logs like this:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# create backup
|
|
||||||
docker run --rm -it \
|
|
||||||
-v "${PWD}/docker-data/dms/config/:/tmp/docker-mailserver/" \
|
|
||||||
-v "${PWD}/docker-data/dms-backups/:/backup/" \
|
|
||||||
--volumes-from mailserver \
|
|
||||||
alpine:latest \
|
|
||||||
tar czf "/backup/mail-$(date +%F).tar.gz" /var/mail /var/mail-state /var/log/mail /tmp/docker-mailserver
|
|
||||||
|
|
||||||
# delete backups older than 30 days
|
|
||||||
find "${PWD}/docker-data/dms-backups/" -type f -mtime +30 -delete
|
|
||||||
```
|
|
||||||
|
|
||||||
### I Want to Know More About the Ports
|
|
||||||
|
|
||||||
See [this part of the documentation](./config/security/understanding-the-ports.md) for further details and best practice advice, **especially regarding security concerns**.
|
|
||||||
|
|
||||||
### How can I configure my email client?
|
|
||||||
|
|
||||||
Login is full email address (`<user>@<domain>`).
|
|
||||||
|
|
||||||
```properties
|
|
||||||
# IMAP
|
|
||||||
username: <user1@example.com>
|
|
||||||
password: <mypassword>
|
|
||||||
server: <mail.example.com>
|
|
||||||
imap port: 143 or 993 with STARTTLS/SSL (recommended)
|
|
||||||
imap path prefix: INBOX
|
|
||||||
|
|
||||||
# SMTP
|
|
||||||
smtp port: 587 or 465 with STARTTLS/SSL (recommended)
|
|
||||||
username: <user1@example.com>
|
|
||||||
password: <mypassword>
|
|
||||||
```
|
|
||||||
|
|
||||||
DMS is properly configured for port 587, if possible, we recommend using port 465 for SMTP though. See [this section to learn more about ports](#i-want-to-know-more-about-the-ports).
|
|
||||||
|
|
||||||
### Can I use a naked/bare domain (i.e. no hostname)?
|
|
||||||
|
|
||||||
Yes, but not without some configuration changes. Normally it is assumed that DMS runs on a host with a name, so the fully qualified host name might be `mail.example.com` with the domain `example.com`. The MX records point to `mail.example.com`.
|
|
||||||
|
|
||||||
To use a bare domain (_where the host name is `example.com` and the domain is also `example.com`_), change `mydestination`:
|
|
||||||
|
|
||||||
- From: `mydestination = $myhostname, localhost.$mydomain, localhost`
|
|
||||||
- To: `mydestination = localhost.$mydomain, localhost`
|
|
||||||
|
|
||||||
Add the latter line to `docker-data/dms/config/postfix-main.cf`. If that doesn't work, make sure that [`OVERRIDE_HOSTNAME` is blank in your `mailserver.env` file][github-comment-override-hostname]. Without these changes there will be warnings in the logs like:
|
|
||||||
|
|
||||||
```log
|
|
||||||
warning: do not list domain example.com in BOTH mydestination and virtual_mailbox_domains
|
|
||||||
```
|
|
||||||
|
|
||||||
Plus of course mail delivery fails.
|
|
||||||
|
|
||||||
Also you need to define `hostname: example.com` in your `compose.yaml`.
|
|
||||||
|
|
||||||
!!! tip "You might not want a bare domain"
|
|
||||||
|
|
||||||
We encourage you to consider using a subdomain where possible.
|
|
||||||
|
|
||||||
- There are [benefits][github-comment-baredomain] to preferring a subdomain.
|
|
||||||
- A bare domain is not required to have `user@example.com`, that is distinct from your hostname which is identified by a DNS MX record.
|
|
||||||
|
|
||||||
### How can I configure a catch-all?
|
|
||||||
|
|
||||||
Considering you want to redirect all incoming e-mails for the domain `example.com` to `user1@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
@example.com user1@example.com
|
|
||||||
```
|
|
||||||
|
|
||||||
### How can I delete all the emails for a specific user?
|
|
||||||
|
|
||||||
First of all, create a special alias named `devnull` by editing `docker-data/dms/config/postfix-aliases.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
devnull: /dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
Considering you want to delete all the e-mails received for `baduser@example.com`, add the following line to `docker-data/dms/config/postfix-virtual.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
baduser@example.com devnull
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! important
|
|
||||||
|
|
||||||
If you use a catch-all rule for the main/sub domain, you need another entry in `docker-data/dms/config/postfix-virtual.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
@mail.example.com hello@example.com
|
|
||||||
baduser@example.com devnull
|
|
||||||
devnull@mail.example.com devnull
|
|
||||||
```
|
|
||||||
|
|
||||||
### What kind of SSL certificates can I use?
|
|
||||||
|
|
||||||
Both RSA and ECDSA certs are supported. You can provide your own cert files manually, or mount a `letsencrypt` generated directory (_with alternative support for Traefik's `acme.json`_). Check out the [`SSL_TYPE` documentation](./config/environment.md#ssl_type) for more details.
|
|
||||||
|
|
||||||
### I just moved from my old mail server to DMS, but "it doesn't work"?
|
|
||||||
|
|
||||||
If this migration implies a DNS modification, be sure to wait for DNS propagation before opening an issue.
|
|
||||||
Few examples of symptoms can be found [here][github-issue-95] or [here][github-issue-97].
|
|
||||||
|
|
||||||
This could be related to a modification of your `MX` record, or the IP mapped to `mail.example.com`. Additionally, [validate your DNS configuration](https://intodns.com/).
|
|
||||||
|
|
||||||
If everything is OK regarding DNS, please provide [formatted logs](https://guides.github.com/features/mastering-markdown/) and config files. This will allow us to help you.
|
|
||||||
|
|
||||||
If we're blind, we won't be able to do anything.
|
|
||||||
|
|
||||||
### Connection refused or No response at all
|
|
||||||
|
|
||||||
You see errors like "Connection Refused" and "Connection closed by foreign host", or you cannot connect at all? You may not be able to connect with your mail client (MUA)? Make sure to check Fail2Ban did not ban you (for exceeding the number of tried logins for example)! You can run
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec <CONTAINER NAME> setup fail2ban
|
|
||||||
```
|
|
||||||
|
|
||||||
and check whether your IP address appears. Use
|
|
||||||
|
|
||||||
```bash
|
|
||||||
docker exec <CONTAINER NAME> setup fail2ban unban <YOUR IP>
|
|
||||||
```
|
|
||||||
|
|
||||||
to unban the IP address.
|
|
||||||
|
|
||||||
### How can I authenticate users with `SMTP_ONLY=1`?
|
|
||||||
|
|
||||||
See [#1247][github-issue-1247] for an example.
|
|
||||||
|
|
||||||
!!! todo
|
|
||||||
|
|
||||||
Write a How-to / Use-Case / Tutorial about authentication with `SMTP_ONLY`.
|
|
||||||
|
|
||||||
### Common Errors
|
|
||||||
|
|
||||||
#### Creating an alias or account with an address for `hostname`
|
|
||||||
|
|
||||||
Normally you will assign DMS a `hostname` such as `mail.example.com`. If you instead use a bare domain (_such as `example.com`_) or add an alias / account with the same value as your `hostname`, this can cause a conflict for mail addressed to `@hostname` as Postfix gets confused where to deliver the mail (_`hostname` is configured for only system accounts via the Postfix `main.cf` setting `mydestination`_).
|
|
||||||
|
|
||||||
When this conflict is detected you'll find logs similar to this:
|
|
||||||
|
|
||||||
```log
|
|
||||||
warning: do not list domain mail.example.com in BOTH mydestination and virtual_mailbox_domains
|
|
||||||
...
|
|
||||||
NOQUEUE: reject: RCPT from HOST[IP]: 550 5.1.1 <RECIPIENT>: Recipient address rejected: User unknown in local recipient table; ...
|
|
||||||
```
|
|
||||||
|
|
||||||
Opt-out of mail being directed to services by excluding `$myhostname` as a destination with a [`postfix-main.cf`][docs-override-postfix] override config:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
mydestination = localhost.$mydomain, localhost
|
|
||||||
```
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
You may want to configure a `postmaster` alias via `setup alias add` to receive system notifications.
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
Internal mail destined for `root`, `amavis` or other accounts will now no longer be received without an alias or account created for them.
|
|
||||||
|
|
||||||
### How to use DMS behind a proxy
|
|
||||||
|
|
||||||
[Using `user-patches.sh`][docs-userpatches], update the container file `/etc/postfix/main.cf` to include:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
proxy_interfaces = X.X.X.X (your public IP)
|
|
||||||
```
|
|
||||||
|
|
||||||
For reverse proxy support you will want to view [our dedicated guide][docs::examples::reverse-proxy].
|
|
||||||
|
|
||||||
### How to restrict login by IP?
|
|
||||||
|
|
||||||
There are a few ways you could approach this, see [this discussion answer][gh-discussion::restrict-login-by-ip] for advice.
|
|
||||||
|
|
||||||
### How to adjust settings with the `user-patches.sh` script
|
|
||||||
|
|
||||||
Suppose you want to change a number of settings that are not listed as variables or add things to the server that are not included?
|
|
||||||
|
|
||||||
DMS has a built-in way to do post-install processes. If you place a script called **`user-patches.sh`** in the config directory it will be run after all configuration files are set up, but before the postfix, amavis and other daemons are started.
|
|
||||||
|
|
||||||
It is common to use a local directory for config added to `docker-mailsever` via a volume mount in your `compose.yaml` (eg: `./docker-data/dms/config/:/tmp/docker-mailserver/`).
|
|
||||||
|
|
||||||
Add or create the script file to your config directory:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
cd ./docker-data/dms/config
|
|
||||||
touch user-patches.sh
|
|
||||||
chmod +x user-patches.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Then fill `user-patches.sh` with suitable code.
|
|
||||||
|
|
||||||
If you want to test it you can move into the running container, run it and see if it does what you want. For instance:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# start shell in container
|
|
||||||
./setup.sh debug login
|
|
||||||
|
|
||||||
# check the file
|
|
||||||
cat /tmp/docker-mailserver/user-patches.sh
|
|
||||||
|
|
||||||
# run the script
|
|
||||||
/tmp/docker-mailserver/user-patches.sh
|
|
||||||
|
|
||||||
# exit the container shell back to the host shell
|
|
||||||
exit
|
|
||||||
```
|
|
||||||
|
|
||||||
You can do a lot of things with such a script. You can find an example `user-patches.sh` script here: [example `user-patches.sh` script][hanscees-userpatches].
|
|
||||||
|
|
||||||
We also have a [very similar docs page][docs-userpatches] specifically about this feature!
|
|
||||||
|
|
||||||
!!! attention "Special use-case - patching the `supervisord` configuration"
|
|
||||||
|
|
||||||
It seems worth noting, that the `user-patches.sh` gets executed through `supervisord`. If you need to patch some supervisord config (e.g. `/etc/supervisor/conf.d/saslauth.conf`), the patching happens too late.
|
|
||||||
|
|
||||||
An easy workaround is to make the `user-patches.sh` reload the supervisord config after patching it:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/bin/bash
|
|
||||||
sed -i 's/rimap -r/rimap/' /etc/supervisor/conf.d/saslauth.conf
|
|
||||||
supervisorctl update
|
|
||||||
```
|
|
||||||
|
|
||||||
### How to ban custom IP addresses with Fail2ban
|
|
||||||
|
|
||||||
Use the following command:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
./setup.sh fail2ban ban <IP>
|
|
||||||
```
|
|
||||||
|
|
||||||
The default bantime is 180 days. This value can be [customized][fail2ban-customize].
|
|
||||||
|
|
||||||
### What to do in case of SPF/Forwarding problems
|
|
||||||
|
|
||||||
If you got any problems with SPF and/or forwarding mails, give [SRS](https://github.com/roehling/postsrsd/blob/master/README.rst) a try. You enable SRS by setting `ENABLE_SRS=1`. See the variable description for further information.
|
|
||||||
|
|
||||||
### Why are my emails not being delivered?
|
|
||||||
|
|
||||||
There are many reasons why email might be rejected, common causes are:
|
|
||||||
|
|
||||||
- Wrong or untrustworthy SSL certificate.
|
|
||||||
- A TLD (your domain) or IP address with a bad reputation.
|
|
||||||
- Misconfigured DNS records.
|
|
||||||
|
|
||||||
DMS does not manage those concerns, verify they are not causing your delivery problems before reporting a bug on our issue tracker. Resources that can help you troubleshoot:
|
|
||||||
|
|
||||||
- [mail-tester](https://www.mail-tester.com/) can test your deliverability.
|
|
||||||
- [helloinbox](https://www.helloinbox.email/) provides a checklist of things to improve your deliverability.
|
|
||||||
|
|
||||||
### SpamAssasin
|
|
||||||
|
|
||||||
#### How can I manage my custom SpamAssassin rules?
|
|
||||||
|
|
||||||
Anti-spam rules are managed in `docker-data/dms/config/spamassassin-rules.cf`.
|
|
||||||
|
|
||||||
#### Why are SpamAssassin `x-headers` not inserted into my `subdomain.example.com` subdomain emails?
|
|
||||||
|
|
||||||
In the default setup, amavis only applies SpamAssassin x-headers into domains matching the template listed in the config file (`05-domain_id` in the amavis defaults).
|
|
||||||
|
|
||||||
The default setup `@local_domains_acl = ( ".$mydomain" );` does not match subdomains. To match subdomains, you can override the `@local_domains_acl` directive in the amavis user config file `50-user` with `@local_domains_maps = (".");` to match any sort of domain template.
|
|
||||||
|
|
||||||
#### How can I make SpamAssassin better recognize spam?
|
|
||||||
|
|
||||||
Put received spams in `.Junk/` imap folder using `SPAMASSASSIN_SPAM_TO_INBOX=1` and `MOVE_SPAM_TO_JUNK=1` and add a _user_ cron like the following:
|
|
||||||
|
|
||||||
!!! example
|
|
||||||
|
|
||||||
**NOTE:** This example assumes you have a [`/var/mail-state` volume][docs::dms-volumes-state] mounted.
|
|
||||||
|
|
||||||
```conf
|
|
||||||
# m h dom mon dow command
|
|
||||||
# Everyday 2:00AM, learn spam from a specific user
|
|
||||||
0 2 * * * docker exec mailserver sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin
|
|
||||||
```
|
|
||||||
|
|
||||||
With `docker-compose` you can more easily use the internal instance of `cron` within DMS. This is less problematic than the simple solution shown above, because it decouples the learning from the host on which DMS is running, and avoids errors if the mail server is not running.
|
|
||||||
|
|
||||||
The following configuration works nicely:
|
|
||||||
|
|
||||||
??? example
|
|
||||||
|
|
||||||
**NOTE:** This example assumes you have a [`/var/mail-state` volume][docs::dms-volumes-state] mounted.
|
|
||||||
|
|
||||||
Create a _system_ cron file:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
# in the compose.yaml root directory
|
|
||||||
mkdir -p ./docker-data/dms/cron
|
|
||||||
touch ./docker-data/dms/cron/sa-learn
|
|
||||||
chown root:root ./docker-data/dms/cron/sa-learn
|
|
||||||
chmod 0644 ./docker-data/dms/cron/sa-learn
|
|
||||||
```
|
|
||||||
|
|
||||||
Edit the system cron file `nano ./docker-data/dms/cron/sa-learn`, and set an appropriate configuration:
|
|
||||||
|
|
||||||
```conf
|
|
||||||
# '> /dev/null' to send error notifications from 'stderr' to 'postmaster@example.com'
|
|
||||||
#
|
|
||||||
# m h dom mon dow user command
|
|
||||||
#
|
|
||||||
# Everyday 2:00AM, learn spam from a specific user
|
|
||||||
# spam: junk directory
|
|
||||||
0 2 * * * root sa-learn --spam /var/mail/example.com/username/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
# ham: archive directories
|
|
||||||
15 2 * * * root sa-learn --ham /var/mail/example.com/username/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
# ham: inbox subdirectories
|
|
||||||
30 2 * * * root sa-learn --ham /var/mail/example.com/username/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
#
|
|
||||||
# Everyday 3:00AM, learn spam from all users of a domain
|
|
||||||
# spam: junk directory
|
|
||||||
0 3 * * * root sa-learn --spam /var/mail/not-example.com/*/.Junk --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
# ham: archive directories
|
|
||||||
15 3 * * * root sa-learn --ham /var/mail/not-example.com/*/.Archive* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
# ham: inbox subdirectories
|
|
||||||
30 3 * * * root sa-learn --ham /var/mail/not-example.com/*/cur* --dbpath /var/mail-state/lib-amavis/.spamassassin > /dev/null
|
|
||||||
```
|
|
||||||
|
|
||||||
Then with `compose.yaml`:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
volumes:
|
|
||||||
- ./docker-data/dms/cron/sa-learn:/etc/cron.d/sa-learn
|
|
||||||
```
|
|
||||||
|
|
||||||
Or with [Docker Swarm](https://docs.docker.com/engine/swarm/configs/):
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
services:
|
|
||||||
mailserver:
|
|
||||||
image: ghcr.io/docker-mailserver/docker-mailserver:latest
|
|
||||||
# ...
|
|
||||||
configs:
|
|
||||||
- source: my_sa_crontab
|
|
||||||
target: /etc/cron.d/sa-learn
|
|
||||||
|
|
||||||
configs:
|
|
||||||
my_sa_crontab:
|
|
||||||
file: ./docker-data/dms/cron/sa-learn
|
|
||||||
```
|
|
||||||
|
|
||||||
With the default settings, SpamAssassin will require 200 mails trained for spam (for example with the method explained above) and 200 mails trained for ham (using the same command as above but using `--ham` and providing it with some ham mails).
|
|
||||||
|
|
||||||
- Until you provided these 200+200 mails, SpamAssassin will not take the learned mails into account.
|
|
||||||
- For further reference, see the [SpamAssassin Wiki](https://wiki.apache.org/spamassassin/BayesNotWorking).
|
|
||||||
|
|
||||||
#### How do I have more control about what SpamAssassin is filtering?
|
|
||||||
|
|
||||||
This is related to Amavis processing the mail after SpamAssassin has analyzed it and assigned a spam score.
|
|
||||||
|
|
||||||
- DMS provides some [common SA tunables via ENV][docs::env::sa_env].
|
|
||||||
- Additional configuration can be managed with the DMS config volume by providing `docker-data/dms/config/amavis.cf`.
|
|
||||||
|
|
||||||
#### How can I send quarantined mail to a mailbox?
|
|
||||||
|
|
||||||
SPAM and INFECTED emails that [reach the `SA_KILL` threshold are archived into quarantine][docs::env::sa_kill].
|
|
||||||
|
|
||||||
Instead of a quarantine folder, you can use a dedicated mailbox instead. Create an account like `quarantine@example.com` and create `docker-data/dms/config/amavis.cf`:
|
|
||||||
|
|
||||||
```cf
|
|
||||||
$clean_quarantine_to = "quarantine\@example.com";
|
|
||||||
$virus_quarantine_to = "quarantine\@example.com";
|
|
||||||
$banned_quarantine_to = "quarantine\@example.com";
|
|
||||||
$bad_header_quarantine_to = "quarantine\@example.com";
|
|
||||||
$spam_quarantine_to = "quarantine\@example.com";
|
|
||||||
```
|
|
||||||
|
|
||||||
[fail2ban-customize]: ./config/security/fail2ban.md
|
|
||||||
[docs::dms-volumes-state]: ./config/advanced/optional-config.md#volumes-state
|
|
||||||
[docs::rspamd-rbl-dnsbl]: ./config/security/rspamd.md#rbls-real-time-blacklists-dnsbls-dns-based-blacklists
|
|
||||||
[docs-maintenance]: ./config/advanced/maintenance/update-and-cleanup.md
|
|
||||||
[docs-override-postfix]: ./config/advanced/override-defaults/postfix.md
|
|
||||||
[docs-userpatches]: ./config/advanced/override-defaults/user-patches.md
|
|
||||||
[docs::env::sa_env]: ./config/environment.md#spamassassin
|
|
||||||
[docs::env::sa_kill]: ./config/environment.md#sa_kill
|
|
||||||
[docs::examples::reverse-proxy]: ./examples/tutorials/mailserver-behind-proxy.md
|
|
||||||
[github-comment-baredomain]: https://github.com/docker-mailserver/docker-mailserver/issues/3048#issuecomment-1432358353
|
|
||||||
[github-comment-override-hostname]: https://github.com/docker-mailserver/docker-mailserver/issues/1731#issuecomment-753968425
|
|
||||||
[github-issue-95]: https://github.com/docker-mailserver/docker-mailserver/issues/95
|
|
||||||
[github-issue-97]: https://github.com/docker-mailserver/docker-mailserver/issues/97
|
|
||||||
[github-issue-1247]: https://github.com/docker-mailserver/docker-mailserver/issues/1247
|
|
||||||
[github-issue-1405-comment]: https://github.com/docker-mailserver/docker-mailserver/issues/1405#issuecomment-590106498
|
|
||||||
[github-issue-1639]: https://github.com/docker-mailserver/docker-mailserver/issues/1639
|
|
||||||
[github-issue-1792]: https://github.com/docker-mailserver/docker-mailserver/pull/1792
|
|
||||||
[gh-discussion::dms-avoid-maintaining-internal-dns]: https://github.com/orgs/docker-mailserver/discussions/3959#discussioncomment-8956322
|
|
||||||
[gh-discussion::restrict-login-by-ip]: https://github.com/orgs/docker-mailserver/discussions/3847
|
|
||||||
[docker-compose::docs::config-dns]: https://docs.docker.com/compose/compose-file/compose-file-v3/#dns
|
|
||||||
[hanscees-userpatches]: https://github.com/hanscees/dockerscripts/blob/master/scripts/tomav-user-patches.sh
|
|
||||||
|
|
@ -1,68 +0,0 @@
|
||||||
---
|
|
||||||
title: Home
|
|
||||||
---
|
|
||||||
|
|
||||||
# Welcome to the Documentation for `docker-mailserver`!
|
|
||||||
|
|
||||||
!!! info "This Documentation is Versioned"
|
|
||||||
|
|
||||||
**Make sure** to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to the `:latest` image tag - [the most recent stable release][docs-tagging].
|
|
||||||
|
|
||||||
This documentation provides you not only with the basic setup and configuration of DMS but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.
|
|
||||||
|
|
||||||
[docs-tagging]: ./usage.md#tagging-convention
|
|
||||||
|
|
||||||
## About
|
|
||||||
|
|
||||||
`docker-mailserver`, or DMS for short, is a production-ready fullstack but simple mail server (SMTP, IMAP, LDAP, Anti-spam, Anti-virus, etc.). It employs only configuration files, no SQL database. The image is focused around the slogan "Keep it simple and versioned".
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
|
|
||||||
### Getting Started
|
|
||||||
|
|
||||||
If you're completely new to mail servers or you want to read up on them, check out our [_Introduction_ page][docs-introduction]. If you're new to DMS as a mail server appliance, make sure to read the [_Usage_ chapter][docs-usage] first. If you want to look at examples for Docker Compose, we have an [_Examples_ page][docs-examples].
|
|
||||||
|
|
||||||
There is also a script - [`setup.sh`][github-file-setupsh] - supplied with this project. It supports you in configuring and administrating your server. Information on how to get it and how to use it is available [on a dedicated page][docs-setupsh].
|
|
||||||
|
|
||||||
[docs-introduction]: ./introduction.md
|
|
||||||
[docs-usage]: ./usage.md
|
|
||||||
[docs-examples]: ./examples/tutorials/basic-installation.md
|
|
||||||
[github-file-setupsh]: https://github.com/docker-mailserver/docker-mailserver/blob/master/setup.sh
|
|
||||||
[docs-setupsh]: ./config/setup.sh/
|
|
||||||
|
|
||||||
### Configuration
|
|
||||||
|
|
||||||
We have a [dedicated configuration page][docs-environment]. It contains most of the configuration and explanation you need to setup _your_ mail server properly. Be aware that advanced tasks may still require reading through all parts of this documentation; it may also involve inspecting your running container for debugging purposes. After all, a mail server is a complex arrangement of various programs.
|
|
||||||
|
|
||||||
!!! important
|
|
||||||
|
|
||||||
If you'd like to change, patch or alter files or behavior of DMS, you can use a script. Just place a script called `user-patches.sh` in your `./docker-data/dms/config/` folder volume (which is mounted to `/tmp/docker-mailserver/` inside the container) and it will be run on container startup. See the ['Modifications via Script' page][docs-userpatches] for additional documentation and an example.
|
|
||||||
|
|
||||||
You might also want to check out:
|
|
||||||
|
|
||||||
1. A list of [all configuration options via ENV][docs-environment]
|
|
||||||
2. A list of [all optional and automatically created configuration files and directories][docs-optionalconfig]
|
|
||||||
3. How to [debug your mail server][docs-debugging]
|
|
||||||
|
|
||||||
!!! tip
|
|
||||||
|
|
||||||
Definitely check out the [FAQ][docs-faq] for more information and tips! Please do not open an issue before you have checked our documentation for answers, including the [FAQ][docs-faq]!
|
|
||||||
|
|
||||||
[docs-environment]: ./config/environment.md
|
|
||||||
[docs-userpatches]: ./faq.md#how-to-adjust-settings-with-the-user-patchessh-script
|
|
||||||
[docs-setupsh]: ./config/setup.sh.md
|
|
||||||
[docs-optionalconfig]: ./config/advanced/optional-config.md
|
|
||||||
[docs-faq]: ./faq.md
|
|
||||||
[docs-debugging]: ./config/debugging.md
|
|
||||||
|
|
||||||
### Tests
|
|
||||||
|
|
||||||
DMS employs a variety of tests. If you want to know more about our test suite, view our [testing docs][docs-tests].
|
|
||||||
|
|
||||||
[docs-tests]: ./contributing/tests.md
|
|
||||||
|
|
||||||
### Contributing
|
|
||||||
|
|
||||||
We are always happy to welcome new contributors. For guidelines and entrypoints please have a look at the [Contributing section][docs-contributing].
|
|
||||||
|
|
||||||
[docs-contributing]: ./contributing/issues-and-pull-requests.md
|
|
||||||
|
|
@ -1,236 +0,0 @@
|
||||||
---
|
|
||||||
title: Introduction
|
|
||||||
---
|
|
||||||
|
|
||||||
# An Overview of Mail Server Infrastructure
|
|
||||||
|
|
||||||
This article answers the question "What is a mail server, and how does it perform its duty?" and it gives the reader an introduction to the field that covers everything you need to know to get started with DMS.
|
|
||||||
|
|
||||||
## The Anatomy of a Mail Server
|
|
||||||
|
|
||||||
A mail server is only a part of a [client-server relationship][wikipedia-clientserver] aimed at exchanging information in the form of [emails][wikipedia-email]. Exchanging emails requires using specific means (programs and protocols).
|
|
||||||
|
|
||||||
DMS provides you with the server portion, whereas the client can be anything from a terminal via text-based software (eg. [Mutt][software-mutt]) to a fully-fledged desktop application (eg. [Mozilla Thunderbird][software-thunderbird], [Microsoft Outlook][software-outlook]…), to a web interface, etc.
|
|
||||||
|
|
||||||
Unlike the client-side where usually a single program is used to perform retrieval and viewing of emails, the server-side is composed of many specialized components. The mail server is capable of accepting, forwarding, delivering, storing and overall exchanging messages, but each one of those tasks is actually handled by a specific piece of software. All of these "agents" must be integrated with one another for the exchange to take place.
|
|
||||||
|
|
||||||
DMS has made informed choices about those components and their (default) configuration. It offers a comprehensive platform to run a fully featured mail server in no time!
|
|
||||||
|
|
||||||
## Components
|
|
||||||
|
|
||||||
The following components are required to create a [complete delivery chain][wikipedia-emailagent]:
|
|
||||||
|
|
||||||
- **MUA**: a [Mail User Agent][wikipedia-mua] is basically any client/program capable of sending emails to a mail server; while also capable of fetching emails from a mail server for presenting them to the end users.
|
|
||||||
- **MTA**: a [Mail Transfer Agent][wikipedia-mta] is the so-called "mail server" as seen from the MUA's perspective. It's a piece of software dedicated to accepting submitted emails, then forwarding them-where exactly will depend on an email's final destination. If the receiving MTA is responsible for the FQDN the email is sent to, then an MTA is to forward that email to an MDA (see below). Otherwise, it is to transfer (ie. forward, relay) to another MTA, "closer" to the email's final destination.
|
|
||||||
- **MDA**: a [Mail Delivery Agent][wikipedia-mda] is responsible for accepting emails from an MTA and dropping them into their recipients' mailboxes, whichever the form.
|
|
||||||
|
|
||||||
Here's a schematic view of mail delivery:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
Sending an email: MUA ----> MTA ----> (MTA relays) ----> MDA
|
|
||||||
Fetching an email: MUA <--------------------------------- MDA
|
|
||||||
```
|
|
||||||
|
|
||||||
There may be other moving parts or sub-divisions (for instance, at several points along the chain, specialized programs may be analyzing, filtering, bouncing, editing… the exchanged emails).
|
|
||||||
|
|
||||||
In a nutshell, DMS provides you with the following components:
|
|
||||||
|
|
||||||
- A MTA: [Postfix](http://www.postfix.org/)
|
|
||||||
- A MDA: [Dovecot](https://dovecot.org/)
|
|
||||||
- A bunch of additional programs to improve security and emails processing
|
|
||||||
|
|
||||||
Here's where DMS's toolchain fits within the delivery chain:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
docker-mailserver is here:
|
|
||||||
┏━━━━━━━┓
|
|
||||||
Sending an email: MUA ---> MTA ---> (MTA relays) ---> ┫ MTA ╮ ┃
|
|
||||||
Fetching an email: MUA <------------------------------ ┫ MDA ╯ ┃
|
|
||||||
┗━━━━━━━┛
|
|
||||||
```
|
|
||||||
|
|
||||||
??? example "An Example"
|
|
||||||
|
|
||||||
Let's say Alice owns a Gmail account, `alice@gmail.com`; and Bob owns an account on a DMS instance, `bob@dms.io`.
|
|
||||||
|
|
||||||
Make sure not to conflate these two very different scenarios:
|
|
||||||
A) Alice sends an email to `bob@dms.io` => the email is first submitted to MTA `smtp.gmail.com`, then relayed to MTA `smtp.dms.io` where it is then delivered into Bob's mailbox.
|
|
||||||
B) Bob sends an email to `alice@gmail.com` => the email is first submitted to MTA `smtp.dms.io`, then relayed to MTA `smtp.gmail.com` and eventually delivered into Alice's mailbox.
|
|
||||||
|
|
||||||
In scenario *A* the email leaves Gmail's premises, that email's *initial* submission is _not_ handled by your DMS instance(MTA); it merely receives the email after it has been relayed by Gmail's MTA. In scenario *B*, the DMS instance(MTA) handles the submission, prior to relaying.
|
|
||||||
|
|
||||||
The main takeaway is that when a third-party sends an email to a DMS instance(MTA) (or any MTA for that matter), it does _not_ establish a direct connection with that MTA. Email submission first goes through the sender's MTA, then some relaying between at least two MTAs is required to deliver the email. That will prove very important when it comes to security management.
|
|
||||||
|
|
||||||
One important thing to note is that MTA and MDA programs may actually handle _multiple_ tasks (which is the case with DMS's Postfix and Dovecot).
|
|
||||||
|
|
||||||
For instance, Postfix is both an SMTP server (accepting emails) and a relaying MTA (transferring, ie. sending emails to other MTA/MDA); Dovecot is both an MDA (delivering emails in mailboxes) and an IMAP server (allowing MUAs to fetch emails from the _mail server_). On top of that, Postfix may rely on Dovecot's authentication capabilities.
|
|
||||||
|
|
||||||
The exact relationship between all the components and their respective (sometimes shared) responsibilities is beyond the scope of this document. Please explore this wiki & the web to get more insights about DMS's toolchain.
|
|
||||||
|
|
||||||
## About Security & Ports
|
|
||||||
|
|
||||||
### Introduction
|
|
||||||
|
|
||||||
In the previous section, three components were outlined. Each one of those is responsible for a specific task when it comes to exchanging emails:
|
|
||||||
|
|
||||||
- **Submission**: for a MUA (client), the act of sending actual email data over the network, toward an MTA (server).
|
|
||||||
- **Transfer** (aka. **Relay**): for an MTA, the act of sending actual email data over the network, toward another MTA (server) closer to the final destination (where an MTA will forward data to an MDA).
|
|
||||||
- **Retrieval**: for a MUA (client), the act of fetching actual email data over the network, from an MDA.
|
|
||||||
|
|
||||||
Postfix handles **Submission** (_and may handle **Relay**_), whereas Dovecot handles **Retrieval**. They both need to be accessible by MUAs in order to act as servers, therefore they expose public [endpoints on specific TCP ports][docs-understandports]. Those endpoints _may_ be secured, using an encryption scheme and TLS certificates.
|
|
||||||
|
|
||||||
When it comes to the specifics of email exchange, we have to look at protocols and ports enabled to support all the identified purposes. There are several valid options and they've been evolving overtime.
|
|
||||||
|
|
||||||
### Overview
|
|
||||||
|
|
||||||
The following picture gives a visualization of the interplay of all components and their [respective ports][docs-understandports]:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
┏━━━━━━━━━━ Submission ━━━━━━━━━━━━━┓┏━━━━━━━━━━━━━ Transfer/Relay ━━━━━━━━━━━┓
|
|
||||||
|
|
||||||
┌─────────────────────┐ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
|
|
||||||
MUA ----- STARTTLS -------> ┤(587) MTA ╮ (25)├ <-- cleartext ---> ┊ Third-party MTA ┊
|
|
||||||
----- implicit TLS ---> ┤(465) │ | └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
|
|
||||||
----- cleartext ------> ┤(25) │ |
|
|
||||||
|┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄|
|
|
||||||
MUA <---- STARTTLS -------- ┤(143) MDA ╯ |
|
|
||||||
<---- implicit TLS ---- ┤(993) |
|
|
||||||
└─────────────────────┘
|
|
||||||
|
|
||||||
┗━━━━━━━━━━ Retrieval ━━━━━━━━━━━━━━┛
|
|
||||||
```
|
|
||||||
|
|
||||||
If you're new to email infrastructure, both that table and the schema may be confusing.
|
|
||||||
Read on to expand your understanding and learn about DMS's configuration, including how you can customize it.
|
|
||||||
|
|
||||||
### Submission - SMTP
|
|
||||||
|
|
||||||
For a MUA to send an email to an MTA, it needs to establish a connection with that server, then push data packets over a network that both the MUA (client) and the MTA (server) are connected to. The server implements the [SMTP][wikipedia-smtp] protocol, which makes it capable of handling _Submission_.
|
|
||||||
|
|
||||||
In the case of DMS, the MTA (SMTP server) is Postfix. The MUA (client) may vary, yet its Submission request is performed as [TCP][wikipedia-tcp] packets sent over the _public_ internet. This exchange of information may be secured in order to counter eavesdropping.
|
|
||||||
|
|
||||||
Now let's say I own an account on a DMS instance, `me@dms.io`. There are two very different use-cases for Submission:
|
|
||||||
|
|
||||||
1. I want to send an email to someone
|
|
||||||
2. Someone wants to send you an email
|
|
||||||
|
|
||||||
In the first scenario, I will be submitting my email directly to my DMS instance/MTA (Postfix), which will then relay the email to its recipient's MTA for final delivery. In this case, Submission is first handled by establishing a direct connection to my own MTA-so at least for this portion of the delivery chain, I'll be able to ensure security/confidentiality. Not so much for what comes next, ie. relaying between MTAs and final delivery.
|
|
||||||
|
|
||||||
In the second scenario, a third-party email account owner will be first submitting an email to some third-party MTA. I have no control over this initial portion of the delivery chain, nor do I have control over the relaying that comes next. My MTA will merely accept a relayed email coming "out of the blue".
|
|
||||||
|
|
||||||
My MTA will thus have to support two kinds of Submission:
|
|
||||||
|
|
||||||
- Outbound Submission (self-owned email is submitted directly to the MTA, then is relayed "outside")
|
|
||||||
- Inbound Submission (third-party email has been submitted & relayed, then is accepted "inside" by the MTA)
|
|
||||||
|
|
||||||
```txt
|
|
||||||
┏━━━ Outbound Submission ━━━┓
|
|
||||||
|
|
||||||
┌────────────────────┐ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
|
|
||||||
Me ---------------> ┤ ├ -----------------> ┊ ┊
|
|
||||||
│ My MTA │ ┊ Third-party MTA ┊
|
|
||||||
│ ├ <----------------- ┊ ┊
|
|
||||||
└────────────────────┘ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
|
|
||||||
|
|
||||||
┗━━━━━━━━━━ Inbound Submission ━━━━━━━━━━┛
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Outbound Submission
|
|
||||||
|
|
||||||
When it comes to securing Outbound Submission you should prefer to use _Implicit TLS connection via ESMTP on port 465_ (see [RFC 8314][rfc-8314]). Please read our article about [**Understanding the Ports**][docs-understandports] for more details!
|
|
||||||
|
|
||||||
!!! warning
|
|
||||||
|
|
||||||
This Submission setup is sometimes referred to as [SMTPS][wikipedia-smtps]. Long story short: this is incorrect and should be avoided.
|
|
||||||
|
|
||||||
Although a very satisfactory setup, Implicit TLS on port 465 is somewhat "cutting edge". There exists another well established mail Submission setup that must be supported as well, SMTP+STARTTLS on port 587. It uses Explicit TLS: the client starts with a cleartext connection, then the server informs a TLS-encrypted "upgraded" connection may be established, and the client _may_ eventually decide to establish it prior to the Submission. Basically it's an opportunistic, opt-in TLS upgrade of the connection between the client and the server, at the client's discretion, using a mechanism known as [STARTTLS][wikipedia-starttls] that both ends need to implement.
|
|
||||||
|
|
||||||
In many implementations, the mail server doesn't enforce TLS encryption, for backwards compatibility. Clients are thus free to deny the TLS-upgrade proposal (or [misled by a hacker](https://security.stackexchange.com/questions/168998/what-happens-if-starttls-dropped-in-smtp) about STARTTLS not being available), and the server accepts unencrypted (cleartext) mail exchange, which poses a confidentiality threat and, to some extent, spam issues. [RFC 8314 (section 3.3)][rfc-8314-s33] recommends for a mail server to support both Implicit and Explicit TLS for Submission, _and_ to enforce TLS-encryption on ports 587 (Explicit TLS) and 465 (Implicit TLS). That's exactly DMS's default configuration: abiding by RFC 8314, it [enforces a strict (`encrypt`) STARTTLS policy](http://www.postfix.org/postconf.5.html#smtpd_tls_security_level), where a denied TLS upgrade terminates the connection thus (hopefully but at the client's discretion) preventing unencrypted (cleartext) Submission.
|
|
||||||
|
|
||||||
- **DMS's default configuration enables and _requires_ Explicit TLS (STARTTLS) on port 587 for Outbound Submission.**
|
|
||||||
- It does not enable Implicit TLS Outbound Submission on port 465 by default. One may enable it through simple custom configuration, either as a replacement or (better!) supplementary mean of secure Submission.
|
|
||||||
- It does not support old MUAs (clients) not supporting TLS encryption on ports 587/465 (those should perform Submission on port 25, more details below). One may relax that constraint through advanced custom configuration, for backwards compatibility.
|
|
||||||
|
|
||||||
A final Outbound Submission setup exists and is akin SMTP+STARTTLS on port 587, but on port 25. That port has historically been reserved specifically for unencrypted (cleartext) mail exchange though, making STARTTLS a bit wrong to use. As is expected by [RFC 5321][rfc-5321], DMS uses port 25 for unencrypted Submission in order to support older clients, but most importantly for unencrypted Transfer/Relay between MTAs.
|
|
||||||
|
|
||||||
- **DMS's default configuration also enables unencrypted (cleartext) on port 25 for Outbound Submission.**
|
|
||||||
- It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Outbound Submission.
|
|
||||||
- One may also secure Outbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.
|
|
||||||
|
|
||||||
#### Inbound Submission
|
|
||||||
|
|
||||||
Granted it's still very difficult enforcing encryption between MTAs (Transfer/Relay) without risking dropping emails (when relayed by MTAs not supporting TLS-encryption), Inbound Submission is to be handled in cleartext on port 25 by default.
|
|
||||||
|
|
||||||
- **DMS's default configuration enables unencrypted (cleartext) on port 25 for Inbound Submission.**
|
|
||||||
- It does not enable Explicit TLS (STARTTLS) on port 25 by default. One may enable it through advanced custom configuration, either as a replacement (bad!) or as a supplementary mean of secure Inbound Submission.
|
|
||||||
- One may also secure Inbound Submission using advanced encryption scheme, such as DANE/DNSSEC and/or MTA-STS.
|
|
||||||
|
|
||||||
Overall, DMS's default configuration for SMTP looks like this:
|
|
||||||
|
|
||||||
```txt
|
|
||||||
┏━━━ Outbound Submission ━━━┓
|
|
||||||
|
|
||||||
┌────────────────────┐ ┌┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
|
|
||||||
Me -- cleartext --> ┤(25) (25)├ --- cleartext ---> ┊ ┊
|
|
||||||
Me -- TLS ---> ┤(465) My MTA │ ┊ Third-party MTA ┊
|
|
||||||
Me -- STARTTLS ---> ┤(587) │ ┊ ┊
|
|
||||||
│ (25)├ <---cleartext ---- ┊ ┊
|
|
||||||
└────────────────────┘ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
|
|
||||||
|
|
||||||
┗━━━━━━━━━━ Inbound Submission ━━━━━━━━━━┛
|
|
||||||
```
|
|
||||||
|
|
||||||
### Retrieval - IMAP
|
|
||||||
|
|
||||||
A MUA willing to fetch an email from a mail server will most likely communicate with its [IMAP][wikipedia-imap] server. As with SMTP described earlier, communication will take place in the form of data packets exchanged over a network that both the client and the server are connected to. The IMAP protocol makes the server capable of handling _Retrieval_.
|
|
||||||
|
|
||||||
In the case of DMS, the IMAP server is Dovecot. The MUA (client) may vary, yet its Retrieval request is performed as [TCP][wikipedia-tcp] packets sent over the _public_ internet. This exchange of information may be secured in order to counter eavesdropping.
|
|
||||||
|
|
||||||
Again, as with SMTP described earlier, the IMAP protocol may be secured with either Implicit TLS (aka. [IMAPS][wikipedia-imaps] / IMAP4S) or Explicit TLS (using STARTTLS).
|
|
||||||
|
|
||||||
The best practice as of 2020 is to enforce IMAPS on port 993, rather than IMAP+STARTTLS on port 143 (see [RFC 8314][rfc-8314]); yet the latter is usually provided for backwards compatibility.
|
|
||||||
|
|
||||||
**DMS's default configuration enables both Implicit and Explicit TLS for Retrievial, on ports 993 and 143 respectively.**
|
|
||||||
|
|
||||||
### Retrieval - POP3
|
|
||||||
|
|
||||||
Similarly to IMAP, the older POP3 protocol may be secured with either Implicit or Explicit TLS.
|
|
||||||
|
|
||||||
The best practice as of 2020 would be [POP3S][wikipedia-pop3s] on port 995, rather than [POP3][wikipedia-pop3]+STARTTLS on port 110 (see [RFC 8314][rfc-8314]).
|
|
||||||
|
|
||||||
**DMS's default configuration disables POP3 altogether.** One should expect MUAs to use TLS-encrypted IMAP for Retrieval.
|
|
||||||
|
|
||||||
## How Does DMS Help With Setting Everything Up?
|
|
||||||
|
|
||||||
As a _batteries included_ container image, DMS provides you with all the required components and a default configuration to run a decent and secure mail server. One may then customize all aspects of its internal components.
|
|
||||||
|
|
||||||
- Simple customization is supported through [Docker Compose configuration][github-file-compose] and the [env-mailserver][github-file-envmailserver] configuration file.
|
|
||||||
- Advanced customization is supported through providing "monkey-patching" configuration files and/or [deriving your own image][github-file-dockerfile] from DMS's upstream, for a complete control over how things run.
|
|
||||||
|
|
||||||
Eventually, it is up to _you_ deciding exactly what kind of transportation/encryption to use and/or enforce, and to customize your instance accordingly (with looser or stricter security). Be also aware that protocols and ports on your server can only go so far with security; third-party MTAs might relay your emails on insecure connections, man-in-the-middle attacks might still prove effective, etc. Advanced counter-measure such as DANE, MTA-STS and/or full body encryption (eg. PGP) should be considered as well for increased confidentiality, but ideally without compromising backwards compatibility so as to not block emails.
|
|
||||||
|
|
||||||
[docs-understandports]: ./config/security/understanding-the-ports.md
|
|
||||||
[github-file-compose]: https://github.com/docker-mailserver/docker-mailserver/blob/master/compose.yaml
|
|
||||||
[github-file-envmailserver]: https://github.com/docker-mailserver/docker-mailserver/blob/master/mailserver.env
|
|
||||||
[github-file-dockerfile]: https://github.com/docker-mailserver/docker-mailserver/blob/master/Dockerfile
|
|
||||||
[rfc-2487]: https://tools.ietf.org/html/rfc2487
|
|
||||||
[rfc-5321]: https://tools.ietf.org/html/rfc5321
|
|
||||||
[rfc-8314]: https://tools.ietf.org/html/rfc8314
|
|
||||||
[rfc-8314-s33]: https://tools.ietf.org/html/rfc8314#section-3.3
|
|
||||||
[software-mutt]: https://en.wikipedia.org/wiki/Mutt_(email_client)
|
|
||||||
[software-outlook]: https://en.wikipedia.org/wiki/Microsoft_Outlook
|
|
||||||
[software-thunderbird]: https://en.wikipedia.org/wiki/Mozilla_Thunderbird
|
|
||||||
[wikipedia-clientserver]: https://en.wikipedia.org/wiki/Client%E2%80%93server_model
|
|
||||||
[wikipedia-email]: https://en.wikipedia.org/wiki/Email
|
|
||||||
[wikipedia-emailagent]: https://en.wikipedia.org/wiki/Email_agent_(infrastructure)
|
|
||||||
[wikipedia-imap]: https://en.wikipedia.org/wiki/IMAP
|
|
||||||
[wikipedia-imaps]: https://en.wikipedia.org/wiki/IMAPS
|
|
||||||
[wikipedia-mda]: https://en.wikipedia.org/wiki/Mail_delivery_agent
|
|
||||||
[wikipedia-mta]: https://en.wikipedia.org/wiki/Message_transfer_agent
|
|
||||||
[wikipedia-mua]: https://en.wikipedia.org/wiki/Email_client
|
|
||||||
[wikipedia-pop3]: https://en.wikipedia.org/wiki/POP3
|
|
||||||
[wikipedia-pop3s]: https://en.wikipedia.org/wiki/POP3S
|
|
||||||
[wikipedia-smtp]: https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
|
|
||||||
[wikipedia-smtps]: https://en.wikipedia.org/wiki/SMTPS
|
|
||||||
[wikipedia-starttls]: https://en.wikipedia.org/wiki/Opportunistic_TLS
|
|
||||||
[wikipedia-tcp]: https://en.wikipedia.org/wiki/Transmission_Control_Protocol
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue