Introducing vdirsyncer for migrating calendars and addressbooks

Vdirsyncer is a command-line tool for synchronizing calendars and addressbooks between servers such as Zimbra and Nextcloud or any server that supports open standards such as CalDAV/CardDAV. Aditionally Vdirsyncer support Google Calendar and Google Contacts. While vdirsyncer excels at migrating calendar and address book data, it’s worth noting that email data migration can be achieved using tools like IMAPSync. However, since IMAPSync is a well-known solution, we won’t cover it in detail in this blog.

If you are in a situation where you are considering migrating using IMAPSync you may also want to take a look at vdirsyncer, this way you can migrate contacts, calendar and email data. Please note that this kind of a migration will not keep user settings, shares and so on. If you need a full fledged zimbra-to-zimbra migration please see the Zimbra wiki.

Vdirsyncer can do two-way sync, but for migrations it is recommended to have an empty target account. As that will make it easier to confirm if the migration works.

Installing vdirsyncer

Vdirsyncer is included in Ubuntu and in Redhat/CentOS via Epel. So you should be able to install it using:

apt install vdirsyncer
# or
dnf install vdirsyncer

Next you have to create a folder for storing vdirsyncer configuration

mkdir -p  ~/.config/vdirsyncer

Syncing a calendar

Next you have to configure vdirsyncer in this example we are going to synchronize one Calendar between Zimbra and Nextcloud . You can find the URL’s for Zimbra Calendar and Address book on the Zimbra wiki. But the URL to use for the default Zimbra calendar is:<YOUR USERNAME HERE>/Calendar

Now you would set-up ~/.config/vdirsyncer/config with the following content:

# A folder where vdirsyncer can store some metadata about each pair.
status_path = "~/.vdirsyncer/status/"

[pair my_calendar_to_sync]
a = "calendar_local"
b = "calendar_remote"
collections = ["Calendar"]

# Calendars also have a color property
metadata = ["displayname", "color"]

[storage calendar_local]
type = "caldav"
url = ""
username = ""

[storage calendar_remote]
type = "caldav"
url = ""
username = ""

Implementation differences

Once you have set-up Vdirsyncer you have to run the discover command to see if the configuration is correct using:

vdirsyncer discover

In many cases it will not be correct. This is due to differences in implementations.

For example if you synchronize only one calendar, the calendar needs to have the same resource name on both sides. For example Zimbra always has the Calendar calendar. This name cannot be changed, even if you change it in the UI, the resource name will stay the same. This works the same for almost all calendar servers. In the Nextcloud UI you can create a calendar and input Calendar in the UI, but Nextcloud always lowercases it, so it becomes calendar. This will not work as in Zimbra it is Calendar. The solution in this case is to not have the calendar pre-created in Nextcloud but have Vdirsyncer create it.

You will also find that some calendar servers will always return ALL calendars on an account regardless whether you use the URL to a single calendar or the root of the account. In some cases you will not be able to create calendars with the same name. In these cases you will need to create a mapping in the collection parameter. See: Long story short, it will take some effort, but in the end it does what it promises.

After the discover command runs successful you can sync the calendars using:

vdirsyncer sync

The good news is, that just like with IMAPSync you can script all this, and do an initial sync. So most of your data is migrated. Then you can do another sync just after cutting over to the new server.

Further reading


6 Responses to Introducing vdirsyncer for migrating calendars and addressbooks

  1. Joe March 28, 2024 at 5:59 AM #

    Hmmm…I wonder if this can be used for bi-directional sync between the Webex Desktop app and Zimbra?

    • Avatar photo
      Barry de Graaff April 2, 2024 at 7:17 AM #

      If Webex supports CalDAV it should work.

  2. Paul April 9, 2024 at 7:43 AM #

    Does it support authentication with admin user or only with user credentials?

    • Avatar photo
      Barry de Graaff April 22, 2024 at 1:17 AM #

      Only user credentials if you are using the default set-up. If you add external authentication or custom authentication you can use admin credentials.

  3. Paul May 15, 2024 at 8:11 AM #

    There are guides for setting up external authentication or custom authentication on vdirsyncer?

    • Avatar photo
      Barry de Graaff May 16, 2024 at 10:44 PM #

      I am not saying it is without effort, but here goes:

      Assume your users are using Zimbra LDAP to authenticate and you want to use a different admin credential to do something with vdirsyncer, you can use zimbraAuthFallbackToLocal set to TRUE. Then you admin credential can be validated using the custom auth, and the users would still use the Zimbra LDAP credential. Be careful when implementing authentication, as the impact is high if it is done incorrectly.

Leave a Reply

Copyright © 2022 Zimbra, Inc. All rights reserved.

All information contained in this blog is intended for informational purposes only. Synacor, Inc. is not responsible or liable in any manner for the use or misuse of any technical content provided herein. No specific or implied warranty is provided in association with the information or application of the information provided herein, including, but not limited to, use, misuse or distribution of such information by any user. The user assumes any and all risk pertaining to the use or distribution in any form of any subject matter contained in this blog.

Legal Information | Privacy Policy | Do Not Sell My Personal Information | CCPA Disclosures