The AddConfigurationItem() method

AddConfigurationItem (IN  (sa{sv}) item,
                      IN  a{sv}    options);

Adds a new configuration item.

See the "Configuration" property for details about valid configuration items.

Some fields can be omitted and will then receive default values. This is useful when passing configuration items to Format, for example, because the proper values are not known before the formatting is done.

If 'fsname' is omitted in a 'fstab' entry, or 'device' is omitted in a 'crypttab' entry, it defaults to "UUID=..." when the block device has a filesystem UUID, or to the name of the device in the filesystem..

If 'name' is omitted in a 'crypttab' entry, it defaults to "luks-<UUID>".

If 'passphrase-path' is omitted, it defaults to "/etc/luks-keys/<NAME>".

If 'track-parents' is set to true in item, then the 'opts' and 'options' fields will be augmented with "x-parent" elements, as appropriate. This will make item appear in the ChildConfiguration properties, and will allow the 'tear-down' option of Format, DeletePartition, and other methods to remove this item reliably.

The RemoveConfigurationItem() method

RemoveConfigurationItem (IN  (sa{sv}) item,
                         IN  a{sv}    options);

Removes an existing configuration item.

See the "Configuration" property for details about valid configuration items.

The UpdateConfigurationItem() method

UpdateConfigurationItem (IN  (sa{sv}) old_item,
                         IN  (sa{sv}) new_item,
                         IN  a{sv}    options);

Removes a configuration item and adds a new one. This is equivalent to calling RemoveConfigurationItem() followed by AddConfigurationItem() with the change that only one PolicyKit check is made and that new_item can be validated against old_item.

See the "Configuration" property for details about valid configuration items.

The GetSecretConfiguration() method

GetSecretConfiguration (IN  a{sv}     options,
                        OUT a(sa{sv}) configuration);

Returns the same value as in the "Configuration" property but without secret information filtered out.

The Format() method

Format (IN  s     type,
        IN  a{sv} options);

Formats the device with a file system, partition table or other well-known content.

Known values for type includes empty (to just zero out areas of the device known to host file system signatures) and swap (Linux swap space) and most file systems supported by the mkfs(8) program through its -t option.

Known partition table formats includes dos and gpt.

If type supports it, you can specify a label with the label option in the options parameter; however, note that this may not be supported on all file systems and, if supported, the maximum allowed length may vary. Similarly, you can specify filesystem UUID with the uuid option in the options parameter given that the particular filesystem type supports this feature. The format of the UUID string should match the "IdUUID" property.

If the file system in question supports owners and the option take-ownership is set to TRUE then the root directory of the created file system will be owned by the caller of this method.

If the option encrypt.passphrase is given then a LUKS device is created with the given passphrase and the file system is created on the unlocked device. The unlocked device will be left open. This parameter can be used to supply the binary contents of an arbitrary keyfile by passing a value of type “ay”. Option encrypt.type can be used to specify encryption "technology" that will be used. Currently only “luks1” and “luks2” are supported. Following additional options for LUKS key derivation function can be used:

If the option erase is used then the underlying device will be erased. Valid values include “zero” to write zeroes over the entire device before formatting, “ata-secure-erase” to perform a secure erase or “ata-secure-erase-enhanced” to perform an enhanced secure erase.

If the option update-partition-type is set to TRUE and the object in question is a partition, then its type (cf. the "Type" property) will be set to the natural partition type matching type, if any. For example, if formatting a GPT partition with a FAT filesystem, the “Microsoft Basic Data” partition type will be chosen; similar, if formatting a DOS partition with a Ext4 filesystem then partition type 0x83 is chosen.

If the option no-block is set to TRUE then the method returns just before the actual formatting takes place but after authorization and other checks are done. This is useful for applications that want to format several devices in parallel.

If the option dry-run-first is set to TRUE then a dry run of the formatting command is performed first, if UDisks knows how to do that. The idea is that this allows a deeper check of the parameters even when no-block is TRUE. Note that the block device has already been modified (wiped) when the dry run check is called.

If the option mkfs-args is set then the caller can provide a list of additional command-line arguments that will be passed to the mkfs program. The arguments specified in this way are not validated by UDisks, and the user is responsible for making sure that the available mkfs program for that filesystem supports them and that they work for the intended purpose. Note that UDisks can also pass its own additional arguments to mkfs, and they may vary between releases, with no guarantees of stability in this regard. The position in which the user-provided arguments are appended to the final mkfs command line is also not defined. Because of all this, mkfs-args should only be used as a last resort when no other dedicated option is available.

If the option no-discard is set to TRUE then Udisks tells the formatting utility not to issue BLKDISCARD ioctls.

