OS X Mavericks Server – Setting Up Contacts

The Contact service in OS X Mavericks Server is a great way to easily sync contacts between users and groups. Along with the Calendar service, it has deep ties with the Apple Push Notification Service (APNS) to push all new changes to your devices.

Contents

What you may not know is that the Contact service is actually tied into the Calendar service. If you enter serveradmin settings calendar and serveradmin settings addressbook you’ll find that they match line for line (with exception to the name of course). You may also notice that there’s not really much that can be configured for Contacts (annoyingly, Contacts is still called Address Book in the serveradmin backend), pretty much the only thing you can change in the GUI are settings for APNS and whether Address Book is allowed to query the Directory Service.

Open up the Server app and click on the Contacts section so we can start it up! Click the On button to start the Contacts server! If you enter tail -f /var/log/caldavd/servermgr_calendar.log in Terminal before you turn Contacts on, you’ll see the config changes get pushed, then the collaboration services will restart.

Now that Contacts is running, you’re pretty much done! You can optionally allow contacts to be shared via LDAP, but that’s not a requirement. Typically you won’t need to enable this.

Pro-Tip: SRV Record For Easy Configuration

Along with Calendar, you can set up a SRV DNS record for the CardDAV TCP protocol. Essentially, it’s like an MX record, but for other protocols. We can utilise the DNS service in OS X Mavericks Server to create this SRV record.

If you open up the Server app and go to the DNS section, I’ll show you how to create a SRV record. Select your Primary Zone, then hit the + (plus) in the bottom-left corner, then click “Add Service Record…”. This will bring up a window overlay with some empty fields.

In these tutorials we’ve only been working with a primary zone, so we won’t change it. Actually, you can’t even change it (because there’s only one zone), so don’t even bother trying. The primary zone should be your domain name.

Next, for Service Name, leave this blank as we aren’t using any Bonjour browser goodness. Finally, the first field we actually enter something in is Service Type. Because we’re using the SSL version of the CardDAV protocol over TCP, we will enter _carddavs._tcp. If you don’t want to use SSL (why?), enter _carddav._tcp.

For the host name, enter the FQDN (Fully Qualified Domain Name) of the server you want to be your CardDAV server. Given the fact that in these examples we have only been using one server, just enter the host name for your server. Mine is mavericks.pretendco.com. The next field is Port, which defines what port this service is running on. Because we’re using SSL, we’ll enter in 8443. If you weren’t using SSL, you’d enter 8008.

If you’re unsure what port your Contact server is using, enter the command below to get your port. Note the command to the right of either command, use the top one if you use SSL, use the bottom command if you don’t.

sudo serveradmin settings addressbook:SSLPort # Using SSL
sudo serveradmin settings addressbook:HTTPPort # Not Using SSL :(

If you really have no idea if you’re using SSL or not, you can enter sudo serveradmin settings addressbook:RedirectHTTPToHTTPS to find out if you are. If the answer is yes, then you’re using SSL.

Okay, that’s enough ranting about ports. The last two important fields are Priority and Weight. As I’ve said a few times earlier, we’re only using one server in these examples, so enter 0 for Priority and 1 for Weight. The final field is Text, we are leaving it blank. Some services may need some information in the Text field, but CalDAV/CardDAV don’t.

For a more readable list, see below:

  • Zone: pretendco.com
  • Service Name: Leave Blank!
  • Service Type: _carddavs._tcp
  • Host Name: mavericks.pretendco.com
  • Port: 8443
  • Priority: 0
  • Weight: 1
  • Text: Leave Blank!

All in all, you should have something that looks like this:

CardDAV SRV Record
The CardDAV SRV Record.

Now that you’re done, click Create to create the SRV record. If all goes well, you should be taken back to your DNS Records list, and your new SRV record should be in that list. If not, you probably did something wrong (hint: maybe you put a space in the Service Name field). To verify that the SRV record has been added, enter the following command in Terminal on the server:

dig SRV _carddavs._tcp.pretendco.com

