167 lines
5.0 KiB
Markdown
167 lines
5.0 KiB
Markdown
# 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](INSTALL.md), adapt `vmailctl.conf.example`, and install:
|
|
|
|
```sh
|
|
sudo make install
|
|
sudoedit /etc/vmailctl.conf
|
|
sudo vmailctl audit
|
|
```
|
|
|
|
Preview a mailbox:
|
|
|
|
```sh
|
|
sudo vmailctl --dry-run mailbox add alice
|
|
```
|
|
|
|
Create it and enter its password at the protected terminal prompts:
|
|
|
|
```sh
|
|
sudo vmailctl mailbox add alice
|
|
```
|
|
|
|
Or generate a strong password, displayed once after successful creation:
|
|
|
|
```sh
|
|
sudo vmailctl mailbox add alice --generate-password
|
|
```
|
|
|
|
Create an alias that delivers to Alice's real mailbox:
|
|
|
|
```sh
|
|
sudo vmailctl alias add shopping alice
|
|
```
|
|
|
|
Other useful commands:
|
|
|
|
```sh
|
|
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](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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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`:
|
|
|
|
```sh
|
|
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](COPYING).
|