Debian Codegraph @

doc/man/udisks.xml

raw
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>