2004-02-02
| Revision History | ||
|---|---|---|
| Revision 2.0 | 2004-02-02 | WRC |
| DRAFTConverted to DocBook4. Completely revised to cover Cyrus IMAP 2.x. Moved Cyrus-SASL to a separate document.DRAFT | ||
| Revision 1.3 | ASG | |
| inetd.conf error fix, authentication information added, more troubleshooting info. | ||
| Revision 1.2 | ASG | |
| SASL Config error fix, new postfix configuration, and database pruning (thanks, Jernej) | ||
| Revision 1.1 | ASG | |
| Fixed sendmail.mc configuration file error and added IMAP information to the introduction. | ||
Abstract
This document presents a guide to installing, configuring, and running Cyrus IMAP.
Table of Contents
(c) 2004 Wil Cooley
(c) 2000 Aurora Skarra-Gallagher
This section was copied from the HOWTO-HOWTO:
This manual may be reproduced in whole or in part, without fee, subject to the following restrictions:
The copyright notice above and this permission notice must be preserved complete on all complete or partial copies.
Any translation or derived work must be approved by the author in writing before distribution.
If you distribute this work in part, instructions for obtaining the complete version of this manual must be included, and a means for obtaining a complete version provided.
Small portions may be reproduced as illustrations for reviews or quotes in other works without this permission notice if proper citation is given. Exceptions to these rules may be granted for academic purposes: Write to the author and ask. These restrictions are here to protect us as authors, not to restrict you as learners and educators. Any source code (aside from the SGML this document was written in) in this document is placed under the GNU General Public License, available via anonymous FTP from the GNU archive.
In this document, I have the pleasure of acknowledging:
Aurora Skarra-Gallagher, who started this document.
The home of this document is at http://nakedape.cc/info/Cyrus-IMAP-HOWTO/. A single-page version is at http://nakedape.cc/info/Cyrus-IMAP-HOWTO/Cyrus-IMAP-HOWTO.html. The source may be checked out from our public Subversion repository at https://haus.nakedape.cc/svn/public/trunk/writing/Cyrus-IMAP-HOWTO/.
This definition is from the ComputerUser.com High-Tech Dictionary:
Internet Message Access Protocol. A protocol that allows a user to perform certain electronic mail functions on a remote server rather than on a local computer. Through IMAP the user can create, delete, or rename mailboxes; get new messages; delete messages; and perform search functions on mail. A separate protocol is required for sending mail. Also called Internet Mail Access Protocol.
IMAP allows the user to read email from many different locations and accounts because email folders are stored on the server, locally, at the home or the office, for instance. Even saved and read messages are stored on the IMAP server. POP only stores new unread messages on the server, and the read and saved messages are stored locally. To force POP to not delete email once it has been read can create many copies of the same email, creating a waste of space and confusion. However, IMAP is usually more complicated to set up. If you only have one email account, POP is most likely your best choice. If you want to access more than one account, from different locations, IMAP will probably serve you most efficiently.
Cyrus IMAP provides a robust, scalable mail architecture. It provides client access through IMAP and POP3, the two most common mail presentation protocols defined by open standards. Through the use of the SASL authentication, it supports a variety of authentication mechanisms and back-ends. It supports wrapping IMAP and POP3 in SSL and negotiating TLS in-channel. It supports multiple storage pools for mailboxes, so adding mailbox space is relatively straight-forward.
Cyrus has its own mailbox database which is standalone and increases performance, whereas Washington uses the stanard UNIX mailbox format, which was designed for a smaller set of users. Washington is portable to more UNIX and non-UNIX systems than Cyrus. The main difference is that with Cyrus, you don't have to add new users to your linux box (i.e. in /etc/passwd) to add new mail users, and with Washington, you do.
Cyrus IMAP is a powerful, modular piece of software. Power and modularity entails a certain degree of complexity.
Like most applications, a Cyrus IMAP installation has a number of files, such as data files for messages, program files for subservers, configuration files, etc. Unfortunately, the default locations for these files are at odds with the Linux Filesystem Heirarchy Standard and depending on whether you installed from source or installed from a package made by someone else, your files could have one of several different locations.
The mail spool is typically located in
/var/spool/mail. This one fact remains
fairly consistent. Below here, there may be three different
sorts of layouts, depending the selected level of mailbox
hashing. If hashimapspool is zero,
then there will just be directories here that map directly
to mailboxes based on the first letter of the mailbox name.
For example, a mailbox for user "wcooley" will be located
at /var/spool/mail/w/user/wcooley.
For very large installations, however, this tends to result
in a disproporationate number of mailboxes under "s" compared
with "z."
If hashimapspool is 1 or true, then
the effect of fulldirhash comes into play.
If it is not set or zero, then mailboxes are set by the
username. For example, for user "wcooley", the mailbox is
located in /var/spool/mail/w/user/wcooley.
However, if fulldirhash is set
to 1 or true,
then the mailbox directories are hashed with a true
hash function to a prime number "buckets," which
are represented as a single character. For example,
/var/spool/imap/I/user/wcooley. The use
of a true hash function provides nearly even distribution
of mailboxes in into directories.
To provide a consistent lookup mechanism for mailbox
names, the mbpath program is provided to
allow a consistent interface for determining the actual mailbox
path without having to account for the hashing yourself.
The dohash and undohash scripts purport to convert between the three levels of mailbox hashing. However, they may not work and are not terribly well documented, so it's probably best to choose the correct one from the beginning. Unless you plan on mucking about with the mailboxes (which you probably should not do), there is no harm in using the full hashing from the get-go.
Metadata for the mailstore is stored by default in
/var/imap, although for FHS compliance,
packages tend to use /var/lib/imap.
(FIXME)
The master process acts as
the controller for all of the Cyrus sub-servers.
It performs tasks similar to those performed by
cron, inetd, and
init scripts, although only for Cyrus processes--it is
not a system-wide replacement for any of these. It is
configured through the cyrus.conf
file, which has three sections: START,
SERVICES, and
EVENTS.
Each section has entries which are restricted to a
single line and composed of a tag name and parameters.
The tag name should be unique and the exact parameters
are specific to the particular section. When Cyrus is
built with support for TCP Wrappers, the tag name is used
as the daemon name for hosts.allow
and hosts.deny.
All sections have a cmd, which
lists the program and parameters to be used when the entry
is invoked. This entry is relative to the --with-cyrus-prefix supplied
at build time.
The START section contains
commands that are run then master is
started, much like an init script. Usually, this section
contains nothing more than a recover
section, for checking the Cyrus databases before starting
processes that use those databases. If your system is
configured to use idled, it is also
started here, because it does not directly listen on a
network or UNIX socket.
The following is a minimal listing of the
START section (taken from the example
master/conf/normal.conf from the
source distribution).
START {
# do not delete this entry!
recover cmd="ctl_cyrusdb -r"
# this is only necessary if using idled for IMAP IDLE
# idled cmd="idled"
}
The SERVICES section contains
entries for the various sub-servers that run under the
system and listen on network sockets. It is very much
like inetd in this respect.
Older versions of Cyrus (1.5 and
1.6) required inetd entries for
sub-servers. In 2.0 and later versions, this section of
cyrus.conf replaces that. If you
find documentation referring to inetd,
your documentation is obsolete!
The listen parameter lists the
TCP or UDP port or UNIX domain socket to be listened-on
for the particular service. UNIX domain sockets are
paths in the filesystem and are differentiated from
ports by starting with a slash (/).
For TCP and UDP sockets, you can give either the
actual port number or the service name, as resolved
through /etc/services or other
NSS means. TCP is the default protocol, although UDP
can be used with the proto parameter.
prefork and maxchild
provide control over the number of processes initially
forked to help manage load and the maximum number of child
processes to be started, to prevent too many processes from
overloading the system. The maxfds
parameter limits the number of open file handles that
the each process my have open.
The following is an example listing of the
SERVICES (taken from the example
master/conf/normal.conf from the
source distribution).
# UNIX sockets start with a slash and are put into /var/imap/socket
SERVICES {
# add or remove based on preferences
imap cmd="imapd" listen="imap" prefork=0
imaps cmd="imapd -s" listen="imaps" prefork=0
pop3 cmd="pop3d" listen="pop3" prefork=0
pop3s cmd="pop3d -s" listen="pop3s" prefork=0
sieve cmd="timsieved" listen="sieve" prefork=0
# these are only necessary if receiving/exporting usenet via NNTP
# nntp cmd="nntpd" listen="nntp" prefork=0
# nntps cmd="nntpd -s" listen="nntps" prefork=0
# at least one LMTP is required for delivery
# lmtp cmd="lmtpd" listen="lmtp" prefork=0
lmtpunix cmd="lmtpd" listen="/var/imap/socket/lmtp" prefork=0
# this is only necessary if using notifications
# notify cmd="notifyd" listen="/var/imap/socket/notify" proto="udp" prefork=1
}
The EVENTS section is similar
to cron in that it schedules commands
to be run. Generally, these commands are for maintenance
of the various databases Cyrus uses.
This section has a period,
which is an interval in minutes to run the listed command,
and an at, which lists a time in
24-hour format to run the listed command.
The following is an example listing from the same
master/conf/normal.conf.
EVENTS {
# this is required
checkpoint cmd="ctl_cyrusdb -c" period=30
# this is only necessary if using duplicate delivery suppression,
# Sieve or NNTP
delprune cmd="cyr_expire -E 3" at=0400
# this is only necessary if caching TLS sessions
tlsprune cmd="tls_prune" at=0400
}
As you might have guessed, the
imapd sub-server provides IMAP access
to the mail store to IMAP clients. It can also provide
SSL-wrapped IMAP with the -s
parameter.
The pop3d sub-server provides POP3
access to the mail store. It can also provide SSL-wrapped
IMAP with the -s parameter.
The timsieved sub-server provides the network service for managing Sieve scripts installed on the server.
The lmtpd sub-server receives deliveries into the mail store, either through TCP/IP or a UNIX domain socket.
The notifyd sub-server provides an interface sending notifications. I've never actually seen this in use and am not sure what it's purpose is, because the docs are a little sketchy. (FIXME).
The fud sub-server provides an interface for client access to information about the mailbox, such as new mail count, total message count, and recent message count. I've not really seen this in use. (FIXME).
Unlike the other sub-servers,
idled is run in the
START section rather
than the SERVICE section.
idled can monitor a mailbox and
signal to listening imapd and
pop3d that new mail has arrived.
The abritron process provides readership statistics for mailboxes. It does not seem to be built by default. It is unclear how commonly used or well-maintained it is.
(Guess???) The cyrdump command dumps mailboxes to a flat-text to standard output, saving seen flags and other state. (NB: There appears to be no reverse command.)
Expires entries from the duplicate delivery database. Can also be used to control automatic expiration of messages based on mailbox annotations.
The ctl_cyrusdb command performs maintenance on the Cyrus databases, such as recovering, check-pointing, and archiving.
The cvt_cyrusdb command is used convert between the various database formats used by Cyrus. It can be used, for example, to perform a dump of data from binary databases to plain-text flat-file databases, which can be more reliably backed-up.
The deliver command used to be
the point of entry for mail coming from the mail transfer
agent (Sendmail, Postfix, etc). It reads messages from
standard input and delivers into the system. However, with
the implementation of LMTP, it is considered obsolete.
In fact, it is just an LMTP client which delivers to
lmtpd. It should not be used by the
MTA to deliver mail into the system unless the MTA does not
support LMTP. It can still be useful, however, with external
programs such as procmail, which does not
operate as an LMTP client. (FIXME: procmail has an option
now to be an LMTP client.) The -q
may still be useful to post over-quota alerts to users'
mailboxes.
The dohash utility is a Perl script which can be used to migrate from older directory layouts and to implement spool directory hashing.
The ipurge utility expires and deletes messages from mailboxes or partitions. It can be configured purge based on message age or mailbox size.
mbpath translates a mailbox name into a filesystem path, taking into consideration spool hashing and partitions.
The mkimap command is a Perl script which creates the directory heirarchies requires by Cyrus. It is generally only needed when installing from source.
Not to be confused with the quota command used for viewing filesystem quotas, this command reports on quota usage and can also be used to repair inconsistencies. (NB: The Cyrus quota command is in section 8 of the man pages; the filesystem quota is in section 1.)
The reconstruct command is used
to rebuild mailboxes, which might have suffered database
corruption or restored from backup. Note that, despite the
fact that the man page has listed a -m
option to rebuild the master mailbox list, it has never
actually worked. It is important, therefore, to maintain
a backup of the mailbox list, perferably as plain-text.
The squatter utility may be one of the most overlooked utilities in the Cyrus distribution. It builds full-text mailbox indexes which allow very fast server-side searching.
The translatesieve command is used to update Sieve scripts when implementing alternative namespaces.
There are lots of little bits of knowledge you need to know to get started. Here I attempt to catalog them.
User mailboxes live under 'user.<username>'. To the user, this mailbox is called simply INBOX; sub-folders such as 'user.<username>.Sent', appear to the user as 'INBOX.Sent' (NB: altnamespace).
Cyrus IMAP's mailbox storage is not Maildir, although it is similar in some respects. You should not expect to access the mailboxes directly as you might other servers; only access messages through POP3 or IMAP.
The mailbox storage does use databases, but it cannot use SQL. People occasionally ask about using SQL, but it does not seem to be an appropriate use of SQL; the data is not especially relational. The data is hashed for fast lookups, which is better done by file-based databases when data is not relational. Most people who are ask about SQL storage have high-availability in mind, which is easy with certain databases (like MySQL); most highly-available Cyrus implementations use SANs and clustered filesystems.
Mailboxes have to be created before being used, either with 'cyradm' or another tool (NB: autocreate patches).
Deleting a message in IMAP requires two steps: First, set the \Deleted flag on the message. Second, EXPUNGE the mailbox. Many MUAs first move messages to a Trash folder, but given the recoverability inherent in a two-step deletion, it is generally considered a design flaw of the MUAs.
Cyrus IMAP logs to syslog facility local6 by default, but can
be overridden at compile-time. (Simon Matter's RPMs default to the
mail facility.) To configure logging, add a line like the following
to your /etc/syslog.conf:
local6.info /var/log/imapd.log
The usual rules for syslog.conf apply;
you must use tabs and not spaces. If your platform, such as
Solaris, requires the log file exist before syslogd will write to
it, you must create it. Finally, you must send syslogd the HUP
signal to make it reload its configuration or restart it.
You might also want to have it log to the same file as the mail facility. If you do not want to recompile, just change the line in for the mail facility to include the local6 facility, such as the following:
mail.info;local6.info /var/log/maillog
Your messages log might have a wildcard facility, so you should exclude local6 from that by changing it to be similar to the following:
*.info;mail.none;authpriv.none;cron.none;local6.none /var/log/messages
If you want more messages, change "info" to "debug", but be warned that some of the debugging messages are informational and might not be generally cause for worry if you are not experiencing problems.
As a debugging aid, Cyrus IMAP can also log protocol conversations on a per-user basis. Note that you cannot debug the authentication process using this, because the protocol logging is only associated with a username and until a user has been successfully authenticated, the username is unknown.
To enable protocol logging, simply create a directory in
/var/lib/imap/log with the user's name you
wish to log. Ensure, of course, that this directory is writable by
the user Cyrus runs as. Cyrus will create files in this directory
with the name of the process ID under which it runs (which changes
per connection due to the forking server model it uses).
# cd /var/lib/imap/log/
# mkdir wcooley
# chown cyrus wcooley/
I've created the directory and now I'm logging in with a mail client, which selects my INBOX, checks messages and ACLs and logs out.
# pwd
/var/lib/imap/log/wcooley
# ls
30069
# less 30069
---------- wcooley Thu Feb 17 11:20:35 2005
>1108668035>a0001 OK User logged in
<1108668035<a0002 LIST "" ""
>1108668035>* LIST (\Noselect) "." ""
a0002 OK Completed (0.000 secs 0 calls)
<1108668035<a0003 SELECT "INBOX"
>1108668035>* FLAGS (\Answered \Flagged \Draft \Deleted \Seen)
* OK [PERMANENTFLAGS (\Answered \Flagged \Draft \Deleted \Seen \*)]
* 0 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 1107062834]
* OK [UIDNEXT 1]
a0003 OK [READ-WRITE] Completed
<1108668035<a0004 MYRIGHTS "INBOX"
>1108668035>* MYRIGHTS INBOX lrswipcda
a0004 OK Completed
<1108668035<a0005 NOOP
>1108668035>a0005 OK Completed
<1108668042<a0006 CLOSE
>1108668042>a0006 OK Completed
<1108668042<a0007 LOGOUT
>1108668042>* BYE LOGOUT received
a0007 OK Completed
Beginning with Core 3, Fedora includes Cyrus IMAP. In Core 3, the package is part of base, but in Core 4, it was moved to extras. The RPMs are built indirectly from Simon Matter's SRPMs, which I have used on Red Hat Enterprise Linux 3 systems and are quite good. While I do not recommend Fedora as a server platform given the brevity of its lifespan, I will use it as a base for demonstration since the Cyrus IMAP RPMs and dependencies are already included.
The following guide gives steps without much explanation about getting started using Cyrus IMAP on this platform; the procedure for RHEL3 (or clones, like CentOS3) is very similar, albeit with additional steps of downloading and perhaps rebuilding.
The configuration I will be using with use PAM authentication with saslauthd, since PAM is configured by default. Delivery will happen with Postfix, because I eschew Sendmail where possible. (Sendmail information may be added at a later date.)
These instructions have been updated and tested for Cyrus IMAP 2.3.13 on Fedora 10; they might work for older versions but have not been tested.
You must remove the imap package; it is the
UW-IMAP server and conflicts with Cyrus IMAP. Newer versions call
the package uw-imap and it may be no longer
installed by default. Obviously, if you have installed another IMAP
server such as dovecot you should remove that
also. The following packages need to be installed:
postfix
cyrus-imapd
cyrus-imapd-utils
perl-Cyrus
cyrus-sasl
cyrus-sasl-plain
The Perl module Term::ReadLine::Gnu
is also recommended, as it provides readline support to
cyradm. An RPM is in
the RPMforge repository.
# rpm -e imap
# yum install postfix cyrus-imapd cyrus-imapd-utils cyrus-sasl \
> cyrus-sasl-plain perl-Term-ReadLine-Gnu
...
Performing the following to resolve dependencies:
Install: perl-Cyrus.i386 0:2.2.10-3.fc3
Is this ok [y/N]: y
...
Complete!
Next, we configure Cyrus SASL to authenticate with PAM and test.
Edit /etc/sysconfig/saslauthd and change
MECH to be pam. Older
versions used shadow by default, which will
authenticate regular UNIX accounts, but PAM is more
flexible.
Start saslauthd by running its init script
and configure it to start on boot:
# /sbin/service saslauthd start Starting saslauthd: [ OK ] # /sbin/chkconfig saslauthd on # chkconfig --list saslauthd saslauthd 0:off 1:off 2:on 3:on 4:on 5:on 6:off
Now let's test that saslauthd is working.
(I assume here that you have already created a user account somewhere.)
Yes, you do have to specify the password on the command line; it is
an annoyance that should be fixed.
$ testsaslauthd -u username -p password 0: OK "Success."
Actually, this is pretty easy. While a usual installation
requires modifying parameters in /etc/imapd.conf
and /etc/cyrus.conf, the Fedora RPMs are already
configured for general use, even SSL support.
All that must be done, then, is to start and test it and create mailboxes. First, we start it up:
# /sbin/service cyrus-imapd start Starting cyrus-imapd: preparing databases... done. [ OK ] # /sbin/chkconfig cyrus-imapd on # /sbin/chkconfig --list cyrus-imapd cyrus-imapd 0:off 1:off 2:on 3:on 4:on 5:on 6:off
And then test it with imtest:
$ imtest -t "" -u wcooley localhost
S: * OK imap.example.com Cyrus IMAP4 v2.2.10-Invoca-RPM-2.2.10-3.fc3 server ready
C: C01 CAPABILITY
S: * CAPABILITY IMAP4 IMAP4rev1 ACL QUOTA LITERAL+ MAILBOX-REFERRALS NAMESPACE UIDPLUS ID NO_ATOMIC_RENAME UNSELECT CHILDREN MULTIAPPEND BINARY SORT THREAD=ORDEREDSUBJECT THREAD=REFERENCES ANNOTATEMORE IDLE STARTTLS LISTEXT LIST-SUBSCRIBED X-NETSCAPE
S: C01 OK Completed
Please enter your password:
C: L01 LOGIN wcooley {6}
S: + go ahead
C: "omitted"
S: L01 OK User logged in
Authenticated.
Security strength factor: 0
. LOGOUT
* BYE LOGOUT received
. OK Completed
Connection closed.
Finally, we must create mailboxes with
cyradm. But in order to do that, we must set
a password for the cyrus account:
# passwd cyrus
Changing password for user cyrus.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.
Now login with cyradm:
$ cyradm --user cyrus --auth PLAIN localhost
verify error:num=18:self signed certificate
IMAP Password:
localhost.localdomain>
And create an initial mailbox and view some stats:
localhost.localdomain> createmailbox user.wcooley localhost.localdomain> listmailbox user.wcooley user.wcooley (\HasNoChildren) localhost.localdomain> listaclmailbox user.wcooley wcooley lrswipcda localhost.localdomain> listquotaroot user.wcooley
Alternatively, you can use abbreviations of the commands:
localhost.localdomain> cm user.wcooley localhost.localdomain> lm user.wcooley user.wcooley (\HasNoChildren) localhost.localdomain> lam user.wcooley wcooley lrswipcda localhost.localdomain> lqr user.wcooley
At this point, you have a working IMAP server. You might want to start an IMAP client and login to the server, just to doublecheck before actually delivering mail to it.
Since Sendmail is the default MTA in Fedora, you must change the default with the alternatives command after stopping Sendmail.
# /sbin/service sendmail stop Shutting down sendmail: [ OK ] Shutting down sm-client: [ OK ] # chkconfig sendmail off # chkconfig --list sendmail sendmail 0:off 1:off 2:off 3:off 4:off 5:off 6:off # alternatives --config mta There are 2 programs which provide 'mta'. Selection Command ----------------------------------------------- *+ 1 /usr/sbin/sendmail.sendmail 2 /usr/sbin/sendmail.postfix Enter to keep the current selection[+], or type selection number: 2 # alternatives --display mta mta - status is manual. link currently points to /usr/sbin/sendmail.postfix ...
Now we configure mailbox_transport in
/etc/postfix/main.cf. Add this line to the
bottom:
mailbox_transport = lmtp:unix:/var/lib/imap/socket/lmtp
Finally, start up Postfix:
# /sbin/service postfix start Starting postfix: [ OK ] # /sbin/chkconfig postfix on # /sbin/chkconfig --list postfix postfix 0:off 1:off 2:on 3:on 4:on 5:on 6:off
Assuming you have a functional SMTP server, you should now have a functional IMAP server ready to go.
The first requirement for an IMAP server is actually getting
messages delivered to it. Usually, Cyrus is used as the default
mailbox on the server and we will configure it as such. However,
if you have a live server that is receiving mail and delivering it
into another system (such as through procmail
into /var/spool/mail/$USER), you might save
this section for later. It is possible to selectively deliver
into Cyrus for certain users which might be useful during a
transition period.
To receive mail, Cyrus uses LMTP, which is a mail transfer protocol like SMTP but much lighter-weight. It is superior to simply reading pipe input because it is more rigidly defined and can more effecient. For example, being able to deliver multiple messages in one connection reduces the overhead from building and tearing down the connection.
Cyrus used to use a program called deliver,
which read standard input and delivered messages into the mail
spool directly. These days, deliver is just
a wrapper that reads a message from standard input and delivers
it via LMTP. Since deliver is now considered
obsolete, it will not be covered here.
To configure Cyrus to receive message via LTMP,
make sure the lmtpunix line in
cyrus.conf is uncommented and looks
something like the following:
SERVICES {
# ...
lmtpunix cmd="lmtpd" listen="/var/lib/imap/socket/lmtp" prefork=0
# ...
}
On the Postfix side, ensure that the
lmtp service in
master.cf is not chrooted:
# ========================================================================== # service type private unpriv chroot wakeup maxproc command + args # (yes) (yes) (yes) (never) (50) # ========================================================================== lmtp unix - - n - - lmtp
and set the mailbox_transport to the
LMTP socket listed in cyrus.conf:
mailbox_transport = lmtp:unix:/var/lib/imap/socket/lmtp
A frequent source of trouble with LMTP delivery is the
permissions on the path to the LMTP socket; it is often the case that Cyrus and Postfix are
in separate groups--ensure that they share a group, such as mail.
To check your permissions, run something like the following (as root):
# P=/var/lib/imap/socket/lmtp; while [ "$P" != "/" ]; do ls -ld $P; P=$(dirname $P); done
srwxrwxrwx 1 root root 0 Jun 16 00:27 /var/lib/imap/socket/lmtp
drwxr-x--- 2 cyrus mail 4096 Jun 16 00:27 /var/lib/imap/socket
drwxr-x--- 14 cyrus mail 4096 Jun 16 00:57 /var/lib/imap
drwxr-xr-x 18 root root 4096 Jun 16 00:25 /var/lib
drwxr-xr-x 22 root root 4096 Jun 13 10:14 /var
Delivering with Sendmail, like Postfix, requirs ignoring
the included but obsolete configuration, intended for use with
deliver and instead delivering with LMTP.
As usual when configuring Sendmail, changes should be made
to the M4 file and the resulting output file replacing
/etc/mail/sendmail.cf.
Cyrus IMAP supports authentication using Cyrus SASL. SASL is the Simple Authentication Security Layer, defined in RFC 2222 and other RFCs. In short, SASL does for network protocols what PAM does for system authentication. More information about Cyrus SASL is (will be) available in the Cyrus-SASL-HOWTO. This document will provide basic configuration information for a typical setup. For more complex installations, see the Cyrus-SASL-HOWTO.
The simplest configuration for the average Linux
installation is to use SASL to authenticate with PAM.
Cyrus SASL provides the saslauthd
server which runs as root to be able to read the
/etc/shadow. It listens on a
UNIX domain socket, through which the client libraries
pass authentication information and receive pass or
fail status. Since most installations will have user
accounts already stored in /etc/passwd
and /etc/shadow, PAM provides a
convenient mechanism.
Run the command saslauthd -v and
verify that "pam", "shadow" or
"getpwent" are available. "pam"
is the preferred mechanism for a PAM-based system like
Red Hat. "shadow" is a lower-layer directly
using the shadow file. "getpwent" uses the
standard UNIX function that abstracts the reading of the
/etc/passwd (and shadow) and allows a
modular naming system with the Name Service Switch. Of these,
PAM is undoubtedly the most flexible of the mechanisms.
If you're using Red Hat, then Cyrus SASL 2.1 should
already be installed with saslauthd
built with PAM support. By default, however,
the init script uses the shadow
mechanism, which is more limited. I recommend you
create /etc/sysconfig/saslauthd
with the line MECH="pam" and
restart with # /sbin/service saslauthd
restart. Ensure that it is configured to start at
boot time by running # /sbin/chkconfig
saslauthd on.
You can verify that it is working with the
testsaslauthd program. Simply supply a
username and password for the -u and
-p options, respectively.
Let's make a quick run-through of everything we'd need to do For example:
$ testsaslauthd -u joebob -p bobjoe
0: OK "Success."
The cyradm command is the main tool that Cyrus administrators use. It allows an administrator to create, delete and rename mailboxes and manage quotas and ACLs.
Assuming that your system is configured, running cyradm should simply be a matter of typing the command, although it is often located in an out-of-the-PATH directory, so you might need the full path. Inevitably, a person will have problems authenticating the first time because he has neglected to limit the advertised SASL mechanisms and cyradm chooses a stronger mechanism than he has support for. If you are unable to login, specify the --auth option with "login". You might also not be working as cyrus, so the "--user cyrus" option may also be necessary. Of course, the IMAP server itself must'nt be forgotten, even if it is only "localhost". So that simple command of starting cyradm ends up being something like this:
$ cyradm --user cyrus --auth login localhost
Upon successfully launching cyradm, you will be presented with a prompt inviting you to start mucking about with things. A good place to start is, of course, "help."
$ cyradm --user cyrus --auth login localhost IMAP Password:localhost.localdomain> help authenticate, login, auth authenticate to server chdir, cd change current directory createmailbox, create, cm create mailbox deleteaclmailbox, deleteacl, dam remove ACLs from mailbox deletemailbox, delete, dm delete mailbox disconnect, disc disconnect from current server exit, quit exit cyradm help, ? show commands info display mailbox/server metadata listacl, lam, listaclmailbox list ACLs on mailbox listmailbox, lm list mailboxes listquota, lq list quotas on specified root listquotaroot, lqr, lqm show quota roots and quotas for mailbox mboxcfg, mboxconfig configure mailbox reconstruct reconstruct mailbox (if supported) renamemailbox, rename, renm rename (and optionally relocate) mailbox server, servername, connect show current server or connect to server setaclmailbox, sam, setacl set ACLs on mailbox setinfo set server metadata setquota, sq set quota on mailbox or resource version, ver display version info of current server xfermailbox, xfer transfer (relocate) a mailbox to a different server
You may, of course, use any SASL mechanism you have configured instead of "login", but login tends to work more readily than more sophisticated mechanisms. cyradm need not be run on localhost either. The administration protocol is integrated in the IMAP protocol itself, so the tool has a level of network transparency. It does not, however, support SSL/TLS, which is why using it on localhost is a good idead.
The command shell will pass any command it does not recognize to your regular shell, which may be confusing at first.
Resist the temptation to give administrative rights to accounts other than dedicated accounts--logging in with administrative rights with a regular mail client may cause unpredictable results. It is not out of sheer laziness that all of my examples use "cyrus" as the admin user.
Listing users is done with the 'listmailbox' command, usually run as 'lm'. There are not a lot of options with 'lm', except in the wildcards that may be used. As with shell wildcards, '*' matches anything; '%', on the other hand, matches anything except the hierarchy separator. This allows only listing the top-level set of folders. For example, let's list all of the folders:
localhost.localdomain> lm news.announce (\HasNoChildren) user.foo.bar (\HasNoChildren) user.foo (\HasChildren) user.wcooley (\HasNoChildren)
Now let's list only users' folders:
localhost.localdomain> lm user.* user.foo (\HasChildren) user.wcooley (\HasNoChildren) user.foo.bar (\HasNoChildren)
Now, let's list only the top-level user folders:
localhost.localdomain> lm user.% user.foo (\HasChildren) user.wcooley (\HasNoChildren)
In order for a user to receive e-mail with Cyrus, his mailbox must first be created. This is unlike many IMAP servers, where the user's INBOX is created initially upon delivery. Because Cyrus does not rely on UNIX accounts to authenticate users nor does it operate with any user's privileges, it cannot know whether a mailbox is valid.
There are patches which allow automatic creation of a user's INBOX (and pre-defined subfolders) upon login. Provided that your users will login before the expect to receive e-mail and that all available accounts should have mailboxes, this is a good method of removing some administrative burden.
Creating a mailbox manually is simply a matter of using the 'createmailbox' command, usually abbreviated 'cm', and providing the correct namespace. For users, that namespace is 'user.', so a mailbox for user 'wcooley' will be created as 'user.wcooley'.
localhost.localdomain> cm user.wcooley localhost.localdomain> lm user.wcooley user.wcooley (\HasNoChildren)
To delete a mailbox, you must fix give the admin user 'create' permissions on the mailbox. To the surprise of many, the admin does not have this permission by default. Then you can delete the mailbox with 'dm'.
localhost> lam user.test test lrswipcda localhost.localdomain> dm user.test deletemailbox: Permission denied localhost> sam user.test cyrus c localhost> lam user.test test lrswipcda cyrus c localhost> dm user.test
Abstract
The following sections provide information on installing Cyrus IMAP. It is expected that most people will be able to use binary packages (or rebuilt source packages) for their distribution; however, basic instructions for installing from source are included.
The homepage is currently located at: http://asg.web.cmu.edu/cyrus/imapd
You will need both IMAP and SASL. Download the latest files here:
ftp://ftp.andrew.cmu.edu/pub/cyrus-mail
Download cyrus-imapd-X.X.X.tar.gz
and cyrus-sasl-X.X.X.tar.gz (where X.X.X
is the latest release) into your temporary directory.
I will use /tmp as the directory
I've uncompressed the files under for the rest of the
examples.
The following commands will tar and gunzip cyrus IMAP
under /tmp.
$cd /tmp$tar -zxvf tar/cyrus-imapd-1.6.24.tar.gz$cd cyrus-imapd-1.6.24
When I tried to install cyrus IMAP, I got errors
regarding the file com_err.h. My com_err.h was located
in /usr/include/et. It needs to reside in
/usr/include. Run the following command to make
sure it is in the correct location:
locate com_err.h
This will show you where the file is. If it is
under /usr/include, you can skip
to the next section. If it is in another directory,
just copy it to /usr/include. If
it doesn't exist, download it here: http://www.ludd.luth.se/~jnilsson/cvsweb/cvsweb.cgi/src/contrib/com_err.
Cyrus requires a user to own its files. The default user is cyrus. The following command adds a user cyrus with the group of "mail"
useradd -g mail cyrus
You'll want to set the password for user cyrus.
passwd cyrus
Type in the password you desire cyrus to have each time you are prompted