If all goes well, you should see something like this:

; <<>> DiG 9.8.3-P1 <<>> SRV _carddavs._tcp.pretendco.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 10499
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 1

;; QUESTION SECTION:
;_carddavs._tcp.pretendco.com. IN SRV

;; ANSWER SECTION:
_carddavs._tcp.pretendco.com. 10800 IN SRV 0 1 8443 mavericks.pretendco.com.

;; AUTHORITY SECTION:
pretendco.com. 10800 IN NS mavericks.pretendco.com.

;; ADDITIONAL SECTION:
mavericks.pretendco.com. 10800 IN A 10.1.125.120

;; Query time: 4 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Sat Oct 19 22:27:32 2013
;; MSG SIZE rcvd: 119

Hooray, everything is OK.

Setting Up In Contacts.app Using CardDAV

So, you’ve got the Contacts service up and running, and now you want to add it to the Contacts app in OS X Mavericks so your users can start adding contacts to their contact list. Open up the Contacts app then go to Preferences then click on the Accounts pane.

Contacts: Add Other Contacts Account
Contacts: Add Other Contacts Account.

Hit the + (plus) in the bottom-left corner to add an account. Because we’re using our own contact system, use the option at the very bottom called “Other contacts account…” then click Continue. Sadly, Contacts still isn’t as nice as Calendar when setting up a custom CardDAV account, you don’t get the nice automatic/manual/advanced options. All you get is CardDAV or LDAP. Given that we’re using CardDAV, ensure that CardDAV is selected.

Contacts: CardDAV User Details
Contacts: CardDAV User Details.

In the User Name field, enter your username. I’m going with Jim Halpert, so I’ll enter in jhalpert. Next up is the Password, and Jim’s password is pam.

Finally, we enter the Server Address. If you did the SRV record step about, you only have to enter your domain name! In my case, it’s pretendco.com. If not, enter the FQDN for your server (mavericks.pretendco.com). If you try and set up the user using the SRV method and you haven’t made the SRV record, you’ll get an error about not being able to make a secure connection. If all is successful, click Create to create the user.

Note: In my testing, I’ve noticed that on OS X Mavericks when adding the CardDAV account Contacts.app freezes for a couple of seconds before adding the account, or it freezes until killed. Just take that into account when adding your account!


OS X Mavericks Server – Setting Up Calendaring

The Calendar service in OS X Mavericks Server is a really easy way to get collaboration between users set up, along with allowing them to allocate resources and locations within your business to events. With deep ties in the Apple Push Notification Service (APNS) and Mail services, notifying people about your events is quick and easy.

Contents

Getting Started

First up, let’s actually get Calendaring up and running! Open the Server app and click on the Calendar section. Hit the little On button to start it up!

When turning on Calendar for the first time, or when you’re upgrading, it’s worth taking a look at a few logs to get an idea of what’s happening in the backend. Getting in the habit of reading logs is a great way to learn, and of course, troubleshoot. All of the Calendaring logs are stored in /var/log/caldavd/, but the most interesting logs at this stage will be /var/log/caldavd/servermgr_calendar.log, /var/log/caldavd/migration.log and /var/log/caldavd/error.log. Once the Calendar server has started we’re ready to rock and/or roll.

Calendar Is Now On!
The Calendar service is now running!

Pro-Tip: SRV Record For Easy Configuration

If you are hosting DNS on your server, or have full access to creating DNS records with your hosting provider, you can add SRV records that can make it that little bit quicker to add Calendar accounts for all your users. From here on, I’m assuming you’re creating the DNS record in the Server app.

Go to the DNS section of the Server app, and click the + (plus) in the bottom-left corner then click on “Add Service Record…”

Because we only have one DNS zone (aka, the Primary Zone), leave the Zone field alone (if you’ve only got one zone, you can’t even change it). Leave the Service Name field blank as it is for an optional Bonjour browsing field, which we aren’t using.

