Debian Codegraph @

doc/udisks2-docs.xml.in

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY version SYSTEM "version.xml">
5 ]>
6 <book id="udisks" xmlns:xi="http://www.w3.org/2003/XInclude">
7 <bookinfo>
8 <title>UDisks Reference Manual</title>
9 <releaseinfo>
10 For version &version; — the latest version of this
11 documentation can be found at <ulink role="online-location"
12 url="https://storaged.org/udisks/docs/">https://storaged.org/udisks/docs/</ulink>.
13 </releaseinfo>
14 </bookinfo>
15
16 <part id="overview">
17 <title>Manual pages and Overview</title>
18 <xi:include href="man/udisksctl.xml"/>
19 <!-- DAEMON_MAN_PAGE -->
20 <!-- LVM2_MAN_PAGE -->
21 <!-- LSM_MAN_PAGE -->
22 <xi:include href="configurable_mount_options.xml"/>
23 </part>
24
25 <part id="ref-dbus">
26 <title>D-Bus API Reference</title>
27 <chapter id="ref-dbus-overview">
28 <title>Overview</title>
29 <sect1 id="ref-dbus-well-known-name">
30 <title>The org.freedesktop.UDisks2 bus name</title>
31 <para>
32 The D-Bus name <literal>org.freedesktop.UDisks2</literal> on
33 the system bus is used by the UDisks Daemon, <link
34 linkend="udisksd.8">udisksd</link>. If this daemon isn't
35 running, it will be started if D-Bus messages are sent to
36 the name.
37 </para>
38 </sect1>
39 <sect1 id="ref-dbus-udisks2-well-known-object">
40 <title>The /org/freedesktop/UDisks2 object</title>
41 <para>
42 The process that owns the well-known D-Bus name <link
43 linkend="ref-dbus-well-known-name">org.freedesktop.UDisks2</link>
44 on the system bus (typically <link
45 linkend="udisksd.8">udisksd</link>) exports an object at the
46 well-known path <literal>/org/freedesktop/UDisks2</literal>.
47 This object implements the <ulink
48 url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
49 interface and should be used by clients to discover other
50 objects.
51 </para>
52 </sect1>
53 <sect1 id="ref-dbus-manager-well-known-object">
54 <title>The /org/freedesktop/UDisks2/Manager object</title>
55 <para>
56 The object at the path
57 <literal>/org/freedesktop/UDisks2/Manager</literal>
58 implements the <link
59 linkend="gdbus-interface-org-freedesktop-UDisks2-Manager.top_of_page">org.freedesktop.UDisks2.Manager</link>
60 D-Bus interface. This object can be used to inspect and
61 manipulate global state.
62 </para>
63 </sect1>
64
65 <sect1 id="ref-dbus-block-devices">
66 <title>The /org/freedesktop/UDisks2/block_devices/* objects</title>
67 <para>
68 Objects with object paths starting with
69 <literal>/org/freedesktop/UDisks2/block_devices/</literal>
70 all represent <ulink url="http://en.wikipedia.org/wiki/Block_device#Block_devices">block devices</ulink>.
71 Such objects implement the
72 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Block.top_of_page">org.freedesktop.UDisks2.Block</link>
73 D-Bus interface and may optionally implement other D-Bus interfaces such as
74 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>,
75 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Partition.top_of_page">org.freedesktop.UDisks2.Partition</link> or
76 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Loop.top_of_page">org.freedesktop.UDisks2.Loop</link> depending on the block device in question.
77 </para>
78 <para>
79 Note that interfaces may be added and removed at
80 run-time. For example, if a block device is full of zeroes
81 (or, at least, have zeroes in the known metadata areas), it
82 will not initially implement the <link
83 linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>
84 interface; however, if a filesystem is later created on the device
85 (using, say, the
86 <citerefentry>
87 <refentrytitle>mkfs</refentrytitle><manvolnum>8</manvolnum>
88 </citerefentry>
89 command) and the filesystem is recognized by the OS (specifically, recognized by
90 <citerefentry>
91 <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
92 </citerefentry> and its device probers), the object will gain the interface. If the device is later zeroed or formatted for use as e.g. swap-space, it will lose the
93 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Filesystem.top_of_page">org.freedesktop.UDisks2.Filesystem</link>
94 interface.
95 </para>
96 </sect1>
97
98 <sect1 id="ref-dbus-drives">
99 <title>The /org/freedesktop/UDisks2/drives/* objects</title>
100 <para>
101 Objects with object paths starting with
102 <literal>/org/freedesktop/UDisks2/drives/</literal>
103 all represent <ulink url="http://en.wikipedia.org/wiki/Disk_drive">disk drives</ulink>,
104 typically physical disk drives.
105 Such objects implement the
106 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Drive.top_of_page">org.freedesktop.UDisks2.Drive</link>
107 D-Bus interface and may optionally implement other D-Bus interfaces such as
108 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Drive-Ata.top_of_page">org.freedesktop.UDisks2.Drive.Ata</link> depending on the drive in question.
109 </para>
110 <para>
111 A drive object should not to be confused with
112 <link linkend="ref-dbus-block-devices">block device</link>
113 objects (which are used for low-level block devices the OS
114 knows about). For example, if <filename>/dev/sda</filename>
115 and <filename>/dev/sdb</filename> are block devices for two
116 paths to the same drive, there will be only drive object but
117 two block device objects.
118 </para>
119 </sect1>
120
121 <sect1 id="ref-dbus-md-raid">
122 <title>The /org/freedesktop/UDisks2/mdraid/* objects</title>
123 <para>
124 Objects with object paths starting with
125 <literal>/org/freedesktop/UDisks2/mdraid/</literal>
126 represent <ulink url="https://raid.wiki.kernel.org/index.php/Linux_Raid">Linux Software RAID arrays</ulink>.
127 Such objects implement the
128 <link linkend="gdbus-interface-org-freedesktop-UDisks2-MDRaid.top_of_page">org.freedesktop.UDisks2.MDRaid</link>
129 D-Bus interface.
130 </para>
131 <para>
132 These objects should not to be confused with
133 <link linkend="ref-dbus-block-devices">block device</link>
134 objects (which are used for low-level block devices the OS
135 knows about).
136 </para>
137 </sect1>
138
139 <sect1 id="ref-iscsi-session">
140 <title>The /org/freedesktop/UDisks2/iscsi/session[0-9]+ objects</title>
141 <para>
142 Objects with object paths starting with
143 <literal>/org/freedesktop/UDisks2/iscsi/session[0-9]+</literal>
144 represent iSCSI session parameters. Such objects implement the
145 <link linkend="gdbus-interface-org-freedesktop-UDisks2-ISCSI-Session.top_of_page">org.freedesktop.UDisks2.ISCSI.Session</link>
146 D-Bus interface.
147 </para>
148 </sect1>
149
150 <sect1 id="ref-dbus-jobs">
151 <title>The /org/freedesktop/UDisks2/jobs/* objects</title>
152 <para>
153 Objects with object paths starting with
154 <literal>/org/freedesktop/UDisks2/jobs/</literal> all
155 represent long-running tasks, typically initiated by the
156 user and are guaranteed to implement the
157 <link linkend="gdbus-interface-org-freedesktop-UDisks2-Job.top_of_page">org.freedesktop.UDisks2.Job</link>
158 D-Bus interface.
159 </para>
160 </sect1>
161
162 <sect1 id="udisks-polkit-actions">
163 <title>Authorization Checks</title>
164 <para>
165 Many methods and operations offered by udisks requires the
166 calling user to be sufficiently authorized. Whether the user
167 is authorized is checked using <ulink
168 url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink>
169 allowing the administrator to configure fine-grained permissions via
170 polkit authorization rules.
171 </para>
172 <para>
173 There is not necessarily a one-to-one relationship between
174 D-Bus methods and polkit actions - typically the
175 relationship is more complicated and depends on both the
176 context of the process invoking the method, the object the
177 method is acting on and possibly more factors. For example,
178 the <link
179 linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Filesystem.Mount()</link>
180 method call may check that the caller is authorized for one
181 of the four actions
182 <emphasis>org.freedesktop.UDisks2.filesystem-mount</emphasis>,
183 <emphasis>org.freedesktop.UDisks2.filesystem-mount-system</emphasis>,
184 <emphasis>org.freedesktop.UDisks2.filesystem-mount-other-seat</emphasis>
185 or
186 <emphasis>org.freedesktop.UDisks2.filesystem-mount-fstab</emphasis>
187 depending on circumstances.
188 </para>
189 <para>
190 Often there will be two polkit actions for one operation -
191 one for so-called <quote>system devices</quote> and one for
192 non-system devices. In this context <quote>system
193 device</quote> refers to the value of the <link
194 linkend="gdbus-property-org-freedesktop-UDisks2-Block.HintSystem">Block:HintSystem</link>
195 D-Bus property and is normally only
196 <constant>TRUE</constant> for devices not considered
197 <quote>removable</quote> (devices considered removable
198 include USB attached storage, Flash media and optical
199 drives). See <xref linkend="udisks.8"/> for how to control
200 if a device is considered a system device.
201 </para>
202 <para>
203 The polkit actions are not considered stable and may change
204 from release to release so administrators should take notice
205 when upgrading from one version of udisks to another. For
206 example, polkit authorization rules may need to be updated
207 to match an updated policy.
208 </para>
209 <para>
210 See <xref linkend="udisks-polkit-details"/> for the
211 variables that can be used to assist in determining if the
212 caller is authorized (note that each variable may not be set
213 for request). For example, a polkit authorization rule for
214 any of the
215 <emphasis>org.freedesktop.UDisks2.filesystem-mount*</emphasis>
216 actions can use the <parameter>device</parameter> variable
217 to determine if the caller is authorized to mount a specific
218 block device.
219 </para>
220
221 <table frame="all" id="udisks-polkit-details">
222 <title>Known polkit variables</title>
223 <tgroup cols="2" align="left" colsep="1" rowsep="1">
224 <thead>
225 <row>
226 <entry>key</entry>
227 <entry>value</entry>
228 </row>
229 </thead>
230 <tbody>
231 <row>
232 <entry><parameter>device</parameter></entry>
233 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.PreferredDevice">Block:PreferredDevice</link> property. If set, this is guaranteed to be a device file, for example <quote>/dev/vg_lucifer/lv_root</quote> or <quote>/dev/sda1</quote>. If the object is not a block device, this is not set.</entry>
234 </row>
235 <row>
236 <entry><parameter>drive</parameter></entry>
237 <entry>Like the <parameter>device</parameter> variable, but if the object is also a drive, this variable includes Vital Product Data about the drive such as the vendor and model identifiers (if available), for example <quote>INTEL SSDSA2MH080G1GC (/dev/sda1)</quote>. Otherwise is just set to the same value as <parameter>device</parameter>. If the object is not a block device, this is not set (it is however set if the object is a block device but not a drive).</entry>
238 </row>
239
240 <row>
241 <entry><parameter>drive.wwn</parameter></entry>
242 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.WWN">Drive:WWN</link> property.</entry>
243 </row>
244 <row>
245 <entry><parameter>drive.serial</parameter></entry>
246 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Serial">Drive:Serial</link> property.</entry>
247 </row>
248 <row>
249 <entry><parameter>drive.vendor</parameter></entry>
250 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Vendor">Drive:Vendor</link> property.</entry>
251 </row>
252 <row>
253 <entry><parameter>drive.model</parameter></entry>
254 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Model">Drive:Model</link> property.</entry>
255 </row>
256 <row>
257 <entry><parameter>drive.revision</parameter></entry>
258 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Revision">Drive:Revision</link> property.</entry>
259 </row>
260 <row>
261 <entry><parameter>drive.removable</parameter></entry>
262 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the string <quote>true</quote> only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry>
263 </row>
264 <row>
265 <entry><parameter>drive.removable.bus</parameter></entry>
266 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.ConnectionBus">Drive:ConnectionBus</link> property. This variable is set only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry>
267 </row>
268 <row>
269 <entry><parameter>drive.removable.media</parameter></entry>
270 <entry>If the object is a drive (or a block device that is part of a drive), this is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.MediaCompatibility">Drive:MediaCompatibility</link> property. This variable is set only if the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Drive.Removable">Drive:Removable</link> property is <constant>TRUE</constant>.</entry>
271 </row>
272
273 <row>
274 <entry><parameter>id.type</parameter></entry>
275 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdType">Block:IdType</link> property.</entry>
276 </row>
277 <row>
278 <entry><parameter>id.usage</parameter></entry>
279 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdUsage">Block:IdUsage</link> property.</entry>
280 </row>
281 <row>
282 <entry><parameter>id.version</parameter></entry>
283 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdVersion">Block:IdVersion</link> property.</entry>
284 </row>
285 <row>
286 <entry><parameter>id.label</parameter></entry>
287 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdLabel">Block:IdLabel</link> property.</entry>
288 </row>
289 <row>
290 <entry><parameter>id.uuid</parameter></entry>
291 <entry>If the object is a block device, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Block.IdUUID">Block:IdUUID</link> property.</entry>
292 </row>
293
294 <row>
295 <entry><parameter>partition.number</parameter></entry>
296 <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Number">Partition:Number</link> property.</entry>
297 </row>
298 <row>
299 <entry><parameter>partition.type</parameter></entry>
300 <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Type">Partition:Type</link> property.</entry>
301 </row>
302 <row>
303 <entry><parameter>partition.flags</parameter></entry>
304 <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Flags">Partition:Flags</link> property.</entry>
305 </row>
306 <row>
307 <entry><parameter>partition.name</parameter></entry>
308 <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.Name">Partition:Name</link> property.</entry>
309 </row>
310 <row>
311 <entry><parameter>partition.uuid</parameter></entry>
312 <entry>If the object is a partition, this property is set to the value of the <link linkend="gdbus-property-org-freedesktop-UDisks2-Partition.UUID">Partition:UUID</link> property.</entry>
313 </row>
314
315 </tbody>
316 </tgroup>
317 </table>
318
319 <para>
320 For reference, the polkit actions defined by udisks &version;
321 are included here:
322 <informalexample id="udisks-polkit-actions-file"><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../data/org.freedesktop.UDisks2.policy.in"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></informalexample>
323 </para>
324 </sect1>
325
326 <sect1 id="udisks-std-options">
327 <title>The <parameter>options</parameter> parameter</title>
328 <para>
329 Many method calls take a parameter of type
330 <link linkend='G-VARIANT-TYPE-VARDICT:CAPS'>'a{sv}'</link>
331 that is normally called <parameter>options</parameter>.
332 The following table lists well-known options:
333 </para>
334 <table frame='all'>
335 <title>Well-known options</title>
336 <tgroup cols='3' align='left' colsep='1' rowsep='1'>
337 <thead>
338 <row>
339 <entry>Option name</entry>
340 <entry>Value type</entry>
341 <entry>Description</entry>
342 </row>
343 </thead>
344 <tbody>
345 <row>
346 <entry>auth.no_user_interaction</entry>
347 <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
348 <entry>
349 If set to <constant>TRUE</constant>, then no user
350 interaction will happen when checking if the method
351 call is authorized.
352 </entry>
353 </row>
354 </tbody>
355 </tgroup>
356 </table>
357 </sect1>
358
359 </chapter>
360
361 <chapter>
362 <title>D-Bus Interfaces</title>
363 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Manager.xml"/>
364 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Drive.xml"/>
365 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Drive.Ata.xml"/>
366 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.MDRaid.xml"/>
367 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Block.xml"/>
368 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Partition.xml"/>
369 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.PartitionTable.xml"/>
370 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Filesystem.xml"/>
371 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Swapspace.xml"/>
372 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Encrypted.xml"/>
373 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Loop.xml"/>
374 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Job.xml"/>
375 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.NVMe.Controller.xml"/>
376 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.NVMe.Namespace.xml"/>
377 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.Manager.NVMe.xml"/>
378 <xi:include href="xml/udisks-generated-doc-org.freedesktop.UDisks2.NVMe.Fabrics.xml"/>
379 <!-- LSM_DBUS_INTERFACE -->
380 <!-- LVM2_DBUS_INTERFACE -->
381 <!-- ISCSI_DBUS_INTERFACE -->
382 <!-- BTRFS_DBUS_INTERFACE -->
383 </chapter>
384 </part>
385
386 <part id="ref-library">
387 <title>Library API Reference</title>
388 <xi:include href="xml/udisksclient.xml"/>
389 <xi:include href="xml/udisksobjectinfo.xml"/>
390 <xi:include href="xml/udiskserror.xml"/>
391 <chapter id="ref-library-generated">
392 <title>Generated Code</title>
393 <xi:include href="xml/UDisksObject.xml"/>
394 <xi:include href="xml/UDisksObjectManagerClient.xml"/>
395 <xi:include href="xml/UDisksManager.xml"/>
396 <xi:include href="xml/UDisksDrive.xml"/>
397 <xi:include href="xml/UDisksDriveAta.xml"/>
398 <xi:include href="xml/UDisksMDRaid.xml"/>
399 <xi:include href="xml/UDisksJob.xml"/>
400 <xi:include href="xml/UDisksBlock.xml"/>
401 <xi:include href="xml/UDisksPartition.xml"/>
402 <xi:include href="xml/UDisksPartitionTable.xml"/>
403 <xi:include href="xml/UDisksFilesystem.xml"/>
404 <xi:include href="xml/UDisksSwapspace.xml"/>
405 <xi:include href="xml/UDisksEncrypted.xml"/>
406 <xi:include href="xml/UDisksLoop.xml"/>
407 <xi:include href="xml/UDisksNVMeController.xml"/>
408 <xi:include href="xml/UDisksNVMeNamespace.xml"/>
409 <xi:include href="xml/UDisksManagerNVMe.xml"/>
410 <xi:include href="xml/UDisksNVMeFabrics.xml"/>
411 <!-- LSM_GENERATED_CODE -->
412 <!-- LVM2_GENERATED_CODE -->
413 <!-- ISCSI_GENERATED_CODE -->
414 <!-- BTRFS_GENERATED_CODE -->
415 </chapter>
416 </part>
417
418 <!-- DAEMON_PART -->
419
420 <index id="api-index">
421 <title>Index</title>
422 </index>
423
424 <index id="api-index-deprecated" role="deprecated">
425 <title>Index of deprecated symbols</title>
426 <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
427 </index>
428
429 <!-- TODO: version -->
430 <index id="api-index-2.11.1" role="2.11.1">
431 <title>Index of new symbols in 2.11.1</title>
432 <xi:include href="xml/api-index-2.11.1.xml"><xi:fallback /></xi:include>
433 </index>
434
435 <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
436
437 <chapter id="gio-hierarchy">
438 <title>Object Hierarchy</title>
439 <xi:include href="xml/tree_index.sgml"/>
440 </chapter>
441 </book>