If the option config-items is set, it should be an array of configuration items suitable for org.freedesktop.UDisks2.Block.AddConfigurationItem. They will all be added after the formatting is done.

If the option tear-down is set to TRUE, then the block device and all its children will be cleaned up before formatting. This cleanup consists of removing entries from /etc/fstab and /etc/crypttab, and locking of encrypted block devices. Entries in /etc/fstab and /etc/crypttab that have been created with the 'track-parents' options to AddConfigurationItem will be removed even if their block device is currently unavailable.

Note that if the operation fails the block device may be left in an inconsistent state. In cases of removing partition table and failed operation it's advised to validate the device e.g. by re-reading the partition table or force-wiping it before performing further operations.

In case the tear-down option is not set and the block device being formatted is partitioned and contains mounted filesystem or an active layered structure inside then the Format operation may not fail, yet could still overwrite nested foreign data regions. It is the caller responsibility to ensure the device is ready for destructive operations. This may be subject to further restrictions in the future.

The OpenForBackup() method

OpenForBackup (IN  a{sv} options,
               OUT h     fd);

Gets a read-only file descriptor for the device intended for a byte-by-byte imaging of the device. This can only be done if the device is not already in use.

This method is deprecated since 2.7.3. Use OpenDevice() with O_EXCL and O_CLOEXEC flags instead.

The OpenForRestore() method

OpenForRestore (IN  a{sv} options,
                OUT h     fd);

Gets a writable file descriptor for the device intended for a byte-by-byte restore of a disk image onto the device. This can only be done if the device is not already in use.

This method is deprecated since 2.7.3. Use OpenDevice() with O_EXCL, O_SYNC and O_CLOEXEC flags instead.

The OpenForBenchmark() method

OpenForBenchmark (IN  a{sv} options,
                  OUT h     fd);

Gets a file descriptor for the device that is suitable to be used for benchmarking the device (transfer rate, access time etc.). Note that the file descriptor may be opened with the O_DIRECT and O_SYNC flags so care must be taken to only perform block-aligned I/O.

If the writable in options is TRUE then the returned file descriptor will be writable. This only works if the device is not already in use.

This method is deprecated since 2.7.3. Use OpenDevice() with O_DIRECT, O_SYNC and O_CLOEXEC flags instead.

The OpenDevice() method

OpenDevice (IN  s     mode,
            IN  a{sv} options,
            OUT h     fd);

Option flags can be used to specify additional flags. See man 2 open for list of supported flags. O_RDONLY, O_WRONLY and O_RDWR are not allowed, use mode instead.

Gets a file descriptor for the device.

Since 2.7.3

The Rescan() method

Rescan (IN  a{sv} options);

Request that the kernel and core OS rescans the contents of the device and update their state to reflect this (including things such as the /dev/disk/ hierarchy of symlinks). This includes requesting that the kernel re-reads the partition table, if appropriate.

This is usually not needed since the OS automatically does this when the last process with a writable file descriptor for the device closes it.

The RestoreEncryptedHeader() method

RestoreEncryptedHeader (IN  s     backup_file,
                        IN  a{sv} options);

Writes header and keyslots from the specified file to the specified device. The specified file must exist.

Since 2.11.0

The "Device" property

Device  readable   ay

The special device file for the block device e.g. /dev/sda2.

The "PreferredDevice" property

PreferredDevice  readable   ay

The special device file to present in the UI instead of the value of the "Device" property.

For example this could be e.g. /dev/mapper/mpathk for a multipath device with special device file /dev/dm-9.

The "Symlinks" property

Symlinks  readable   aay

Known symlinks in /dev that points to the device file in the "Device" property.

For example, this array could include symlinks such as /dev/disk/by-id/ata-INTEL_SSDSA2MH080G1GC_CVEM842101HD080DGN and /dev/disk/by-id/wwn-0x5001517387d61905.

The "DeviceNumber" property

DeviceNumber  readable   t

The dev_t of the block device.

The "Id" property

Id  readable   s

since: 2.0.0 A unique and persistent identifier for the device or blank if no such identifier is available.

For devices with fixed media, this identifier is derived from vital product data / UUIDs / serial numbers of the drive or construct (e.g. LVM or MD-RAID) the block device is part of. For devices with removable media, this identifier is derived from the medium currently inserted.

This identifier is guaranteed to not include the slash character '/' (U+002F SOLIDUS) which means it can be used as a filename.

Examples: “by-id-ata-INTEL_SSDSA2MH080G1GC_CVEM842101HD080DGN”, “by-id-ata-ST1000LM024_HN-M101MBB_S2TBJA0C230233-part3”, “by-id-usb-Kingston_DataTraveler_2.0_0013729940C4F9A166250D3E-0:0”, “by-id-dm-name-luks-6d81fe85-26b1-4f8b-b834-405454c1cd46”, “by-id-dm-name-vg_thinkpad-lv_swap”, “by-label-HARRY_POTTER_SORCERERS_STONE-”, “by-uuid-D22D-08B8”.

