1UDISKS(8)                    System Administration                   UDISKS(8)
2
3
4

NAME

6       udisks - Disk Manager
7

DESCRIPTION

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

ACCESS CONTROL

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

DRIVE CONFIGURATION

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
41   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
45       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
58       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
70       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
83       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
88       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

DEVICE INFORMATION

95       udisks relies on recent versions of udev(7) and the Linux kernel.
96       Influential device properties in the udev database include:
97
98       UDISKS_SYSTEM
99           If set, this overrides the value of the HintSystem property.
100
101       UDISKS_IGNORE
102           If set, this overrides the value of the HintIgnore property.
103
104       UDISKS_AUTO
105           If set, this overrides the value of the HintAuto property.
106
107       UDISKS_CAN_POWER_OFF
108           If set, this overrides the value of the CanPowerOff property.
109
110       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
114       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
120       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
126       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
132       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

API STABILITY

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
145       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
156       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

AUDIENCE

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
169       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
181       Viable alternatives to udisks are APIs that are guaranteed to be around
182       for longer time-frames, including:
183
184       •   Low-level APIs and commands such as e.g.  sysfs[7], libudev[8],
185           /proc/self/mountinfo[9] and util-linux[10].
186
187       •   High-level APIs such as GVolumeMonitor[11].
188
189       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

AUTHOR

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

BUGS

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

SEE ALSO

204       udev(7), polkit(8), udisksd(8), udisksctl(1), umount.udisks2(8), gnome-
205       disks(1)
206

NOTES

208        1. system message bus
209           http://www.freedesktop.org/wiki/Software/dbus
210
211        2. GObjectIntrospection
212           https://live.gnome.org/GObjectIntrospection
213
214        3. Desktop Entry Specification
215           http://freedesktop.org/wiki/Specifications/desktop-entry-spec
216
217        4. freedesktop.org icon theme specification
218           http://www.freedesktop.org/wiki/Specifications/icon-theme-spec
219
220        5. GNOME
221           http://www.gnome.org
222
223        6. Disks
224           https://live.gnome.org/Design/Apps/Disks
225
226        7. sysfs
227           http://en.wikipedia.org/wiki/Sysfs
228
229        8. libudev
230           https://www.freedesktop.org/software/systemd/man/libudev.html
231
232        9. /proc/self/mountinfo
233           http://www.kernel.org/doc/Documentation/filesystems/proc.txt
234
235       10. util-linux
236           http://en.wikipedia.org/wiki/Util-linux
237
238       11. GVolumeMonitor
239           http://developer.gnome.org/gio/stable/volume_mon.html
240
241
242
243udisks 2.9.2                      August 2018                        UDISKS(8)
Impressum