Unix domain sockets

Unix domain sockets provide a secure, high-performance, stream-based transport accessible via filesystem endpoints. They come with a few platform restrictions, caveats, and additional configuration options which are outlined below.

Platform support

Unix domain sockets are supported on POSIX systems and Windows 10 (build 17063 or later).

Access rights

Filesystem socket entries have permissions just like any other file, and these are often critical to ensuring the security of an application. Mutagen allows socket ownership and permissions to be set for the listener sockets it creates.

Caution: Due to POSIX and Windows API limitations, there will be a very small window when creating a Unix domain socket where the socket endpoint is visible on disk with its default permissions before Mutagen can set the specified ownership and permissions. On POSIX systems, the Unix domain socket will be created with ownership based on the user running the Mutagen daemon or agent process and permissions based on the associated umask value for the process. The umask value on most systems defaults to 0022, which will restrict connectivity to the creating user (though you should verify this setting for your system(s)). On Windows systems, the socket will be created with the permissions of the parent directory by default. More information about Unix domain socket permissions on Windows can be found here.

Ownership

Socket ownership can be specified on a per-session and/or per-endpoint basis by passing the --socket-owner=<owner> or --socket-owner-(source|destination)=<owner> flag, respectively, to the mutagen forward create command. Socket ownership can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

forward:
  defaults:
    socket:
      owner: "<owner>"

Socket groups can be specified on a per-session and/or per-endpoint basis by passing the --socket-group=<group> or --socket-group-(source|destination)=<group> flag, respectively, to the mutagen forward create command. Socket groups can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

forward:
  defaults:
    socket:
      group: "<owner>"

Owner and group specifications are the same as those used in synchronization ownership specifications and carry the same caveats.

Permissions

Socket permissions can be specified on a per-session and/or per-endpoint basis by passing the --socket-permission-mode=<mode> or --socket-permission-mode-(source|destination)=<mode> flag, respectively, to the mutagen forward create command. Default permissions can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

forward:
  defaults:
    socket:
      permissionMode: <mode>

Permission specifications are the same as those used in synchronization permission mode specifications and carry the same caveats.

Overwrites

When an application attempts to bind a Unix domain socket to a filesystem location and finds that an entry already exists at that path, the bind will fail. Although Mutagen cleans up its socket filesystem entries when it closes its Unix domain socket listeners, many applications do not, and there’s always the possibility that Mutagen is abruptly terminated without the opportunity to clean up up these entries.

As a result, it’s often necessary to remove stale socket entries from the filesystem when creating a new listener. To that end, Mutagen has two different “socket overwrite” modes that control how it behaves when a conflicting filesystem entry exists:

leave (Default): In this mode, Mutagen will leave any conflicting filesystem entry in place and abort creation of the listener.
overwrite: In this mode, Mutagen will remove any conflicting filesystem entry and re-attempt creation of the listener. Removal will only be attempted for a single filesystem entry, meaning that it can only remove a file, symbolic link, or socket — it can’t remove a conflicting directory.

These modes can be specified on a per-session and/or per-endpoint basis by passing the --socket-overwrite-mode=<mode> or --socket-overwrite-mode-(source|destination)=<mode> flag, respectively, to the mutagen forward create command. These modes can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

forward:
  defaults:
    socket:
      overwriteMode: "<mode>"