table of contents
- bookworm 2.9.4-4
- testing 2.10.1-11
- unstable 2.10.1-11
- experimental 2.10.90-1
UDISKS(8) | System Administration | UDISKS(8) |
NAME¶
udisks - Disk Manager
DESCRIPTION¶
udisks provides interfaces to enumerate and perform operations on disks and storage devices. Any application (including unprivileged ones) can access the udisksd(8) daemon via the name org.freedesktop.UDisks2 on the system message bus[1]. In addition to the D-Bus API, a library, libudisks2 is also provided. This library can be used from C/C++ and any high-level language with GObjectIntrospection[2] support such as Javascript and Python. udisks is only indirectly involved in what devices and objects are shown in the user interface.
ACCESS CONTROL¶
By default, logged-in users in active log-in sessions are permitted to perform operations (for example, mounting, unlocking or modifying) on devices attached to the seat their session is on. Access-control is fine-grained and based on polkit(8), see the “Authorization Checks” chapter in the udisks documentation for more information. Note that the x-udisks-auth option can be used in the /etc/fstab and /etc/crypttab files to specify that additional authorization is required to mount resp. unlock the device (typically requiring the user to authenticate as an administrator).
DRIVE CONFIGURATION¶
At start-up and when a drive is connected, udisksd(8) will apply configuration stored in the file /etc/udisks2/IDENTIFIER.conf where IDENTIFIER is the value of the Drive:Id property for the drive. If the file changes on disk its new contents will also be applied to the drive. Typically, users or administrators will never need to edit drive configuration files as they are effectively managed through graphical applications such as gnome-disks(1). Manually editing configuration files is however supported — the file format is a simple .ini-like format (see the Desktop Entry Specification[3] for the exact syntax). New groups and keys may be added in the future.
ATA group¶
The ATA group is for settings that apply to drives using the ATA command-set. The following keys are supported:
StandbyTimeout
APMLevel
AAMLevel
WriteCacheEnabled
ReadLookaheadEnabled
DEVICE INFORMATION¶
udisks relies on recent versions of udev(7) and the Linux kernel. Influential device properties in the udev database include:
UDISKS_SYSTEM
UDISKS_IGNORE
UDISKS_AUTO
UDISKS_CAN_POWER_OFF
UDISKS_NAME
UDISKS_ICON_NAME
UDISKS_SYMBOLIC_ICON_NAME
UDISKS_FILESYSTEM_SHARED
ID_SEAT
API STABILITY¶
udisks guarantees a stable D-Bus API within the same major version and this guarantee also extends to the client-side library libudisks2. Additionally, several major versions of udisks can be installed and operate at the same time although interoperability may be limited - for example, a device mounted using the udisks N.x API may require additional authorization if attempting to unmount it through the the (N-1).x API.
The udisks developers do not anticipate breaking API but does reserve the right to do so and if it happens, promises to bump the major version and ensure the new major version of udisks is parallel-installable with any older major version. However, note that programs, man pages and other artifacts may change name (for example, adopt a “2” suffix) to make room for the next major version. Therefore, applications can not rely on tools like e.g. udisksctl(1) to be available. Additionally, there is no guarantee that the options, command-line switches etc. of command-line tools or similar will remain stable.
Instead, applications should only use the D-Bus API, the libudisks2 library or tools such as dbus-send(1) or gdbus(1) to interact with udisksd(8).
AUDIENCE¶
The intended audience of udisks include operating system developers working on the higher-level parts of the operating system, for example the desktop shell (such as GNOME[5]) and disk management applications (e.g. GNOME's Disks[6] application). Software on this level typically depend on a specific (major) version of udisks and may even have support for previous versions of udisks or alternative interfaces performing the same role as udisks.
While udisks indeed provides a stable API and a clear upgrade path, it may not be an appropriate dependency for third party applications. For example, if the operating system switches to udisks version N.x and an application is still using the udisks (N-1).x API, the application will not work unless udisks (N-1).x is installed. While this situation is still workable (since both udisks N.x and udisks (N-1).x can be installed) it may not be desirable to ask the user to install the old version - in fact, the operating system vendor may not even provide a packaged version of the old version. Hence, if an application does not want to tie itself to a specific version of the operating system, it should not use udisks.
Viable alternatives to udisks are APIs that are guaranteed to be around for longer time-frames, including:
In particular, for desktop applications it is a much better idea to use something like GVolumeMonitor since it will make the application show the same devices as the desktop shell (e.g. file manager, file chooser and so on) is showing.
AUTHOR¶
This man page was originally written for UDisks2 by David Zeuthen <zeuthen@gmail.com> with a lot of help from many others.
BUGS¶
Please send bug reports to either the distribution bug tracker or the upstream bug tracker at https://github.com/storaged-project/udisks/issues.
SEE ALSO¶
udev(7), polkit(8), udisksd(8), udisksctl(1), umount.udisks2(8), gnome-disks(1)
NOTES¶
- 1.
- system message bus
- 2.
- GObjectIntrospection
- 3.
- Desktop Entry Specification
- 4.
- freedesktop.org icon theme specification
- 5.
- GNOME
- 6.
- Disks
- 7.
- sysfs
- 8.
- libudev
- 9.
- /proc/self/mountinfo
- 10.
- util-linux
- 11.
- GVolumeMonitor
August 2018 | udisks 2.10.1 |