1UDISKS(8) System Administration UDISKS(8)
2
6 udisks - Disk Manager
7
9 udisks provides interfaces to enumerate and perform operations on disks
10 and storage devices. Any application (including unprivileged ones) can
11 access the udisksd(8) daemon via the name org.freedesktop.UDisks2 on
12 the system message bus[1]. In addition to the D-Bus API, a library,
13 libudisks2 is also provided. This library can be used from C/C++ and
14 any high-level language with GObjectIntrospection[2] support such as
15 Javascript and Python. udisks is only indirectly involved in what
16 devices and objects are shown in the user interface.
17
19 By default, logged-in users in active log-in sessions are permitted to
20 perform operations (for example, mounting, unlocking or modifying) on
21 devices attached to the seat their session is on. Access-control is
22 fine-grained and based on polkit(8), see the “Authorization Checks”
23 chapter in the udisks documentation for more information. Note that the
24 x-udisks-auth option can be used in the /etc/fstab and /etc/crypttab
25 files to specify that additional authorization is required to mount
26 resp. unlock the device (typically requiring the user to authenticate
27 as an administrator).
28
30 At start-up and when a drive is connected, udisksd(8) will apply
31 configuration stored in the file /etc/udisks2/IDENTIFIER.conf where
32 IDENTIFIER is the value of the Drive:Id property for the drive. If the
33 file changes on disk its new contents will also be applied to the
34 drive. Typically, users or administrators will never need to edit drive
35 configuration files as they are effectively managed through graphical
36 applications such as gnome-disks(1). Manually editing configuration
37 files is however supported — the file format is a simple .ini-like
38 format (see the Desktop Entry Specification[3] for the exact syntax).
39 New groups and keys may be added in the future.
40 ATA group
42 The ATA group is for settings that apply to drives using the ATA
43 command-set. The following keys are supported:
44 StandbyTimeout
46 The standby timeout. A value of zero means "timeouts are disabled":
47 the device will not automatically enter standby mode. Values from 1
48 to 240 specify multiples of 5 seconds, yielding timeouts from 5
49 seconds to 20 minutes. Values from 241 to 251 specify from 1 to 11
50 units of 30 minutes, yielding timeouts from 30 minutes to 5.5
51 hours. A value of 252 signifies a timeout of 21 minutes. A value of
52 253 sets a vendor-defined timeout period between 8 and 12 hours,
53 and the value 254 is reserved. 255 is interpreted as 21 minutes
54 plus 15 seconds. Note that some older drives may have very
55 different interpretations of these values. This is similar to the
56 -S option in hdparm(8).
57 APMLevel
59 The Advanced Power Management level. A low value means aggressive
60 power management and a high value means better performance.
61 Possible settings range from values 1 through 127 (which permit
62 spin-down), and values 128 through 254 (which do not permit
63 spin-down). The highest degree of power management is attained with
64 a setting of 1, and the highest I/O performance with a setting of
65 254. A value of 255 can be used to disable Advanced Power
66 Management altogether on the drive (not all drives support
67 disabling it, but most do). This is similar to the -B option in
68 hdparm(8).
69 AAMLevel
71 The Automatic Acoustic Management level. Most modern harddisk
72 drives have the ability to speed down the head movements to reduce
73 their noise output. The possible values are between 0 and 254. 128
74 is the most quiet (and therefore slowest) setting and 254 the
75 fastest (and loudest). Some drives have only two levels (quiet /
76 fast), while others may have different levels between 128 and 254.
77 At the moment, most drives only support 3 options, off, quiet, and
78 fast. These have been assigned the values 0, 128, and 254 at
79 present, respectively, but integer space has been incorporated for
80 future expansion, should this change. This is similar to the -M
81 option in hdparm(8).
82 WriteCacheEnabled
84 A boolean specifying whether to enable or disable the Write Cache.
85 Valid values for this key are “true” and “false”. This is similar
86 to the -W option in hdparm(8). This key was added in 2.1.
87 ReadLookaheadEnabled
89 A boolean specifying whether to enable or disable the Read
90 Look-ahead. Valid values for this key are “true” and “false”. This
91 is similar to the -A option in hdparm(8). This key was added in
92 2.6.0.
93
95 udisks relies on recent versions of udev(7) and the Linux kernel.
96 Influential device properties in the udev database include:
97 UDISKS_SYSTEM
99 If set, this overrides the value of the HintSystem property.
100 UDISKS_IGNORE
102 If set, this overrides the value of the HintIgnore property.
103 UDISKS_AUTO
105 If set, this overrides the value of the HintAuto property.
106 UDISKS_CAN_POWER_OFF
108 If set, this overrides the value of the CanPowerOff property.
109 UDISKS_NAME
111 The name to use for the device when presenting it in an user
112 interface. This corresponds to the HintName property.
113 UDISKS_ICON_NAME
115 The icon to use for the device when presenting it in an user
116 interface. If set, the name must adhere to the freedesktop.org icon
117 theme specification[4]. This corresponds to the HintIconName
118 property.
119 UDISKS_SYMBOLIC_ICON_NAME
121 The icon to use for the device when presenting it in an user
122 interface using a symbolic icon. If set, the name must adhere to
123 the freedesktop.org icon theme specification[4]. This corresponds
124 to the HintSymbolicIconName property.
125 UDISKS_FILESYSTEM_SHARED
127 If set to 1, the filesystem on the device will be mounted in a
128 shared directory (e.g. /media/VolumeName) instead of a private
129 directory (e.g. /run/media/$USER/VolumeName) when the
130 Filesystem.Mount() method is handled.
131 ID_SEAT
133 The physical seat the device is attached to. If unset or set to the
134 empty string, “seat0” (the first seat) is assumed.
135
137 udisks guarantees a stable D-Bus API within the same major version and
138 this guarantee also extends to the client-side library libudisks2.
139 Additionally, several major versions of udisks can be installed and
140 operate at the same time although interoperability may be limited - for
141 example, a device mounted using the udisks N.x API may require
142 additional authorization if attempting to unmount it through the the
143 (N-1).x API.
144 The udisks developers do not anticipate breaking API but does reserve
146 the right to do so and if it happens, promises to bump the major
147 version and ensure the new major version of udisks is
148 parallel-installable with any older major version. However, note that
149 programs, man pages and other artifacts may change name (for example,
150 adopt a “2” suffix) to make room for the next major version. Therefore,
151 applications can not rely on tools like e.g. udisksctl(1) to be
152 available. Additionally, there is no guarantee that the options,
153 command-line switches etc. of command-line tools or similar will remain
154 stable.
155 Instead, applications should only use the D-Bus API, the libudisks2
157 library or tools such as dbus-send(1) or gdbus(1) to interact with
158 udisksd(8).
159
161 The intended audience of udisks include operating system developers
162 working on the higher-level parts of the operating system, for example
163 the desktop shell (such as GNOME[5]) and disk management applications
164 (e.g. GNOME's Disks[6] application). Software on this level typically
165 depend on a specific (major) version of udisks and may even have
166 support for previous versions of udisks or alternative interfaces
167 performing the same role as udisks.
168 While udisks indeed provides a stable API and a clear upgrade path, it
170 may not be an appropriate dependency for third party applications. For
171 example, if the operating system switches to udisks version N.x and an
172 application is still using the udisks (N-1).x API, the application will
173 not work unless udisks (N-1).x is installed. While this situation is
174 still workable (since both udisks N.x and udisks (N-1).x can be
175 installed) it may not be desirable to ask the user to install the old
176 version - in fact, the operating system vendor may not even provide a
177 packaged version of the old version. Hence, if an application does not
178 want to tie itself to a specific version of the operating system, it
179 should not use udisks.
180 Viable alternatives to udisks are APIs that are guaranteed to be around
182 for longer time-frames, including:
183 • Low-level APIs and commands such as e.g. sysfs[7], libudev[8],
185 /proc/self/mountinfo[9] and util-linux[10].
186 • High-level APIs such as GVolumeMonitor[11].
188 In particular, for desktop applications it is a much better idea to use
190 something like GVolumeMonitor since it will make the application show
191 the same devices as the desktop shell (e.g. file manager, file chooser
192 and so on) is showing.
193
195 This man page was originally written for UDisks2 by David Zeuthen
196 <zeuthen@gmail.com> with a lot of help from many others.
197
199 Please send bug reports to either the distribution bug tracker or the
200 upstream bug tracker at
201 https://github.com/storaged-project/udisks/issues.
202
204 udev(7), polkit(8), udisksd(8), udisksctl(1), umount.udisks2(8), gnome-
205 disks(1)
206
208 1. system message bus
209 http://www.freedesktop.org/wiki/Software/dbus
210 2. GObjectIntrospection
212 https://live.gnome.org/GObjectIntrospection
213 3. Desktop Entry Specification
215 http://freedesktop.org/wiki/Specifications/desktop-entry-spec
216 4. freedesktop.org icon theme specification
218 http://www.freedesktop.org/wiki/Specifications/icon-theme-spec
219 5. GNOME
221 http://www.gnome.org
222 6. Disks
224 https://live.gnome.org/Design/Apps/Disks
225 7. sysfs
227 http://en.wikipedia.org/wiki/Sysfs
228 8. libudev
230 https://www.freedesktop.org/software/systemd/man/libudev.html
231 9. /proc/self/mountinfo
233 http://www.kernel.org/doc/Documentation/filesystems/proc.txt
234 10. util-linux
236 http://en.wikipedia.org/wiki/Util-linux
237 11. GVolumeMonitor
239 http://developer.gnome.org/gio/stable/volume_mon.html
240udisks 2.9.4 August 2018 UDISKS(8)