5.3. iCal Server

So far in this chapter we have focused on using Mac OS X as a client to other solutions. Now we're going to shift gears a little and talk about using an entirely Apple-based groupware solution. The first step on this journey is using iCal Server to supply shared calendars to users. To do this, you will need an Open Directory environment, or at a minimum, augment records to another directory service. The augments will be created automatically if you first set up your OS X server in WorkGroup mode, bind to your directory service, and then use the Server Preferences tool rather than Server Admin to perform the setup.

iCal Server uses CalDAV, an extension of the WebDAV protocol that Microsoft Entourage can use to interface with Exchange. CalDAV is a well-defined open standard and so developing around it is in no way a black box. However, it is not as widely dispersed as Microsoft Exchange and so there are fewer tools that integrate with it. Still, nothing is likely to work better with iCal Server than the iCal client itself, included by default with all Mac OS X installations. Alternative clients include open source programs Mozilla Sunbird and the Mulberry email and calendaring application. Additionally, there are several third-party Outlook plug-ins available, though they tend to perform as second-class citizens.

5.3.1. Setting up iCal Server

To get started with iCal Server, first install the service. On a freshly installed Mac OS X Server that is either running as a directory server or already bound to one, open the Server Preferences application. Server Preferences can be found at /Applications/Server and when opened looks far less intimidating than Server Admin (see Figure 5-12). This is because Server Preferences is a fairly dummied down version of Server Admin.

To enable the iCal service, click on the orb just to the left of the iCal icon. Then, as shown in Figure 5-13, click on the Limit each calendar event's size to: field and provide a number (in megabytes for the maximum size of a calendar event, keeping in mind that calendar events can contain attachments). Next, click on the Limit each user's total calendar size to: field and provide a maximum per user. If you will not be using attachments, you can use a number around one megabyte or smaller, at which point storage becomes a minimal issue. Next, move the slider to the On position and the service will start up.

At this point you might be saying to yourself, "that can't be all there is." Well, you're right. You can use the iCal service in Server Admin in order to more granularly configure settings, as shown in Figure 5-14. To set up the iCal service from the Server Admin tool, click on the name of the server in the SERVERS list and then on the Settings icon. Next, click on the check box next to the iCal entry and you should see the iCal service appear in the SERVERS list underneath the name of the servers when you click on the Save button.

Now click on the iCal server entry and you will see a number of options, including:

• Data Store: The location on the server's file system for the iCal database.

• Maximum Attachment Size: The maximum size of a given attachment (and therefore the maximum size of a given event).

• User Quota: The maximum size of a user's calendar.

• Authentication: The authentication method used—Digest, Kerberos or Any Method. (Forcing to Kerberos or Digest can be useful in troubleshooting or to enforce encryption policies.)

• Host Name: The DNS name of the server (or service if you have multiple records pointing to the host).

• SSL: Allows you to select a certificate that has been installed on the host. Even if you are using a self-assigned certificate on the Mac OS X Server, you should use SSL when possible.

• HTTP Port Number: The port number that the HTTP iCal Service's listener uses.

• SSL Port Number: The port number that the SSL iCal Service's listener uses.

• Log Level: The verbosity with which you want the iCal server to trap event logs.

• Push Notification Server: By default this will list the current server, but it can be used to select another host in high-volume environments. The Push Notification Server enables the most seamless interaction between iPhone and Mac OS X Server's groupware services offerings. More on Push Notification later in this chapter.

  Figure 5.14. Configuring the iCal service using Server Admin

  

Once you are satisfied with your settings, click on the Save button to start up the service. Again, you may be thinking, "that can't be all the options, can it?" Again, you'd be correct. In addition to the two GUI panels developed by Apple, there are a host of other options that can be accessed using the serveradmin command. To see the available settings, use this:

serveradmin settings calendar

You will then see the following items:

calendar:SudoersFile = "/etc/caldavd/sudoers.plist"
calendar:DirectoryService:params:restrictEnabledRecords = no
calendar:DirectoryService:params:restrictToGroup = ""
calendar:DirectoryService:params:cacheTimeout = 30
calendar:DirectoryService:params:node = "/Search"
calendar:DirectoryService:type = "twistedcaldav.directory.appleopendirectory.

