vmail
Rebuild the Postfix and Dovecot mail maps (domains, mailboxes, aliases, passwords, relays, and filters) from GoAdmio's databases, then restart the mail services
- Command:
/go/vmail - Category: Mail
- Required arguments: None
- Output: Mostly silent. Only errors, a lock message, or
postfix checkwarnings are shown. - Last updated: 2026-11-20
On this page: Overview · Quick start · Syntax · Output · Examples · Troubleshooting · Details · Security notes · See also
Overview
GoAdmio keeps its mail accounts, domains, relay settings, and filters in databases. Postfix and Dovecot read plain files. /go/vmail turns the first into the second. It:
- rewrites the mail map files from scratch (domains, mailboxes, aliases, and login passwords)
- writes the SMTP relay logins and tests new relay credentials
- builds the spam-filter and subject-logging rules
- regenerates the Postfwd, Postfix, and Dovecot configuration
- restarts the mail services and runs
postfix check
Run it when mail data looks out of date, for example after changing mail data in the databases, or when a mailbox cannot log in or receive mail.
[!WARNING] This command changes data, not only files:
- it deletes mailbox rows whose address contains
*or has no@- it sets an empty mailbox password to
Go, which anyone can guess- it restarts the mail services, which briefly interrupts mail connections
The map files are emptied and refilled, so logins and mail delivery can fail for a short time while it runs. Run it at a quiet time.
Quick start
/go/vmail
Syntax
/go/vmail
The command takes no options. Anything you type after it is only written to the log.
Output
| Message | Meaning |
|---|---|
VMAIL: There are currently no active domains. |
The Site table is empty. Exit code 1. |
Instance (vmail) already running. |
Another run started within the last 15 minutes. Exit code 1. |
Messages from postfix check |
A problem with the Postfix configuration or its folder permissions. |
| Nothing | The run finished without errors. |
The command also prints package-install output the first time, if opendmarc or swaks has to be installed.
Examples
# Rebuild everything
/go/vmail
# Check the Postfix configuration afterwards
sudo postfix check
# See which domains Postfix now accepts mail for
cat /etc/postfix/vmail_domains
# Find mailboxes that were given the default password "Go"
sudo sqlite3 /var/lib/sqlite/mail.db "SELECT Email FROM Mail WHERE Pass='Go'"
# Check the status of the saved SMTP relays
sudo sqlite3 /var/lib/sqlite/smtp.db "SELECT SMTPHost, SMTPPort, SMTPStatus FROM SMTP"
# The relay file holds passwords. It should be readable by root only
ls -l /etc/postfix/vmail_sasl_passwd
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
There are currently no active domains. |
No account has been created. | Create one with create. |
Instance (vmail) already running. |
A run started within 15 minutes. A lock older than 15 minutes is ignored. | Wait. If no run is active and the message stays, check for a stuck process. |
| A mailbox cannot log in | It is suspended, its address does not look valid, or the domain has no /home/<domain>/mail folder. A | in the password also breaks the row. |
Fix the account, then run /go/vmail again. Check /etc/dovecot/passwd. |
A mailbox has the password Go |
Its password was empty in the database, and the command fills empty passwords with Go. |
Set a real password. For a whole domain see mailpwd. |
| A mailbox receives no mail | The address is missing from vmail_mailbox, or its domain is missing from vmail_domains. |
Check that the address is valid and /home/<domain>/mail exists, then run again. |
A wildcard address (*@...) disappeared |
Rows with * in the address are deleted on every run. |
Use the domain's default (catch-all) address instead. |
| A suspended mailbox still receives mail | Suspending removes the login only. The mailbox stays in the alias and mailbox maps. | This is expected. Delete the account to stop mail. |
A relay's status stays -1 |
Credentials are only tested on port 587, and only while the status is -1. |
Use port 587, or test the relay by hand. |
| A relay was removed | A relay whose host equals the server's own hostname is deleted on every run. | Use a different relay host. |
| Brief login or delivery failures during a run | The map files are emptied, then refilled. | Run at a quiet time. |
postfix check shows warnings |
A permission or configuration problem. | Fix what it reports. |
| Slow on a large server | Each mailbox password is hashed separately, and relays are tested one by one. | Wait for it to finish. |
Details
What it does
flowchart TD
A["/go/vmail"] --> B{"Any domains in Site?"}
B -- "No" --> C["Print message and exit"]
B -- "Yes" --> D["Install opendmarc and swaks if missing"]
D --> E["Remove relays that point to this server's own hostname"]
E --> F{"Lock under 15 minutes old?"}
F -- "Yes" --> G["Print message and exit"]
F -- "No" --> H["Create lock, regenerate Postfwd, Postfix, and Dovecot config"]
H --> I["Clean the Mail table"]
I --> J["Empty the map files and write headers"]
J --> K["Write global SMTP relays and test them"]
K --> L["Write mailboxes, aliases, and passwords"]
L --> M["Write domains, SSL, and per-domain relays"]
M --> N["Write filter rules"]
N --> O["Restart mail, run postfix check, remove lock"]
Steps in order
- Appends a timestamped line with the arguments to
/var/log/go/vmail.log. - Stops if the
Sitetable has no domains. - Installs OpenDMARC (with
installdmarc) andswaksif they are missing. - If the server's hostname contains a dot, deletes any relay (global or per site) that uses that hostname as its host, so the server never relays through itself.
- Works out the password hash for the internal account
goadmio@<hostname domain>. - Stops if a lock file was changed within the last 15 minutes. Otherwise creates the lock. It is removed when the command ends.
- Runs the helpers
/go/postfwd,/go/postconf, anddoveconfto regenerate the Postfwd, Postfix, and Dovecot configuration. - Cleans the
Mailtable (see Database changes). - Empties the map files and writes a comment line in each.
- Writes the global SMTP relay logins and tests the new ones.
- Writes the mailboxes, aliases, and passwords.
- Writes the domains, the SSL map, and the per-domain relays, and sets ownership of each domain's
mailfolder. - Writes the filter rules.
- Restarts the mail services with
/go/mail restart, runspostfix check, and removes the lock.
The hostname domain used in step 5 is the server's hostname without its first part, so mail.example.com gives example.com.
Files it writes
| File | Contents |
|---|---|
/etc/postfix/vmail_domains |
<domain> OK for each domain that has a mail folder |
/etc/postfix/vmail_aliases |
Each address and where its mail goes: its own mailbox, a forward, or a catch-all |
/etc/postfix/vmail_mailbox |
Each address and its folder, <domain>/mail/<user>/ |
/etc/dovecot/passwd |
Login password hashes for each address that is not suspended |
/etc/postfix/vmail_ssl |
For each domain with a Let's Encrypt certificate, smtp.<domain> with its key and certificate files |
/etc/postfix/vmail_relay |
The relay host for each domain that has its own SMTP relay |
/etc/postfix/vmail_sasl_passwd |
Relay logins: global relays first, then per-domain ones. Plain text. |
/etc/postfix/vmail_relayhost |
A comment line only. The command does not add anything else to it. |
/etc/postfix/vmail_body_checks |
Reject rules for message bodies |
/etc/postfix/vmail_header_checks |
Reject rules for subjects, plus a rule that logs every subject |
/etc/postfix/vmail_outgoing_header_checks |
A rule that logs the subject of outgoing mail |
The internal account goadmio@<hostname domain> is always written first.
How each address is routed
| Mailbox setting | Entry written in vmail_aliases |
|---|---|
| Default (catch-all) address | @<domain> <address>: all mail for the domain that has no other match goes here |
| Forward to another address, keep a copy | <address> <address>,<forward> |
| Forward to another address, no copy | <address> <forward> |
| None of these | <address> <address> |
An address is skipped, with no message, if it does not look like name@domain.tld (a top-level domain of at least two letters) or if /home/<domain>/mail does not exist.
Database changes
| Database | Change |
|---|---|
mail.db |
Deletes rows whose Email contains * or has no @. Sets Pass to Go where it is empty. |
smtp.db |
Deletes relays whose host equals the server's hostname. Updates SMTPStatus after a credential test. |
site.db |
Clears SMTPHost where it equals the server's hostname. Updates SMTPStatus after a credential test. |
Relay credential tests
A relay is tested only when its status is -1 (not tested yet) and its port is 587. The test connects with STARTTLS and logs in with swaks, then stops.
| Status | Meaning | Set when |
|---|---|---|
-1 |
Not tested | Default |
1 |
Login accepted | The answer contains 235 |
0 |
Login failed | The answer contains failed |
-2 |
Could not tell | Any other answer |
A relay with status 0 is still written to the relay files. The test only records the result.
Filter rules
| Filter type | Rule written |
|---|---|
| Body | /<keyword>/i REJECT <description> |
| Header | /^Subject:.*<keyword>/ REJECT <description>. Only the subject line is matched. |
Keywords are used as regular expressions, so special characters in them act as pattern characters. Repeated .*.* is shortened to .*. A final rule logs every subject to the mail log, which is what subjecttop reports on.
Notes
- The databases are read with
|as the field separator. A|inside a password or other value shifts the fields and corrupts that row. - If the Go SMTP settings file (
smtp.php) is missing, the internal account gets a new random password on every run, so nobody can log in to it. - The command reads some values it does not use here, such as the
SMTPAuthsetting and each mailbox's reject and admin fields. - The mail-management commands, such as
mail,mailpwd, andforward, change data in GoAdmio's databases. This command is what turns that data into the files Postfix and Dovecot read.
Security notes
| Item | Detail |
|---|---|
| Mailbox passwords | Stored as plain text in mail.db, and hashed with unsalted SHA-1 in /etc/dovecot/passwd. |
| Relay passwords | Written as plain text to /etc/postfix/vmail_sasl_passwd. Check that only root can read it. |
| Process list | Each password is passed to doveadm on the command line, so it can be seen briefly with ps. |
| Empty passwords | Become Go. Find them with the query in Examples and replace them. |
See also
| Command | Description |
|---|---|
mail |
Create an email address in GoAdmio via the command line |
mailpwd |
Bulk-change passwords for all email accounts of a single domain |
forward |
Configure per-domain email forwarding |
doveconf |
Rebuild the Dovecot configuration |
postfwd |
Build the Postfwd rate-limiting rules |
installdmarc |
Install and configure OpenDMARC |
troubleshoot |
Troubleshoot email problems in GoAdmio |
restoremail |
Recreate mail accounts from folders on disk |