The "Size" property

Size  readable   t

The size of the block device.

The "ReadOnly" property

ReadOnly  readable   b

If TRUE, the device can not be written to, only read from.

The "Drive" property

Drive  readable   o

The org.freedesktop.UDisks2.Drive object that the block device belongs to, or '/' if no such object exists.

The "MDRaid" property

MDRaid  readable   o

since: 2.0.0 If the block device is a running MD-RAID array, this is set to the org.freedesktop.UDisks2.MDRaid object that it correspond to. Is '/' if no such object exists.

The "MDRaidMember" property

MDRaidMember  readable   o

since: 2.0.0 If the block device is a member of a MD-RAID array, this is set to the org.freedesktop.UDisks2.MDRaid object that it correspond to. Is '/' if no such object exists.

The "IdUsage" property

IdUsage  readable   s

A result of probing for signatures on the block device. Known values include:

If blank, no known signature was detected. This doesn't necessarily mean the device contains no structured data; it only means that no signature known to the probing code was detected.

Applications should not rely on the value in this or the "IdType" property - instead, applications should check for whether the object in question implements interfaces such as e.g. org.freedesktop.UDisks2.Filesystem, org.freedesktop.UDisks2.Swapspace or org.freedesktop.UDisks2.Encrypted.

The "IdType" property

IdType  readable   s

This property contains more information about the result of probing the block device. Its value depends of the value the "IdUsage" property:

See the note for the "IdUsage" property about usage.

The "IdVersion" property

IdVersion  readable   s

The version of the filesystem or other structured data on the block device. Do not make any assumptions about the format.

This property is blank if there is no version or the version is unknown.

The "IdLabel" property

IdLabel  readable   s

The label of the filesystem or other structured data on the block device.

This property is blank if there is no label or the label is unknown.

The "IdUUID" property

IdUUID  readable   s

The UUID of the filesystem or other structured data on the block device. Do not make any assumptions about the UUID as its format depends on what kind of data is on the device.

This property is blank if there is no UUID or the UUID is unknown.

The "Configuration" property

Configuration  readable   a(sa{sv})

The configuration for the device.

This is an array of pairs of (type, details) where type is a string identifying the configuration source (e.g. fstab) and details contains the actual configuration data.

Use the AddConfigurationItem(), RemoveConfigurationItem() and UpdateConfigurationItem() methods to add, remove and update configuration items.

Use GetSecretConfiguration() to get the secrets (e.g. passphrases) that may be part of the configuration but isn't exported in this property for security reasons.

For entries of type fstab, it means that the block device is referenced in the system-wide /etc/fstab file. Known configuration items for type fstab are

For entries of type crypttab, it means that the block device is referenced in the system-wide /etc/crypttab file. Known configuration items for type crypttab are

For security reasons, when creating a new crypttab entry (via the AddConfigurationItem() method), then the passphrase-path must reference an unexisting file in the /etc/luks-keys directory.

The "CryptoBackingDevice" property

CryptoBackingDevice  readable   o

The org.freedesktop.UDisks2.Block object that is backing the device or / if unknown or if the block device is not the cleartext device for an encrypted device.

The "HintPartitionable" property

HintPartitionable  readable   b

If TRUE, the device is normally expected to be partitionable. Devices for which this is not the case include floppy drives, optical drives and LVM logical volumes.

The "HintSystem" property

HintSystem  readable   b

If TRUE, the device is considered a system device.

System devices are devices that require additional permissions to access.

See udisks(8) for how to influence the value of this property.

The "HintIgnore" property

HintIgnore  readable   b

If TRUE, the device should be hidden from users. See udisks(8) for how to influence the value of this property.

The "HintAuto" property

HintAuto  readable   b

If TRUE, the device should be automatically started (e.g. mounted, unlocked etc.). See udisks(8) for how to influence the value of this property.

The "HintName" property

HintName  readable   s

If not blank, the name to use when presenting the device. See udisks(8) for how to influence the value of this property.

The "HintIconName" property

HintIconName  readable   s

If not blank, the icon name to use when presenting the device.

The name must adhere to the freedesktop.org icon theme specification.

See udisks(8) for how to influence the value of this property.

The "HintSymbolicIconName" property

HintSymbolicIconName  readable   s

since: 2.0.0 If not blank, the icon name to use when presenting the device using a symbolic icon.

The name must adhere to the freedesktop.org icon theme specification.

See udisks(8) for how to influence the value of this property.

The "UserspaceMountOptions" property

UserspaceMountOptions  readable   as

List of userspace mount options.