321 lines
8.4 KiB
Plaintext
321 lines
8.4 KiB
Plaintext
.\" SPDX-FileCopyrightText: 2026 Eric Ireland
|
|
.\" SPDX-License-Identifier: GPL-3.0-or-later
|
|
.TH VMAILCTL 8 "26 July 2026" "vmailctl 0.1.0" "System Administration Commands"
|
|
.SH NAME
|
|
vmailctl \- manage flat-file Postfix and Dovecot virtual mailboxes
|
|
.SH SYNOPSIS
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.B audit
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.B mailbox list
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.RB [ \-\-dry\-run ]
|
|
.B mailbox add
|
|
.I address
|
|
.RB [ \-\-generate\-password ]
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.RB [ \-\-dry\-run ]
|
|
.B mailbox passwd
|
|
.I address
|
|
.RB [ \-\-generate\-password ]
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.B alias list
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-config
|
|
.IR file ]
|
|
.RB [ \-\-dry\-run ]
|
|
.B alias add
|
|
.I alias target
|
|
.PP
|
|
.B vmailctl
|
|
.RB [ \-\-help ]
|
|
.RB [ \-\-version ]
|
|
.SH DESCRIPTION
|
|
.B vmailctl
|
|
is a root-only administration command for a small Postfix and Dovecot
|
|
virtual-mail setup that uses flat text files and compiled Postfix hash maps.
|
|
It creates mailbox logins, changes mailbox passwords, creates aliases, lists
|
|
the current configuration, and audits the complete setup.
|
|
.PP
|
|
The domain is selected in the configuration file.
|
|
An address may be supplied either as a local part, such as
|
|
.BR alice ,
|
|
or as a complete address in that domain, such as
|
|
.BR alice@example.com .
|
|
Input is normalised to lowercase.
|
|
.PP
|
|
Mailbox passwords are hashed by
|
|
.BR doveadm (1)
|
|
using ARGON2ID.
|
|
Plaintext passwords are passed to
|
|
.B doveadm
|
|
through standard input and are never placed in command arguments or written
|
|
to configuration files.
|
|
.PP
|
|
The command does not provide mailbox or alias deletion.
|
|
.SH GLOBAL OPTIONS
|
|
.TP
|
|
.BI \-\-config " file"
|
|
Read configuration from
|
|
.I file
|
|
instead of
|
|
.IR /etc/vmailctl.conf .
|
|
.TP
|
|
.B \-\-dry\-run
|
|
Validate a proposed mailbox or alias change and describe the resulting
|
|
actions without prompting for a password or writing any files.
|
|
This option is meaningful only with
|
|
.BR "mailbox add" ,
|
|
.BR "mailbox passwd" ,
|
|
and
|
|
.BR "alias add" .
|
|
.TP
|
|
.B \-\-version
|
|
Print the program version and exit.
|
|
.TP
|
|
.BR \-h ", " \-\-help
|
|
Print usage information and exit.
|
|
Help is also available after the
|
|
.B mailbox
|
|
and
|
|
.B alias
|
|
subcommands.
|
|
.SH COMMANDS
|
|
.SS audit
|
|
Parse the Dovecot passwd file and both Postfix maps, check ownership and
|
|
permissions, detect duplicate or conflicting entries, inspect Maildir paths,
|
|
compare source and compiled map timestamps, validate the Postfix and Dovecot
|
|
configurations, and test every configured lookup.
|
|
.PP
|
|
Consistent compatibility entries that occur in both the alias map and the
|
|
direct-delivery map are reported as information rather than errors.
|
|
The audit makes no changes.
|
|
.SS mailbox list
|
|
List all addresses that have a Dovecot mailbox login and print the total.
|
|
.SS mailbox add address
|
|
Create a mailbox login and its matching Postfix delivery mapping.
|
|
The command creates the Maildir and its
|
|
.BR cur ,
|
|
.BR new ,
|
|
and
|
|
.B tmp
|
|
directories, then creates and subscribes the standard
|
|
.BR Archive ,
|
|
.BR Drafts ,
|
|
.BR Sent ,
|
|
.BR Trash ,
|
|
and
|
|
.B Junk
|
|
folders.
|
|
.PP
|
|
Unless
|
|
.B \-\-generate\-password
|
|
is specified, the new password is read twice from the controlling terminal.
|
|
It must contain at least 12 characters.
|
|
.TP
|
|
.B \-\-generate\-password
|
|
Generate a 24-character password with the system cryptographic random-number
|
|
generator.
|
|
The password is displayed once, and only after the transaction succeeds.
|
|
.SS mailbox passwd address
|
|
Replace the password hash for an existing Dovecot mailbox login without
|
|
altering its user database fields or Maildir.
|
|
Password entry and
|
|
.B \-\-generate\-password
|
|
behave as described for
|
|
.BR "mailbox add" .
|
|
.SS alias list
|
|
List the entries in the Postfix virtual alias map and print the total.
|
|
.SS alias add alias target
|
|
Create
|
|
.I alias
|
|
as a new address delivering to
|
|
.IR target .
|
|
The target must be a real mailbox in the configured Postfix mailbox map;
|
|
alias-to-alias chains are not created.
|
|
.SH ADDRESS RULES
|
|
Local parts may contain lowercase ASCII letters, digits, dots, underscores,
|
|
and hyphens.
|
|
They must begin with a letter or digit, may not end with a dot, and may not
|
|
contain consecutive dots.
|
|
They are limited to 63 characters.
|
|
.PP
|
|
A plus sign is rejected because plus addressing is handled by Postfix's
|
|
recipient delimiter and does not represent a separate mailbox.
|
|
Addresses in domains other than the configured domain are rejected.
|
|
The configured domain must be a conventional dotted ASCII DNS name.
|
|
.PP
|
|
A new address must not already occur in the Dovecot user file, Postfix
|
|
mailbox map, or Postfix alias map.
|
|
.SH TRANSACTIONS AND RECOVERY
|
|
Every modifying command takes an exclusive lock before re-reading and
|
|
changing the live files.
|
|
Before a write, it creates a timestamped, root-only backup beneath
|
|
.IR /var/backups/vmailctl .
|
|
.PP
|
|
Text files are replaced using temporary files in the destination directory.
|
|
Postfix hash-map candidates are compiled before they replace the live source
|
|
and database files.
|
|
The command then validates the service configurations and the affected
|
|
lookups.
|
|
No routine Postfix or Dovecot reload is required.
|
|
.PP
|
|
If validation fails, the previous files and compiled maps are restored.
|
|
The same rollback is attempted if the operation is interrupted from the
|
|
terminal.
|
|
When a failed mailbox creation has already made a Maildir, that Maildir is
|
|
moved into the transaction backup as
|
|
.B rolled-back-mailhome
|
|
instead of being deleted.
|
|
.SH SECURITY
|
|
.B vmailctl
|
|
must run as root.
|
|
The installed program is root-owned, and its lock and transaction backups
|
|
are accessible only to root.
|
|
.PP
|
|
The configuration, Dovecot users file, Postfix source and compiled maps, and
|
|
configured command executables must be real, root-owned files.
|
|
Symbolic links and group- or world-writable files are rejected.
|
|
Their containing directories must be root-owned and must not be writable by
|
|
untrusted users.
|
|
The configured command paths must name regular executable files rather than
|
|
symbolic links.
|
|
.PP
|
|
The standard folder list rejects option-like names, path separators, control
|
|
characters, and duplicates before any invocation of
|
|
.BR doveadm (1).
|
|
.PP
|
|
Interactive passwords are not echoed.
|
|
Generated passwords are printed to standard output once; use them only from
|
|
a trusted terminal and take care when terminal output is recorded.
|
|
Transaction backups contain Dovecot password hashes and must remain
|
|
root-only.
|
|
.SH FILES
|
|
.TP
|
|
.I /etc/vmailctl.conf
|
|
Non-secret configuration: domain, data paths, mail UID and GID, password
|
|
scheme, standard folders, command paths, backup directory, lock path, and
|
|
Maildir mode.
|
|
It must be a root-owned regular file, must not be group- or world-writable,
|
|
and must not be a symbolic link.
|
|
.TP
|
|
.I /usr/local/sbin/vmailctl
|
|
Installed administration command.
|
|
.TP
|
|
.I /etc/dovecot/virtual-users
|
|
Dovecot passwd-file user and password database.
|
|
.TP
|
|
.I /etc/postfix/vmailbox
|
|
Postfix virtual mailbox source map.
|
|
.TP
|
|
.I /etc/postfix/vmailbox.db
|
|
Compiled Postfix virtual mailbox hash map.
|
|
.TP
|
|
.I /etc/postfix/virtual
|
|
Postfix virtual alias source map.
|
|
.TP
|
|
.I /etc/postfix/virtual.db
|
|
Compiled Postfix virtual alias hash map.
|
|
.TP
|
|
.I /var/mail/vhosts/domain
|
|
Mailbox home hierarchy, where
|
|
.I domain
|
|
is the configured virtual-mail domain.
|
|
.TP
|
|
.I /var/backups/vmailctl
|
|
Root-only transaction backups.
|
|
.TP
|
|
.I /run/lock/vmailctl.lock
|
|
Exclusive operation lock.
|
|
.SH EXIT STATUS
|
|
.TP
|
|
.B 0
|
|
The command completed successfully.
|
|
.TP
|
|
.B 1
|
|
An operational, validation, configuration, or transaction error occurred.
|
|
.TP
|
|
.B 2
|
|
The command-line syntax was invalid, or
|
|
.B audit
|
|
found one or more configuration errors.
|
|
.TP
|
|
.B 130
|
|
The operation was interrupted from the terminal.
|
|
.SH EXAMPLES
|
|
Audit the current mail configuration:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl audit
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Preview a new mailbox without prompting or writing:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl \-\-dry\-run mailbox add alice
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Create a mailbox and enter its password securely:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl mailbox add alice
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Create a service mailbox with a generated password:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl mailbox add notifications \-\-generate\-password
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Change a password:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl mailbox passwd alice
|
|
.EE
|
|
.RE
|
|
.PP
|
|
Deliver another address into Alice's mailbox:
|
|
.PP
|
|
.RS
|
|
.EX
|
|
sudo vmailctl alias add shopping alice
|
|
.EE
|
|
.RE
|
|
.SH SEE ALSO
|
|
.BR doveadm (1),
|
|
.BR doveconf (1),
|
|
.BR postfix (1),
|
|
.BR postmap (1),
|
|
.BR virtual (5)
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2026 Eric Ireland.
|
|
.PP
|
|
This program is free software: you can redistribute it and/or modify it under
|
|
the terms of the GNU General Public License as published by the Free Software
|
|
Foundation, either version 3 of the License, or (at your option) any later
|
|
version.
|