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.

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>"