Permissions

Mutagen uses a portable but flexible permission propagation system focused on development scenarios.

By default, the only permission propagated by Mutagen is POSIX executability. This propagation only applies when synchronizing between POSIX systems, though it is tracked even when synchronizing with Windows systems so that it can be correctly preserved. Mutagen considers POSIX executability to be set for a file if any executable bit is set for the file. When setting executability for a file, Mutagen sets the executable bit for any entity with a corresponding read bit set. When clearing executability for a file, Mutagen clears all executable bits.

When creating directories or creating/updating files on an endpoint, Mutagen uses a default set of user-only permissions (0700 for directories, 0600 for files, and 0700 for executable files) and sets file ownership and group information according to the user running either the Mutagen daemon (for local endpoints) or mutagen-agent binary (for remote endpoints).1

1 The descriptions here are given in terms of POSIX semantics, but they are conceptually identical in the Windows implementation.

Specifying owner and group

The default owner for new and updated files can be overridden on a per-session and/or per-endpoint basis by passing the --default-owner=<identifier> or --default-owner-(alpha|beta)=<identifier> flag, respectively, to the create command. The default owner can be specified on a default per-session basis by including the following in ~/mutagen.toml:

[permissions]
defaultOwner = "<identifier>"

The default group for new and updated files can be overridden on a per-session or per-endpoint basis by passing the --default-group=<identifier> or --default-group-(alpha|beta)=<identifier> flag, respectively, to the create command. The default group can be specified on a default per-session basis by including the following in ~/mutagen.toml:

[permissions]
defaultGroup = "<identifier>"

Owner and group identifiers can be provided in three 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.

Please note that on POSIX systems you’ll need superuser privileges to set ownership to a user besides yourself, or to set a group to which you do not belong.

Also note that 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 do this at the moment because having the SeRestorePrivilege gives a process write access to an entire system (including system files) and this can be dangerous.
  • Setting group ownership on Windows has no real effect. This information is not visible from the Win32 subsystem - it’s a Windows POSIX relic.

Specifying permissions

The default base file permissions (excluding executable bits) for new and updated files can be overridden on a per-session or per-endpoint basis by passing the --default-file-mode=<mode> or --default-file-mode-(alpha|beta)=<mode> flag, respectively, to the create command. The default base file permissions can be specified on a default per-session basis by including the following in ~/mutagen.toml:

[permissions]
defaultFileMode = "<mode>"

The default base directory permissions for newly created directories can be overridden on a per-session or per-endpoint basis by passing the --default-directory-mode=<mode> or --default-directory-mode-(alpha|beta)=<mode> flag, respectively, to the create command. The default base directory permissions can be specified on a default per-session basis by including the following in ~/mutagen.toml:

[permissions]
defaultDirectoryMode = "<mode>"

File and directory permissions are specified in octal format (the 0 prefix is optional), e.g. 0644 or 750. They default to 0600 for files and 0700 for directories. They are also restricted by the umask (if applicable) on the endpoint. Base file permissions should not include executable bits since these are managed by Mutagen.

On Windows, these numeric file and directory permissions are processed as outlined in the Go os.Chmod function. This will improve over time, but POSIX permission bits are not a natural fit for Windows.