feat: Support for Dovecot master accounts (#2535)

Dovecot master accounts can now be configured in DMS via `setup.sh`.
A master account is useful for administration purposes, or to perform mailbox backups of every user account over IMAP.
Upstream Docs: https://doc.dovecot.org/configuration_manual/authentication/master_users/

Co-authored-by: Casper <casperklein@users.noreply.github.com>
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

target/bin/adddovecotmasteruser

@@ -0,0 +1,59 @@
+#! /bin/bash
+
+# shellcheck disable=SC2094
+
+# shellcheck source=../scripts/helpers/index.sh
+source /usr/local/bin/helpers/index.sh
+
+DATABASE=/tmp/docker-mailserver/dovecot-masters.cf
+
+function __usage
+{
+  printf "\e[35mADDDOVECOTMASTERUSER\e[31m(\e[93m8\e[31m)
+
+\e[38;5;214mNAME\e[39m
+    addmasteruser - add a dovecot master user (for POP3/IMAP administration)
+
+\e[38;5;214mSYNOPSIS\e[39m
+    ./setup.sh dovecot-master add <USERNAME> [<PASSWORD>]
+
+\e[38;5;214mOPTIONS\e[39m
+    \e[94mGeneric Program Information\e[39m
+        help       Print the usage information.
+
+\e[38;5;214mEXAMPLES\e[39m
+    \e[37m./setup.sh dovecot-master add test-user\e[39m
+        Add the dovecot master account 'test-user'. You will be prompted
+        to input a password afterwards since no password was supplied.
+
+\e[38;5;214mEXIT STATUS\e[39m
+    Exit status is 0 if command was successful. If wrong arguments are provided
+    or arguments contain errors, the script will exit early with exit status 1.
+
+"
+}
+
+[[ ${1:-} == 'help' ]] && { __usage ; exit 0 ; }
+
+USERNAME="${1}"
+shift
+PASSWD="${*}"
+
+[[ -z ${USERNAME} ]] && { __usage ; _exit_with_error 'No username specified' ; }
+
+touch "${DATABASE}"
+_create_lock # Protect config file with lock to avoid race conditions
+if grep -qi "^$(_escape "${USERNAME}")|" "${DATABASE}"
+then
+  _exit_with_error "User '${USERNAME}' already exists"
+fi
+
+if [[ -z ${PASSWD} ]]
+then
+  read -r -s -p "Enter Password: " PASSWD
+  echo
+  [[ -z ${PASSWD} ]] && _exit_with_error "Password must not be empty"
+fi
+
+HASH="$(doveadm pw -s SHA512-CRYPT -u "${USERNAME}" -p "${PASSWD}")"
+echo "${USERNAME}|${HASH}" >> "${DATABASE}"

target/bin/deldovecotmasteruser

@@ -0,0 +1,75 @@
+#! /bin/bash
+
+# shellcheck disable=SC2094
+# ? This is done to ignore the message "Make sure not to read and write
+# ? the same file in the same pipeline", which is a result of ${DATABASE}
+# ? being used below. (This disables the message file-wide.)
+
+# shellcheck source=../scripts/helpers/index.sh
+source /usr/local/bin/helpers/index.sh
+
+DATABASE=/tmp/docker-mailserver/dovecot-masters.cf
+
+function __usage
+{
+  echo -e "\e[35mDELDOVECOTMASTERUSER\e[31m(\e[93m8\e[31m)
+
+\e[38;5;214mNAME\e[39m
+    deldovecotmasteruser - delete a dovecot master user
+
+\e[38;5;214mSYNOPSIS\e[39m
+    ./setup.sh dovecot-master del { <USERNAME> [<USERNAME>\e[31m...\e[39m] \e[31m|\e[39m help }
+
+\e[38;5;214mDESCRIPTION\e[39m
+    Delete a dovecot master user.
+
+\e[38;5;214mOPTIONS\e[39m
+    -h
+        Show this help dialogue.
+
+\e[38;5;214mEXAMPLES\e[39m
+    \e[37m./setup.sh dovecot-master del administrator\e[39m
+        Delete the dovecot master user called 'administrator'.
+
+    \e[37m./setup.sh dovecot-master del administrator admin\e[39m
+        Delete dovecot master users 'administrator' and 'admin'.
+
+\e[38;5;214mEXIT STATUS\e[39m
+    Exit status is 0 if command was successful, and 1 if there was an error.
+"
+}
+
+if [[ ${1} == 'help' ]]
+then
+  __usage
+  exit 0
+fi
+
+shift $((OPTIND-1))
+
+[[ -z ${*} ]] && { __usage ; _exit_with_error 'No user specified' ; }
+[[ -s ${DATABASE} ]] || exit 0
+
+_create_lock # Protect config file with lock to avoid race conditions
+
+for USER in "${@}"
+do
+  ERROR=false
+
+  # ${USER} must not contain /s and other syntactic characters
+  UNESCAPED_USER="${USER}"
+  USER=$(_escape "${USER}")
+
+  if [[ -f ${DATABASE} ]]
+  then
+    if ! sedfile --strict -i "/^${USER}|/d" "${DATABASE}"
+    then
+      _log 'error' "'${UNESCAPED_USER}' couldn't be deleted in '${DATABASE}'"
+      ERROR=true
+    fi
+  fi
+
+  ${ERROR} && _exit_with_error 'See the messages above.'
+done
+
+exit 0

target/bin/listdovecotmasteruser

@@ -0,0 +1,21 @@
+#! /bin/bash
+
+# shellcheck source=../scripts/helpers/index.sh
+source /usr/local/bin/helpers/index.sh
+
+# suppress error output, e.g. when listmailuser runs in a fresh container (DMS not running)
+# shellcheck source=/dev/null
+source /etc/dms-settings 2>/dev/null
+
+DATABASE='/tmp/docker-mailserver/dovecot-masters.cf'
+
+[[ -f ${DATABASE} ]] || _exit_with_error "No 'dovecot-masters.cf' file"
+[[ -s ${DATABASE} ]] || _exit_with_error "Empty 'dovecot-masters.cf' - no dovecot master accounts have been added"
+
+while read -r LINE
+do
+  USER=$(echo "${LINE}" | cut -d'|' -f1)
+  echo "* ${USER}"
+done < "${DATABASE}"
+
+exit 0

target/bin/setup

@@ -25,7 +25,7 @@ ${ORANGE}NAME${RESET}
 ${ORANGE}SYNOPSIS${RESET}
     ./${SCRIPT:-${0}} [ OPTIONS${RED}...${RESET} ] COMMAND [ help ${RED}|${RESET} ARGUMENTS${RED}...${RESET} ]
 
-    COMMAND ${RED}:=${RESET} { email ${RED}|${RESET} alias ${RED}|${RESET} quota ${RED}|${RESET} config ${RED}|${RESET} relay ${RED}|${RESET} debug } SUBCOMMAND
+    COMMAND ${RED}:=${RESET} { email ${RED}|${RESET} alias ${RED}|${RESET} quota ${RED}|${RESET} dovecot-master ${RED}|${RESET} config ${RED}|${RESET} relay ${RED}|${RESET} debug } SUBCOMMAND
 
 ${ORANGE}DESCRIPTION${RESET}
     This is the main administration script that you use for all your interactions with
@@ -59,6 +59,12 @@ ${RED}[${ORANGE}SUB${RED}]${ORANGE}COMMANDS${RESET}
         ${0} quota ${CYAN}set${RESET} <EMAIL ADDRESS> [<QUOTA>]
         ${0} quota ${CYAN}del${RESET} <EMAIL ADDRESS>
 
+    ${LBLUE}COMMAND${RESET} dovecot-master ${RED}:=${RESET}
+        ${0} dovecot-master ${CYAN}add${RESET} <USERNAME> [<PASSWORD>]
+        ${0} dovecot-master ${CYAN}update${RESET} <USERNAME> [<PASSWORD>]
+        ${0} dovecot-master ${CYAN}del${RESET} [ OPTIONS${RED}...${RESET} ] <USERNAME> [ <USERNAME>${RED}...${RESET} ]
+        ${0} dovecot-master ${CYAN}list${RESET}
+
     ${LBLUE}COMMAND${RESET} config ${RED}:=${RESET}
         ${0} config ${CYAN}dkim${RESET} [ ARGUMENTS${RED}...${RESET} ]
 
@@ -132,6 +138,16 @@ function _main
       esac
       ;;
 
+    ( dovecot-master )
+      case ${2:-} in
+        ( add      ) shift 2 ; adddovecotmasteruser "${@}" ;;
+        ( update   ) shift 2 ; updatedovecotmasteruser "${@}" ;;
+        ( del      ) shift 2 ; deldovecotmasteruser "${@}" ;;
+        ( list     ) listdovecotmasteruser ;;
+        ( *        ) _invalid_command "${1}" "${2}" ;;
+      esac
+      ;;
+
     ( config )
       case ${2:-} in
         ( dkim     ) shift 2 ; open-dkim "${@}" ;;

target/bin/updatedovecotmasteruser

@@ -0,0 +1,33 @@
+#! /bin/bash
+
+# ? This is done to ignore the message "Make sure not to read and write
+# ? the same file in the same pipeline", which is a result of ${DATABASE}
+# ? being used below. (This disables the message file-wide.)
+# shellcheck disable=SC2094
+
+# shellcheck source=../scripts/helpers/index.sh
+source /usr/local/bin/helpers/index.sh
+
+DATABASE=/tmp/docker-mailserver/dovecot-masters.cf
+
+USER="${1}"
+shift
+PASSWD="${*}"
+
+function __usage { echo 'Usage: updatedovecotmasteruser <USERNAME> [PASSWORD]' ; }
+
+[[ -z ${USER} ]] && { __usage ; _exit_with_error 'No username specified' ; }
+
+if [[ -z ${PASSWD} ]]
+then
+  read -r -s -p 'Enter Password: ' PASSWD
+  echo
+  [[ -z ${PASSWD} ]] && _exit_with_error 'Password must not be empty'
+fi
+
+HASH="$(doveadm pw -s SHA512-CRYPT -u "${USER}" -p "${PASSWD}")"
+
+touch "${DATABASE}"
+_create_lock # Protect config file with lock to avoid race conditions
+grep -qi "^$(_escape "${USER}")|" "${DATABASE}" 2>/dev/null || _exit_with_error "Master user \"${USER}\" does not exist"
+sed -i "s ^""${USER}""|.* ""${USER}""|""${HASH}"" " "${DATABASE}"