udisks
udisks provides a daemon udisksd, that implements D-Bus interfaces used to query and manipulate storage devices, and a command-line tool udisksctl, used to query and use the daemon.
Installation
udisksd(8) is started on-demand by D-Bus and should not be enabled explicitly. It can be controlled through the command-line with udisksctl(1).
Configuration
Permissions
Actions a user can perform using udisks are restricted with polkit. If the user session is not activated or present (for example, when controlling udisks from a systemd/User service), adjust polkit rules accordingly.
See https://github.com/coldfix/udiskie/wiki/Permissions for common udisks permissions for the storage
group, and [2] for a more restrictive example. If you are using Dolphin, you may see [3].
Default mount options
It is possible to define default mount options in /etc/udisks2/mount_options.conf
. Create the file if it does not already exist. The built-in defaults and some examples can be seen in /etc/udisks2/mount_options.conf.example
.[4]
The options can target specific filesystem types. For example, mount btrfs filesystems with zstd compression enabled:
/etc/udisks2/mount_options.conf
[defaults] btrfs_defaults=compress=zstd
Usage
To manually mount a removable drive, for example /dev/sdc
:
$ udisksctl mount -b /dev/sdc1
To unmount:
$ udisksctl unmount -b /dev/sdc1
See udisksctl help
for more.
Tips and tricks
Mount helpers
The automatic mounting of devices is easily achieved with udisks wrappers. See also List of applications/Utilities#Mount tools.
- bashmount — A bash script to mount and manage removable media as a regular user.
- dolphin-plugins — uses udisksctl to either mount or unmount the iso in Dolphin.
- udiskie — Automounter with optional notifications, tray icon and support for password protected LUKS devices. See the udiskie wiki for details
- udiskie-dmenu — dmenu interface for udiskie.
- udisksvm — GUI wrapper written in Python3 and using the Qt5 framework. It uses mouse clicks to mount, unmount removable devices or eject a CD/DVD. See the README file for details.
- udevil — Includes devmon.
- Note: devmon only uses udisks2 for mounting (in this order) if udevil or pmount miss the SUID permission. To remove this permission, run
chmod -s /usr/bin/udevil
as root.
udevadm monitor
You may use udevadm monitor
to monitor block events and mount drives when a new block device is created. Stale mount points are automatically removed by udisksd, such that no special action is required on deletion.
#!/bin/sh pathtoname() { udevadm info -p /sys/"$1" | awk -v FS== '/DEVNAME/ {print $2}' } stdbuf -oL -- udevadm monitor --udev -s block | while read -r -- _ _ event devpath _; do if [ "$event" = add ]; then devname=$(pathtoname "$devpath") udisksctl mount --block-device "$devname" --no-user-interaction fi done
Mount to /media
By default, udisks2 mounts removable drives under the ACL controlled directory /run/media/$USER/
. If you wish to mount to /media
instead, use this rule:
/etc/udev/rules.d/99-udisks2.rules
# UDISKS_FILESYSTEM_SHARED # ==1: mount filesystem to a shared directory (/media/VolumeName) # ==0: mount filesystem to a private directory (/run/media/$USER/VolumeName) # See udisks(8) ENV{ID_FS_USAGE}=="filesystem|other|crypto", ENV{UDISKS_FILESYSTEM_SHARED}="1"
Since /media
, unlike /run
, is not mounted by default as a tmpfs, you may also wish to create a tmpfiles.d snippet to clean stale mountpoints at every boot:
/etc/tmpfiles.d/media.conf
D /media 0755 root root 0 -
Mount loop devices
To easily mount ISO images, use the following command:
$ udisksctl loop-setup -r -f image.iso
This will create a read only loop device and show the ISO image ready to mount. Remove the -r
flag to be able to write to it. The name of the created loop device is output by the above loop-setup
command.
You can unmount, and remount, the image as long as the specific loop device is in place. When done working with the specific loop device, use
$ udisksctl loop-delete -b /dev/loop0
to delete it. Substitute /dev/loop0
with the name of the specific loop device.
Loop devices are cheap. Therefore, many loop devices can be created in practice without worrying about a denial of service issue. See [5].
Hide selected partitions
If you wish to prevent certain partitions or drives appearing on the desktop, you can create a udev rule, for example /etc/udev/rules.d/10-local.rules
:
KERNEL=="sda1", ENV{UDISKS_IGNORE}="1" KERNEL=="sda2", ENV{UDISKS_IGNORE}="1"
shows all partitions with the exception of sda1
and sda2
on your desktop.
Because block device names can change between reboots, it is also possible to use UUIDs to hide partitions or whole devices. Matching by UUID is only possible after /usr/lib/udev/rules.d/60-persistent-storage.rules
has been processed, so make sure to choose a file name that will be ordered after it. For example:
/etc/udev/rules.d/61-hide-partitions.rules
SUBSYSTEM=="block", ENV{ID_FS_UUID}=="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX", ENV{UDISKS_IGNORE}="1"
The above line is also useful to hide multi device btrfs filesystems, as all the devices from a single btrfs filesystem will share the same UUID across the devices but will have different SUB_UUID for each individual device.
Apply ATA settings
At start-up and when a drive is connected, udisksd will apply configuration stored in the file /etc/udisks2/IDENTIFIER.conf
where IDENTIFIER
is the value of the Drive:Id property for the drive. Currently ATA settings are supported. See udisks(8) for available options. These settings have essentially the same effect as those of hdparm, but they are persistent as long as the udisks daemon is autostarted.
For example, to set standby timeout to 240 (20 minutes) for a drive, add the following:
/etc/udisks2/DriveId.conf
[ATA] StandbyTimeout=240
To obtain the DriveId for your drive, use udevadm info --query=all --name=sdx | grep ID_SERIAL | sed "s/_/-/g"
Alternatively, use a GUI utility to manage the configuration file, such as gnome-disk-utility.
Troubleshooting
Hidden devices
Udisks2 hides certain devices from the user by default. If this is undesired or otherwise problematic, copy /usr/lib/udev/rules.d/80-udisks2.rules
to /etc/udev/rules.d/80-udisks2.rules
and remove the following section in the copy:
# ------------------------------------------------------------------------ # ------------------------------------------------------------------------ # ------------------------------------------------------------------------ # Devices which should not be display in the user interface [...]
Broken standby timer
The udisks daemon polls S.M.A.R.T. data from drives regularly. Hard drives with a longer standby timeout than the polling interval may fail to enter standby. Drives that are already spun down are usually not affected. There seems no way to disable polling or change the interval as for udisks2 by now. See [6], [7][dead link 2024-10-12 ⓘ].
However, Standby timeout applied by udisks2 seems to be unaffected. To set standby timeout via udisks, see #Apply ATA settings.
Other possible workarounds could be setting the timeout below the polling interval (10 minutes) or forcing a manual spindown using hdparm -y /dev/sdx
.
NTFS mount failing
If mounting a ntfs partition fails with the error:
Error mounting /dev/sdXY at [...]: wrong fs type, bad option, bad superblock on /dev/sdXY, missing codepage or helper program, or other error
and in the kernel log with journalctl
/dmesg
ran as root:
ntfs: (device sdXY): parse_options(): Unrecognized mount option windows_names.
Then the problem is that udisks is trying to use the kernel ntfs driver, which does not understand this (default) mount option. For this to work the optional dependency NTFS-3G must be installed.
NTFS file creation failing (filename-dependent)
udisks 2.8.2 introduced a breaking change by adding windows_names
to NTFS mount options, preventing creation of Win32-incompatible filenames such as nul
, screenshot 23-08-21 19:22.jpg
. Among other things, this causes Steam Proton to stop initializing. To revert this behavior, use:
/etc/udisks2/mount_options.conf
[defaults] ntfs:ntfs_defaults=uid=$UID,gid=$GID
Bad filenames generally do not cause issues in Windows unless accessed. chkdsk will treat these names as errors and move the renamed files to found.nnn
folders under filesystem root.
See also
- Gentoo:udisks
- Introduction to udisks[dead link 2024-07-30 ⓘ]