Advanced usage

Using CalDAV via a Unix Domain Socket

Aside from connecting to servers via HTTP, pimsync can connect to servers via a Unix domain socket (see unix(7)). This feature is considered an “escape hatch” for connecting to servers which require any transport feature not natively supported by pimsync.

This feature allows tunnelling the connection to a server which is not directly reachable. Some example usages are:

• Using ssh -L path/to/local/socket:…, to tunnel a remote socket or port.

• Using an HTTP proxy server (e.g.: nginx) to perform any rewrites (or either requests and/or responses), perform TLS client authentication, or any other custom feature.

Using a Unix socket instead of a TCP socket facilitates exposing a service to a single local user (or group of users) without having to reconfigure a local firewall.

If you are running your local CalDAV on a Unix domain socket, you can configure pimsync to communicate with it directly without having to expose the server on a TCP port.

To use CalDAV or CardDAV with a Unix domain socket, use configure a url in the style of unix:///path/to/socket. See STORAGE SECTIONS in the pimsync.conf.5 manual page.

One instance per pair

If pimsync daemon encounters a fatal error when synchronising a pair (i.e.: cannot read or write from the status database), it will stop synchronising that pair and continue with others. Pimsync will exit only if all pairs have failed.

As a result, it might not be entirely obvious when a single pair has encountered a fatal error.

Running one pimsync process per pair provides better status indication when executed via a service manager. When a single pair fails, that process will exit, and the service’s status would reflect this failure.

Running one instance per pair also yields cleaner logging, since each pair logs into a separate the stderr of separate processes.

This is considered an advanced usage because it requires that you configure your service manager to run multiple instances of the pimsync service.