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.
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 (e.g. 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, e.g., 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
flag, respectively, to the
mutagen sync create command. Default ownership can
be specified on a default per-session basis by including the following
sync: defaults: permissions: defaultOwner: "<owner>"
Default groups can be specified on a per-session and/or per-endpoint basis by
flag, respectively, to the
mutagen sync create command. Default groups can be
specified on a default per-session basis by including the following
sync: defaults: permissions: defaultGroup: "<group>"
Owner and group specifications can be provided in three different formats:
- POSIX-ID-based: A string of the form
Nis a number representing the user or group ID. This is only supported for POSIX endpoints.
- Windows-SID-based: A string of the form
XXXXXXXXXXis 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).
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.
On Windows systems, setting file ownership to a group or another user requires
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
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.
By default, files and directories have their permission bits set to user-only
Default permissions can be specified on a per-session and/or per-endpoint basis
by passing the
--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
sync: defaults: permissions: defaultFileMode: <mode> defaultDirectoryMode: <mode>
File and directory modes are specified in octal format with an optional
750. They default to
0600 for files and
directories. File modes should not include executability bits since these are
managed by Mutagen.
Please note that default file and directory permissions are still subject to
At the moment, file and directory modes on Windows are processed as outlined in