OpenDirectoryService"
calendar:Aliases = _empty_dictionary
calendar:BindSSLPorts = _empty_array
calendar:EnablePrincipalListings = no
calendar:DocumentRoot = "/Library/CalendarServer/Documents/"
calendar:EnableDropBox = yes
calendar:SSLPrivateKey = ""
calendar:ServerStatsFile = "/var/run/caldavd/stats.plist"
calendar:ProcessType = "Combined"
calendar:UserName = "calendar"
calendar:BindHTTPPorts = _empty_array
calendar:EnableAnonymousReadRoot = yes
calendar:HTTPPort = 8008
calendar:ServerHostName = ""
calendar:PIDFile = "/var/run/caldavd.pid"
calendar:Authentication:Digest:Algorithm = "md5"
calendar:Authentication:Digest:Qop = ""
calendar:Authentication:Digest:Enabled = yes
calendar:Authentication:Kerberos:ServicePrincipal = ""
calendar:Authentication:Kerberos:Enabled = yes
calendar:Authentication:Wiki:Enabled = yes
calendar:Authentication:Basic:Enabled = no
calendar:ReadPrincipals = _empty_array
calendar:EnableTimezoneService = yes
calendar:FreeBusyURL:AnonymousAccess = no
calendar:FreeBusyURL:Enabled = yes
calendar:FreeBusyURL:TimePeriod = 14
calendar:UserQuota = 104857600
calendar:MaximumAttachmentSize = 1048576
calendar:MultiProcess:ProcessCount = 0
calendar:EnableProxyPrincipals = yes
calendar:DefaultLogLevel = "warn"
calendar:EnableMonolithicCalendars = yes
calendar:ErrorLogFile = "/var/log/caldavd/error.log"
calendar:SSLCertificate = ""
calendar:EnableSACLs = no
calendar:Notifications:CoalesceSeconds = 10
calendar:Notifications:Services:XMPPNotifier:Host = "snowleopardserver.krypted.com"
calendar:Notifications:Services:XMPPNotifier:JID = "com.apple.notificationuser@

snowleopardserver.krypted.com"
calendar:Notifications:Services:XMPPNotifier:Enabled = yes
calendar:Notifications:Services:XMPPNotifier:Service = "twistedcaldav.notify.

XMPPNotifierService"
calendar:Notifications:Services:XMPPNotifier:Port = 5222
calendar:Notifications:Services:XMPPNotifier:ServiceAddress = "pubsub.

snowleopardserver.krypted.com"
calendar:EnableAnonymousReadNav = no
calendar:DataRoot = "/Library/CalendarServer/Data/"
calendar:BindAddresses = _empty_array
calendar:AdminPrincipals = _empty_array
calendar:RedirectHTTPToHTTPS = no
calendar:RotateAccessLog = no
calendar:GroupName = "calendar"
calendar:EnablePrivateEvents = yes
calendar:AccessLogFile = "/var/log/caldavd/access.log"

calendar:Scheduling:CalDAV:EmailDomain = ""
calendar:Scheduling:CalDAV:HTTPDomain = ""
calendar:Scheduling:CalDAV:AddressPatterns = _empty_array
calendar:Scheduling:iSchedule:Servers = "/etc/caldavd/servertoserver.xml"
calendar:Scheduling:iSchedule:Enabled = no
calendar:Scheduling:iSchedule:AddressPatterns = _empty_array
calendar:Scheduling:iMIP:Receiving:Server = ""
calendar:Scheduling:iMIP:Receiving:UseSSL = yes
calendar:Scheduling:iMIP:Receiving:PollingSeconds = 30
calendar:Scheduling:iMIP:Receiving:Username = ""
calendar:Scheduling:iMIP:Receiving:Type = ""
calendar:Scheduling:iMIP:Receiving:Password = ""
calendar:Scheduling:iMIP:Receiving:Port = 995
calendar:Scheduling:iMIP:MailGatewayServer = "localhost"
calendar:Scheduling:iMIP:Enabled = no
calendar:Scheduling:iMIP:MailGatewayPort = 62310
calendar:Scheduling:iMIP:AddressPatterns = _empty_array
calendar:Scheduling:iMIP:Sending:Server = ""
calendar:Scheduling:iMIP:Sending:Username = ""
calendar:Scheduling:iMIP:Sending:Address = ""
calendar:Scheduling:iMIP:Sending:UseSSL = yes
calendar:Scheduling:iMIP:Sending:Password = ""
calendar:Scheduling:iMIP:Sending:Port = 587

