From 2d86c3d9a1f882cea723a38a0bcda9eafcb6d7e9 Mon Sep 17 00:00:00 2001 From: polarathene <5098581+polarathene@users.noreply.github.com> Date: Mon, 15 Jul 2024 15:10:55 +1200 Subject: [PATCH] docs: Refactor master accounts page This rewrite should more clearly document the feature, along with a better example and additional links for reference. --- .../supplementary/master-accounts.md | 46 +++++++++++++++---- 1 file changed, 38 insertions(+), 8 deletions(-) diff --git a/docs/content/config/account-management/supplementary/master-accounts.md b/docs/content/config/account-management/supplementary/master-accounts.md index 88d66932..bcab6cd1 100644 --- a/docs/content/config/account-management/supplementary/master-accounts.md +++ b/docs/content/config/account-management/supplementary/master-accounts.md @@ -4,19 +4,49 @@ title: 'Account Management | Master Accounts (Dovecot)' ## Introduction -A master account is able to login as any configured user. This is useful for administrative tasks like hot backups. +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. + +This feature is useful for administrative tasks like hot backups. + +!!! note + + This feature is presently [not supported with LDAP][dms::feature::dovecot-master-accounts::caveat-ldap] account provisioning. + + +??? 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] using the upstream default value (`*`). ## Configuration -It is possible to create, update, delete and list master accounts using `setup`. See `setup help` for usage. +The DMS `setup` CLI can create, update, delete, and list master accounts. Run `setup help` for usage. -This feature is presently [not supported with LDAP](https://github.com/docker-mailserver/docker-mailserver/pull/2535). +## Login via Master Account -## Logging in +To login as another DMS account (`user@example.com`) with POP3/IMAP, use the following credentials format: -Once a master account is configured, it is possible to connect to any users mailbox using this account. +- Username: `*` (`user@example.com*admin`) +- Password: `` -Log in over POP3/IMAP using the following credential scheme: +!!! example "Verify login functionality" -- Username: `*` -- Password: `` + In the DMS container, you can verify with the `testsaslauthd` command: + + ```bash + # 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 + + 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