# UDisks Reference Manual

For version &version; — the latest version of this documentation can be found at https://storaged.org/udisks/docs/.

## Manual pages and Overview

## D-Bus API Reference

### Overview

#### The org.freedesktop.UDisks2 bus name

The D-Bus name `org.freedesktop.UDisks2` on the system bus is used by the UDisks Daemon, udisksd. If this daemon isn't running, it will be started if D-Bus messages are sent to the name.

#### The /org/freedesktop/UDisks2 object

The process that owns the well-known D-Bus name org.freedesktop.UDisks2 on the system bus (typically udisksd) exports an object at the well-known path `/org/freedesktop/UDisks2`. This object implements the org.freedesktop.DBus.ObjectManager interface and should be used by clients to discover other objects.

#### The /org/freedesktop/UDisks2/Manager object

The object at the path `/org/freedesktop/UDisks2/Manager` implements the org.freedesktop.UDisks2.Manager D-Bus interface. This object can be used to inspect and manipulate global state.

#### The /org/freedesktop/UDisks2/block_devices/* objects

Objects with object paths starting with `/org/freedesktop/UDisks2/block_devices/` all represent block devices. Such objects implement the org.freedesktop.UDisks2.Block D-Bus interface and may optionally implement other D-Bus interfaces such as org.freedesktop.UDisks2.Filesystem, org.freedesktop.UDisks2.Partition or org.freedesktop.UDisks2.Loop depending on the block device in question.

Note that interfaces may be added and removed at run-time. For example, if a block device is full of zeroes (or, at least, have zeroes in the known metadata areas), it will not initially implement the org.freedesktop.UDisks2.Filesystem interface; however, if a filesystem is later created on the device (using, say, the mkfs 8 command) and the filesystem is recognized by the OS (specifically, recognized by udev 7 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 org.freedesktop.UDisks2.Filesystem interface.

#### The /org/freedesktop/UDisks2/drives/* objects

Objects with object paths starting with `/org/freedesktop/UDisks2/drives/` all represent disk drives, typically physical disk drives. Such objects implement the org.freedesktop.UDisks2.Drive D-Bus interface and may optionally implement other D-Bus interfaces such as org.freedesktop.UDisks2.Drive.Ata depending on the drive in question.

A drive object should not to be confused with block device objects (which are used for low-level block devices the OS knows about). For example, if `/dev/sda` and `/dev/sdb` are block devices for two paths to the same drive, there will be only drive object but two block device objects.

#### The /org/freedesktop/UDisks2/mdraid/* objects

Objects with object paths starting with `/org/freedesktop/UDisks2/mdraid/` represent Linux Software RAID arrays. Such objects implement the org.freedesktop.UDisks2.MDRaid D-Bus interface.

These objects should not to be confused with block device objects (which are used for low-level block devices the OS knows about).

#### The /org/freedesktop/UDisks2/iscsi/session[0-9]+ objects

Objects with object paths starting with `/org/freedesktop/UDisks2/iscsi/session[0-9]+` represent iSCSI session parameters. Such objects implement the org.freedesktop.UDisks2.ISCSI.Session D-Bus interface.

#### The /org/freedesktop/UDisks2/jobs/* objects

Objects with object paths starting with `/org/freedesktop/UDisks2/jobs/` all represent long-running tasks, typically initiated by the user and are guaranteed to implement the org.freedesktop.UDisks2.Job D-Bus interface.

#### Authorization Checks

Many methods and operations offered by udisks requires the calling user to be sufficiently authorized. Whether the user is authorized is checked using polkit allowing the administrator to configure fine-grained permissions via polkit authorization rules.

There is not necessarily a one-to-one relationship between D-Bus methods and polkit actions - typically the relationship is more complicated and depends on both the context of the process invoking the method, the object the method is acting on and possibly more factors. For example, the Filesystem.Mount() method call may check that the caller is authorized for one of the four actions org.freedesktop.UDisks2.filesystem-mount, org.freedesktop.UDisks2.filesystem-mount-system, org.freedesktop.UDisks2.filesystem-mount-other-seat or org.freedesktop.UDisks2.filesystem-mount-fstab depending on circumstances.

Often there will be two polkit actions for one operation - one for so-called system devices and one for non-system devices. In this context system device refers to the value of the Block:HintSystem D-Bus property and is normally only `TRUE` for devices not considered removable (devices considered removable include USB attached storage, Flash media and optical drives). See for how to control if a device is considered a system device.

The polkit actions are not considered stable and may change from release to release so administrators should take notice when upgrading from one version of udisks to another. For example, polkit authorization rules may need to be updated to match an updated policy.

See for the variables that can be used to assist in determining if the caller is authorized (note that each variable may not be set for request). For example, a polkit authorization rule for any of the org.freedesktop.UDisks2.filesystem-mount* actions can use the `device` variable to determine if the caller is authorized to mount a specific block device.

##### Known polkit variables

key | value
--- | ---
`device` | If the object is a block device, this property is set to the value of the Block:PreferredDevice property. If set, this is guaranteed to be a device file, for example /dev/vg_lucifer/lv_root or /dev/sda1. If the object is not a block device, this is not set.

`drive`

Like the `device` 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 INTEL SSDSA2MH080G1GC (/dev/sda1). Otherwise is just set to the same value as `device`. 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).

`drive.wwn` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:WWN property.
`drive.serial` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:Serial property.
`drive.vendor` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:Vendor property.
`drive.model` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:Model property.
`drive.revision` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:Revision property.
`drive.removable` | If the object is a drive (or a block device that is part of a drive), this is set to the string true only if the value of the Drive:Removable property is `TRUE`.
`drive.removable.bus` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:ConnectionBus property. This variable is set only if the value of the Drive:Removable property is `TRUE`.
`drive.removable.media` | If the object is a drive (or a block device that is part of a drive), this is set to the value of the Drive:MediaCompatibility property. This variable is set only if the value of the Drive:Removable property is `TRUE`.
`id.type` | If the object is a block device, this property is set to the value of the Block:IdType property.
`id.usage` | If the object is a block device, this property is set to the value of the Block:IdUsage property.
`id.version` | If the object is a block device, this property is set to the value of the Block:IdVersion property.
`id.label` | If the object is a block device, this property is set to the value of the Block:IdLabel property.
`id.uuid` | If the object is a block device, this property is set to the value of the Block:IdUUID property.
`partition.number` | If the object is a partition, this property is set to the value of the Partition:Number property.
`partition.type` | If the object is a partition, this property is set to the value of the Partition:Type property.
`partition.flags` | If the object is a partition, this property is set to the value of the Partition:Flags property.
`partition.name` | If the object is a partition, this property is set to the value of the Partition:Name property.
`partition.uuid` | If the object is a partition, this property is set to the value of the Partition:UUID property.

For reference, the polkit actions defined by udisks &version; are included here:

    FIXME: MISSING XINCLUDE CONTENT

#### The `options` parameter

Many method calls take a parameter of type 'a{sv}' that is normally called `options`. The following table lists well-known options:

##### Well-known options

Option name | Value type | Description
--- | --- | ---
auth.no_user_interaction | 'b' | If set to `TRUE`, then no user interaction will happen when checking if the method call is authorized.

### D-Bus Interfaces

## Library API Reference

### Generated Code

## Daemon Implementation Details

### Core

### State and Configuration

### Jobs

### Linux-specific types

### Drives on Linux

### Linux RAID

### Block devices on Linux

## Index

## Index of deprecated symbols

## Index of new symbols in 2.11.1

## Object Hierarchy