Many of these settings appear fairly cryptic, but you'll find they allow for very granular configuration of the service. You can customize these items by using the same command and but pasting the particular setting on to the end of it, along with the desired value. For example, if you want to force all users who can authenticate into the iCal service to have an account in the directory services, you would use the following command:

serveradmin settings calendar:DirectoryService:params:restrictEnabledRecords = yes

You can further reduce the maximum attachment size to the bytes level using the calendar:MaximumAttachmentSize setting.

5.3.2. Managing Calendars

Once you have enabled the iCal service, you will want to provide access to calendars for your users. To do so, you can enable the service for an account, again using the Server Preferences tool. Simply open Server Preferences and click on the name of a user you'd like to configure and you'll see a listing of services the user can access on the right side of the screen as in Figure 5-15.

The next step is to set up iCal on the user's workstation. To get started, open iCal from the /Application directory, then click on the iCal menu, selecting the preference option (or use the Command+comma keystroke). Next, click on the Accounts icon in the application preferences toolbar and then on the plus (+) sign. You will see the Add an Account screen where you can fill in the name, e-mail address, and password of the user whose account you are setting up (see Figure 5-16). Click on the Create button when you are finished.

The server will now look up the account type and automatically fill it in for you (see Figure 5-17). If it can't find an account type, it will automatically select CalDAV. (iCal supports both Exchange 2007 and CalDAV.) Next, fill in the Description field with a name that will appear in iCal for the calendar and then fill in the Account URL, which should generally be http:// or https:// followed by the name of the server and then the calendar in question, (for example, http://myserver.com/calendarname). Next, supply the username and password for the user whose calendar was just enabled, clicking on the Create button when you are ready to move to the next screen. If you are in a Kerberized environment, you can click on the Use Kerberos v5 for authentication check box to enable Kerberos access (standard Kerberos considerations apply).

If you don't enable Kerberos or SSL, you will be prompted as to whether you want to use an unsecured connection. Now you can click on the Continue button to complete the setup of your server as seen in Figure 5-18.

5.3.3. Delegating Access

Using iCal Server, it is possible to delegate access to a user's calendar from another user. Once your account has been configured in iCal, you can access delegation capabilities through the Accounts tab of iCal preferences, as shown in Figure 5-19. With iCal open, select Preferences under the iCal menu, and then select Accounts. From here, highlight your account and select the Delegation Tab. You can then click the Edit button at the bottom of the window to access the delegation tab, where you can add users and grant them read only or write privileges as desired.

5.3.4. Backing up Calendars

The calendar file itself is located by default in the /Library/CalendarServer/Documents directory. You can customize this folder, so when you're going to back it up, be careful that no one has changed the default location. Simply backing up the contents of this directory with standard software will provide an archive of the data. You can verify the directory used by your Calendar store by running the command:

serveradmin settings calendar:DocumentRoot

However, you may choose to back up the settings for the service as well. To do so, you can use the serveradmin command and list all of the settings as shown earlier in this chapter. But this time we will push the contents into a file by adding the greater-than symbol > at the end of the command, followed by the file name. For example, the following will back up the service settings to a file called icalbak in the /backups directory:

serveradmin settings calendar > /backups/icalbak

5.3.5. Clustering CalDAV

In Chapter 4 we covered storage options for Mac OS X. Assuming you are using a storage medium capable of supporting multiple writes on the same volume, you can use the iCal service in a clustered fashion. Clustering iCal Server can provide an Active-Active solution, giving users a performance boost if the connections on your server are saturated, and also providing high availability.

To cluster the iCal service, you configure two iCal servers in an identical manner. To do this, you can configure the settings as you just did when backing up the iCal server to the /backups/icalbak file. To configure the same settings on the second host, use the same serveradmin command but swap the > for a <, assuming that the icalbak file has been copied to the same location on the second server:

