Contents

Permissions

Mutagen’s permission synchronization model is designed around portability and development work. Unlike many synchronization systems, Mutagen does not propagate raw file ownership or permissions. Doing so is neither well-defined nor safe in general. Instead, the only permission that Mutagen propagates is POSIX executability. For any other files that Mutagen propagates or updates, ownership and permissions are set using explicit configuration parameters. Permissions for any other files in a synchronization root are left untouched by Mutagen.

Executability propagation

For development work, propagation and preservation of POSIX executability bits is crucial, and as such they are only permissions that Mutagen aims to support automatically. For filesystems that don’t preserve executability bits (for example, those on Windows), preservation is emulated in-memory as part of the reconciliation algorithm (as opposed to trying to attach metadata to files on disk). This allows users to, for example, edit POSIX shell scripts on Windows and have those changes synchronized without wiping out executability bits.

Mutagen considers a file executable if any executability bit is set. When setting permissions for an executable file, executability bits are set for any entities that have a corresponding read bit set.

Owners and groups

By default, files and directories are created with their owner set to the user under which Mutagen or its agent executable is operating and their group set to that user’s default group. Both of these behaviors are configurable.

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

sync:
  defaults:
    permissions:
      defaultOwner: "<owner>"

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

sync:
  defaults:
    permissions:
      defaultGroup: "<group>"

Owner and group specifications can be provided in three different formats:

  • POSIX-ID-based: A string of the form id:N, where N is a number representing the user or group ID. This is only supported for POSIX endpoints.
  • Windows-SID-based: A string of the form sid:XXXXXXXXXX where XXXXXXXXXX is some valid Windows SID (the formats are highly variable). This is only supported for Windows endpoints.
  • Name-based: A non-empty string that does not adhere to one of the above formats is treated as a literal user or group name. This is supported on both POSIX and Windows endpoints.

Empty ownership specifications specify that the default ownership should be used for the file (whatever that happens to be on the endpoint).

POSIX

Please note that, on POSIX systems, superuser privileges are required to set ownership to a user other that oneself, or to set a group to which one does not belong.

Windows

On Windows systems, setting file ownership to a group or another user requires the SeRestorePrivilege, which has to be granted by a system administrator and then requires that the requesting process activate that privilege. Mutagen doesn’t activate this privilege at the moment because having the SeRestorePrivilege gives a process write access to an entire system (including system files).

Setting group ownership on Windows also has essentially no effect, since group information is a relic of POSIX support on Windows and isn’t used by the Win32 subsystem.

Permissions

By default, files and directories have their permission bits set to user-only access (0600 and 0700, respectively).

Default permissions can be specified on a per-session and/or per-endpoint basis by passing the --default-(file|directory)-mode=<mode> or --default-(file|directory)-mode-(alpha|beta)=<mode> flag, respectively, to the mutagen sync create command. Default permissions can be specified on a default per-session basis by including the following configuration in ~/.mutagen.yml:

sync:
  defaults:
    permissions:
      defaultFileMode: 0XXX
      defaultDirectoryMode: 0XXX

File and directory modes are specified in octal format with an optional 0 prefix (for example, 0644 or 750). They default to 0600 for files and 0700 for directories. File modes should not include executability bits since these are managed by Mutagen.

POSIX

Please note that default file and directory permissions are still subject to umask.

Windows

At the moment, file and directory modes on Windows are processed as outlined in the Go os.Chmod function.