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:

https://zimbra.example.com/dav/<YOUR USERNAME HERE>/Calendar

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

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

# CALDAV
[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 = "https://nextcloud.example.com/nextcloud/remote.php/dav/Calendar"
username = "user@example.com"
password = "PUT A PASSWORD OR APPTOKEN HERE"

[storage calendar_remote]
type = "caldav"
url = "https://zimbra.example.nl/dav/other-user%40example.nl/Calendar"
username = "other-user@example.nl"
password = "PUT A PASSWORD OR APPTOKEN HERE"

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: http://vdirsyncer.pimutils.org/en/stable/tutorial.html?highlight=collections#more-information-about-collections 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

• https://vdirsyncer.pimutils.org/en/stable/tutorials/index.html#supported-servers