serveradmin settings calendar < /backups/icalbak

After running this, update the SSL settings on the second host to ensure a proper SSL cert is specified. Next, we'll move the calendar files to the server in a shared directory location. In this case, we'll copy the /Library/CalendarServer directory to the /volumes/Xsan/ volume we previously created. Then we'll point the directories for the calendar server at our shared storage:

serveradmin settings calendar:DocumentRoot = "/Volumes/Xsan/CalendarServer/Documents/"
serveradmin settings calendar:DataRoot = "/Volumes/Xsan/CalendarServer/Data/"

When you are comfortable with the settings, stop and start the iCal service:

serveradmin stop calendar
serveradmin start calendar

The part that is up to you is how to distribute the load across the two servers. Load balancers are the most obvious choice in many environments, but operating in a shared namespace and using round robin DNS will work as well, likely incurring no additional hardware costs for your setup (beyond, of course, having two or more copies of the Mac OS X Server software).

5.3.6. Wiki Integration

Users are also able to view and manage calendars through the OS X server's web services, provided it is enabled. To do so, simply turn on Calendar Services through the web pane of Server Preferences, as seen in Figure 5-20. The web interface, also shown in Figure 5-20, allows users full read and write access to their calendars, and enables them to create new calendars, schedule events and send invites, and view free/busy schedules. Notable limitations include the inability to access delegated calendars, to-dos do not register, nor can you attach files to events.

5.3.7. Troubleshooting

So you installed your new server and you're having a few problems. Let's look at the common issues and a few simple fixes for them.

If you find yourself in a situation where iCal will not start, there are a few things you can try. As always, consult the log entries. In many cases where the service simply won't start, your log entries may indicate that the service is unable to create a virtual host. This is typically a DNS related problem so check your host name. iCal needs the host name to be correct in order to start. Use scutil -get HostName or changeip -checkhostname to verify DNS resolution. Next, make sure that the host name listed in the iCal Server settings is identical to this value. If you prefer to use the serveradmin CLI to control your services, you can also use the command:

serveradmin settings calendar:ServerHostName

And then configure the setting using:

serveradmin settings calendar:ServerHostName  = "SomeHostName"

You can also use the calendar:HTTPPort to change the port number you are using for connectivity.

If the service is reportedly running, but you still don't have connectivity, you can verify that your iCal server is running by visiting it in a web browser at http://icalserver.myco.com:8008/

If the server is up and running, you should be presented with a generic web page that lists various XML configuration settings used by the Python-based twistd engine that iCal server is based on. If the service is not running, verify proper settings of the service, paying close attention to the Document Root. Verify that there is a data store at this location, which will be nested inside of two folders: Data and Documents. Verify that the calendar user _calendar is the owner of these directories and has full read/write/execute access.

Here's another common problem with the iCal server: you set up a user, check the box in Workgroup Manager to Enable Calendaring, and then save your settings—but you get the following error in your logs:

Jul10 10:21:56 cedge Workgroup Manager[2282]: +[WPUser userWithGUID::] returned nil!

In this case, you are probably enabling a calendar for a local user. Make sure you are using an OD-based user and see if you get the same error. Likewise, you can navigate to the user calendar URI in a web browser:

http://icalserver.myco.com:8008/principals/users/snowcat

If you receive a 404 when browsing to this address, the calendar server is not properly resolving the user record.

Another issue you may run across occurs when everything is configured and the account has been created for the user, but when you add the account in iCal it fails to connect. If you find yourself in this situation, verify that the port specified at the end of the hostname in the http:// URL is correct. Verify that you can connect to the remote server port via telnet if necessary, or by using a web browser as previously discussed. When you connect to the server this way, you will be prompted to authenticate. If you can authenticate as the user whose calendar you are trying to set up, you can use the information in this screen to determine ACL information and other security settings that could be keeping the calendars from working. Pay attention as well to the authentication method you are using. If you have selected Kerberos authentication only, your client will need to be able to directly contact the KDC to receive the proper service principal. Also keep in mind that while your default port might be 8008, if you are using SSL your default port is actually 8443.

Once you get this far, you should be able to create an event and see data listed in the Overview tab for iCal. If so, you should be able to find out about anything you want in the iCal server.