Debian Codegraph @

doc/man/udisksctl.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="udisksctl.1">
6 <refentryinfo>
7 <title>udisksctl</title>
8 <date>August 2018</date>
9 <productname>udisks</productname>
10 </refentryinfo>
11
12 <refmeta>
13 <refentrytitle>udisksctl</refentrytitle>
14 <manvolnum>1</manvolnum>
15 <refmiscinfo class="manual">User Commands</refmiscinfo>
16 <refmiscinfo class="source">udisks</refmiscinfo>
17 <refmiscinfo class="version">&version;</refmiscinfo>
18 </refmeta>
19
20 <refnamediv>
21 <refname>udisksctl</refname>
22 <refpurpose>The udisks command line tool</refpurpose>
23 </refnamediv>
24
25 <refsynopsisdiv><title>SYNOPSIS</title>
26 <cmdsynopsis>
27 <command>udisksctl</command>
28 <arg choice="plain">status</arg>
29 </cmdsynopsis>
30
31 <cmdsynopsis>
32 <command>udisksctl</command>
33 <arg choice="plain">info</arg>
34 <group choice="req">
35 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
36 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
37 <arg choice="plain">--drive <replaceable>DRIVE</replaceable></arg>
38 </group>
39 </cmdsynopsis>
40
41 <cmdsynopsis>
42 <command>udisksctl</command>
43 <arg choice="plain">mount </arg>
44 <group choice="req">
45 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
46 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
47 </group>
48 <group>
49 <arg choice="plain">--filesystem-type <replaceable>TYPE</replaceable></arg>
50 </group>
51 <arg choice="opt" rep="repeat">--options <replaceable>OPTIONS</replaceable></arg>
52 <arg choice="opt">--no-user-interaction</arg>
53 </cmdsynopsis>
54
55 <cmdsynopsis>
56 <command>udisksctl</command>
57 <arg choice="plain">unmount </arg>
58 <group choice="req">
59 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
60 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
61 </group>
62 <arg choice="opt">--force</arg>
63 <arg choice="opt">--no-user-interaction</arg>
64 </cmdsynopsis>
65
66 <cmdsynopsis>
67 <command>udisksctl</command>
68 <arg choice="plain">unlock </arg>
69 <group choice="req">
70 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
71 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
72 </group>
73 <arg choice="opt">--no-user-interaction</arg>
74 <arg choice="opt">--key-file <replaceable>PATH</replaceable></arg>
75 <arg choice="opt">--read-only</arg>
76 </cmdsynopsis>
77
78 <cmdsynopsis>
79 <command>udisksctl</command>
80 <arg choice="plain">lock </arg>
81 <group choice="req">
82 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
83 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
84 </group>
85 <arg choice="opt">--no-user-interaction</arg>
86 </cmdsynopsis>
87
88 <cmdsynopsis>
89 <command>udisksctl</command>
90 <arg choice="plain">loop-setup </arg>
91 <arg choice="plain">--file <replaceable>PATH</replaceable></arg>
92 <arg choice="opt">--read-only</arg>
93 <arg choice="opt">--offset <replaceable>OFFSET</replaceable></arg>
94 <arg choice="opt">--size <replaceable>SIZE</replaceable></arg>
95 <arg choice="opt">--no-user-interaction</arg>
96 </cmdsynopsis>
97
98 <cmdsynopsis>
99 <command>udisksctl</command>
100 <arg choice="plain">loop-delete </arg>
101 <group choice="req">
102 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
103 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
104 </group>
105 <arg choice="opt">--no-user-interaction</arg>
106 </cmdsynopsis>
107
108 <cmdsynopsis>
109 <command>udisksctl</command>
110 <arg choice="plain">power-off </arg>
111 <group choice="req">
112 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
113 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
114 </group>
115 <arg choice="opt">--no-user-interaction</arg>
116 </cmdsynopsis>
117
118 <cmdsynopsis>
119 <command>udisksctl</command>
120 <arg choice="plain">smart-simulate </arg>
121 <arg choice="plain">--file <replaceable>PATH</replaceable></arg>
122 <group choice="req">
123 <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
124 <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
125 </group>
126 <arg choice="opt">--no-user-interaction</arg>
127 </cmdsynopsis>
128
129 <cmdsynopsis>
130 <command>udisksctl</command>
131 <arg choice="plain">monitor</arg>
132 </cmdsynopsis>
133
134 <cmdsynopsis>
135 <command>udisksctl</command>
136 <arg choice="plain">dump</arg>
137 </cmdsynopsis>
138
139 <cmdsynopsis>
140 <command>udisksctl</command>
141 <arg choice="plain">help</arg>
142 </cmdsynopsis>
143 </refsynopsisdiv>
144
145 <refsect1><title>DESCRIPTION</title>
146 <para>
147 <command>udisksctl</command> is a command-line program used
148 to interact with the
149 <citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
150 daemon process.
151 </para>
152 </refsect1>
153
154 <refsect1>
155 <title>COMMANDS</title>
156 <variablelist>
157
158 <varlistentry>
159 <term><option>status</option></term>
160 <listitem>
161 <para>
162 Shows high-level information about disk drives and block
163 devices.
164 </para>
165 </listitem>
166 </varlistentry>
167
168 <varlistentry>
169 <term><option>info</option></term>
170 <listitem>
171 <para>
172 Shows detailed information about
173 <replaceable>OBJECT</replaceable>,
174 <replaceable>DEVICE</replaceable> or
175 <replaceable>DRIVE</replaceable>.
176 </para>
177 </listitem>
178 </varlistentry>
179
180 <varlistentry>
181 <term><option>mount</option></term>
182 <listitem>
183 <para>
184 Mounts a device. The device will be mounted in a
185 subdirectory in the <filename>/run/media</filename> hierarchy
186 - upon successful completion, the mount point will be
187 printed to standard output.
188 </para>
189 </listitem>
190
191 <varlistentry>
192 <term><option>-t</option></term>
193 <term><option>--filesystem-type</option></term>
194 <listitem>
195 <para>
196 Filesystem type to use. If not specified, autodetected filesystem
197 type will be used.
198 </para>
199 </listitem>
200 </varlistentry>
201
202 <varlistentry>
203 <term><option>-o</option></term>
204 <term><option>--options</option></term>
205 <listitem>
206 <para>
207 The device will be mounted with a safe set of default
208 options. You can influence the options passed to the
209 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
210 command using this option. Note that only
211 safe options are allowed - requests with inherently unsafe
212 options such as <parameter>suid</parameter> or
213 <parameter>dev</parameter> that would allow the caller to
214 gain additional privileges, are rejected.
215 </para>
216 </listitem>
217 </varlistentry>
218
219 </varlistentry>
220
221 <varlistentry>
222 <term><option>unmount</option></term>
223 <listitem>
224 <para>
225 Unmounts a device. This only works if the device is
226 mounted. The option <option>--force</option> can be used
227 to request that the device is unmounted even if active
228 references exists.
229 </para>
230 </listitem>
231
232 <varlistentry>
233 <term><option>-f</option></term>
234 <term><option>--force</option></term>
235 <listitem>
236 <para>
237 Lazy unmount. Detach the filesystem from the file hierarchy
238 now, and clean up all references to this filesystem as soon
239 as it is not busy anymore.
240 </para>
241 </listitem>
242 </varlistentry>
243 </varlistentry>
244
245 <varlistentry>
246 <term><option>unlock</option></term>
247 <listitem>
248 <para>
249 Unlocks an encrypted device. The passphrase will be
250 requested from the controlling terminal and upon
251 successful completion, the cleartext device will be
252 printed to standard output.
253 </para>
254 </listitem>
255
256 <varlistentry>
257 <term><option>--key-file=<replaceable>PATH</replaceable></option></term>
258 <listitem>
259 <para>
260 Read passphrase from the given file.
261 </para>
262 </listitem>
263 </varlistentry>
264 </varlistentry>
265
266 <varlistentry>
267 <term><option>lock</option></term>
268 <listitem>
269 <para>
270 Locks a device. This only works if the device is a
271 cleartext device backed by a cryptotext device.
272 </para>
273 </listitem>
274 </varlistentry>
275
276 <varlistentry>
277 <term><option>loop-setup</option></term>
278 <listitem>
279 <para>
280 Sets up a loop device backed by <replaceable>FILE</replaceable>.
281 </para>
282 </listitem>
283
284 <varlistentry>
285 <term><option>-f</option></term>
286 <term><option>--file=<replaceable>FILE</replaceable></option></term>
287 <listitem>
288 <para>
289 File to set up a loop device for.
290 </para>
291 </listitem>
292 </varlistentry>
293
294 <varlistentry>
295 <term><option>-r</option></term>
296 <term><option>--read-only</option></term>
297 <listitem>
298 <para>
299 Set up a read-only loop device.
300 </para>
301 </listitem>
302 </varlistentry>
303
304 <varlistentry>
305 <term><option>-o</option></term>
306 <term><option>--offset=<replaceable>OFFSET</replaceable></option></term>
307 <listitem>
308 <para>
309 The data start is moved <replaceable>OFFSET</replaceable> bytes
310 into the specified file.
311 </para>
312 </listitem>
313 </varlistentry>
314
315 <varlistentry>
316 <term><option>-s</option></term>
317 <term><option>--size=<replaceable>SIZE</replaceable></option></term>
318 <listitem>
319 <para>
320 The data end is set to no more than <replaceable>SIZE</replaceable>
321 bytes after the data start.
322 </para>
323 </listitem>
324 </varlistentry>
325 </varlistentry>
326
327 <varlistentry>
328 <term><option>loop-delete</option></term>
329 <listitem>
330 <para>
331 Tears down a loop device.
332 </para>
333 </listitem>
334 </varlistentry>
335
336 <varlistentry>
337 <term><option>power-off</option></term>
338 <listitem>
339 <para>
340 Arranges for the drive to be safely removed and powered
341 off. On the OS side this includes ensuring that no process
342 is using the drive, then requesting that in-flight buffers
343 and caches are committed to stable storage. The exact
344 steps for powering off the drive depends on the drive
345 itself and the interconnect used. For drives connected
346 through USB, the effect is that the USB device will be
347 deconfigured followed by disabling the upstream hub port
348 it is connected to.
349 </para>
350 <para>
351 Note that as some physical devices contain multiple drives
352 (for example 4-in-1 flash card reader USB devices)
353 powering off one drive may affect other drives. As such
354 there are not a lot of guarantees associated with
355 performing this action. Usually the effect is that the
356 drive disappears as if it was unplugged.
357 </para>
358 </listitem>
359 </varlistentry>
360
361 <varlistentry>
362 <term><option>smart-simulate</option></term>
363 <listitem>
364 <para>
365 Sets SMART data from the libatasmart blob given by
366 <replaceable>FILE</replaceable> - see
367 <filename>/usr/share/doc/libatasmart-devel-VERSION/</filename>
368 for blobs shipped with libatasmart. This is a debugging
369 feature used to check that applications act correctly when
370 a disk is failing.
371 </para>
372 </listitem>
373
374 <varlistentry>
375 <term><option>-f</option></term>
376 <term><option>--file=<replaceable>FILE</replaceable></option></term>
377 <listitem>
378 <para>
379 File with the libatasmart blob.
380 </para>
381 </listitem>
382 </varlistentry>
383 </varlistentry>
384
385 <varlistentry>
386 <term><option>monitor</option></term>
387 <listitem><para>
388 Monitors the daemon for events.
389 </para></listitem>
390 </varlistentry>
391
392 <varlistentry>
393 <term><option>dump</option></term>
394 <listitem><para>
395 Prints the current state of the daemon.
396 </para></listitem>
397 </varlistentry>
398
399 <varlistentry>
400 <term><option>help</option></term>
401 <listitem><para>
402 Prints help and exit.
403 </para></listitem>
404 </varlistentry>
405
406 </variablelist>
407 </refsect1>
408
409 <refsect1>
410 <title>DEVICE SPECIFICATION</title>
411 <para>
412 For commands that require a device as an argument following options
413 can be used to specify it.
414 </para>
415 <variablelist>
416
417 <varlistentry>
418 <term><option>-b</option></term>
419 <term><option>--block-device=<replaceable>DEVICE</replaceable></option></term>
420 <listitem>
421 <para>
422 Specify a device by its device file path. For example
423 <emphasis>/dev/sda</emphasis>.
424 </para>
425 </listitem>
426 </varlistentry>
427
428 <varlistentry>
429 <term><option>-p</option></term>
430 <term><option>--object-path=<replaceable>OBJECT</replaceable></option></term>
431 <listitem>
432 <para>
433 Specify a device by the UDisks internal object path without the
434 /org/freedesktop/UDisks2 prefix. For example
435 <emphasis>block_devices/sda</emphasis>
436 for the <filename class="devicefile">/dev/sda</filename> disk.
437 </para>
438 </listitem>
439 </varlistentry>
440
441 <varlistentry>
442 <term><option>-d</option></term>
443 <term><option>--drive=<replaceable>DRIVE</replaceable></option></term>
444 <listitem>
445 <para>
446 Specify a drive by name, for example <emphasis>VirtIO_Disk</emphasis>.
447 This can be currently used only together with the
448 <option>info</option> command.
449 </para>
450 </listitem>
451 </varlistentry>
452
453 </variablelist>
454 </refsect1>
455
456 <refsect1>
457 <title>COMMON OPTIONS</title>
458 <para>
459 The option <option>--no-user-interaction</option> can be used
460 to request that no interaction (such as the user being
461 presented with an authentication dialog) must occur when
462 checking with
463 <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>
464 whether the caller is authorized to perform the requested
465 action.
466 </para>
467 </refsect1>
468
469 <refsect1><title>AUDIENCE</title>
470 <para>
471 This program does not assume that the caller is the super user -
472 it is intended to be used by unprivileged users and
473 authorizations are checked by the udisks daemon using
474 <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
475 Additionally, this program is not intended to be used by scripts
476 or other programs - options/commands may change in incompatible
477 ways in the future even in maintenance releases. See the
478 <quote>API STABILITY</quote> section of
479 <link linkend="udisks.8"><citerefentry><refentrytitle>udisks</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>
480 for more information.
481 </para>
482 </refsect1>
483
484 <refsect1><title>BASH COMPLETION</title>
485 <para>
486 <command>udisksctl</command> ships with a bash completion script to
487 complete commands, objects, block devices and some options.
488 </para>
489 </refsect1>
490
491 <refsect1><title>AUTHOR</title>
492 <para>
493 This man page was originally written for UDisks2 by David Zeuthen
494 <email><![CDATA[[email protected]]]></email> with a lot of help
495 from many others.
496 </para>
497 </refsect1>
498
499 <refsect1>
500 <title>BUGS</title>
501 <para>
502 Please send bug reports to either the distribution bug tracker
503 or the upstream bug tracker at
504 <ulink url="https://github.com/storaged-project/udisks/issues"/>.
505 </para>
506 </refsect1>
507
508 <refsect1>
509 <title>SEE ALSO</title>
510 <para>
511 <link linkend="udisks.8"><citerefentry><refentrytitle>udisks</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
512 <link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
513 <link linkend="umount.udisks2.8"><citerefentry><refentrytitle>umount.udisks2</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
514 <citerefentry>
515 <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
516 </citerefentry>
517 </para>
518 </refsect1>
519 </refentry>