vmailctl is a small, root-only command for safely managing virtual mailboxes and aliases in an existing Postfix and Dovecot installation that uses flat files rather than SQL or LDAP.

It is intended for personal and small-community mail servers where a complete administration panel would add more machinery than it removes.

Status: 0.1.0 is a public beta. Review the assumptions and configuration carefully, retain independent backups, and test with --dry-run before using it on a production mail server.

Features

Creates Dovecot passwd-file mailbox logins
Generates ARGON2ID hashes through doveadm
Creates Maildir storage and standard subscribed folders
Changes passwords without exposing plaintext in command arguments
Creates aliases to real local mailboxes
Audits files, permissions, maps, Maildirs, configurations and lookups
Compiles Postfix hash maps before installing them
Locks concurrent changes
Creates root-only transaction backups before every write
Rolls failed transactions back and quarantines a partially created Maildir
Supports non-writing dry runs
Deliberately provides no destructive deletion command

Scope and assumptions

vmailctl does not install or configure a mail server. It manages one specific kind of existing setup:

GNU/Linux or a closely compatible POSIX system
Python 3.10 or newer
One Postfix virtual-mail domain
Postfix hash: mailbox and alias maps
Dovecot passwd-file passdb and userdb
Dovecot LMTP delivery into Maildir storage
A shared numeric UID and GID for virtual mail
Eight-field Dovecot passwd entries with userdb_mail_path=~/Maildir

The paths, domain, UID/GID, password scheme and standard folders are explicit configuration values. The example configuration follows common Debian-style paths but is not a universal default.

Quick start

Read INSTALL.md, adapt vmailctl.conf.example, and install:

sudo make install
sudoedit /etc/vmailctl.conf
sudo vmailctl audit

Preview a mailbox:

sudo vmailctl --dry-run mailbox add alice

Create it and enter its password at the protected terminal prompts:

sudo vmailctl mailbox add alice

Or generate a strong password, displayed once after successful creation:

sudo vmailctl mailbox add alice --generate-password

Create an alias that delivers to Alice's real mailbox:

sudo vmailctl alias add shopping alice

Other useful commands:

sudo vmailctl mailbox list
sudo vmailctl alias list
sudo vmailctl mailbox passwd alice
sudo vmailctl audit
man 8 vmailctl

Safety model

Every modifying operation:

Validates input, trusted-file metadata and address collisions.
Acquires an exclusive operation lock.
Re-reads the live state while holding the lock.
Creates a root-only backup of every file it may replace.
Prepares and compiles candidate Postfix maps.
Replaces files using same-filesystem temporary files.
Validates Postfix, Dovecot and the affected lookups.
Restores the previous files if validation fails.

If a failed mailbox transaction has created a Maildir, it is moved into the transaction backup rather than deleted. Routine service reloads are not required.

The configuration, mail data files, compiled maps and configured command executables must be real, root-owned files and must not be group- or world-writable. Their containing directories are also checked. The backup directory and lock file are restricted to root. Unsafe metadata causes the command to stop before it reads or changes the mail configuration.

This does not replace independent system backups. See SECURITY.md before installation.

Project links

Source: https://git.sdf.org/erici/vmailctl
Issues: https://git.sdf.org/erici/vmailctl/issues
Releases: https://git.sdf.org/erici/vmailctl/releases

Clone the repository over HTTPS:

git clone https://git.sdf.org/erici/vmailctl.git

Tests

The test suite uses temporary directories and fake mail commands; it does not need root and does not touch the host's mail configuration:

make check

If GNU groff is installed, make man-check also validates the manual page.

Development and provenance

The initial version was designed and developed by Eric Ireland with assistance from OpenAI Codex. All generated and suggested material was reviewed and tested before inclusion. Substantial automated assistance in future contributions should likewise be disclosed and human-reviewed.

Licence

vmailctl is free software licensed under the GNU General Public License, version 3 or (at your option) any later version. See COPYING.