GoAdmio

vmail

Rebuild the Postfix and Dovecot mail maps (domains, mailboxes, aliases, passwords, relays, and filters) from GoAdmio's databases, then restart the mail services

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:

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

  1. Appends a timestamped line with the arguments to /var/log/go/vmail.log.
  2. Stops if the Site table has no domains.
  3. Installs OpenDMARC (with installdmarc) and swaks if they are missing.
  4. 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.
  5. Works out the password hash for the internal account goadmio@<hostname domain>.
  6. Stops if a lock file was changed within the last 15 minutes. Otherwise creates the lock. It is removed when the command ends.
  7. Runs the helpers /go/postfwd, /go/postconf, and doveconf to regenerate the Postfwd, Postfix, and Dovecot configuration.
  8. Cleans the Mail table (see Database changes).
  9. Empties the map files and writes a comment line in each.
  10. Writes the global SMTP relay logins and tests the new ones.
  11. Writes the mailboxes, aliases, and passwords.
  12. Writes the domains, the SSL map, and the per-domain relays, and sets ownership of each domain's mail folder.
  13. Writes the filter rules.
  14. Restarts the mail services with /go/mail restart, runs postfix 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


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