2
$Id: README.Debian 229 2005-12-08 23:26:29Z astronut $
5
"All systems administrators have their horror stories. For me, it was
6
setting up a HP Color Bubblejet under Linux using ghostscript before
7
linuxprinting.org was alive. Well that was a piece of cake compared
8
to what I am about to describe in this document."
9
-- "Hosting email for virtual domains using Postfix and Cyrus"
10
Haim Dimermanas, 2001-08-01
12
"I warned you to read all the documentation first, didn't I?"
13
-- Henrique M. Holschuh, 2002-10-01
15
IMPORTANT: Cyrus is a closed-box email system. Your system will access your
16
email through LMTP, IMAP and POP3 *only*. No direct file access to the email
17
store is supposed to take place.
19
For more information, please consult http://asg.web.cmu.edu/cyrus/imapd/ and
20
http://asg.web.cmu.edu/twiki/bin/view/Cyrus/WebHome (Cyrus WiKi). There is
21
also Cyrus-HOWTO (Cyrus-IMAP.txt) available as part of the LDP HOWTO
22
collection. Upgrade hints are in UPGRADE.Debian. Outdated documentation will
23
cause you much grief, so beware of that when hunting anywhere else than the
24
Cyrus mailinglist for information.
26
Information about updated packages for Debian stable (i.e. of updates that
27
are not necessarily security updates) is available at
28
http://people.debian.org/~hmh/
30
WARNING: For one to get Cyrus IMAPd to work correctly, one must first get the
31
SASL layer to work correctly. This is far from trivial, so if you don't manage
32
at first, don't go around filling bugs against Cyrus IMAPd before you make damn
33
sure it is not a SASL configuration error. Read the hint list later on this
34
file as well. Start by reading README.Debian.simpleinstall.
36
The Debian packaging of Cyrus has a few quirks which are important to know
39
1. Renaming of some Cyrus IMAP utilities
41
The quota, reconstruct, master and deliver utilities have been renamed to
42
cyrquota, cyrreconstruct, cyrmaster and cyrdeliver, following the template
43
set by upstream with "cyradm". This was done because both Cyrus Debian
44
maintainers found the original names to be too generic and likely to cause
45
namespace collisions later.
47
Since documentation may refer to these utilities using their original
48
name, you must be aware of this fact. Also, installsieve is deprecated
49
and not included in the Debian package; use sieveshell instead.
51
2. Relocation of many Cyrus IMAP files
53
The default Cyrus install scatters files all over the place. The Debian
54
package installs only a few files in /usr/bin (cyradm, sieveshell).
55
IMAP/email administrator utilities are installed in /usr/sbin (such as
56
cyrreconstruct). Programs that must be run by cyrmaster are installed in
57
/usr/lib/cyrus (such as imapd and pop3d). Sockets go into
58
/var/run/cyrus/socket, per FHS 2.2. Sieve files go in /var/spool/sieve, but
59
an /etc/sieve compatibility symlink is also installed just in case.
61
The imapd.conf and cyrus.conf configuration files are in /etc. The PAM
62
policy files are in /etc/pam.d.
64
Feel free to use dpkg-statoverride to change the permission of
65
/var/run/cyrus/socket, the cyrus packages will not override your
66
configuration if dpkg-statoverride is used. In fact, you will most probably
67
have to do so for postfix to deliver to Cyrus, for example.
69
3. Removal of netnews support
71
Netnews support as it were is dead. Cyrus 2.2 has a brand new approach,
72
and the stuff in Cyrus 2.2 is not functional, and thus removed from this
75
4. Debian Cyrus IMAPd logs with facility MAIL instead of LOCAL6. Also, it
76
prefixes *all* log output with "cyrus/" (e.g.: imapd logs appear as
77
"cyrus/imapd[#####]" instead of "imapd[#####]"). This last change was
78
accepted upstream for Cyrus 2.2.
80
5. Cyrus Murder, the Cyrus IMAPd/POP3 aggregator is available.
82
However, you will have to configure it yourself. No pre-packaged
83
configuration of Murder is available at this time... The documentation is
84
all there, and the Cyrus packages will happily preserve your Cyrus Murder
85
configuration. You do not have to install the cyrus-imapd-2.2 or
86
cyrus-pop3d-2.2 packages in hosts that only need the proxy daemons running,
87
but do note that the /etc/pam.d/imap and /etc/pam.d/pop files are in those
88
packages (and they are needed by the proxies), so you will have to create
91
One important note: MUPDATE doesn't support TLS, so you won't be able to
92
use plaintext authentication methods. The easiest thing to do is to put
93
an entry for your mupdate user in sasldb2 and use DIGEST-MD5.
96
General notes and hints:
97
------------------------
99
o *** ALWAYS READ /usr/share/doc/cyrus-common-2.2/NEWS.Debian *** after
100
you upgrade the package.
102
o QUOTAS ARE LIMITIED TO 2GB on some platforms.
103
Be careful to not set quotas over that ammount if your platform doesn't
104
support the C datatype "long long". Things will break in very bad ways.
105
Yes, it is a big glitch, and no, there are no easy workarounds.
106
see https://bugzilla.andrew.cmu.edu/show_bug.cgi?id=1212
108
o Either turn off logging of the DEBUG level, or don't complain about cyrus
109
verbosity on the logs. Don't ever ask in the mailing lists about messages
110
logged in the DEBUG level before reading the source code.
112
o Watch out for your /dev/random bitbucket! SASL may use it, and if it
113
empties, it will hang the processes wrapped up by SASL. This means
114
just about every Cyrus service (lmtp, imap, pop3, sieve)... Disable
115
APOP in /etc/imapd.conf if you don't need it, as it is a serious draw
116
on randomness resources.
118
o One extremely important point to notice is that saslauthd works ONLY
119
with plaintext. APOP, CRAM-MD5, OTP, DIGEST-MD5 and any other "auxprop"
120
SASL mech will *not* work through saslauthd. This can and will cause
121
serious issues in Cyrus murder environments.
123
o When using ext3, Cyrus really wants data=journal. However, up to
124
kernel 2.4.20 there are dangerous bugs in that option, so you're better
125
off not using that. xfs is faster and better for Cyrus, anyway.
127
o nscd users: nscd is highly incompatible with ldap, and somewhat buggy
128
otherwise. If you use nscd and Cyrus segfaults on you, try restarting
129
nscd, or disabling it.
131
o "The Debian libldap2 and cyrus-imapd packages are both compiled using the
132
SASL library. If you use cyrus-imapd together with libnss-ldap, or
133
saslauthd together with libpam-ldap, the resulting double calls to SASL
134
library functions can trigger a double-free bug which may cause the calling
135
process to crash. To avoid such a crash, you must recompile the libldap2
136
package --without-cyrus-sasl." -- http://bugs.debian.org/145766 [!@#$%!!!
137
I didn't expect SASL 2.1 to still have this annoying problem]
139
o The lmtp service (allocated in Debian Woody to port 2003, and non-existent
140
on Debian Sarge) is non-standard. It has no port officially allocated
141
anywhere; it is usually run bound to the localhost interface, unless one
142
needs it for clustering and high-availability scenarios. If you need it
143
elsewhere, by all means move it -- you only need to edit /etc/services, or
144
change the port for the lmtp service in /etc/cyrus.conf.
146
o The lmtp service will only allow Cyrus lmtp administrators to authenticate.
147
Set them in /etc/imapd.conf.
149
o Cyrus can now use two different namespaces (the standard one, where all
150
subfolders are children of INBOX, and one where they are all in the same
153
See /usr/share/doc/cyrus-common-2.2/html/altnamespace.html for details. If
154
you deal with a large population of winboze users, this option can save
157
o One can also chose between netnews-style notation for folders
158
(INBOX.subfolder), where the "." character is reserved to separate folders;
159
or UNIX-style notation (INBOX/subfolder), where dots are allowed in names,
160
and the slash separate folders (the "^" character is reserved in this
163
See /usr/share/doc/cyrus-common-2.2/html/altnamespace.html for details.
165
o When using SASL, do keep in mind that cyrus runs under user cyrus, and not
166
root. It cannot read shadow files (unless you add the user cyrus to group
167
shadow), or perform any root-only operations directly. You need to use the
168
saslauthd (or, if available, auxpropd) mechanism to authenticate against
169
root-only data. And that also means user cyrus must be able to talk to the
170
unix socket saslauthd uses (which is controlled by SASL, not Cyrus IMAPd).
172
o Any of the SASL configure options can be inserted in imapd.conf, just
173
prefix it with "sasl_" (e.g.: sasl_mech_list: PLAIN). The list of SASL
174
options is in /usr/share/doc/libsasl2/options.html.
176
o The services are tcp-wrapped. Their hosts.allow/hosts.deny id is the
177
service name in /etc/cyrus.conf. See hosts_access(5).
179
o The PAM service names for use with SASL (via saslauthd) are:
180
"imap", "sieve", "lmtp", "pop", "mupdate".
182
o You need to specify your admin users in /etc/imapd.conf before you can
183
add mailboxes, or deliver through authenticated lmtp. Do NOT use root.
184
We suggest user cyrus, which is already used by the system for all
185
things Cyrus IMAPd... but it need not be an existing user. As long as
186
SASL will authenticate against it, it will work.
188
o Do NOT read your admin user's email via IMAP (see the FAQ for details).
190
o Don't export your mail store over NFS or AFS (read the FAQ for more info).
191
You have been warned. You really want a journaled (as in journaling for the
192
metadata), local filesystem for the store. Failing that, you need
193
something with very strict and correct lock semanthics, and full mmap
196
o Ext2 is slow on very large directories (right now), and sync medatada
197
writes enabled are a huge performance hit. If you need high IO throughput
198
from Cyrus, you will need to use ext3, reiserfs, xfs or something like
199
that. xfs is probably the best one.
201
o You may want to enable/disable synchronous metadata writes to your mail
202
store dirs (check /usr/share/doc/cyrus-doc-2.2/html/install.html for more
203
info, in package cyrus-docs-2.2). The cyrus-makedirs script tries to do the
204
right thing for ext2 and ext3 filesystems. Failure to correctly update the
205
metadata in the right order can completely screw up your Cyrus store on a
206
power-loss or another disk failure.
208
o Try mounting the store and cyrus database filesystems with noatime for
209
performance gains. Load-balance the store using multiple partitions on
210
different physical devices for even better performance gains.
212
o Cyrus IMAPd should be fed mail through LMTP. If at all possible, use
213
the Unix socket for that -- it automatically authenticates as user
214
postman and that will help wonders. cyrdeliver can also be used to
215
inject mail, but it will simply open an LMTP socket to cyrus and
216
deliver through that -- this is much slower than using LMTP directly.
217
The UNIX socket is in /var/run/cyrus/socket/lmtp. Use dpkg-statoverride
218
if you need to change the permissions of the socket directory.
220
o You can use /usr/sbin/cyrus-makedirs to generate the needed directories
221
for cyrus partitions. It is run automatically by the package postinst,
222
and it knows to parse the /etc/imapd.conf file to verify if hash
223
subdirectories are needed or not. It cannot detect what kind of hashing
224
should be used yet. If you recompile the package with full hashing,
227
o Refer to cyrus-utils.sourceforge.net and the info-cyrus mailinglist
228
for mailbox/imap to cyrus conversion scripts.
230
o If you don't use pop3, or something else enabled by default in cyrus.conf,
231
disable it. Otherwise, Cyrus master will log warnings that the service
232
could not be started.
234
o If you want to run something that is not in /usr/lib/cyrus/bin in
235
cyrus.conf, just use the full path in cyrus.conf (e.g.:
236
cmd="/usr/sbin/squatter").
238
o Sieveshell is really lacking on auth capabilities, and timsieved is quite
239
strict on what auth capabilities it offers. So, pay attention to
240
sasl_minimum_layer, and see bug #151925 for more details
241
(http://bugs.debian.org/151925). Also, make sure you have the correct set
242
of SASL2 modules installed in in your system.
244
o uw-mailutils has some nice utilities to migrate mail stores from/to imap
245
servers. You might find it quite useful to migrate a site to Cyrus.
250
o Group lookups in LDAP (through nss-ldap) will not work well. See Debian
257
cyrmaster is an agentx SNMP subagent, and it can interface to a agentx SNMP
258
master. It will export data at OID .1.3.6.1.4.1.3.6.1 (cyrusMasterMIB).
260
The ucd-snmp daemon (package snmpd) is NOT configured to work
261
as agentx master agent by default -- you have to do that manually,
262
by adding "master agentx" to the /etc/snmp/snmpd.conf file.
264
cyrmaster will register with the snmp agentx master when it is started,
265
so if the snmp master is restarted after cyrmaster, it will not forward
266
the snmp requests to cyrmaster anymore. Check your system for any cron
267
scripts that might be restarting the snmp process if that happens.
269
See /usr/share/snmp/mib/CYRUS-MASTER-MIB.txt for more details.
272
Backing up for rainy days
273
------------------------
275
Cyrus automatically checkpoints and backups some of its databases, using the
276
ctl_cyrusdb(8) utility (EVENTS in /etc/cyrus.conf). It is supposed to be also
277
capable of recovering automatically from these backups, and to attempt to do so
278
at startup. However, ctl_cyrusdb -r is NOT FULLY IMPLEMENTED YET... you are on
279
your own to recover from corrupt databases.
281
This recovery can be done using the db3 utilities, and even by smart usage of
282
cvt_cyrusdb(8) and ctl_mboxlist(8). The automatic backups are useful, too,
283
even if they are not restored automatically.
285
The database backups are stored at /var/lib/cyrus/db.backup*, you may want to
286
copy the files there to backup media in a cronjob, or something like that. You
287
can kill the TLS cache database, as long as Cyrus is stopped when you do it.
288
Loss of the delivery database is not very bad, it just means some users might
289
get duplicated messages.
291
Cyrus does NOT backup the mail store automatically. To backup the mail store
292
partitions, you must stop Cyrus and dump the entire partition to your backup
293
media. The MH-like structure of the Cyrus store do make them suitable for
294
incremental backups. Hot-backups of the store can be made, but you risk losing
295
some non-critical metadata when the restore is done.
297
You can backup all Cyrus non-text databases to a flat text file format using the
298
cvt_cyrusdb utility (and recover back from the flat text file format), but you
299
should stop Cyrus first.
301
If you ever need to recover the mail store from backup, you should run
302
cyrreconstruct(8) to rebuild the mailbox indexes.
304
A daily maintenance cronjob uses ctl_mboxlist(8) to dump the mailboxes database
305
to /var/backup. That backup copy can be used as a last-resort copy if the hot
306
backups become corrupted somehow.
309
Debian source package quirks
310
----------------------------
312
There aren't many. Patchset numbers as provided by the cvsps utility in its
313
default configuration are used to denote patches taken from upstream CVS in the
314
changelog. Less important patches from upstream CVS (such as documentation
315
updates) are applied without adding a changelog entry.
321
Thanks go to the CMU crew for producing Cyrus IMAPd in the first place;
322
Michael-John Turner <mj@debian.org> for maintaining the v1.5 branch and setting
323
the groundstones for the v2.1 package; David Parker <david@neongoat.com> and
324
David D. Kilzer <ddkilzer@theracingworld.com> for their huge help in getting
325
the v2.1 packages out-of-the-door, and the upgrade from v1.5 guide; Fabian
326
Fagerholm <fabbe@paniq.net> for stress testing the daemons, and useful
327
feedback; and Gilles Bouthenot <gilles.bouthenot@fcomte.iufm.fr> for good
330
-- Henrique de Moraes Holschuh <hmh@debian.org>
added
removed
debian/README.Debian
