| 1 |
<?xml version="1.0"?> |
| 2 |
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" |
| 4 |
[<!ENTITY version SYSTEM "../version.xml">]> |
| 5 |
<refentry id="udisks.8"> |
| 6 |
<refentryinfo> |
| 7 |
<title>udisks</title> |
| 8 |
<date>August 2018</date> |
| 9 |
<productname>udisks</productname> |
| 10 |
</refentryinfo> |
| 11 |
|
| 12 |
<refmeta> |
| 13 |
<refentrytitle>udisks</refentrytitle> |
| 14 |
<manvolnum>8</manvolnum> |
| 15 |
<refmiscinfo class="manual">System Administration</refmiscinfo> |
| 16 |
<refmiscinfo class="source">udisks</refmiscinfo> |
| 17 |
<refmiscinfo class="version">&version;</refmiscinfo> |
| 18 |
</refmeta> |
| 19 |
|
| 20 |
<refnamediv> |
| 21 |
<refname>udisks</refname> |
| 22 |
<refpurpose>Disk Manager</refpurpose> |
| 23 |
</refnamediv> |
| 24 |
|
| 25 |
<refsect1><title>DESCRIPTION</title> |
| 26 |
<para> |
| 27 |
udisks provides interfaces to enumerate and perform operations |
| 28 |
on disks and storage devices. Any application (including |
| 29 |
unprivileged ones) can access the |
| 30 |
<link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link> |
| 31 |
daemon via the name <emphasis>org.freedesktop.UDisks2</emphasis> |
| 32 |
on the <ulink url="http://www.freedesktop.org/wiki/Software/dbus">system message bus</ulink>. |
| 33 |
In addition to the D-Bus API, a |
| 34 |
library, <filename>libudisks2</filename> is also provided. This |
| 35 |
library can be used from C/C++ and any high-level language with |
| 36 |
<ulink |
| 37 |
url="https://live.gnome.org/GObjectIntrospection">GObjectIntrospection</ulink> |
| 38 |
support such as Javascript and Python. |
| 39 |
udisks is only indirectly involved in what devices and objects |
| 40 |
are shown in the user interface. |
| 41 |
</para> |
| 42 |
</refsect1> |
| 43 |
|
| 44 |
<refsect1><title>ACCESS CONTROL</title> |
| 45 |
<para> |
| 46 |
By default, logged-in users in active log-in sessions are |
| 47 |
permitted to perform operations (for example, mounting, |
| 48 |
unlocking or modifying) on devices attached to the seat their |
| 49 |
session is on. Access-control is fine-grained and based on |
| 50 |
<citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| 51 |
see the <quote><link |
| 52 |
linkend="udisks-polkit-actions">Authorization |
| 53 |
Checks</link></quote> chapter in the udisks documentation for |
| 54 |
more information. |
| 55 |
Note that the <literal>x-udisks-auth</literal> option can be |
| 56 |
used in the <filename>/etc/fstab</filename> and |
| 57 |
<filename>/etc/crypttab</filename> files to specify that |
| 58 |
additional authorization is required to mount resp. unlock the |
| 59 |
device (typically requiring the user to authenticate as an |
| 60 |
administrator). |
| 61 |
</para> |
| 62 |
</refsect1> |
| 63 |
|
| 64 |
<refsect1><title>DRIVE CONFIGURATION</title> |
| 65 |
<para> |
| 66 |
At start-up and when a drive is connected, |
| 67 |
<link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link> |
| 68 |
will apply configuration stored in the file |
| 69 |
<filename class='directory'>/etc/udisks2/IDENTIFIER.conf</filename> |
| 70 |
where <emphasis>IDENTIFIER</emphasis> is the value of the |
| 71 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Id">Drive:Id</link> |
| 72 |
property for the drive. If the file changes on disk its new |
| 73 |
contents will also be applied to the drive. |
| 74 |
Typically, users or administrators will never need to edit drive |
| 75 |
configuration files as they are effectively managed through |
| 76 |
graphical applications such as |
| 77 |
<citerefentry><refentrytitle>gnome-disks</refentrytitle><manvolnum>1</manvolnum></citerefentry>. |
| 78 |
Manually editing configuration files is however supported — the file |
| 79 |
format is a simple <emphasis>.ini-like format</emphasis> |
| 80 |
(see the |
| 81 |
<ulink url="http://freedesktop.org/wiki/Specifications/desktop-entry-spec">Desktop Entry Specification</ulink> |
| 82 |
for the exact syntax). New groups and keys may |
| 83 |
be added in the future. |
| 84 |
</para> |
| 85 |
|
| 86 |
<refsect2> |
| 87 |
<title>ATA group</title> |
| 88 |
<para> |
| 89 |
The <literal>ATA</literal> group is for settings that apply to |
| 90 |
drives using the ATA command-set. The following keys are |
| 91 |
supported: |
| 92 |
</para> |
| 93 |
|
| 94 |
<variablelist> |
| 95 |
<varlistentry> |
| 96 |
<term><option>StandbyTimeout</option></term> |
| 97 |
<listitem> |
| 98 |
<para> |
| 99 |
The standby timeout. A value of zero means "timeouts |
| 100 |
are disabled": the device will not automatically enter |
| 101 |
standby mode. Values from 1 to 240 specify multiples of |
| 102 |
5 seconds, yielding timeouts from 5 seconds to 20 |
| 103 |
minutes. Values from 241 to 251 specify from 1 to 11 |
| 104 |
units of 30 minutes, yielding timeouts from 30 minutes |
| 105 |
to 5.5 hours. A value of 252 signifies a timeout of 21 |
| 106 |
minutes. A value of 253 sets a vendor-defined timeout |
| 107 |
period between 8 and 12 hours, and the value 254 is |
| 108 |
reserved. 255 is interpreted as 21 minutes plus 15 |
| 109 |
seconds. Note that some older drives may have very |
| 110 |
different interpretations of these values. |
| 111 |
This is similar to the <option>-S</option> option in |
| 112 |
<citerefentry><refentrytitle>hdparm</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
| 113 |
</para> |
| 114 |
</listitem> |
| 115 |
</varlistentry> |
| 116 |
<varlistentry> |
| 117 |
<term><option>APMLevel</option></term> |
| 118 |
<listitem> |
| 119 |
<para> |
| 120 |
The Advanced Power Management level. A low value means |
| 121 |
aggressive power management and a high value means |
| 122 |
better performance. Possible settings range from values |
| 123 |
1 through 127 (which permit spin-down), and values 128 |
| 124 |
through 254 (which do not permit spin-down). The |
| 125 |
highest degree of power management is attained with a |
| 126 |
setting of 1, and the highest I/O performance with a |
| 127 |
setting of 254. A value of 255 can be used to disable |
| 128 |
Advanced Power Management altogether on the drive (not |
| 129 |
all drives support disabling it, but most do). |
| 130 |
This is similar to the <option>-B</option> option in |
| 131 |
<citerefentry><refentrytitle>hdparm</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
| 132 |
</para> |
| 133 |
</listitem> |
| 134 |
</varlistentry> |
| 135 |
<varlistentry> |
| 136 |
<term><option>AAMLevel</option></term> |
| 137 |
<listitem> |
| 138 |
<para> |
| 139 |
The Automatic Acoustic Management level. Most modern |
| 140 |
harddisk drives have the ability to speed down the head |
| 141 |
movements to reduce their noise output. The possible |
| 142 |
values are between 0 and 254. 128 is the most quiet (and |
| 143 |
therefore slowest) setting and 254 the fastest (and |
| 144 |
loudest). Some drives have only two levels (quiet / |
| 145 |
fast), while others may have different levels between |
| 146 |
128 and 254. At the moment, most drives only support 3 |
| 147 |
options, off, quiet, and fast. These have been assigned |
| 148 |
the values 0, 128, and 254 at present, respectively, but |
| 149 |
integer space has been incorporated for future |
| 150 |
expansion, should this change. |
| 151 |
This is similar to the <option>-M</option> option in |
| 152 |
<citerefentry><refentrytitle>hdparm</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
| 153 |
</para> |
| 154 |
</listitem> |
| 155 |
</varlistentry> |
| 156 |
<varlistentry> |
| 157 |
<term><option>WriteCacheEnabled</option></term> |
| 158 |
<listitem> |
| 159 |
<para> |
| 160 |
A boolean specifying whether to enable or disable the |
| 161 |
Write Cache. Valid values for this key are |
| 162 |
<quote>true</quote> and <quote>false</quote>. This is |
| 163 |
similar to the <option>-W</option> option in |
| 164 |
<citerefentry><refentrytitle>hdparm</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
| 165 |
This key was added in 2.1. |
| 166 |
</para> |
| 167 |
</listitem> |
| 168 |
</varlistentry> |
| 169 |
<varlistentry> |
| 170 |
<term><option>ReadLookaheadEnabled</option></term> |
| 171 |
<listitem> |
| 172 |
<para> |
| 173 |
A boolean specifying whether to enable or disable the |
| 174 |
Read Look-ahead. Valid values for this key are |
| 175 |
<quote>true</quote> and <quote>false</quote>. This is |
| 176 |
similar to the <option>-A</option> option in |
| 177 |
<citerefentry><refentrytitle>hdparm</refentrytitle><manvolnum>8</manvolnum></citerefentry>. |
| 178 |
This key was added in 2.6.0. |
| 179 |
</para> |
| 180 |
</listitem> |
| 181 |
</varlistentry> |
| 182 |
</variablelist> |
| 183 |
</refsect2> |
| 184 |
</refsect1> |
| 185 |
|
| 186 |
<refsect1> |
| 187 |
<title>DEVICE INFORMATION</title> |
| 188 |
<para> |
| 189 |
udisks relies on recent versions of |
| 190 |
<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> |
| 191 |
and the Linux kernel. Influential device properties in the udev |
| 192 |
database include: |
| 193 |
</para> |
| 194 |
<variablelist> |
| 195 |
<varlistentry> |
| 196 |
<term><option>UDISKS_SYSTEM</option></term> |
| 197 |
<listitem> |
| 198 |
<para> |
| 199 |
If set, this overrides the value of the |
| 200 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintSystem">HintSystem</link> property. |
| 201 |
</para> |
| 202 |
</listitem> |
| 203 |
</varlistentry> |
| 204 |
<varlistentry> |
| 205 |
<term><option>UDISKS_IGNORE</option></term> |
| 206 |
<listitem> |
| 207 |
<para> |
| 208 |
If set, this overrides the value of the |
| 209 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintIgnore">HintIgnore</link> property. |
| 210 |
</para> |
| 211 |
</listitem> |
| 212 |
</varlistentry> |
| 213 |
<varlistentry> |
| 214 |
<term><option>UDISKS_AUTO</option></term> |
| 215 |
<listitem> |
| 216 |
<para> |
| 217 |
If set, this overrides the value of the |
| 218 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintAuto">HintAuto</link> property. |
| 219 |
</para> |
| 220 |
</listitem> |
| 221 |
</varlistentry> |
| 222 |
<varlistentry> |
| 223 |
<term><option>UDISKS_CAN_POWER_OFF</option></term> |
| 224 |
<listitem> |
| 225 |
<para> |
| 226 |
If set, this overrides the value of the |
| 227 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.CanPowerOff">CanPowerOff</link> property. |
| 228 |
</para> |
| 229 |
</listitem> |
| 230 |
</varlistentry> |
| 231 |
<varlistentry> |
| 232 |
<term><option>UDISKS_NAME</option></term> |
| 233 |
<listitem> |
| 234 |
<para> |
| 235 |
The name to use for the device when presenting it in an user interface. |
| 236 |
This corresponds to the |
| 237 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintName">HintName</link> property. |
| 238 |
</para> |
| 239 |
</listitem> |
| 240 |
</varlistentry> |
| 241 |
<varlistentry> |
| 242 |
<term><option>UDISKS_ICON_NAME</option></term> |
| 243 |
<listitem> |
| 244 |
<para> |
| 245 |
The icon to use for the device when presenting it in an user interface. If |
| 246 |
set, the name must adhere to the |
| 247 |
<ulink url="http://www.freedesktop.org/wiki/Specifications/icon-theme-spec">freedesktop.org icon theme specification</ulink>. |
| 248 |
This corresponds to the |
| 249 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintIconName">HintIconName</link> property. |
| 250 |
</para> |
| 251 |
</listitem> |
| 252 |
</varlistentry> |
| 253 |
<varlistentry> |
| 254 |
<term><option>UDISKS_SYMBOLIC_ICON_NAME</option></term> |
| 255 |
<listitem> |
| 256 |
<para> |
| 257 |
The icon to use for the device when presenting it in an user interface using a symbolic icon. If |
| 258 |
set, the name must adhere to the |
| 259 |
<ulink url="http://www.freedesktop.org/wiki/Specifications/icon-theme-spec">freedesktop.org icon theme specification</ulink>. |
| 260 |
This corresponds to the |
| 261 |
<link linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintIconName">HintSymbolicIconName</link> property. |
| 262 |
</para> |
| 263 |
</listitem> |
| 264 |
</varlistentry> |
| 265 |
<varlistentry> |
| 266 |
<term><option>UDISKS_FILESYSTEM_SHARED</option></term> |
| 267 |
<listitem> |
| 268 |
<para> |
| 269 |
If set to 1, the filesystem on the device will be mounted in a shared directory (e.g. <filename class='directory'>/media/VolumeName</filename>) instead of a private directory (e.g. <filename class='directory'>/run/media/$USER/VolumeName</filename>) when the <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Filesystem.Mount()</link> method is handled. |
| 270 |
</para> |
| 271 |
</listitem> |
| 272 |
</varlistentry> |
| 273 |
<varlistentry> |
| 274 |
<term><option>ID_SEAT</option></term> |
| 275 |
<listitem> |
| 276 |
<para> |
| 277 |
The physical seat the device is attached to. If unset or |
| 278 |
set to the empty string, <quote>seat0</quote> (the first |
| 279 |
seat) is assumed. |
| 280 |
</para> |
| 281 |
</listitem> |
| 282 |
</varlistentry> |
| 283 |
<varlistentry> |
| 284 |
<term><option>ID_ATA_SMART_ACCESS</option></term> |
| 285 |
<listitem> |
| 286 |
<para> |
| 287 |
Override the access method for SMART data retrieval. Valid values include: <literal>sat16</literal>, <literal>sat12</literal>, <literal>linux-ide</literal>, <literal>sunplus</literal>, <literal>jmicron</literal>, <literal>none</literal> and <literal>auto</literal> (default). |
| 288 |
Specify <literal>none</literal> to avoid any I/O, in such a case the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive-Ata.SmartUpdated">SmartUpdated</link> property will always equal to <quote>0</quote>. |
| 289 |
</para> |
| 290 |
</listitem> |
| 291 |
</varlistentry> |
| 292 |
</variablelist> |
| 293 |
</refsect1> |
| 294 |
|
| 295 |
<refsect1><title>API STABILITY</title> |
| 296 |
<para> |
| 297 |
udisks guarantees a stable D-Bus API within the same major |
| 298 |
version and this guarantee also extends to the client-side |
| 299 |
library <filename>libudisks2</filename>. Additionally, several |
| 300 |
major versions of udisks can be installed and operate at the |
| 301 |
same time although interoperability may be limited - for |
| 302 |
example, a device mounted using the udisks N.x API may require |
| 303 |
additional authorization if attempting to unmount it through the |
| 304 |
the (N-1).x API. |
| 305 |
</para> |
| 306 |
<para> |
| 307 |
The udisks developers do not anticipate breaking API but does |
| 308 |
reserve the right to do so and if it happens, promises to bump |
| 309 |
the major version and ensure the new major version of udisks is |
| 310 |
parallel-installable with any older major version. However, note |
| 311 |
that programs, man pages and other artifacts may change name |
| 312 |
(for example, adopt a <quote>2</quote> suffix) to make room for |
| 313 |
the next major version. Therefore, applications can not rely on |
| 314 |
tools like e.g. |
| 315 |
<link linkend="udisksctl.1"><citerefentry><refentrytitle>udisksctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></link> |
| 316 |
to be available. Additionally, there is no guarantee that the |
| 317 |
options, command-line switches etc. of command-line tools or |
| 318 |
similar will remain stable. |
| 319 |
</para> |
| 320 |
<para> |
| 321 |
Instead, applications should only use the D-Bus API, the |
| 322 |
<filename>libudisks2</filename> library or tools such as |
| 323 |
<citerefentry> |
| 324 |
<refentrytitle>dbus-send</refentrytitle><manvolnum>1</manvolnum> |
| 325 |
</citerefentry> |
| 326 |
or |
| 327 |
<citerefentry> |
| 328 |
<refentrytitle>gdbus</refentrytitle><manvolnum>1</manvolnum> |
| 329 |
</citerefentry> |
| 330 |
to interact with |
| 331 |
<link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>. |
| 332 |
</para> |
| 333 |
</refsect1> |
| 334 |
|
| 335 |
<refsect1><title>AUDIENCE</title> |
| 336 |
<para> |
| 337 |
The intended audience of udisks include operating system |
| 338 |
developers working on the higher-level parts of the operating |
| 339 |
system, for example the desktop shell (such as <ulink |
| 340 |
url="http://www.gnome.org">GNOME</ulink>) and disk management |
| 341 |
applications (e.g. GNOME's <ulink |
| 342 |
url="https://live.gnome.org/Design/Apps/Disks">Disks</ulink> |
| 343 |
application). Software on this level typically depend on a |
| 344 |
specific (major) version of udisks and may even have support for |
| 345 |
previous versions of udisks or alternative interfaces performing |
| 346 |
the same role as udisks. |
| 347 |
</para> |
| 348 |
<para> |
| 349 |
While udisks indeed provides a stable API and a clear upgrade |
| 350 |
path, it may not be an appropriate dependency for third party |
| 351 |
applications. For example, if the operating system switches to |
| 352 |
udisks version N.x and an application is still using the udisks |
| 353 |
(N-1).x API, the application will not work unless udisks (N-1).x |
| 354 |
is installed. While this situation is still workable (since both |
| 355 |
udisks N.x and udisks (N-1).x can be installed) it may not be |
| 356 |
desirable to ask the user to install the old version - in fact, |
| 357 |
the operating system vendor may not even provide a packaged |
| 358 |
version of the old version. Hence, if an application does not |
| 359 |
want to tie itself to a specific version of the operating |
| 360 |
system, it should not use udisks. |
| 361 |
</para> |
| 362 |
<para> |
| 363 |
Viable alternatives to udisks are APIs that are guaranteed to be |
| 364 |
around for longer time-frames, including: |
| 365 |
<itemizedlist> |
| 366 |
<listitem> |
| 367 |
<para> |
| 368 |
Low-level APIs and commands such as e.g. |
| 369 |
<ulink url="http://en.wikipedia.org/wiki/Sysfs">sysfs</ulink>, |
| 370 |
<ulink url="https://www.freedesktop.org/software/systemd/man/libudev.html">libudev</ulink>, |
| 371 |
<ulink url="http://www.kernel.org/doc/Documentation/filesystems/proc.txt">/proc/self/mountinfo</ulink> and |
| 372 |
<ulink url="http://en.wikipedia.org/wiki/Util-linux">util-linux</ulink>. |
| 373 |
</para> |
| 374 |
</listitem> |
| 375 |
<listitem> |
| 376 |
<para> |
| 377 |
High-level APIs such as <ulink url="http://developer.gnome.org/gio/stable/volume_mon.html">GVolumeMonitor</ulink>. |
| 378 |
</para> |
| 379 |
</listitem> |
| 380 |
</itemizedlist> |
| 381 |
In particular, for desktop applications it is a much better idea |
| 382 |
to use something like GVolumeMonitor since it will make the |
| 383 |
application show the same devices as the desktop shell |
| 384 |
(e.g. file manager, file chooser and so on) is showing. |
| 385 |
</para> |
| 386 |
</refsect1> |
| 387 |
|
| 388 |
<refsect1><title>AUTHOR</title> |
| 389 |
<para> |
| 390 |
This man page was originally written for UDisks2 by David Zeuthen |
| 391 |
<email><![CDATA[[email protected]]]></email> with a lot of help |
| 392 |
from many others. |
| 393 |
</para> |
| 394 |
</refsect1> |
| 395 |
|
| 396 |
<refsect1> |
| 397 |
<title>BUGS</title> |
| 398 |
<para> |
| 399 |
Please send bug reports to either the distribution bug tracker |
| 400 |
or the upstream bug tracker at |
| 401 |
<ulink url="https://github.com/storaged-project/udisks/issues"/>. |
| 402 |
</para> |
| 403 |
</refsect1> |
| 404 |
|
| 405 |
<refsect1> |
| 406 |
<title>SEE ALSO</title> |
| 407 |
<para> |
| 408 |
<citerefentry> |
| 409 |
<refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum> |
| 410 |
</citerefentry>, |
| 411 |
<citerefentry> |
| 412 |
<refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum> |
| 413 |
</citerefentry>, |
| 414 |
<link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>, |
| 415 |
<link linkend="udisksctl.1"><citerefentry><refentrytitle>udisksctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>, |
| 416 |
<link linkend="umount.udisks2.8"><citerefentry><refentrytitle>umount.udisks2</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>, |
| 417 |
<citerefentry><refentrytitle>gnome-disks</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| 418 |
</para> |
| 419 |
</refsect1> |
| 420 |
</refentry> |