Debian Codegraph @

doc/html/udisks.8.html

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