should be an image here

Email invitations with iCal server in Mac OS X 10.6 (Snow Leopard) Server

The following write-up was created after I had problems getting email invitations to external users to function correctly (really, at all).
I received a significant amount of help from Andre LaBranche (see http://www.dreness.com/blog/ ) who deserves all of the credit for helping me pinpoint this issue and effectively remedying the problem. I had reached a point of frustration and – while I certainly hadn’t given up – when I thought about using dtrace tools (iosnoop, rwsnoop) on caldavd, and then realized that several (eight or more) related processes were spawned ( with iCal server running, ps auxw | grep [_]calendar ), I stopped and contacted Andre, who worked with me in troubleshooting the problem(s) I was having – thanks Andre !

For the purposes of clarity and coherency, please note that when I say “iCal” on its own, I am referring to an end-user’s iCal application on their Mac OS X workstation. When I say “iCal Server” I am referring to caldav server as supplied with OS X 10.6 (“Snow Leopard”) Server, and entitled “iCal” in Apples’s Server Admin application.

If you work with the “serveradmin” command, the service name is instead: calendar (i.e.: “serveradmin stop calendar” – or, “serveradmin start calendar” – or, ”serveradmin settings calendar” without the actual quotes when invoking the command in question).

An important conceptual aspect that you need to be aware of is the way in which – by design at this time – users with an account on your server will receive invitations from other fellow users on the same system (server): Invites and invite-replies happen via end-users’ iCal application (configured with their account credentials on your server), and not through email messaging. Email messages can however be sent to external entities – meaning: people without an account on your server, and with email residing externally to your server.

When such a user replies to an invitation, also note that the reply will show up in the iCal application of the person who sent the invite, in the “NOTIFICATIONS” window in the lower-left of iCal. If the Notifications frame is collapsed in your iCal window, you can expand it by clicking the Mail-symbol just below (at the bottom-left).

While setting up iCal Server merits a larger tutorial in and of itself, that’s not the goal here, and the Apple documentation does cover the fundamentals. Please know that there are so very many factors and variables involved in terms of getting this working correctly,  and the existing documentation does not try to cover them all – far from it.

However, there are a number of conditions that you need to have right, prior to iCal Server (service) working correctly for you, and for email invitations to work. Expanding on page 14 of the iCal Server Admin guide (see http://www.apple.com/server/macosx/resources/documentation.html ), the following requirements must be met:

  1. DNS properly configured for your server – whether or not your server provides DNS services, you have confirmed, working (forward and reverse) DNS records for your server.
  2. If your server is behind a firewall and/or NAT, then you do have the required firewall and routing rules correctly configured in your router/firewall, and/or correct settings in the Mac OS X Server firewall.
  3. For calendar invitations to external entities, you do have working email services. If your email services are hosted on another server, then you will need to configure your iCal Server settings accordingly & appropriately. However, for the purpose of this write-up, the assumption is that you are running both calendar (iCal Server) services and email services on the same server.

When setting up email invitations for iCal Server, there is a system-default user that is assigned for this purpose: com.apple.calendarserver

should be an image here

email invitation settings

Be advised that if you make changes in the iCal service settings, there are some situations where that change is not propagated to System keychain entries, and can result in email invitations not working correctly.

I recommend sticking with the supplied user for invitations, com.apple.calendarserver  – while you can change this to a custom-created user-account, please make certain that such an account is created in the Local directory and has mail service enabled. However, before doing so, I recommend extracting and documenting the existing password for the default, Apple-supplied account (com.apple.calendarserver).

You can accomplish this via the Keychain Access utility, as the password in question is stored in the System keychain on your server itself. Launch Keychain Access (in the Utilities folder), highlight the “System” keychain and use the search field to enter: com.apple.calendar
and you should see two stored entires listed. Double-click the first one, entitled “com.apple.servermgr_calendar”  – note that the Account field shows as com.apple.calendarserver – and click the “Show password” box. When asked to authenticate, provide the credentials for your initial, local admin account for your server (the username is normally auto-populated). If you have made any changes along the way in your iCal Server settings, you’ll want to check the password stored in the other keychain entry, icalserver.invitations and ensure that your entires in Server Admin for iCal Server match – in terms of the Outgoing Mail Server (SMTP) settings.

Note that for both the incoming and outgoing mail settings, when working with the existing server itself, you can use “localhost” (no actual quotes) for the Incoming and Outgoing Mail Server settings. And in that case, SSL is not strictly necessary. However – and as a point of interest – Server Admin appears to default to using SSL (presumably, if and when available) for these settings – in contrast to the screenshot shown above.

Here’s the key issue that resulted in email invites not working in my own case: If you’re not aware or not careful, stored entries can get out of sync in terms of the password for the provisioned user-account for sending email invitations.

Quoting Andre (with his permission): “When the email notification password is updated in Server Admin, iCal Server updates a keychain item called icalserver.invitations with the new password. As it turns out, that keychain item’s password is NOT used for the smtp side of the mail gateway, but it IS used for the imap (and probably pop, if configured) side. The smtp mail gateway is authenticated using the password stored in another keychain item – com.apple.servermgr_calendar – which is NOT updated when you change the email password settings in Server Admin. Manually editing this keychain item to set the password to be equal to the ‘new’ password does the trick, and then it all works.”

For troubleshooting email invitations, you should set the iCal Server log setting to: Debug (Server Admin > iCal > Settings > Log Level , and if asked, do restart the service. You will want to watch the caldavd error log, which is most easily done via the Terminal, by invoking:

sudo tail -f /var/log/caldavd/error.log

(if you are logged in as an administrator, you’ll need to use sudo to have permission to read the log file) and using (simultaneously) control (and) c , to cancel watching the log file.

As well, you should watch the postfix log for incoming and outgoing mail, via (a second Terminal window):

tail -f /var/log/mail.log

A successful email invitation should show up in the caldavd error log with some of the following:

 2010-04-05 10:45:22-0400 [-] [caldav-8009]  [PooledMemCacheProtocol,client]
[twistedcaldav.scheduling.imip#debug]
POSTing iMIP message to gateway...
To: 'mailto:username@externalhost.com',
From :'urn:uuid:<UUID for user account sending the invite>

<numerous lines excluded>

2010-04-05 10:45:23-0400 [-] [mailgateway] 2010-04-05 10:45:23-0400 [-]
[twistedcaldav.mail.MailHandler#debug]
Mail gateway sending calendar body

and then several entries beginning with a number enclosed in dashes, followed by:

MIME-Version: 1.0 

and then a whole lot of text representing base64-encoded content and ending with:

2010-04-05 10:45:23-0400 [-] [mailgateway] 2010-04-05 10:45:23-0400 [ESMTPSender,client]
[twistedcaldav.mail.MailHandler#info] Mail gateway sent message <20100405104523.55096.357159289.0@server.yourcompany.com>
from com.apple.calendarserver@yourcompany.com to mailto:user@externalhost.com

You should also see corresponding entries in /var/log/mail.log for the outgoing message, beginning with:

Apr  5 10:45:29 server postfix/smtpd[55185]: E0FBD128199: client=localhost[127.0.0.1]
Apr  5 10:45:29 server postfix/cleanup[55182]: E0FBD128199:
message-id=<20100405104523.55096.357159289.0@server.yourcompany.com>
Apr  5 10:45:29 server postfix/smtpd[55185]: disconnect from localhost[127.0.0.1]
Apr  5 10:45:29 server postfix/qmgr[93444]: E0FBD128199: from=<com.apple.calendarserver@yourcompany.com>, size=215955, nrcpt=1 (queue active)

As a final importantnote, be advised that greylisting is enabled by default in 10.6 Server mail service, and this will likely interfere with incoming replies to invitations sent to external entities.
You can either setup a whitelist, or disable greylisting – see http://www.google.com/search?q=10.6+server+disable+greylisting