# 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).