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
:doc:`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.