Next up, we enter the Service Type. The Server app thinks it can be helpful by offering you a few suggestions, but the CalDAV service isn’t listed there. We need to add it. In the Service Type field, enter _caldavs._tcp. If you’re not using SSL, remove the s from caldavs.

For Host Name, enter your hostname. I will be entering mavericks.pretendco.com. As we are using SSL, we’ll put in 8443 as that is the default SSL port for CalDAV. If for some reason you decided you aren’t using SSL, you should enter 8008 as the port instead.

If you’re using multiple servers for collaboration, you can specify different priority and weight numbers. In a normal environment with one server, we will enter 0 for priority, and 1 for weight, as they are the defaults. Leave Text blank, we don’t need it.

For a more readable list, see below:

  • Zone: pretendco.com
  • Service Name: Leave Blank!
  • Service Type: _caldavs._tcp
  • Host Name: mavericks.pretendco.com
  • Port: 8443
  • Priority: 0
  • Weight: 1
  • Text: Leave Blank!

You should now see something like this:

CalDAV SRV Record
The CalDAV SRV Record.

To double-check this is working, enter the following command in Terminal:

dig SRV _caldavs._tcp.pretendco.com

With any hope, you should see the following result:

; <<>> DiG 9.8.3-P1 <<>> SRV _caldavs._tcp.pretendco.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 21649
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 1, ADDITIONAL: 1

;; QUESTION SECTION:
;_caldavs._tcp.pretendco.com. IN SRV

;; ANSWER SECTION:
_caldavs._tcp.pretendco.com. 10800 IN SRV 0 1 8443 mavericks.pretendco.com.

;; AUTHORITY SECTION:
pretendco.com. 10800 IN NS mavericks.pretendco.com.

;; ADDITIONAL SECTION:
mavericks.pretendco.com. 10800 IN A 10.1.125.120

;; Query time: 0 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Sat Oct 19 16:28:47 2013
;; MSG SIZE rcvd: 118

Hooray! Your SRV record is now working correctly. Go over to the Calendar app and we can set up a user account. Open Preferences in the Calendar app and jump over to the Accounts section, then click the + (plus) to add a new account

Calendar: Add a New Account
Add a New Account in the Calendar app.

Now, choose the option “Add CalDAV Account…” and then click Continue.

Calendar: CalDAV Account Details
Add Our User Using the “Automatic” Method.

Because we set up the SRV record, we don’t have to choose the “Manual” or “Advanced” options. Type in your email address and password, then click Create. For example, the user Jim Halpert that we set up earlier, we would enter the details below:

  • Email Address: jhalpert@pretendco.com
  • Password: pam

Once you’ve clicked Create, you should be taken back to the Accounts pane of Preferences. The first thing I change is the Description to the first name of the user. For example, I’ll change it to Jim. The only other option you might want to change is the Availability field.

Calendar: Account Settings
Account Information for the User Jim Halpert.

Email Invitations

First up, we’ll configure our Email user that will be able to send and receive calendar invitations. To do this, check the box next to “Enable invitations by email”. This will run you through a few steps of configuration, most of which you shouldn’t have to change.

Set Up A Calendar Email User
Set Up A Calendar Email User.

The first setting to review is the email address of the Calendar user. Normally, I would leave this as com.apple.calendarserver@mavericks.pretendco.com, but you can change it to another user (if you’ve already added them into the Open Directory database). It would be wise to leave it alone.

Enter the Calendar Email User IMAP Details
Enter the Calendar Email User IMAP Details.

Next up is configuring the incoming mail server settings for the Calendar email user. If the server you’re configuring is the same server as your Mail server, you won’t have to change a thing. Otherwise, you’ll have to enter your Mail server settings for IMAP (or POP, but please tell me you’re using IMAP!). Note that the email address you chose in the first step should match the user name for authentication.

Enter the Calendar Email User SMTP Details
Enter the Calendar Email User SMTP Details.

Now it’s time to configure the SMTP server settings for sending Calendar invitations. Like above, you may not have to change any settings at all, but if you’re using another Mail server, enter the configuration details as applicable.

