For the reference this is what the builtin set of options looks like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

[defaults]
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,relatime,strictatime,lazytime,ro,rw,sync,dirsync,noload,acl

vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec,flush
vfat_allow=uid=$UID,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec

# common options for both the native kernel driver and exfat-fuse
exfat_defaults=uid=$UID,gid=$GID,iocharset=utf8,errors=remount-ro
exfat_allow=uid=$UID,gid=$GID,dmask,errors,fmask,iocharset,namecase,umask

ntfs_defaults=uid=$UID,gid=$GID,windows_names
ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names,compression,nocompression,big_writes

iso9660_defaults=uid=$UID,gid=$GID,iocharset=utf8,mode=0400,dmode=0500
iso9660_allow=uid=$UID,gid=$GID,norock,nojoliet,iocharset,mode,dmode

udf_defaults=uid=$UID,gid=$GID,iocharset=utf8
udf_allow=uid=$UID,gid=$GID,iocharset,utf8,umask,mode,dmode,unhide,undelete

hfsplus_defaults=uid=$UID,gid=$GID,nls=utf8
hfsplus_allow=uid=$UID,gid=$GID,creator,type,umask,session,part,decompose,nodecompose,force,nls

btrfs_allow=compress,compress-force,datacow,nodatacow,datasum,nodatasum,degraded,device,discard,nodiscard,subvol,subvolid,space_cache

f2fs_allow=discard,nodiscard,compress_algorithm,compress_log_size,compress_extension,alloc_mode

xfs_allow=discard,nodiscard,inode32,largeio,wsync

reiserfs_allow=hashed_relocation,no_unhashed_relocation,noborder,notail

For each filesystem type a pair of two sets are defined: _allow and _defaults.

The _allow set define mount options ever allowed and considered, the _defaults are the target options to use that are then finally passed to the mount command.

The _defaults always need to be a subset of _allow. The _defaults options are also merged with any extra options passed via the Mount() method call.

Other than the filesystem specific options there's also a group of general options that are always merged with fs-specific ones. These include general options like rw, ro, etc. Let's refer to them as any filesystem type options for simplicity in the further text. The result of option set stacking, overrides and merging is referred to as (resulting) computed set of options.

Apart from the final computed options UDisks always adds the following options: nodev, nosuid, uhelper=udisks2 no matter if included in _allow or not. These are hardcoded and can't be changed.

Options that are not allowed in the computed _allow set will fail the mount operation with an error.

UDisks daemon typically runs as root and spawns the mount command with root privileges while processing requests from unprivileged clients and it needs a way to set proper permissions for the mounted filesystem. This is usually done by passing the uid and gid mount options that common filesystems honour. UDisks take the D-Bus method caller effective UID and finds its corresponding primary GID.

Also a uhelper=udisks2 mount option is added automatically to indicate the umount command to use UDisks again for unmounting when called by an unprivileged user.

To allow flexibility in mount option naming, two special values are defined as placeholders for aforementioned IDs: $UID and $GID. These are supposed to be defined as values for specific mount options (typically uid and gid) within the _allow set and are then replaced with numerical values in the late phase of mount option computation.

It's worth noting that there are few more options whose arguments are being replaced by computed values: mode and dmode. These options are hardcoded at the moment and its values depend on the udev UDISKS_FILESYSTEM_SHARED attribute presence on the block device.

Option sets are composite strings of mount options with or without arguments separated by commas. There's generally no difference from an option string commonly used with the mount command. However UDisks brings a couple of specifics for greater flexibility.

As explained above any particular mount option either defined in the _defaults set or passed as an extra argument via the Mount() method call need to be allowed by the _allow set of mount options. There's however a difference in how the option is allowed and what arguments are valid.

When a considered option is defined with either of the $UID or $GID values within the _allow set (see previous chapter), special rules apply. In case the value of a considered option is the $UID/$GID placeholder (as is the case of builtin set of options) or no value is specified at all (e.g. the uid= string), the Mount() method caller UID or GID is automatically added. In case a particular value is present (e.g. uid=1001) it is only allowed when the caller UID matches the option value.

In case a considered option is specified explicitly with a value within the _allow set no other checks are performed and this option=value pair is always allowed. This even bypasses UID and GID checks, except of the $UID or $GID strings.

