vmailctl/INSTALL.md

Installing vmailctl

vmailctl manages an existing Postfix/Dovecot flat-file virtual-mail setup. Do not install it until the live configuration matches the documented assumptions.

Requirements

• Python 3.10 or newer
• Postfix with postmap and hash: map support
• Dovecot with doveadm, doveconf, passwd-file authentication and Maildir
• Root access
• GNU make, install, gzip and mandb for the provided installation target

The example paths suit many Debian-family systems. Other systems may place the commands or manual hierarchy elsewhere.

Verify the existing mail layout

The Dovecot users file must contain exactly eight colon-separated fields per account:

user@example.com:{SCHEME}HASH:5000:5000::/var/mail/vhosts/example.com/user::userdb_mail_path=~/Maildir

The Postfix mailbox source map must use two whitespace-separated fields:

user@example.com example.com/user/Maildir/

The Postfix alias source map must likewise use two fields:

alias@example.com user@example.com

Both Postfix maps must be configured as hash: maps. The corresponding .db files should already exist and match their sources.

Before installation, make an independent backup of:

/etc/dovecot/virtual-users
/etc/postfix/vmailbox
/etc/postfix/vmailbox.db
/etc/postfix/virtual
/etc/postfix/virtual.db
/var/mail/vhosts

Adapt that list if your paths differ.

Configure

Review vmailctl.conf.example. At minimum, set:

• domain
• dovecot_users
• postfix_mailboxes
• postfix_aliases
• mail_root
• uid and gid
• the paths to postmap, postfix, doveadm and doveconf

The UID and GID must match the virtual-mail owner already used by Dovecot. hash_scheme must appear in doveadm pw -l; ARGON2ID is recommended where supported.

The configuration, Dovecot users file, Postfix source maps and compiled .db maps must be regular root-owned files, not symbolic links, and must not be group- or world-writable. Their containing directories must be root-owned and not writable by untrusted users. The configured command paths must likewise name root-owned regular executable files in trusted directories. If a distribution exposes a command through a symbolic link, configure its resolved real path instead (for example, obtain it with readlink -f /path/to/command).

The configured domain directory beneath mail_root may be owned either by root or by the configured virtual-mail UID/GID. It must be a real directory and must not be world-writable. backup_dir is created as a root-only 0700 directory when its parent is trusted; the lock is maintained as a root-only regular file.

Install with make

sudo make install

The installation target:

• installs vmailctl as /usr/local/sbin/vmailctl
• installs the man page beneath /usr/local/share/man/man8
• creates /var/backups/vmailctl with mode 0700
• installs /etc/vmailctl.conf only when that file does not already exist
• refreshes the manual database when mandb is available

It deliberately does not overwrite an existing configuration.

For packaging or staged installation, set DESTDIR. Installation locations may also be adjusted with PREFIX and SYSCONFDIR:

make DESTDIR=/tmp/package-root install

Validate

Inspect the installed configuration:

sudo chown root:root /etc/vmailctl.conf
sudo chmod 0644 /etc/vmailctl.conf
sudoedit /etc/vmailctl.conf
sudo vmailctl audit

Do not proceed until the audit reports no errors. Warnings should be understood before making changes.

Then exercise dry-run paths:

sudo vmailctl --dry-run mailbox add test-account
sudo vmailctl --dry-run alias add test-alias existing-mailbox

Read the complete manual:

man 8 vmailctl

Manual installation

If make install is unsuitable, copy the files with equivalent ownership and permissions:

sudo install -o root -g root -m 0755 vmailctl /usr/local/sbin/vmailctl
sudo install -o root -g root -m 0644 vmailctl.conf.example /etc/vmailctl.conf
sudo install -d -o root -g root -m 0700 /var/backups/vmailctl
sudo install -d -o root -g root -m 0755 /usr/local/share/man/man8
sudo install -o root -g root -m 0644 man/vmailctl.8 \
  /usr/local/share/man/man8/vmailctl.8
sudo gzip -n -9 -f /usr/local/share/man/man8/vmailctl.8
sudo mandb -q

Do not copy the example configuration over an existing customised /etc/vmailctl.conf.

Updating

Back up the installed program and configuration, run the new version's tests, review CHANGELOG.md, and replace the executable and man page. Preserve and compare /etc/vmailctl.conf rather than replacing it automatically.

There is intentionally no automated uninstall target. Removing a root mail administration tool should be a deliberate manual operation; transaction backups and mail data are never removed automatically.