Double-Check Your Email User Settings
Double-Check Your Email User Settings.

Finally, ensure all your settings are correct before clicking Finish. Once you click Finish, the Calendar server will restart to save those changes. Now you’re all done configuring mail for the Calendar service. For the curious, enter sudo serveradmin settings calendar | grep "iMIP" to see all the settings for the sending and receiving of Calendar invitations by email.

If you create a sample event then invite yourself using an email address, you’ll get an email invitation that has some interesting information that you can look at.

You’ll notice that the reply-to email address is in the format calendar-email-user+event-guid@domain.com. For example, a sample event I did had the reply-to email address com.apple.calendarserver+35f7b7c1-1295-4513-a9b7-c859ec3a7d94@mavericks.pretendco.com. This uses the concept of email address tagging whereby you have the local part of the email address (com.apple.calendarserver, mscott, etc) then you add a + (plus) and enter the tag. What this does is allows the mail server to do is, using a combination of rules, direct email flow depending on what tag it has. A few modern mail providers (like Gmail) support tagging. Essentially, if I replied to the email address com.apple.calendarserver+35f7b7c1-1295-4513-a9b7-c859ec3a7d94@mavericks.pretendco.com, the inbuilt mail server would know that this email is related to the event that has a GUID of 35f7b7c1-1295-4513-a9b7-c859ec3a7d94. Pretty clever huh?

Another neat’o trick is when you invite someone who isn’t in Open Directory domain they’ll get an email with the event details, along with an .ics that they can add to their own calendar! For those curious about what an .ics (or iCalendar file) contains, take a look below: BEGIN:VCALENDAR
CALSCALE:GREGORIAN
VERSION:2.0
X-WR-CALNAME:Board Meeting
METHOD:PUBLISH
PRODID:-//Apple Inc.//Mac OS X 10.9//EN
BEGIN:VTIMEZONE
TZID:Australia/Melbourne
BEGIN:STANDARD
TZOFFSETFROM:+1100
RRULE:FREQ=YEARLY;BYMONTH=4;BYDAY=1SU
DTSTART:20080406T030000
TZNAME:AEST
TZOFFSETTO:+1000
END:STANDARD
BEGIN:DAYLIGHT
TZOFFSETFROM:+1000
RRULE:FREQ=YEARLY;BYMONTH=10;BYDAY=1SU
DTSTART:20081005T020000
TZNAME:AEDT
TZOFFSETTO:+1100
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VEVENT
TRANSP:OPAQUE
DTEND;TZID=Australia/Melbourne:20131022T110000
X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-TITLE="Meeting Room 1, 13927 Saticoy Street, Panorama City, CA 91402, USA":
ORGANIZER;CN="Michael Scott";EMAIL="mscott@pretendco.com":urn:uuid:1C3F7FD2-2ECA-4F5E-A332-458D59BF3EAE
UID:4E773374-E5C3-4F66-9E71-7F151D31E7B2
DTSTAMP:20131019T003921Z
LOCATION:Meeting Room 1\, 13927 Saticoy Street\, Panorama City\, CA 91402\, USA
DESCRIPTION:Be sure to bring the monthly reports.
SEQUENCE:12
X-CALENDARSERVER-ATTENDEE-COMMENT;X-CALENDARSERVER-ATTENDEE-REF="urn:uuid:B6103F55-0E50-4254-80B45CFF73E32B8E";X-CALENDARSERVER-DTSTAMP=2013101 9T003950Z:Will bring this months estimates too!
SUMMARY:Board Meeting
DTSTART;TZID=Australia/Melbourne:20131022T100000
CREATED:20131018T225816Z
ATTENDEE;CN="Jim Halpert";CUTYPE=INDIVIDUAL;EMAIL="jhalpert@pretendco.com";PARTSTAT=NEEDS-ACTION;ROLE=REQ-PARTICIPANT;RSVP=TRUE;SCHEDULE-STATUS="1.2":urn:uuid:7FD59E48-6836-4AC4-9674-284B1FC383BD
ATTENDEE;CN="Michael Scott";CUTYPE=INDIVIDUAL;EMAIL="mscott@pretendco.com";PARTSTAT=ACCEPTED:urn:uuid:1C3F7FD2-2ECA-4F5E-A332-458D59BF3EAE
ATTENDEE;CN="Pam Halpert";CUTYPE=INDIVIDUAL;EMAIL="phalpert@pretendco.com";PARTSTAT=ACCEPTED;ROLE=REQ-PARTICIPANT;SCHEDULE-STATUS="2.0":urn:uuid:B6103F55-0E50-4254-80B4-5CFF73E32B8E
END:VEVENT
END:VCALENDAR

