mirror/docker-mailserver
1
1
Fork 0
mirror of https://github.com/docker-mailserver/docker-mailserver synced 2024-12-18 23:14:11 +01:00
Code Issues
master
docker-mailserver/docs/content/config/advanced/optional-config.md
Brennan Kinney 0698ad9370
docs: Refactor pages for Account Management (#4122) 
* docs: Relocate account / auth pages into a common section

* docs: Update references to relocated pages

* docs: Add account management overview page

Updates remaining links to account sections on this page instead (_for `accounts`, `aliases`, `quotas`_).

This page will cover the features and defer to separate pages for more specific content where relevant.

* docs: Correct relocated pages titles and links

* docs: Accounts (Dovecot Master) - Minor revisions

* docs: Fix highlighting roundcube PHP snippet in OAuth2 page

* docs: Accounts (File) - Refactor

- Manual method not necessary to document.
- Condense `setup` example guidance.
- Quotas / Aliases content migrated to Overview when not specific about file provisioner.

Some of the content is this commit is not a complete revision.

* chore: Temporary commit

* docs(refactor): Sub-addressing section

Much better docs on the sub-addressing feature supported by Postfix and Dovecot, along with the guidance with usage in Sieve.

* docs:  Revise accounts section

Add some context regarding DMS accounts and their distinction/overlap from the email address functionality, and it's relevant context for receiving/sending.

File provisioner, minor revisions to referencing associated config files and account management.

* docs: Minor adjustments

* docs: Refactor the quota section

Better documented with links and coverage over the workaround details we've implemented.

* docs: Revise the quota section

Minor revisions with phrasing, admonitions for structure and better explanation of the feature functionality/purpose.

* docs: Alias section refactor

Extensively covers known issues and technical details that have been discussed often enough.

The improvements should benefit both users and maintainers.

* docs: Refactor master accounts page

This rewrite should more clearly document the feature, along with a better example and additional links for reference.

* docs: OAuth2 revision

Minor update to this page:
- Links extracted to bottom of page as per convention.
- ENV file example converted to preferred `compose.yaml` ENV settings.

* docs: Sieve minor revisions

- Correct link to subaddressing section
- Make the config file example snippets intended filename less ambiguous.
- Minor rephrasng.

* docs: Revise accounts overview section

Revised the account section and added additional clarity for common confusion with relation to sender address and multi-domain support.

Top of the page now clarifies it's a technical reference and directs users to the related pages for configuration / caveats.

Technical Overview links to Dovecot docs were missing.

* docs: Another revision pass

File based provisioner docs:
- Sections indent with info admonitions.
- Accounts section expanded with config format and example.
- Quotas section expanded and shifted to bottom (alphabetical sort).
- Split into `setup` CLI and config reference groups.

Overview page:
- Sections indent with info admonitions.
- Revised content.

* docs(chore): Shift sub-addressing section

This is related to accounts and aliases, but not provisioners, thus extract out of the accounts parent section.

* docs: Document `postfix-accounts.cf` third column

This lacked documentation but was community contributed feature to allow further customization of a Dovecot Account.

It has caveats as DMS does not take these into consideration anywhere in scripts. Documenting officially for better awareness.

* docs: Revise and expand supplementary pages

Better outline the OAuth2 login process, the two supported login mechanisms and their docs/rfcs, along with documenting caveat with mail client compatibility.

Add a verification tip for the OAuth2 support, showing how `curl` can be used, along with caveat presently affecting the `curl` in DMS v14.

Additionally note the feature still isn't documented fully, providing the user with additional references for more information.

`ACCOUNT_PROVISIONER` ENV docs minimized. No `OIDC` provisioner plans, the OAuth2 docs page now mentions SCIM 2.0 API as the next step towards resolving that concern. The tip admonition was removed as it no longer provides value, instead we link to the Account Management overview page.

Dovecot Master Accounts docs page now lightly document the `setup` CLI and config format for the feature.

* docs: Fix broken anchor links

Some anchor links to different parts of our docs have gone stale. This branch also broke a few itself that I missed.

The build now only reports issues with anchor links to Content Tabs, which it must not be aware of during the build (_MKDocs Material specific feature?_)

* docs(lint): Fix indentation level

* chore: Add entry to `CHANGELOG.md` + corrections
2024-07-22 10:00:53 +12:00

7.7 KiB
Raw Permalink Blame History

title hide
Advanced | Optional Configuration
toc

Volumes

DMS has several locations in the container which may be worth persisting externally via Docker Volumes.

  • Often you will want to prefer bind mount volumes 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

This is the location where mail is delivered to your mailboxes.

State Volume

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_).

Logs Volume

This can be a useful volume to persist for troubleshooting needs for the full set of log files.

Config Volume

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)
  • sieve-pipe: directory for sieve pipe scripts. (Docs: Sieve)
  • opendkim: DKIM directory. Auto-configurable via setup.sh config dkim. (Docs: DKIM)
  • ssl: SSL Certificate directory if SSL_TYPE is set to self-signed or custom. (Docs: SSL)
  • rspamd: Override directory for custom settings when using Rspamd (Docs: Rspamd)

Files

  • {user_email_address}.dovecot.sieve: User specific Sieve filter file. (Docs: Sieve)
  • before.dovecot.sieve: Global Sieve filter file, applied prior to the ${login}.dovecot.sieve filter. (Docs: Sieve)
  • after.dovecot.sieve: Global Sieve filter file, applied after the ${login}.dovecot.sieve filter. (Docs: Sieve)
  • postfix-main.cf: Every line will be added to the postfix main configuration. (Docs: Override Postfix Defaults)
  • postfix-master.cf: Every line will be added to the postfix master configuration. (Docs: Override Postfix Defaults)
  • postfix-accounts.cf: User accounts file. Modify via the setup.sh email script.
  • postfix-send-access.cf: List of users denied sending. Modify via setup.sh email restrict.
  • postfix-receive-access.cf: List of users denied receiving. Modify via setup.sh email restrict.
  • postfix-virtual.cf: Alias configuration file. Modify via setup.sh alias.
  • 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)
  • 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)
  • postfix-regexp.cf: Regular expression alias file. (Docs: Aliases)
  • ldap-users.cf: Configuration for the virtual user mapping virtual_mailbox_maps. See the setup-stack.sh script.
  • ldap-groups.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
  • ldap-aliases.cf: Configuration for the virtual alias mapping virtual_alias_maps. See the setup-stack.sh script.
  • ldap-domains.cf: Configuration for the virtual domain mapping virtual_mailbox_domains. See the setup-stack.sh 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)
  • fail2ban-fail2ban.cf: Additional config options for fail2ban.cf. (Docs: Fail2Ban)
  • fail2ban-jail.cf: Additional config options for fail2ban's jail behavior. (Docs: Fail2Ban)
  • amavis.cf: replaces the /etc/amavis/conf.d/50-user file
  • dovecot.cf: replaces /etc/dovecot/local.conf. (Docs: Override Dovecot Defaults)
  • dovecot-quotas.cf: list of custom quotas per mailbox. (Docs: Accounts)
  • 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)
  • rspamd/custom-commands.conf: list of simple commands to adjust Rspamd modules in an easy way (Docs: Rspamd)