-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathstepbystep.htm
333 lines (312 loc) · 11.9 KB
/
stepbystep.htm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>cmail: Step-by-step setup</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="icon" href="static/cmail_logo.png" type="image/x-icon" />
<link rel="shortcut icon" href="static/cmail_logo.png" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="static/cmail.css" />
<meta name="description" content="cmail - Internet mail processing suite with SQLite backend" />
<meta name="keywords" content="cmail, smtp, email, pop, webmail, messaging, setup from source, step by step" />
<meta name="robots" content="index,follow" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<div>
<a href="index.htm">Back</a> to the main page
</div>
<div>
<h1>Step by step setup</h1>
<p>
This page details the process of installing and configuring
a functional cmail server. Please note that running your own email server is a
nontrivial commitment to keeping that service up and running in order to allow people
to reach you. It may be useful to run at least two physically separate mail servers for redundancy.
</p>
</div>
<div class="section">
<h2>0 Setting up your domain</h2>
<p>
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).
</p>
<p>
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 <a href="https://en.wikipedia.org/wiki/MX_record">
<em>MX record</em></a> in its DNS table. The server responsible for your domains DNS is most often
configurable by some kind of panel at your registrar.
</p>
<p>
An <em>MX record</em> 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.
</p>
<p>
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.
</p>
</div>
<div class="section">
<h2>1a Setup from packages</h2>
<p>
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.
</p>
</div>
<div class="section">
<h2>1b Setup from source</h2>
<i>(Examples given for debian-based systems)</i>
<p>
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.
</p>
<p>
<code style="display:block;">
~# apt-get install libsqlite3-dev nettle-dev libgnutls28-dev libadns1-dev
</code>
</p>
<p>
Additionally, we're going to install some tools needed for initial setup operations.
</p>
<p>
<code style="display:block;">
~# apt-get install sqlite3<br/>
~# apt-get install openssl<br/>
</code>
</p>
<p>
Next, we'll clone the cmail repository to the disk
</p>
<p>
<code style="display:block;">
~# git clone https://github.com/cmail-mta/cmail
</code>
</p>
<p>
In the cloned directory, run <code>make</code> to build all modules, followed
by <code>make install</code> to copy the binaries to a system path (by default
<code>/usr/sbin/</code>, this may be changed by supplying the environment variable
<code>PREFIX</code>). The system documentation, available with
<code>man <em><component></em></code> is installed by running
<code>make install-doc</code>.
</p>
<p>
Running <code>make init</code> 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 <code>make tls-init</code> 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.
</p>
<p>
<code style="display:block;">
~# cd cmail<br/>
~/cmail# make<br/>
~/cmail# make install<br/>
~/cmail# make install-doc<br/>
~/cmail# make tls-init
</code>
</p>
<p>
<strong>Advanced users</strong> may specify some parameters to the makefile install process via environment
variables. Currently, these are:
<table border>
<tr>
<td><code>PREFIX</code></td>
<td>Installation prefix</td>
</tr>
<tr>
<td><code>DOCDIR</code></td>
<td>Path to install generated manpages to</td>
</tr>
<tr>
<td><code>LOGDIR</code></td>
<td>Path to store logfiles</td>
</tr>
<tr>
<td><code>CONFDIR</code></td>
<td>Path for configuration files</td>
</tr>
<tr>
<td><code>DBDIR</code></td>
<td>Path for master database file</td>
</tr>
<tr>
<td><code>BANNER</code></td>
<td>Announce banner</td>
</tr>
</table>
</p>
<p>
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.
</p>
<p>
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 <code>startup-scripts/</code> for systemd and sysvinit.
Check the documentation for your system to find out how to install these files.
</p>
</div>
<div class="section">
<h2>2 Check the generated configuration files</h2>
For most distributions, you can find these under <code>/etc/cmail/</code>. Read them carefully to verify
the system is configured the way you want it.
<p>
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
<code>example-configs/</code> folder in the repository.
</p>
<p>
Make sure to check the <code>announce</code> parameters to the <code>bind</code> directives.
Most install processes will set those to your current hostname.
</p>
<p>
Also make sure to replace the TLS key material generated by <code>make tls-init</code> with properly
signed and trusted keys.
</p>
</div>
<div class="section">
<h2>2a Test the configuration</h2>
This step might not be needed when installing from source, but it is nevertheless useful for learning
how to debug your mail server.
<p>
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 <code>Ctrl-C</code>.
<p>
<code style="display:block;">
~# cmail-smtpd nodetach /etc/cmail/smtpd.conf<br/>
~# cmail-popd nodetach /etc/cmail/popd.conf<br/>
~# cmail-dispatchd nodetach /etc/cmail/dispatchd.conf<br/>
</code>
</p>
</p>
<p>
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
<code>verbosity</code> parameter in the configuration files.
</p>
<p>
<h3>Common problems</h3>
<ul>
<li>
<strong>"Could not bind to port 25"</strong><br/>
There might already be an MTA installed on your system (such as exim or
OpenSMTPd). List all currently bound listening sockets with
<p>
<code style="display:block;">
~# ss -lt
</code>
</p>
To find out what program is using the port, run
<p>
<code style="display:block;">
~# lsof | grep TCP
</code>
</p>
To solve this problem, uninstall the conflicting program with
e.g
<p>
<code style="display:block;">
~# apt-get uninstall exim4*
</code>
</p>
</li>
<li>
<strong>No connection to the services from remote hosts</strong><br />
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
<p>
<code>
~# tcptraceroute <em>your-server</em> 25
</code>
</p>
from another computer and find out where the trace stops.
</li>
</ul>
</p>
</div>
<div class="section">
<h2>3 Set up the master database</h2>
cmail uses <a href="https://sqlite.org/">SQLite</a>, 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.
<p>
<h3>Relevant tools:</h3>
<a href="admin/user.htm">cmail-admin-user</a>,
<a href="admin/address.htm">cmail-admin-address</a>,
<a href="admin/smtpd.htm">cmail-admin-smtpd</a>,
<a href="admin/popd.htm">cmail-admin-popd</a>
</p>
</div>
<div class="section">
<h2>4 Testing the server</h2>
This section describes some steps you can take to confirm your server is operating
correctly.
<p>
<h3>Testing socket level connectivity (using gnutls-cli)</h3>
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.
<p>
<code style="display:block;">
~# gnutls-cli --starttls --insecure --crlf --port <em><port></em> <em><host></em>
</code>
</p>
Watch for the following prompts:
<ul>
<li><strong>SMTP</strong>: 220 <em><banner></em> ESMTP service ready</li>
<li><strong>POP3</strong>: +OK <em><banner></em> POP3 ready</li>
</ul>
For <code>tlsonly</code> ports you may need to press <code>Ctrl-D</code> once to
start TLS negotiation. A second <code>Ctrl-D</code> will close the connection.
</p>
<p>
<h3>Testing protocol level operation (using swaks)</h3>
<code>swaks</code> is a tool used for testing mail server operation by simply sending
test mails. Run the tool from another host with
<p>
<code style="display:block;">
~# swaks --from [email protected] --to <em><recipient></em> --server <em><host></em>
</code>
</p>
The recipient account should now have a new message.
</p>
<p>
<h3>Testing operation using your email client</h3>
Configure your email client to use your new server for receiving and sending and send some
test emails ;)
</p>
<p>
<h3>Common problems</h3>
<ul>
<li>
<strong>No connection from outside to port 25 (or any other ports)</strong><br/>
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
<p>
<code style="display:block;">
~# ss -lt
</code>
</p>
and check your local firewall rules with
<p>
<code style="display:block;">
~# iptables -L -v
</code>
</p>
</li>
</ul>
</p>
</div>
<div class="section">
<h2>Upgrading your installation</h2>
Please refer to the <a href="upgrading.htm">upgrade guide</a>.
</div>
</body>
</html>