Back to the main page


Manage cmail users and per-user settings

This administration utility is used for creating and modifying users and their attributes for a cmail server system.

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/user 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 known to the system. Optionally, filter the list for entries matching expression. cmail-admin-user list %mpease%
add username [password] Create a new user and update the login credentials if supplied. User names must be unique. cmail-admin-user add mpease donotusethisasyourpassword
revoke user Reset the password for the specified user. This causes all login attempts for the user to be rejected. Note that the system will still accept mail on the users behalf, as revoke only invalidates the login credentials, not the account. cmail-admin-user revoke cbdev
password user [password] Update the password for the specified user to a new one. If none is supplied, the password is queried interactively. cmail-admin-user password mpease dontusethispassword
alias user [alias] Mark user as an alias for alias. This functionality enables alias to have multiple virtual passwords, thus allowing safe sharing of a mailbox. Take note that user will only be able to access mail stored to alias. This operation can be undone by not specifying the alias parameter. cmail-admin-user alias cbdev cdbev
userdb user [path] Have all mail stored for user be physically located in an SQLite database at path. The user database must conform to the schema outlined in the cmail developer documentation, such as databases created with cmail-admin-database. path should always be an absolute path, as the working directory of processes accessing the user databases is subject to change. User databases and the directory containing them must be read- and writable by the user running the cmail daemons. This change can be undone by not specifying path. Note that mail stored in a user database that is no longer known to the system can not be retrieved via the cmail suite. cmail-admin-user userdb cbdev /home/cbdev/mail.db3
delete user Delete user from the system. Take note that all mail belonging to this user will be lost. cmail-admin-user delete cbdev