Step by step setup

0 Setting up your domain

Depending on your experience and requirements, this may either be the first step to perform (if you are configuring a fresh domain) or the last (if you are moving an existing domain or already are experienced with running mail servers).

In order to announce to the rest of the world that any particular server on the internet should receive mail for a domain, that domain needs to have a so-called MX record in its DNS table. The server responsible for your domains DNS is most often configurable by some kind of panel at your registrar.

An MX record contains the IP addresses or hostnames of one or more servers that will be connected to by other mail servers trying to send you mail. These records are ordered, so that if one of them should fail another one is automatically tried.

In order to properly receive mail adressed to your domain, you will have to set up these records to point at the machine running your upcoming cmail installation.

1a Setup from packages

Install the package with your package manager of choice (eg. dpkg, pacman). Depending on the package maintainer, this process may already run a dialog of some sorts querying basic configuration information.

1b Setup from source

(Examples given for debian-based systems)

We're going to assume the system already sports a working C compiler as well as the git version control system. First, we're going to install the build prerequisites.

~# apt-get install libsqlite3-dev nettle-dev libgnutls28-dev libadns1-dev

Additionally, we're going to install some tools needed for initial setup operations.

~# apt-get install sqlite3
~# apt-get install openssl


Next, we'll clone the cmail repository to the disk

~# git clone https://github.com/cmail-mta/cmail

In the cloned directory, run make to build all modules, followed by make install to copy the binaries to a system path (by default /usr/sbin/, this may be changed by supplying the environment variable PREFIX). The system documentation, available with man <component> is installed by running make install-doc.

Running make init after this step will create a new user for cmail (in order to minimize attack surface, cmail is not usually run as root and instead drops its privileges after initialization), copy over default configuration files, correctly set privileges and generally set up the basic structure needed for operation. Alternatively, the make tls-init command does all that and also generates a temporary TLS certificate and key for initial usage and testing (openssl required). Please remember to replace the generated key and certificate with secure ones when using this option.

~# cd cmail
~/cmail# make
~/cmail# make install
~/cmail# make install-doc
~/cmail# make tls-init

Advanced users may specify some parameters to the makefile install process via environment variables. Currently, these are:

PREFIX	Installation prefix
DOCDIR	Path to install generated manpages to
LOGDIR	Path to store logfiles
CONFDIR	Path for configuration files
DBDIR	Path for master database file
BANNER	Announce banner

After these steps, the core cmail binaries as well as the administration tool suite will have been installed. Should you prefer using the web administration interface to the command line tools, the HTTP API and web panel need to be installed additionally.

In order to have cmail start up at boot time, your init system may need specific files (such as service files or init scripts). Example files are provided in startup-scripts/ for systemd and sysvinit. Check the documentation for your system to find out how to install these files.

2 Check the generated configuration files

For most distributions, you can find these under /etc/cmail/. Read them carefully to verify the system is configured the way you want it.

If your setup method did not automatically create the configuration files for you (or you did not want to use the provided setup mechanisms), you may also copy over example configuration files to modify from the example-configs/ folder in the repository.

Make sure to check the announce parameters to the bind directives. Most install processes will set those to your current hostname.

Also make sure to replace the TLS key material generated by make tls-init with properly signed and trusted keys.

2a Test the configuration

This step might not be needed when installing from source, but it is nevertheless useful for learning how to debug your mail server.

To do this, run the daemons one by one without having them detach from the console, so you can see their debug information printed. After verifying that the configuration works, exit the daemons again by pressing Ctrl-C.

~# cmail-smtpd nodetach /etc/cmail/smtpd.conf
~# cmail-popd nodetach /etc/cmail/popd.conf
~# cmail-dispatchd nodetach /etc/cmail/dispatchd.conf


After this step, you may want to turn down the verbosity of the cmail services so they do not log as much information as they would by default. This can be done by decreasing the verbosity parameter in the configuration files.

Common problems

• "Could not bind to port 25"
  There might already be an MTA installed on your system (such as exim or OpenSMTPd). List all currently bound listening sockets with

  ~# ss -lt

  To find out what program is using the port, run

  ~# lsof | grep TCP

  To solve this problem, uninstall the conflicting program with e.g

  ~# apt-get uninstall exim4*

• No connection to the services from remote hosts
  Be sure to configure your firewall (and in some cases, your provider's firewall) to allow connections on the cmail service ports. Try running the command

  ~# tcptraceroute your-server 25

  from another computer and find out where the trace stops.

3 Set up the master database

cmail uses SQLite, a file-based database to store most of its running configuration and data. Administration of a running cmail server can either be performed by using the cmail-admin suite of command line tools or by using the HTTP API and web panel.

Relevant tools:

cmail-admin-user, cmail-admin-address, cmail-admin-smtpd, cmail-admin-popd

4 Testing the server

This section describes some steps you can take to confirm your server is operating correctly.

Testing socket level connectivity (using gnutls-cli)

To confirm your server is responding to connections from the outside world, run the following command from another host for each relevant port and confirm you see a prompt.

~# gnutls-cli --starttls --insecure --crlf --port <port> <host>

Watch for the following prompts:

• SMTP: 220 <banner> ESMTP service ready
• POP3: +OK <banner> POP3 ready

For tlsonly ports you may need to press Ctrl-D once to start TLS negotiation. A second Ctrl-D will close the connection.

Testing protocol level operation (using swaks)

swaks is a tool used for testing mail server operation by simply sending test mails. Run the tool from another host with

~# swaks --from foo@bar.baz --to <recipient> --server <host>

The recipient account should now have a new message.

Testing operation using your email client

Configure your email client to use your new server for receiving and sending and send some test emails ;)

Common problems

• No connection from outside to port 25 (or any other ports)
  Some providers may configure servers with a default firewall blocking access to certain ports. Make sure your server is listening on the relevant ports with

  ~# ss -lt

  and check your local firewall rules with

  ~# iptables -L -v

Upgrading your installation

Please refer to the upgrade guide.