And here is the event in Calendar:

Event: Board Meeting
The Board Meeting event as it appears in the Calendar app.

Resources & Locations

As with almost any other calendaring solution, OS X Mavericks Server has the ability to define unique resources and locations. These resources and locations are defined as invitees so you can allocate them events as, you guessed it, resources and locations.

For example, say the company has a car that can be used by employees for onsite visits or meetings. For them to use the car, they first have to allocate it to their event. If the car is already being used by someone else, they will be told when adding the car that it is not available, otherwise, they’ll be able to add the car to the event and have it assigned to them. First, we need to create the car resource!

Resource: PretendCo Car
Resource: PretendCo Car

In the “Locations and Resources” section of the Calendar pane in the Server app you’ll see a + (plus) in the bottom-left corner. Click it to create a new Location or Resource. Since the car is obviously a resource and not a location, we’ll make the Type a “Resource”.

Next, we need to give the resource a unique name. Given that PretendCo only has one car, we’ll call the resource “PretendCo Car”. We’re going to trust our employees enough to be able to organise the car amongst themselves so we won’t require the resource to be approved by a delegate.

Finally, with Delegate, I’m going to leave it blank. You can however enter a username or groupname that can both view and manage the resource (or location). Even though you have automatically accept requests for this resource, delegates can override that status to manually deny a request.

Click Create to create your first resource! You can now assign this resource in an event by entering “PretendCo Car” as an invitee. Give it a go, you’ll see that the PretendCo car is automatically approved.

Next up is Locations. Locations, like Resources, give you the ability to define specific locations that are applicable for your server, and allow people to assign locations to their events. Along with resources, these can be reserved, and give users that are trying to organise times for locations the ability to check their availability.

Location: Meeting Room 1
Location: Meeting Room 1

Like we did with resources, click the plus in the bottom-left corner to create a new location. Make sure to change the Type to Location in the drop down menu. You need to ensure that locations are actually added as locations, because you add them in a different place when creating an event.

Next we give it a name. I’m going to go with “Meeting Room 1” because it’s simple. Because this is a meeting room, I’m going to make the Management group approve every request to use the room. Why? Because I can. And it’s a good reason to talk about delegation. With that in mind, change Accepted Invitations to “With Delegate Approval” in the drop down menu.

In the Delegate field you can enter either a username, or a group name if you’d like a specific group to manage delegation. For example, if you have one person in the company you trust to manage delegation, enter that person’s username into the field. Otherwise, you may have a group of people that manage delegation, so enter their group name in.

Finally, for Accept Group, you can enter the name of a group that this location will automatically accept requests from, even if you require invitations to be accepted with delegate approval. Typically, you would probably add your Management group to that list. For PretendCo, I did.

Click Create and you have now created your first location. Open up the Calendar app and create an event. The field down from the event title is location. Start typing in Meeting Room 1, Calendar should predict you’re going to invite Meeting Room 1, so click on it (or press Return). Note that if you assign a location that’s in the Open Directory domain, you can add a secondary location, i.e. the address of said Meeting Room 1. See my event below for an example of two locations being assigned for 1 event.

Calendar Event with a Location and Address
Calendar Event with a Location and Address.