Back to the main page


Configure SMTP daemon authentication and outbound mail handling

Manage user authentication against the SMTP daemon and configure how originated mail (mail that is being sent by a local, authenticated user) is handled.

Building & Prerequisites

The following packages are required for building this utility (Debian packages are listed) A build of only this specific binary can be initiated by running make from within cmail-admin/smtpd in the main repository. A build of all administration utilities may be initiated by running make from within cmail-admin/.

Setup information

The utility is automatically installed to a location accessible by the administrator with the make install step of the installation (/usr/sbin/ by default).


This utility needs read and write access to the master database AS WELL AS the folder containing it. The location of the master database file is assumed to be /etc/cmail/databases/master.db3 by default and can be overridden by specifying either the --dbpath command line option or the CMAIL_MASTER_DB environment variable when running this utility.

Specifying the --help argument to an invocation prints additional information about the utility.

The cmail-admin utilities operate in one of several modes, as specified in the table below. Modes may optionally accept mode-specific arguments. Changes in cmail configuration databases become active immediately, requiring no restart of the system.

Modes of operation

Mode Arguments
variable [optional] verbatim
Description Example
list [expression] List all users currently able to authenticate with the SMTP daemon. Optionally, filter the list for entries matching expression. cmail-admin-smtpd list mpease%
enable username [router [router-argument]] Allow username to authenticate with the SMTP daemon. Users must exist and have valid login credentials to successfully authenticate. User management tasks may for example be performed with cmail-admin-user. See below for a table of valid router values. cmail-admin-smtpd enable cbdev any
update user router [router-argument] Update an existing entry in the access control list with new routing data. cmail-admin-smtpd update cbdev reject "No more mail, please"
disable user Remove a user from the ACL. Note that this does not prevent the user from receiving mail, only from authenticating with the SMTP daemon and originating it. cmail-admin-smtpd disable cbdev

Outbound routers

Outbound routers are filters limiting the paths which a user may use as reverse paths in originated mails (that is, they limit the addresses a user may send from).
Router Arguments Description
any Accept any reverse path.
defined Accept only reverse paths that have a store router pointing back to the authorized user. Note that while there needs to be a store router set to the user, it need not be the one actually taken when the path is routed inbound (that is, an outbound path may be allowed to multiple users, while the inbound mail for that path can only go to one).
handoff remote-spec Have originated mail by this user handled by another SMTP server (smarthost). This effectively relays the entire envelope section verbatim to the remote server. If the remote-spec is not set, this router behaves the same way as the drop router. If the remote-spec is invalid, the outbound SMTP client will generate a bounce notification message after a configured amount of retries.

A remote-spec must consist of a host name, optionally prefixed by authentication information in the form user:password@hostname and optionally trailed by a non-default port and TLS mode specification of the form hostname:port/tlsmode. tlsmode must be one of none (default), starttls or tlsonly. When a remote port is specified, only that port is connected to and any additional ports configured in the cmail-dispatchd configuration are ignored for that remote.

The optional parts of a remote-spec may be combined, for example to form
reject [reason] Reject any reverse path (SMTP 551), optionally presenting reason as failure reason.
drop Accept any reverse path, but quietly drop all originated mail for this user.