This permits various combinations of caller mount options such as uid=$UID,uid=ignore for UDF filesystem where the uid=ignore mount options is always allowed yet standard checks (uid=$UID) for numerical UID values are still preserved. Similarly, certain numeric UID/GID values may be explicitly allowed this way, allowing non-privileged callers to use predefined IDs (e.g. uid=1000,uid=1500,uid=ignore within _allow). This also allows to specify arbitrary values permitted, where each pair needs to be specified separately, i.e. iocharset=utf8,iocharset=iso8859-1,iocharset=iso8859-2.

Allowed option defined with no value is treated as any value is permitted but only if passed all checks described above. There's generally no difference between option and option= (i.e. an empty value) in such definitions.

A sample config file showing rich syntax:

[defaults]
# common options, applied to any filesystem, always merged with specific filesystem type options
defaults=ro
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload

# specific filesystem type options
vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec,flush
vfat_allow=uid=$UID,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
ntfs_defaults=uid=$UID,gid=$GID,windows_names
ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names

[/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
vfat_defaults=uid=$UID,gid=$GID,noexec

[/dev/disk/by-label/EFI]
vfat_defaults=noexec,umask=111,dmask=000

The format of the configuration file is an INI-style key-value file parseable by GKeyFile. The default location of the file unless specified otherwise during build time is /etc/udisks2/mount_options.conf. Sample config file is shipped along the source code.

The config file may contain multiple groups with a common [defaults] group. One of the new features is an ability to override mount options for particular block device, matched by the block device path. In such case the name of the group is the block device path. It's strongly encouraged to use stable block device identifiers (that is e.g. /dev/disk/by-*). No wildcards or glob expansion is performed, for fine-grained matching please use overrides through the custom udev rules. This shouldn't be abused to weaken security requirements though, it's quite easy to fake storage identifiers, more so on removable media.

Another possibility of overriding mount options is from the udev rules. This brings the flexibility of fine-grained matching by various identifiers and even using external helpers for identification. It's also a less error-prone way than matching by block device symlinks at the config file level.

This is a separate level of overrides that is positioned on top of the config file level, i.e. definitions coming from udev rules will override respective keys from both the config file level and the base builtin mount options. The override mechanism and rules are no different from the config file level [defaults] group. There's just a slight syntactic difference to align with usual udev ENV naming conventions, consisting of the UDISKS_MOUNT_OPTIONS_ key prefix.

Depending on your distribution specifics there are usually several paths designated for placing custom udev rules, with /etc/udev/rules.d/ and /lib/udev/rules.d being the common ones. It's strongly recommended to make the rules run last, by the 99- filename prefix.

Sample udev rules may look as follows:

# This file contains custom mount options for udisks 2.x
#

# Skip if not a block device or if requested by other rules
#
SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"


# Additional mount options passed to udisksd to allow sysadmins to restrict mount to read-only or "noexec"
# for example:
#
# ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro,noexec"
# ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload"

#
# Use specific charset for FAT filesystems
#
# ENV{ID_FS_TYPE}=="vfat", \
# ENV{UDISKS_MOUNT_OPTIONS_VFAT_DEFAULTS}="uid=$UID,gid=$GID,shortname=mixed,utf8=0,iocharset=iso8859-15,showexec,flush"

#
# Mount all USB devices read-only
#
# SUBSYSTEMS="usb", ENV{ID_FS_USAGE}=="filesystem", ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro"

LABEL="udisks_mount_options_end"

Levels from lower to higher:

Higher level options always fully override lower levels.

While the builtin options are always present, upper levels are optional.

Each level may consist of a common group and block device specific groups.

This is the most important part to understand as badly formulated options may lead to unforeseen consequences.

As a general rule, set of options from higher levels always fully replace (cover, override) options from lower levels. This works on per-set basis, i.e. separately for each of the _allow and _defaults sets. Please pay attention to allowance of the mount options overriden in the _defaults set at a given level without overriding the _allow set at the same place - lower levels may not allow all the options.

First, overrides are computed within each level. At a given level, block device specific options take higher priority over the common options (the [defaults] group) and fully override them.

As a second step, overrides are computed vertically across all levels, from higher down to lower ones, again separately per-set basis. At this point, there are no block device specific options as they have been computed in the previous step.

The filesystem type specific options and common options (any) are computed separately across all levels per-set basis.

As a final step, when all sets are layered and computed onto a flat level, filesystem specific options and common options are merged together.

See the examples for further illustration.