# Installing vmailctl

`vmailctl` manages an existing Postfix/Dovecot flat-file virtual-mail setup. Do
not install it until the live configuration matches the documented assumptions.

## Requirements

- Python 3.10 or newer
- Postfix with `postmap` and `hash:` map support
- Dovecot with `doveadm`, `doveconf`, passwd-file authentication and Maildir
- Root access
- GNU `make`, `install`, `gzip` and `mandb` for the provided installation target

The example paths suit many Debian-family systems. Other systems may place the
commands or manual hierarchy elsewhere.

## Verify the existing mail layout

The Dovecot users file must contain exactly eight colon-separated fields per
account:

```text
user@example.com:{SCHEME}HASH:5000:5000::/var/mail/vhosts/example.com/user::userdb_mail_path=~/Maildir
```

The Postfix mailbox source map must use two whitespace-separated fields:

```text
user@example.com example.com/user/Maildir/
```

The Postfix alias source map must likewise use two fields:

```text
alias@example.com user@example.com
```

Both Postfix maps must be configured as `hash:` maps. The corresponding `.db`
files should already exist and match their sources.

Before installation, make an independent backup of:

```text
/etc/dovecot/virtual-users
/etc/postfix/vmailbox
/etc/postfix/vmailbox.db
/etc/postfix/virtual
/etc/postfix/virtual.db
/var/mail/vhosts
```

Adapt that list if your paths differ.

## Configure

Review `vmailctl.conf.example`. At minimum, set:

- `domain`
- `dovecot_users`
- `postfix_mailboxes`
- `postfix_aliases`
- `mail_root`
- `uid` and `gid`
- the paths to `postmap`, `postfix`, `doveadm` and `doveconf`

The UID and GID must match the virtual-mail owner already used by Dovecot.
`hash_scheme` must appear in `doveadm pw -l`; ARGON2ID is recommended where
supported.

The configuration, Dovecot users file, Postfix source maps and compiled
`.db` maps must be regular root-owned files, not symbolic links, and must not
be group- or world-writable. Their containing directories must be
root-owned and not writable by untrusted users. The configured command paths
must likewise name root-owned regular executable files in trusted
directories. If a distribution exposes a command through a symbolic link,
configure its resolved real path instead (for example, obtain it with
`readlink -f /path/to/command`).

The configured domain directory beneath `mail_root` may be owned either by
root or by the configured virtual-mail UID/GID. It must be a real directory
and must not be world-writable. `backup_dir` is created as a root-only `0700`
directory when its parent is trusted; the lock is maintained as a root-only
regular file.

## Install with make

```sh
sudo make install
```

The installation target:

- installs `vmailctl` as `/usr/local/sbin/vmailctl`
- installs the man page beneath `/usr/local/share/man/man8`
- creates `/var/backups/vmailctl` with mode `0700`
- installs `/etc/vmailctl.conf` only when that file does not already exist
- refreshes the manual database when `mandb` is available

It deliberately does not overwrite an existing configuration.

For packaging or staged installation, set `DESTDIR`. Installation locations may
also be adjusted with `PREFIX` and `SYSCONFDIR`:

```sh
make DESTDIR=/tmp/package-root install
```

## Validate

Inspect the installed configuration:

```sh
sudo chown root:root /etc/vmailctl.conf
sudo chmod 0644 /etc/vmailctl.conf
sudoedit /etc/vmailctl.conf
sudo vmailctl audit
```

Do not proceed until the audit reports no errors. Warnings should be understood
before making changes.

Then exercise dry-run paths:

```sh
sudo vmailctl --dry-run mailbox add test-account
sudo vmailctl --dry-run alias add test-alias existing-mailbox
```

Read the complete manual:

```sh
man 8 vmailctl
```

## Manual installation

If `make install` is unsuitable, copy the files with equivalent ownership and
permissions:

```sh
sudo install -o root -g root -m 0755 vmailctl /usr/local/sbin/vmailctl
sudo install -o root -g root -m 0644 vmailctl.conf.example /etc/vmailctl.conf
sudo install -d -o root -g root -m 0700 /var/backups/vmailctl
sudo install -d -o root -g root -m 0755 /usr/local/share/man/man8
sudo install -o root -g root -m 0644 man/vmailctl.8 \
  /usr/local/share/man/man8/vmailctl.8
sudo gzip -n -9 -f /usr/local/share/man/man8/vmailctl.8
sudo mandb -q
```

Do not copy the example configuration over an existing customised
`/etc/vmailctl.conf`.

## Updating

Back up the installed program and configuration, run the new version's tests,
review `CHANGELOG.md`, and replace the executable and man page. Preserve and
compare `/etc/vmailctl.conf` rather than replacing it automatically.

There is intentionally no automated uninstall target. Removing a root mail
administration tool should be a deliberate manual operation; transaction
backups and mail data are never removed automatically.