Cyrus IMAP Aggregator install ----------------------------- This is a simple set of instructions on how to install the Cyrus IMAP Aggregator. Do not skimp by thinking you can get this to work by putting the mupdate on one of the frontend machines. Prepare your machine's names IN ADVANCE and then DO NOT CHANGE THEM. sasl2 auth uses the machine name as part of the authentication and will fail if you change the machine name. Please note that there is a better way to do this setup - e.g. by not using the same password on all machines. Personally, I could not care less about having separate passwords for update access and frontend access - I am just happy that the frakkin thing works at all. Please also note that if you have specified weird things like "altnamespace: 1" in your backend servers that you will ALSO have to put the same options in your frontend servers - otherwise your users will think that half their folders have disappeared. Please also note that you cannot yet deploy automailboxcreate on a Cyrus Aggregator system because the automailboxcreate patch doesn't support mupdates yet. Also a word of caution: if you are thinking of deploying this on an existing sendmail + cyrus installation, or are thinking of deploying cyrus aggregator in combination with sendmail - don't. sendmail, like perl, is a complete dog that was introduced in an era when saving a few bytes here and there resulted in necessary saving of a few tens of K everywhere, and as a result the expression of configuration is so obscure as to be hostile. You will find it so much easier to deploy exim4 or even postfix. Additionally, like I did, you will run into difficulties with doing AUTH on LMTP. So, if you are one of those people with an IQ over 150 and know how to get sendmail to talk authenticated LMTP over TCP, then go for it. For the rest of us, there are always other mail servers. Anyway: onwards... 0) buy at least three separate machines, call one frontend(1-N), one mupdate, and one backend(1-N). 1) on all machines, install cyrus murder: root# apt-get install cyrus21-murder cyrus21-imapd sasl2-bin \ cyrus21-admin libsasl2-modules 2) on front-ends (and only the frontends) you must choose one of two options: for LDAP configuration of front-ends: check /etc/saslauthd.conf to make sure it contains: ldap_servers: ldap://yourserver:389/ ldap_search_base: dc=yourdomain,dc=co,dc=uk edit /etc/default/sasl and make sure that a) saslauthd is started b) that "MECHANISMS" is set to "ldap" add the usernames "murder" and "cyrus" to the LDAP database, like you would expect, set the passwords for these two accounts, like you would expect (using your LDAP management tools). make sure that the imapd.conf contains the following: saslpwcheck_method: saslauthd allowplaintext: yes sasl_mech_list: PLAIN sasl_minimum_layer: 0 for non-LDAP configuration of front-ends: root# saslpasswd2 -c murder remember to type the same password for all machines. root# saslpasswd2 -c cyrus type the same password for all machines. 3) on the mupdate machines and on the backend machines, run this: root# saslpasswd2 -c murder type the same password for all machines. root# saslpasswd2 -c cyrus type the same password for all machines. 4) on the frontend machines, make sure that the SERVICES section of /etc/cyrus.conf looks like this: SERVICES { mupdate cmd="mupdate" listen=3905 prefork=1 imap cmd="proxyd" listen="imap" prefork=0 maxchild=100 imaps cmd="proxyd -s" listen="imaps" prefork=0 maxchild=100 #pop3 cmd="pop3proxyd" listen="pop3" prefork=0 maxchild=50 #pop3s cmd="pop3proxyd -s" listen="pop3s" prefork=0 maxchild=50 lmtp cmd="lmtpproxyd" listen="lmtp" prefork=1 maxchild=20 } remember (duh) that if you are going to run lmtp proxy, you must (duh) add a line to /etc/services to say what port it's running on. lmtp is NON-STANDARD and so e.g. on the machines i am configuring it shares port 2003 (with cfinger). make sure that the /etc/imapd.conf has the following, which means just adding "murder" to your preexisting list of admins of course and substituting "foo" for your correct password, and adding as many lines "backendmachinename_password: ..." as you have actual back-end machines, and substituting "master" with your "mupdate" machine's name: admins: cyrus murder mupdate_server: master mupdate_port: 3905 mupdate_authname: murder mupdate_username: murder # mupdate_realm mupdate_password: foo mupdate_retry_delay: 10 backendmachinename1_password: foo backendmachinename2_password: foo proxy_authname: murder 5) on the mupdate machine, only (!) have the following lines in /etc/cyrus.conf: START { recover cmd="/usr/sbin/ctl_cyrusdb -r" } SERVICES { mupdate cmd="mupdate -m" listen=3905 prefork=1 } EVENTS { checkpoint cmd="/usr/sbin/ctl_cyrusdb -c" period=30 delprune cmd="/usr/sbin/ctl_deliver -E 3" at=0401 tlsprune cmd="/usr/sbin/tls_prune" at=0401 } and in imapd.conf: configdirectory: /var/lib/cyrus partition-default: /var/spool/cyrus/mail admins: murder it may be the case that the EVENTS section isn't even needed: i don't honestly know. 6) on the backend machine(s), you _can_ if you want to (and it's a good idea) add the following line to /etc/cyrus.conf, in the START section: mupdatepush cmd="/usr/sbin/ctl_mboxlist -m" but the main thing is to add these options to /etc/imapd.conf, remembering duh to substitute YOUR mupdate/master machine name for "master" and YOUR duh password for "foo": admins: cyrus proxyservers: murder mupdate_server: master mupdate_port: 3905 mupdate_username: murder mupdate_authname: murder # mupdate_realm mupdate_password: foo #mupdate_retry_delay: 10 7) start everything and then pray. alternatively, test it with mutt or some other imap client, remembering to use the frontends not the backends. you can make your life easier in a live upgrade deployment by making your imap server you're not quite done yet: what you've got working so far is just the cyrus part. now you have to integrate it with your SMTP server so that email can actually be delivered. there is a curious lack in cyrus - the ability to accept email over TCP on a really well-known protocol called SMTP. This would be really useful - but it doesn't exist in cyrus, so you have to use LMTP instead. The brick wall: despite the backends (on their own, not in aggregator mode) supporting non-authenticated LMTP on TCP, when you put the backends into aggregator mode and deploy frontends, the LMTP proxies on the frontends require AUTH. And it's not just any old auth - it must be a cyrus admin username and password. This is the bit where configuring sendmail to do this becomes a complete bitch. Exim4 took me 5 minutes to follow the instructions on how to set up (for about the fifth time in two years) delivery into cyrus by exim using LMTP, whereupon I ran into the same brick wall. It then took me a further 25 minutes of looking at the documentation to work out how do mandate authentication in the LMTP section: hosts_require_auth = localhost So, in short, you should have a slightly different file called conf.d/transports/30_exim4-config_cyrus_lmtp from that which the cyrus22 doc advises you to create. Assuming that you are sensible and listen to reason, I'm going to assume that you want to use exim4. 8) install exim4 from debian and answer the bog-standard debian config questions, suitable for your site. make sure that you specify "split config into little files". 9) edit /etc/exim4/conf.d/transports/30_exim4-config_cyrus_lmtp and make it contain the following: cyrus_delivery: driver = smtp protocol = lmtp hosts = localhost hosts_require_auth = localhost allow_localhost this config assumes that you have installed exim4 on one of the frontends, and consequently, the frontend will be running LMTP proxy on TCP, and you will be able to change the lmtp config line to listen on "localhost:lmtp" not "lmtp". the reason for putting exim4 on the frontends is because you could then, assuming you haven't listened to the advice about not using sendmail, get sendmail to simply forward to exim4 and exim4 will then talk AUTHenticated LMTP to cyrus for you. alternatively, if you intend exim4 to be your frontline SMTP server, you will of course need to use this instead: cyrus_delivery: driver = smtp protocol = lmtp hosts = frontend1 frontend2 frontend3 hosts_require_auth = frontend1 frontend2 frontend3 10) edit /etc/exim4/conf.d/router/900_exim4-config_local_user and comment out or remove the "check_local_user" line. this is in strict accordance with the debian cyrus exim4 HOWTO which you will find in /usr/share/doc/cyrus22-doc/README.exim and you wil still need to do it. 10) edit /etc/exim4/update-exim4.conf.conf and add, at the bottom, the following line: dc_localdelivery='cyrus_delivery' then, run "update-exim4.conf". What this does is rebuild the exim4 config to use the cyrus delivery section you created in step 9). So, when exim4 wants to deliver email it will shove it down LMTP like what you asked for. 11) edit /etc/exim4/passwd.client to contain your cyrus admin usernames and passwords for any of the "hosts" you specified in cyrus_delivery in step 9). for example, because I have hosts=localhost, and my test server has a cyrus admin password of "foo", I have the following line in passwd.client: localhost:cyrus:foo These passwords and account names are the passwords of the BACKEND servers. You don't necessarily know which backend the email is going to be delivered to, therefore you realistically HAVE to have the same account name and the same password. oops. by this point, you should be giving serious consideration to deploying kerberos. but in case you are not insane enough to do that, here's where you might run into another brick wall (especially if you are using LDAP as an authentication mechanism). To use saslauthd (with LDAP as the back end), you must realistically specify PLAIN as the only sasl_mech_list, otherwise clients will go "oh, CRAM-MD5 is available, let's use that" and then logins will fail. To successfully authenticate for mail delivery using LMTP, your SMTP server must have a cyrus administrator password in cleartext placed in an exim config file, and it may even be easy to sniff out from a network if your SMTP server is on a different host from the LMTP-listening cyrus frontend. To avoid this happening, you want to give serious consideration to deploying dedicated frontend(s) which is/are for the exclusive use of your SMTP server(s), and to configure them as described in step 2) but NOT configuring them to use LDAP - use saslpasswd2 instead, and make sure that the imapd.conf file uses this: sasl_pwcheck_method: auxprop I did say it would be an awful lot easier if you used kerberos, didn't I? are you _quite_ mad??? kerberos??? Anyway - when the CMU guys said that deployment of a Cyrus Aggregator is not for the faint hearted, they really bloody meant it. That having been said, once up-and-running, it's just... so much easier: the users don't have to worry about which frontend they use when they move between remote sites, and the administrators don't have to worry about whether one server is getting overloaded with too many users or too large mailboxes - simply add another backend server and move some of the mailboxes to it. What else. REMEMBER - don't change machine names. don't access the "backend" machines using cyradm to add, remove or move mailboxes, always go via the "frontend" machines with cyradm. if you want to move a mailbox to a different backend server, do this: cyrus> rename user.fred user.fred backend(1-N) read the CMU documentation which is sparse and annoying because it doesn't have examples, and has "back-references" because someone was too lazy to cut/paste the instructions for setting up frontends. also, setting up the mupdate to run on the frontend didn't work for me, so if you can possibly avoid it and use a third machine, do so. remember also, for gawd's sake, to set up four or five test machines: two frontends, two backends and one mupdate. make sure it works for you. this will reassure you greatly and if your managers freak out at you acquiring five test machines and won't let you have them then they certainly are too stupid to have a cyrus aggregator deployment set up under their responsibility, and you should tell them so (or leave this document lying around somewhere accidentally for them to read). joy.