vmailctl/README.md

vmailctl

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:

1. Validates input, trusted-file metadata and address collisions.
2. Acquires an exclusive operation lock.
3. Re-reads the live state while holding the lock.
4. Creates a root-only backup of every file it may replace.
5. Prepares and compiles candidate Postfix maps.
6. Replaces files using same-filesystem temporary files.
7. Validates Postfix, Dovecot and the affected lookups.
8. 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.

Release archives

Maintainers can create a reproducible source archive and SHA-256 checksum from the annotated tag matching the version in vmailctl:

make dist

The files are written beneath dist/. The archive is generated from the tag, not the working tree, so an existing release cannot silently acquire later changes. This maintainer target requires Git, gzip, sha256sum, and GNU groff.

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

Copyright © 2026 Eric Ireland.

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