path: root/doc/man/udisksctl.xml

<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[<!ENTITY version SYSTEM "../version.xml">]>
<refentry id="udisksctl.1">
  <refentryinfo>
    <title>udisksctl</title>
    <date>October 2012</date>
    <productname>udisks</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>udisksctl</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
    <refmiscinfo class="source">udisks</refmiscinfo>
    <refmiscinfo class="version">&version;</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>udisksctl</refname>
    <refpurpose>The udisks command line tool</refpurpose>
  </refnamediv>

  <refsynopsisdiv><title>SYNOPSIS</title>
    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">status</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">info</arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">mount </arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <group>
        <arg choice="plain">--filesystem-type <replaceable>TYPE</replaceable></arg>
      </group>
      <arg choice="opt" rep="repeat">--options <replaceable>OPTIONS</replaceable></arg>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">unmount </arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <arg choice="opt">--force</arg>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">unlock </arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">lock </arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">loop-setup </arg>
      <arg choice="plain">--file <replaceable>PATH</replaceable></arg>
      <arg choice="opt">--read-only</arg>
      <arg choice="opt">--offset <replaceable>OFFSET</replaceable></arg>
      <arg choice="opt">--size <replaceable>SIZE</replaceable></arg>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">loop-delete </arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">smart-simulate </arg>
      <arg choice="plain">--file <replaceable>PATH</replaceable></arg>
      <group choice="req">
        <arg choice="plain">--object-path <replaceable>OBJECT</replaceable></arg>
        <arg choice="plain">--block-device <replaceable>DEVICE</replaceable></arg>
      </group>
      <arg choice="opt">--no-user-interaction</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">monitor</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">dump</arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command>udisksctl</command>
      <arg choice="plain">help</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1><title>DESCRIPTION</title>
    <para>
      <command>udisksctl</command> is a command-line program used
      to interact with the
      <citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      daemon process.
    </para>
  </refsect1>

  <refsect1>
    <title>COMMANDS</title>
    <variablelist>

      <varlistentry>
        <term><option>status</option></term>
        <listitem>
          <para>
            Shows high-level information about disk drives and block
            devices.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>info</option></term>
        <listitem>
          <para>
            Shows detailed information about
            <replaceable>OBJECT</replaceable> or
            <replaceable>DEVICE</replaceable>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>mount</option></term>
        <listitem>
          <para>
            Mounts a device. The device will be mounted in a
            subdirectory in the <filename>/media</filename> hierarchy
            - upon successful completion, the mount point will be
            printed to standard output.
          </para>
          <para>
            The device will be mounted with a safe set of default
            options. You can influence the options passed to the
            <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
            command with <option>--options</option>. Note that only
            safe options are allowed - requests with inherently unsafe
            options such as <parameter>suid</parameter> or
            <parameter>dev</parameter> that would allow the caller to
            gain additional privileges, are rejected.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>unmount</option></term>
        <listitem>
          <para>
            Unmounts a device. This only works if the device is
            mounted. The option <option>--force</option> can be used
            to request that the device is unmounted even if active
            references exists.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>unlock</option></term>
        <listitem>
          <para>
            Unlocks an encrypted device. The passphrase will be
            requested from the controlling terminal and upon
            successful completion, the cleartext device will be
            printed to standard output.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>lock</option></term>
        <listitem>
          <para>
            Locks a device. This only works if the device is a
            cleartext device backed by a cryptotext device.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>loop-setup</option></term>
        <listitem>
          <para>
            Sets up a loop device backed by <replaceable>FILE</replaceable>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>loop-delete</option></term>
        <listitem>
          <para>
            Tears down a loop device.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>smart-simulate</option></term>
        <listitem>
          <para>
            Sets SMART data from the libatasmart blob given by
            <replaceable>FILE</replaceable> - see
            <filename>/usr/share/doc/libatasmart-devel-VERSION/</filename>
            for blobs shipped with libatasmart. This is a debugging
            feature used to check that applications act correctly when
            a disk is failing.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>monitor</option></term>
        <listitem><para>
          Monitors the daemon for events.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>dump</option></term>
        <listitem><para>
          Prints the current state of the daemon.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><option>help</option></term>
        <listitem><para>
          Prints help and exit.
        </para></listitem>
      </varlistentry>

    </variablelist>
  </refsect1>

  <refsect1>
    <title>COMMON OPTIONS</title>
    <para>
      The option <option >--no-user-interaction</option> can be used
      to request that no interaction (such as the user being
      presented with an authentication dialog) must occur when
      checking with
      <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>
      whether the caller is authorized to perform the requested
      action.
    </para>
  </refsect1>

  <refsect1><title>AUDIENCE</title>
    <para>
      This program does not assume that the caller is the super user -
      it is intended to be used by unprivileged users and
      authorizations are checked by the udisks daemon using
      <citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
      Additionally, this program is not intended to be used by scripts
      or other programs - options/commands may change in incompatible
      ways in the future even in maintenance releases. See the
      <quote>API STABILITY</quote> section of
      <link linkend="udisks.8"><citerefentry><refentrytitle>udisks</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>
      for more information.
    </para>
  </refsect1>

  <refsect1><title>BASH COMPLETION</title>
    <para>
      <command>udisksctl</command> ships with a bash completion script to
      complete commands, objects, block devices and some options.
    </para>
  </refsect1>

  <refsect1><title>AUTHOR</title>
    <para>
      Written by David Zeuthen
      <email><![CDATA[zeuthen@gmail.com]]></email> with a lot of help
      from many others.
    </para>
  </refsect1>

  <refsect1>
    <title>BUGS</title>
    <para>
      Please send bug reports to either the distribution bug tracker
      or the upstream bug tracker at
      <ulink url="http://bugs.freedesktop.org/enter_bug.cgi?product=udisks"/>.
    </para>
  </refsect1>

  <refsect1>
    <title>SEE ALSO</title>
    <para>
      <link linkend="udisks.8"><citerefentry><refentrytitle>udisks</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
      <link linkend="udisksd.8"><citerefentry><refentrytitle>udisksd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
      <citerefentry>
        <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>