Harden optional mailbox hook scripts (#1080)

- backport only the generic hardening of the existing optional Maildir and Dovecot hook examples
- validate the documented hook argument contracts before constructing filesystem paths
- quote filesystem operations, replace legacy shell constructs and propagate command failures
- make domain and mailbox deletion safely retryable when their target is already absent
- update the Dovecot password example for Dovecot 2.3.19 or newer, with a Dovecot 2.4 setting note

The hooks remain optional and disabled by default. Administrators must review `basedir`, `trashbase` and the service account used by sudo. The mail-crypt password example now requires Dovecot 2.3.19 or newer.
This commit is contained in:
Rodrigo Cortés Cano authored and GitHub committed 2026-07-19 09:52:50 +01:00
1 parent dcf9318d27
commit 510715cef0
5 files changed
+256 -179

No files matched your search

+17 -6
View File
@@ -48,22 +48,33 @@ See also : https://github.com/postfixadmin/postfixadmin/tree/master/ADDITIONS/s
by George Vieira <george at citadelcomputer dot com dot au>
Deletes all unused mailboxes
## Example mailbox / domain scripts for Postfixadmin
## Example mailbox / domain scripts for PostfixAdmin
- postfixadmin-mailbox-postcreation.sh
- postfixadmin-mailbox-postdeletion.sh
- postfixadmin-domain-postdeletion.sh
by Troels Arvin <troels@arvin.dk>
Examples of scripts relevant to the optional
Examples relevant to the optional `mailbox_postcreation_script`,
`mailbox_postdeletion_script` and `domain_postdeletion_script` configuration
options.
Review and adjust `basedir` and `trashbase` before installing the scripts. Run
them as the account that owns the Maildirs, not as root. If sudo is required,
grant the web server permission to run only the exact script as that account;
never grant access to a generic `mv` command. Install privileged hooks in a
root-owned directory that is not writable by the web server or mail users.
$CONF['mailbox_postcreation_script'],
$CONF['mailbox_postdeletion_script'] and
$CONF['domain_postdeletion_script'] configuration options.
The scripts validate the argument contracts documented in `config.inc.php`.
Deletion is idempotent: an already absent Maildir is reported as a successful
no-op so an interrupted hook can be retried safely.
`postfixadmin-mailbox-postpassword.sh` is an example for Dovecot mail-crypt. It
requires Dovecot 2.3.19 or newer. Its default private-password setting name is
for Dovecot 2.3; follow the comment in the script when using Dovecot 2.4.
## Cyrus Quota Usage
See https://github.com/o-m-d/cyrus-quotausage-to-pfa
+60 -47
View File
@@ -1,62 +1,75 @@
#!/bin/sh
# Example script for removing a Maildir domain top-level folder
# from a Courier-IMAP virtual mail hierarchy.
# Example script for moving a deleted Maildir domain to a recovery directory.
# PostfixAdmin passes the domain as argument 1.
# The script only looks at argument 1, assuming that it
# indicates the relative name of a domain, such as
# "somedomain.com". If $basedir/somedomain.com exists, it will
# be removed.
# Run this script as the user that owns the Maildirs. If the web server needs
# sudo, restrict the sudoers rule to that user and this exact script. Do not
# grant a generic mv command.
# The script will not actually delete the directory. It moves it
# to a special directory which may once in a while be cleaned up
# by the system administrator.
# This script should be run as the user which owns the maildirs. If
# the script is actually run by the apache user (e.g. through PHP),
# then you could use "sudo" to grant apache the rights to run
# this script as the relevant user.
# Assume this script has been saved as
# /usr/local/bin/postfixadmin-domain-postdeletion.sh and has been
# made executable. Now, an example /etc/sudoers line:
# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-domain-postdeletion.sh
# The line states that the apache user may run the script as the
# user "courier" without providing a password.
# Change this to where you keep your virtual mail users' maildirs.
# Change these paths to match the virtual mail layout.
basedir=/var/spool/maildirs
# Change this to where you would like deleted maildirs to reside.
trashbase=/var/spool/deleted-maildirs
if [ `echo $1 | fgrep '..'` ]; then
echo "First argument contained a double-dot sequence; bailing out."
fail()
{
printf '%s\n' "$0: $*" >&2
exit 1
fi
}
if [ ! -e "$trashbase" ]; then
echo "trashbase '$trashbase' does not exist; bailing out."
exit 1
fi
valid_domain()
{
candidate=$1
trashdir="${trashbase}/`date +%F_%T`_$1"
domaindir="${basedir}/$1"
[ -n "$candidate" ] && [ "${#candidate}" -le 253 ] || return 1
case "$candidate" in
-*|.*|*.|*..*|*/*|*\\*|*[!A-Za-z0-9.-]*) return 1 ;;
esac
remainder=$candidate
while :; do
case "$remainder" in
*.*)
label=${remainder%%.*}
remainder=${remainder#*.}
;;
*)
label=$remainder
remainder=
;;
esac
[ -n "$label" ] && [ "${#label}" -le 63 ] || return 1
case "$label" in
-*|*-) return 1 ;;
esac
[ -n "$remainder" ] || break
done
}
[ "$#" -eq 1 ] || fail "expected exactly one domain argument"
domain=$1
valid_domain "$domain" || fail "invalid domain '$domain'"
[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory"
[ -d "$trashbase" ] || fail "trashbase '$trashbase' is not a directory"
domaindir="${basedir%/}/$domain"
[ "$domaindir" != "${trashbase%/}" ] || fail "refusing to move trashbase itself"
if [ ! -e "$domaindir" ]; then
echo "Directory '$domaindir' does not exits; nothing to do."
exit 0;
printf '%s\n' "$0: directory '$domaindir' does not exist; nothing to do."
exit 0
fi
if [ ! -d "$domaindir" ]; then
echo "'$domaindir' is not a directory; bailing out."
exit 1
fi
if [ -e "$trashdir" ]; then
echo "Directory '$trashdir' already exits; bailing out."
exit 1;
[ -d "$domaindir" ] || fail "'$domaindir' is not a directory"
timestamp=$(date '+%Y%m%dT%H%M%S') || fail "could not generate a timestamp"
trashdir="${trashbase%/}/${timestamp}_$$_${domain}"
[ ! -e "$trashdir" ] || fail "trash destination '$trashdir' already exists"
if ! mv "$domaindir" "$trashdir"; then
fail "could not move '$domaindir' to '$trashdir'"
fi
mv $domaindir $trashdir
exit $?
printf '%s\n' "$0: moved '$domaindir' to '$trashdir'."
exit 0
+60 -52
View File
@@ -1,71 +1,79 @@
#!/bin/sh
# Example script for adding a Maildir to a Courier-IMAP virtual mail
# hierarchy.
# hierarchy. PostfixAdmin passes username, domain, Maildir and quota as
# arguments 1 through 4. This example uses only the relative Maildir path.
# The script only looks at argument 3, assuming that it
# indicates the relative name of a maildir, such as
# "somedomain.com/peter/".
# Run this script as the user that owns the Maildirs. If the web server needs
# sudo, restrict the sudoers rule to that user and this exact script.
# This script should be run as the user which owns the maildirs. If
# the script is actually run by the apache user (e.g. through PHP),
# then you could use "sudo" to grant apache the rights to run
# this script as the relevant user.
# Assume this script has been saved as
# /usr/local/bin/postfixadmin-mailbox-postcreation.sh and has been
# made executable. Now, an example /etc/sudoers line:
# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-mailbox-postcreation.sh
# The line states that the apache user may run the script as the
# user "courier" without providing a password.
# Change this to where you keep your virtual mail users' maildirs.
# Change this to where you keep your virtual mail users' Maildirs.
basedir=/var/spool/maildirs
if [ ! -e "$basedir" ]; then
echo "$0: basedir '$basedir' does not exist; bailing out."
fail()
{
printf '%s\n' "$0: $*" >&2
exit 1
fi
}
if [ `echo $3 | fgrep '..'` ]; then
echo "$0: An argument contained a double-dot sequence; bailing out."
exit 1
fi
valid_relative_maildir()
{
candidate=${1%/}
[ -n "$candidate" ] || return 1
case "$candidate" in
/*|*\\*|*//*|*[![:print:]]*) return 1 ;;
esac
remainder=$candidate
while :; do
case "$remainder" in
*/*)
component=${remainder%%/*}
remainder=${remainder#*/}
;;
*)
component=$remainder
remainder=
;;
esac
case "$component" in
''|.|..) return 1 ;;
esac
[ -n "$remainder" ] || break
done
}
[ "$#" -eq 4 ] || fail "expected username, domain, Maildir and quota arguments"
relative_maildir=${3%/}
valid_relative_maildir "$relative_maildir" || fail "invalid relative Maildir '$3'"
[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory"
maildir="${basedir%/}/$relative_maildir"
parent=$(dirname "$maildir") || fail "could not determine the parent directory"
maildir="${basedir}/$3"
parent=`dirname "$maildir"`
if [ ! -d "$parent" ]; then
if [ -e "$parent" ]; then
echo "$0: strange - directory '$parent' exists, but is not a directory; bailing out."
exit 1
else
mkdir -p "${parent}"
if [ $? -ne 0 ]; then
echo "$0: mkdir -p '$parent' returned non-zero; bailing out."
exit 1
fi
[ ! -e "$parent" ] || fail "'$parent' exists but is not a directory"
if ! mkdir -p "$parent"; then
fail "could not create parent directory '$parent'"
fi
fi
if [ -e "$maildir" ]; then
echo "$0: Directory '$maildir' already exists! bailing out"
exit 1
[ ! -e "$maildir" ] || fail "Maildir '$maildir' already exists"
if maildirmake_path=$(command -v maildirmake 2>/dev/null); then
:
elif maildirmake_path=$(command -v courier-maildirmake 2>/dev/null); then
:
else
fail "could not find maildirmake or courier-maildirmake in PATH"
fi
# try looking for maildirmake ...
MDM=`which maildirmake || which courier-maildirmake`
if [ "x${MDM}" = "x" ]; then
echo "Couldn't find maildirmake or courier-maildirmake in your PATH etc (via which)" >/dev/stderr
exit 1
fi
"${MDM}" "${maildir}"
if [ ! -d "$maildir" ]; then
echo "$0: maildirmake didn't produce a directory; bailing out."
exit 1
if ! "$maildirmake_path" "$maildir"; then
fail "maildirmake failed for '$maildir'"
fi
[ -d "$maildir" ] || fail "maildirmake did not create '$maildir'"
exit 0
+80 -62
View File
@@ -1,77 +1,95 @@
#!/bin/sh
# Example script for removing a Maildir from a Courier-IMAP virtual mail
# hierarchy.
# Example script for moving a deleted Maildir to a recovery directory.
# PostfixAdmin passes username and domain as arguments 1 and 2.
# The script looks at arguments 1 and 2, assuming that they
# indicate username and domain, respectively.
# Run this script as the user that owns the Maildirs. If the web server needs
# sudo, restrict the sudoers rule to that user and this exact script. Do not
# grant a generic mv command.
# The script will not actually delete the maildir. It moves it
# to a special directory which may once in a while be cleaned up
# by the system administrator.
# This script should be run as the user which owns the maildirs. If
# the script is actually run by the apache user (e.g. through PHP),
# then you could use "sudo" to grant apache the rights to run
# this script as the relevant user.
# Assume this script has been saved as
# /usr/local/bin/postfixadmin-mailbox-postdeletion.sh and has been
# made executable. Now, an example /etc/sudoers line:
# apache ALL=(courier) NOPASSWD: /usr/local/bin/postfixadmin-mailbox-postdeletion.sh
# The line states that the apache user may run the script as the
# user "courier" without providing a password.
# Change this to where you keep your virtual mail users' maildirs.
# Change these paths to match the virtual mail layout.
basedir=/var/spool/maildirs
# Change this to where you would like deleted maildirs to reside.
trashbase=/var/spool/deleted-maildirs
if [ ! -e "$trashbase" ]; then
echo "trashbase '$trashbase' does not exist; bailing out."
fail()
{
printf '%s\n' "$0: $*" >&2
exit 1
}
valid_domain()
{
candidate=$1
[ -n "$candidate" ] && [ "${#candidate}" -le 253 ] || return 1
case "$candidate" in
-*|.*|*.|*..*|*/*|*\\*|*[!A-Za-z0-9.-]*) return 1 ;;
esac
remainder=$candidate
while :; do
case "$remainder" in
*.*)
label=${remainder%%.*}
remainder=${remainder#*.}
;;
*)
label=$remainder
remainder=
;;
esac
[ -n "$label" ] && [ "${#label}" -le 63 ] || return 1
case "$label" in
-*|*-) return 1 ;;
esac
[ -n "$remainder" ] || break
done
}
valid_mailbox_component()
{
case "$1" in
''|.|..|*/*|*\\*|*[![:print:]]*) return 1 ;;
esac
}
[ "$#" -eq 2 ] || fail "expected username and domain arguments"
username=$1
domain=$2
valid_domain "$domain" || fail "invalid domain '$domain'"
case "$username" in
*@"$domain") subdir=${username%"@$domain"} ;;
*) fail "username '$username' does not belong to domain '$domain'" ;;
esac
valid_mailbox_component "$subdir" || fail "unsafe mailbox directory component"
[ -d "$basedir" ] || fail "basedir '$basedir' is not a directory"
[ -d "$trashbase" ] || fail "trashbase '$trashbase' is not a directory"
maildir="${basedir%/}/$domain/$subdir"
if [ ! -e "$maildir" ]; then
printf '%s\n' "$0: Maildir '$maildir' does not exist; nothing to do."
exit 0
fi
[ -d "$maildir" ] || fail "'$maildir' is not a directory"
if [ `echo $1 | fgrep '..'` ]; then
echo "First argument contained a double-dot sequence; bailing out."
exit 1
fi
if [ `echo $2 | fgrep '..'` ]; then
echo "First argument contained a double-dot sequence; bailing out."
exit 1
fi
subdir=`echo "$1" | sed 's/@.*//'`
maildir="${basedir}/$2/${subdir}"
trashdir="${trashbase}/$2/`date +%F_%T`_${subdir}"
parent=`dirname "$trashdir"`
if [ ! -d "$parent" ]; then
if [ -e "$parent" ]; then
echo "Strainge - directory '$parent' exists, but is not a directory."
echo "Bailing out."
exit 1
else
mkdir -p "$parent"
if [ $? -ne 0 ]; then
echo "mkdir -p '$parent' returned non-zero; bailing out."
exit 1
fi
trashparent="${trashbase%/}/$domain"
if [ ! -d "$trashparent" ]; then
[ ! -e "$trashparent" ] || fail "'$trashparent' exists but is not a directory"
if ! mkdir -p "$trashparent"; then
fail "could not create trash directory '$trashparent'"
fi
fi
if [ ! -e "$maildir" ]; then
echo "maildir '$maildir' does not exist; nothing to do."
exit 1
fi
if [ -e "$trashdir" ]; then
echo "trashdir '$trashdir' already exists; bailing out."
exit 1
timestamp=$(date '+%Y%m%dT%H%M%S') || fail "could not generate a timestamp"
trashdir="${trashparent}/${timestamp}_$$_${subdir}"
[ ! -e "$trashdir" ] || fail "trash destination '$trashdir' already exists"
if ! mv "$maildir" "$trashdir"; then
fail "could not move '$maildir' to '$trashdir'"
fi
mv $maildir $trashdir
exit $?
printf '%s\n' "$0: moved '$maildir' to '$trashdir'."
exit 0
+39 -12
View File
@@ -1,19 +1,46 @@
#!/bin/bash
# Example script for dovecot mail-crypt-plugin
# https://doc.dovecot.org/configuration_manual/mail_crypt_plugin/
# Example script for Dovecot's mail-crypt plugin.
# Requires Dovecot 2.3.19 or newer for the -O/-N prompt behaviour.
# https://doc.dovecot.org/2.3/configuration_manual/mail_crypt_plugin/
IFS= read -r -d $'\0' OLD_PASSWORD
IFS= read -r -d $'\0' NEW_PASSWORD
# Dovecot 2.3 setting name. For Dovecot 2.4, use:
# private_password_setting=crypt_user_key_password
private_password_setting=plugin/mail_crypt_private_password
# New user
if [ -z "$OLD_PASSWORD" ]; then
OLD_PASSWORD="$(openssl rand -hex 16)"
doveadm -o plugin/mail_crypt_private_password="$OLD_PASSWORD" mailbox cryptokey generate -u "$1" -U
fail()
{
printf '%s\n' "$0: $*" >&2
exit 1
}
[[ $# -eq 2 ]] || fail "expected username and domain arguments"
username=$1
domain=$2
[[ -n $username && -n $domain && $username == *@"$domain" ]] || fail "invalid username or domain"
IFS= read -r -d '' old_password || fail "could not read the NUL-terminated old password"
IFS= read -r -d '' new_password || fail "could not read the NUL-terminated new password"
[[ -n $new_password ]] || fail "new password must not be empty"
openssl_path=$(command -v openssl 2>/dev/null) || fail "could not find openssl in PATH"
doveadm_path=$(command -v doveadm 2>/dev/null) || fail "could not find doveadm in PATH"
if [[ -z $old_password ]]; then
old_password=$("$openssl_path" rand -hex 16) || fail "could not generate a temporary password"
[[ -n $old_password ]] || fail "openssl returned an empty temporary password"
if ! "$doveadm_path" -o "$private_password_setting=$old_password" \
mailbox cryptokey generate -u "$username" -U; then
fail "could not generate the mailbox cryptokey"
fi
fi
# If you're using dovecot >= 2.3.19, try this instead (See: https://github.com/postfixadmin/postfixadmin/issues/646)
# printf "%s\n%s\n" "$OLD_PASSWORD" "$NEW_PASSWORD" "$NEW_PASSWORD" | doveadm mailbox cryptokey password -u "$1" -N -O
# Since Dovecot 2.3.19, -O asks for the old password and -N asks for the new
# password twice. Keep passwords on stdin instead of command-line arguments.
if ! printf '%s\n%s\n%s\n' "$old_password" "$new_password" "$new_password" | \
"$doveadm_path" mailbox cryptokey password -u "$username" -O -N; then
fail "could not update the mailbox cryptokey password"
fi
# Password change
printf "%s\n%s\n" "$OLD_PASSWORD" "$NEW_PASSWORD" | doveadm mailbox cryptokey password -u "$1" -N -O ""
exit 0