Librbd (Python)

The rbd python module provides file-like access to RBD images.

Example: Creating and writing to an image

To use rbd, you must first connect to RADOS and open an IO context:

cluster = rados.Rados(conffile='my_ceph.conf')
cluster.connect()
ioctx = cluster.open_ioctx('mypool')

Then you instantiate an :class:rbd.RBD object, which you use to create the image:

rbd_inst = rbd.RBD()
size = 4 * 1024**3  # 4 GiB
rbd_inst.create(ioctx, 'myimage', size)

To perform I/O on the image, you instantiate an :class:rbd.Image object:

image = rbd.Image(ioctx, 'myimage')
data = 'foo' * 200
image.write(data, 0)

This writes ‘foo’ to the first 600 bytes of the image. Note that data cannot be :type:unicode - Librbd does not know how to deal with characters wider than a :c:type:char.

In the end, you will want to close the image, the IO context and the connection to RADOS:

image.close()
ioctx.close()
cluster.shutdown()

To be safe, each of these calls would need to be in a separate :finally block:

cluster = rados.Rados(conffile='my_ceph_conf')
try:
    cluster.connect()
    ioctx = cluster.open_ioctx('my_pool')
    try:
        rbd_inst = rbd.RBD()
        size = 4 * 1024**3  # 4 GiB
        rbd_inst.create(ioctx, 'myimage', size)
        image = rbd.Image(ioctx, 'myimage')
        try:
            data = 'foo' * 200
            image.write(data, 0)
        finally:
            image.close()
    finally:
        ioctx.close()
finally:
    cluster.shutdown()

This can be cumbersome, so the Rados, Ioctx, and Image classes can be used as context managers that close/shutdown automatically (see PEP 343). Using them as context managers, the above example becomes:

with rados.Rados(conffile='my_ceph.conf') as cluster:
    with cluster.open_ioctx('mypool') as ioctx:
        rbd_inst = rbd.RBD()
        size = 4 * 1024**3  # 4 GiB
        rbd_inst.create(ioctx, 'myimage', size)
        with rbd.Image(ioctx, 'myimage') as image:
            data = 'foo' * 200
            image.write(data, 0)

API Reference

This module is a thin wrapper around librbd.

It currently provides all the synchronous methods of librbd that do not use callbacks.

Error codes from librbd are turned into exceptions that subclass Error. Almost all methods may raise Error (the base class of all rbd exceptions), PermissionError and IOError, in addition to those documented for the method.

class rbd.RBD

This class wraps librbd CRUD functions.

clone(self, p_ioctx, p_name, p_snapname, c_ioctx, c_name, features=None, order=None, stripe_unit=None, stripe_count=None, data_pool=None)

Clone a parent rbd snapshot into a COW sparse child.

Parameters
  • p_ioctx – the parent context that represents the parent snap

  • p_name – the parent image name

  • p_snapname – the parent image snapshot name

  • c_ioctx – the child context that represents the new clone

  • c_name – the clone (child) name

  • features (int) – bitmask of features to enable; if set, must include layering

  • order (int) – the image is split into (2**order) byte objects

  • stripe_unit (int) – stripe unit in bytes (default None to let librbd decide)

  • stripe_count (int) – objects to stripe over before looping

  • data_pool (str) – optional separate pool for data blocks

Raises

TypeError

Raises

InvalidArgument

Raises

ImageExists

Raises

FunctionNotSupported

Raises

ArgumentOutOfRange

config_get(self, ioctx, key)

Get a pool-level configuration override.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – key

Returns

str - value

config_list(self, ioctx)

List pool-level config overrides.

Returns

ConfigPoolIterator

config_remove(self, ioctx, key)

Remove a pool-level configuration override.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – key

Returns

str - value

config_set(self, ioctx, key, value)

Get a pool-level configuration override.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – key

  • value (str) – value

create(self, ioctx, name, size, order=None, old_format=True, features=None, stripe_unit=None, stripe_count=None, data_pool=None)

Create an rbd image.

Parameters
  • ioctx (rados.Ioctx) – the context in which to create the image

  • name (str) – what the image is called

  • size (int) – how big the image is in bytes

  • order (int) – the image is split into (2**order) byte objects

  • old_format (bool) – whether to create an old-style image that is accessible by old clients, but can’t use more advanced features like layering.

  • features (int) – bitmask of features to enable

  • stripe_unit (int) – stripe unit in bytes (default None to let librbd decide)

  • stripe_count (int) – objects to stripe over before looping

  • data_pool (str) – optional separate pool for data blocks

Raises

ImageExists

Raises

TypeError

Raises

InvalidArgument

Raises

FunctionNotSupported

features_from_string(self, str_features)

Get features bitmask from str, if str_features is empty, it will return RBD_FEATURES_DEFAULT.

Parameters

str_features (str) – feature str

Returns

int - the features bitmask of the image

Raises

InvalidArgument

features_to_string(self, features)

Convert features bitmask to str.

Parameters

features (int) – feature bitmask

Returns

str - the features str of the image

Raises

InvalidArgument

group_create(self, ioctx, name)

Create a group.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is used

  • name (str) – the name of the group

Raises

ObjectExists

Raises

InvalidArgument

Raises

FunctionNotSupported

group_list(self, ioctx)

List groups.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

list – a list of groups names

Raises

FunctionNotSupported

group_remove(self, ioctx, name)

Delete an RBD group. This may take a long time, since it does not return until every image in the group has been removed from the group.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the group is in

  • name (str) – the name of the group to remove

Raises

ObjectNotFound

Raises

InvalidArgument

Raises

FunctionNotSupported

group_rename(self, ioctx, src, dest)

Rename an RBD group.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the group is in

  • src (str) – the current name of the group

  • dest (str) – the new name of the group

Raises

ObjectExists

Raises

ObjectNotFound

Raises

InvalidArgument

Raises

FunctionNotSupported

list(self, ioctx)

List image names.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

list – a list of image names

list2(self, ioctx)

Iterate over the images in the pool.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool the image is in

Returns

ImageIterator

migration_abort(self, ioctx, image_name, on_progress=None)

Cancel a previously started but interrupted migration.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_name (str) – the name of the image

  • on_progress (callback function) – optional progress callback function

Raises

ImageNotFound

migration_commit(self, ioctx, image_name, on_progress=None)

Commit an executed RBD image migration.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_name (str) – the name of the image

  • on_progress (callback function) – optional progress callback function

Raises

ImageNotFound

migration_execute(self, ioctx, image_name, on_progress=None)

Execute a prepared RBD image migration.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_name (str) – the name of the image

  • on_progress (callback function) – optional progress callback function

Raises

ImageNotFound

migration_prepare(self, ioctx, image_name, dest_ioctx, dest_image_name, features=None, order=None, stripe_unit=None, stripe_count=None, data_pool=None)

Prepare an RBD image migration.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_name – the current name of the image

  • dest_ioctx (rados.Ioctx) – determines which pool to migration into

  • dest_image_name (str) – the name of the destination image (may be the same image)

  • features (int) – bitmask of features to enable; if set, must include layering

  • order (int) – the image is split into (2**order) byte objects

  • stripe_unit (int) – stripe unit in bytes (default None to let librbd decide)

  • stripe_count (int) – objects to stripe over before looping

  • data_pool (str) – optional separate pool for data blocks

Raises

TypeError

Raises

InvalidArgument

Raises

ImageExists

Raises

FunctionNotSupported

Raises

ArgumentOutOfRange

migration_status(self, ioctx, image_name)

Return RBD image migration status.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_name (str) – the name of the image

Returns

dict - contains the following keys:

  • source_pool_id (int) - source image pool id

  • source_pool_namespace (str) - source image pool namespace

  • source_image_name (str) - source image name

  • source_image_id (str) - source image id

  • dest_pool_id (int) - destination image pool id

  • dest_pool_namespace (str) - destination image pool namespace

  • dest_image_name (str) - destination image name

  • dest_image_id (str) - destination image id

  • state (int) - current migration state

  • state_description (str) - migration state description

Raises

ImageNotFound

mirror_image_instance_id_list(self, ioctx)

Iterate over the mirror image instance ids of a pool.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

MirrorImageInstanceIdIterator

mirror_image_status_list(self, ioctx)

Iterate over the mirror image statuses of a pool.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

MirrorImageStatusIterator

mirror_image_status_summary(self, ioctx)

Get mirror image status summary of a pool.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

list - a list of (state, count) tuples

mirror_mode_get(self, ioctx)

Get pool mirror mode.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

int - pool mirror mode

mirror_mode_set(self, ioctx, mirror_mode)

Set pool mirror mode.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • mirror_mode (int) – mirror mode to set

mirror_peer_add(self, ioctx, site_name, client_name, direction=RBD_MIRROR_PEER_DIRECTION_RX_TX)

Add mirror peer.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is used

  • site_name (str) – mirror peer site name

  • client_name (str) – mirror peer client name

  • direction (int) – the direction of the mirroring

Returns

str - peer uuid

mirror_peer_bootstrap_create(self, ioctx)

Creates a new RBD mirroring bootstrap token for an external cluster.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is written

Returns

str - bootstrap token

mirror_peer_bootstrap_import(self, ioctx, direction, token)

Import a bootstrap token from an external cluster to auto-configure the mirror peer.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • direction (int) – mirror peer direction

  • token (str) – bootstrap token

mirror_peer_get_attributes(self, ioctx, uuid)

Get optional mirror peer attributes

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • uuid (str) – uuid of the mirror peer

Returns

dict - contains the following keys:

  • mon_host (str) - monitor addresses

  • key (str) - CephX key

mirror_peer_list(self, ioctx)

Iterate over the peers of a pool.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool is read

Returns

MirrorPeerIterator

mirror_peer_remove(self, ioctx, uuid)

Remove mirror peer.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is used

  • uuid (str) – peer uuid

mirror_peer_set_attributes(self, ioctx, uuid, attributes)

Set optional mirror peer attributes

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • uuid (str) – uuid of the mirror peer

  • attributes (dict) – ‘mon_host’ and ‘key’ attributes

mirror_peer_set_client(self, ioctx, uuid, client_name)

Set mirror peer client name

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • uuid (str) – uuid of the mirror peer

  • client_name (str) – client name of the mirror peer to set

mirror_peer_set_cluster(self, ioctx, uuid, cluster_name)
mirror_peer_set_name(self, ioctx, uuid, site_name)

Set mirror peer site name

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is written

  • uuid (str) – uuid of the mirror peer

  • site_name (str) – site name of the mirror peer to set

mirror_site_name_get(self, rados)

Get the local cluster’s friendly site name

Parameters

rados – cluster connection

Returns

str - local site name

mirror_site_name_set(self, rados, site_name)

Set the local cluster’s friendly site name

Parameters
  • rados – cluster connection

  • site_name – friendly site name

namespace_create(self, ioctx, name)

Create an RBD namespace within a pool

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool

  • name (str) – namespace name

namespace_exists(self, ioctx, name)

Verifies if a namespace exists within a pool

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool

  • name (str) – namespace name

Returns

bool - true if namespace exists

namespace_list(self, ioctx)

List all namespaces within a pool

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool

Returns

list - collection of namespace names

namespace_remove(self, ioctx, name)

Remove an RBD namespace from a pool

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool

  • name (str) – namespace name

pool_init(self, ioctx, force)

Initialize an RBD pool :param ioctx: determines which RADOS pool :type ioctx: rados.Ioctx :param force: force init :type force: bool

pool_metadata_get(self, ioctx, key)

Get pool metadata for the given key.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – metadata key

Returns

str - metadata value

pool_metadata_list(self, ioctx)

List pool metadata.

Returns

PoolMetadataIterator

pool_metadata_remove(self, ioctx, key)

Remove pool metadata for the given key.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – metadata key

Returns

str - metadata value

pool_metadata_set(self, ioctx, key, value)

Set pool metadata for the given key.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool is read

  • key (str) – metadata key

  • value (str) – metadata value

pool_stats_get(self, ioctx)

Return RBD pool stats

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool

Returns

dict - contains the following keys:

  • image_count (int) - image count

  • image_provisioned_bytes (int) - image total HEAD provisioned bytes

  • image_max_provisioned_bytes (int) - image total max provisioned bytes

  • image_snap_count (int) - image snap count

  • trash_count (int) - trash image count

  • trash_provisioned_bytes (int) - trash total HEAD provisioned bytes

  • trash_max_provisioned_bytes (int) - trash total max provisioned bytes

  • trash_snap_count (int) - trash snap count

remove(self, ioctx, name, on_progress=None)

Delete an RBD image. This may take a long time, since it does not return until every object that comprises the image has been deleted. Note that all snapshots must be deleted before the image can be removed. If there are snapshots left, ImageHasSnapshots is raised. If the image is still open, or the watch from a crashed client has not expired, ImageBusy is raised.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • name (str) – the name of the image to remove

  • on_progress (callback function) – optional progress callback function

Raises

ImageNotFound, ImageBusy, ImageHasSnapshots

rename(self, ioctx, src, dest)

Rename an RBD image.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • src (str) – the current name of the image

  • dest (str) – the new name of the image

Raises

ImageNotFound, ImageExists

trash_get(self, ioctx, image_id)

Retrieve RBD image info from trash.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_id (str) – the id of the image to restore

Returns

dict - contains the following keys:

  • id (str) - image id

  • name (str) - image name

  • source (str) - source of deletion

  • deletion_time (datetime) - time of deletion

  • deferment_end_time (datetime) - time that an image is allowed to be removed from trash

Raises

ImageNotFound

trash_list(self, ioctx)

List all entries from trash.

Parameters

ioctx (rados.Ioctx) – determines which RADOS pool the image is in

Returns

TrashIterator

trash_move(self, ioctx, name, delay=0)

Move an RBD image to the trash.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • name (str) – the name of the image to remove

  • delay (int) – time delay in seconds before the image can be deleted from trash

Raises

ImageNotFound

trash_purge(self, ioctx, expire_ts=None, threshold=-1)

Delete RBD images from trash in bulk.

By default it removes images with deferment end time less than now.

The timestamp is configurable, e.g. delete images that have expired a week ago.

If the threshold is used it deletes images until X% pool usage is met.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • expire_ts (datetime) – timestamp for images to be considered as expired (UTC)

  • threshold (float) – percentage of pool usage to be met (0 to 1)

trash_remove(self, ioctx, image_id, force=False, on_progress=None)

Delete an RBD image from trash. If image deferment time has not expired PermissionError is raised.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_id (str) – the id of the image to remove

  • force (bool) – force remove even if deferment time has not expired

  • on_progress (callback function) – optional progress callback function

Raises

ImageNotFound, PermissionError

trash_restore(self, ioctx, image_id, name)

Restore an RBD image from trash.

Parameters
  • ioctx (rados.Ioctx) – determines which RADOS pool the image is in

  • image_id (str) – the id of the image to restore

  • name (str) – the new name of the restored image

Raises

ImageNotFound

version(self)

Get the version number of the librbd C library.

Returns

a tuple of (major, minor, extra) components of the librbd version

class rbd.Image(ioctx, name=None, snapshot=None, read_only=False, image_id=None)

This class represents an RBD image. It is used to perform I/O on the image and interact with snapshots.

Note: Any method of this class may raise ImageNotFound if the image has been deleted.

access_timestamp(self)

Return the access timestamp for the image.

aio_discard(self, offset, length, oncomplete)

Asynchronously trim the range from the image. It will be logically filled with zeroes.

aio_flush(self, oncomplete)

Asynchronously wait until all writes are fully flushed if caching is enabled.

aio_read(self, offset, length, oncomplete, fadvise_flags=0)

Asynchronously read data from the image

Raises InvalidArgument if part of the range specified is outside the image.

oncomplete will be called with the returned read value as well as the completion:

oncomplete(completion, data_read)

Parameters
  • offset (int) – the offset to start reading at

  • length (int) – how many bytes to read

  • oncomplete (completion) – what to do when the read is complete

  • fadvise_flags (int) – fadvise flags for this read

Returns

Completion - the completion object

Raises

InvalidArgument, IOError

aio_write(self, data, offset, oncomplete, fadvise_flags=0)

Asynchronously write data to the image

Raises InvalidArgument if part of the write would fall outside the image.

oncomplete will be called with the completion:

oncomplete(completion)

Parameters
  • data (bytes) – the data to be written

  • offset (int) – the offset to start writing at

  • oncomplete (completion) – what to do when the write is complete

  • fadvise_flags (int) – fadvise flags for this write

Returns

Completion - the completion object

Raises

InvalidArgument, IOError

block_name_prefix(self)

Get the RBD block name prefix

Returns

str - block name prefix

break_lock(self, client, cookie)

Release a lock held by another rados client.

close(self)

Release the resources used by this image object.

After this is called, this object should not be used.

config_get(self, key)

Get an image-level configuration override.

Parameters

key (str) – key

Returns

str - value

config_list(self)

List image-level config overrides.

Returns

ConfigImageIterator

config_remove(self, key)

Remove an image-level configuration override.

Parameters

key (str) – key

config_set(self, key, value)

Set an image-level configuration override.

Parameters
  • key (str) – key

  • value (str) – value

copy(self, dest_ioctx, dest_name, features=None, order=None, stripe_unit=None, stripe_count=None, data_pool=None)

Copy the image to another location.

Parameters
  • dest_ioctx (rados.Ioctx) – determines which pool to copy into

  • dest_name (str) – the name of the copy

  • features (int) – bitmask of features to enable; if set, must include layering

  • order (int) – the image is split into (2**order) byte objects

  • stripe_unit (int) – stripe unit in bytes (default None to let librbd decide)

  • stripe_count (int) – objects to stripe over before looping

  • data_pool (str) – optional separate pool for data blocks

Raises

TypeError

Raises

InvalidArgument

Raises

ImageExists

Raises

FunctionNotSupported

Raises

ArgumentOutOfRange

create_snap(self, name)

Create a snapshot of the image.

Parameters

name (str) – the name of the snapshot

Raises

ImageExists

create_timestamp(self)

Return the create timestamp for the image.

data_pool_id(self)

Get the pool id of the pool where the data of this RBD image is stored.

Returns

int - the pool id

deep_copy(self, dest_ioctx, dest_name, features=None, order=None, stripe_unit=None, stripe_count=None, data_pool=None)

Deep copy the image to another location.

Parameters
  • dest_ioctx (rados.Ioctx) – determines which pool to copy into

  • dest_name (str) – the name of the copy

  • features (int) – bitmask of features to enable; if set, must include layering

  • order (int) – the image is split into (2**order) byte objects

  • stripe_unit (int) – stripe unit in bytes (default None to let librbd decide)

  • stripe_count (int) – objects to stripe over before looping

  • data_pool (str) – optional separate pool for data blocks

Raises

TypeError

Raises

InvalidArgument

Raises

ImageExists

Raises

FunctionNotSupported

Raises

ArgumentOutOfRange

diff_iterate(self, offset, length, from_snapshot, iterate_cb, include_parent=True, whole_object=False)

Iterate over the changed extents of an image.

This will call iterate_cb with three arguments:

(offset, length, exists)

where the changed extent starts at offset bytes, continues for length bytes, and is full of data (if exists is True) or zeroes (if exists is False).

If from_snapshot is None, it is interpreted as the beginning of time and this generates all allocated extents.

The end version is whatever is currently selected (via set_snap) for the image.

iterate_cb may raise an exception, which will abort the diff and will be propagated to the caller.

Raises InvalidArgument if from_snapshot is after the currently set snapshot.

Raises ImageNotFound if from_snapshot is not the name of a snapshot of the image.

Parameters
  • offset (int) – start offset in bytes

  • length (int) – size of region to report on, in bytes

  • from_snapshot (str or None) – starting snapshot name, or None

  • iterate_cb (function acception arguments for offset, length, and exists) – function to call for each extent

  • include_parent (bool) – True if full history diff should include parent

  • whole_object (bool) – True if diff extents should cover whole object

Raises

InvalidArgument, IOError, ImageNotFound

discard(self, offset, length)

Trim the range from the image. It will be logically filled with zeroes.

features(self)

Get the features bitmask of the image.

Returns

int - the features bitmask of the image

flags(self)

Get the flags bitmask of the image.

Returns

int - the flags bitmask of the image

flatten(self, on_progress=None)

Flatten clone image (copy all blocks from parent to child) :param on_progress: optional progress callback function :type on_progress: callback function

flush(self)

Block until all writes are fully flushed if caching is enabled.

get_name(self)

Get the RBD image name

Returns

str - image name

get_parent_image_spec(self)

Get spec of the cloned image’s parent

Returns

dict - contains the following keys: * pool_name (str) - parent pool name * pool_namespace (str) - parent pool namespace * image_name (str) - parent image name * snap_name (str) - parent snapshot name

Raises

ImageNotFound if the image doesn’t have a parent

get_snap_limit(self)

Get the snapshot limit for an image.

Returns

int - the snapshot limit for an image

get_snap_timestamp(self, snap_id)

Get the snapshot timestamp for an image. :param snap_id: the snapshot id of a snap shot :returns: datetime - the snapshot timestamp for an image

group(self)

Get information about the image’s group.

Returns

dict - contains the following keys:

  • pool (int) - id of the group pool

  • name (str) - name of the group

id(self)

Get the RBD v2 internal image id

Returns

str - image id

invalidate_cache(self)

Drop any cached data for the image.

is_exclusive_lock_owner(self)

Get the status of the image exclusive lock.

Returns

bool - true if the image is exclusively locked

is_protected_snap(self, name)

Find out whether a snapshot is protected from deletion.

Parameters

name (str) – the snapshot to check

Returns

bool - whether the snapshot is protected

Raises

IOError, ImageNotFound

list_children(self)

List children of the currently set snapshot (set via set_snap()).

Returns

list - a list of (pool name, image name) tuples

list_children2(self)

Iterate over the children of the image or its snapshot.

Returns

ChildIterator

list_descendants(self)

Iterate over the descendants of the image.

Returns

ChildIterator

list_lockers(self)

List clients that have locked the image and information about the lock.

Returns

dict - contains the following keys:

  • tag - the tag associated with the lock (every additional locker must use the same tag)

  • exclusive - boolean indicating whether the

    lock is exclusive or shared

  • lockers - a list of (client, cookie, address) tuples

list_snaps(self)

Iterate over the snapshots of an image.

Returns

SnapIterator

lock_acquire(self, lock_mode)

Acquire a managed lock on the image.

Parameters

lock_mode (int) – lock mode to set

Raises

ImageBusy if the lock could not be acquired

lock_break(self, lock_mode, lock_owner)

Break the image lock held by a another client.

Parameters

lock_owner (str) – the owner of the lock to break

lock_exclusive(self, cookie)

Take an exclusive lock on the image.

Raises

ImageBusy if a different client or cookie locked it ImageExists if the same client and cookie locked it

lock_get_owners(self)

Iterate over the lock owners of an image.

Returns

LockOwnerIterator

lock_release(self)

Release a managed lock on the image that was previously acquired.

lock_shared(self, cookie, tag)

Take a shared lock on the image. The tag must match that of the existing lockers, if any.

Raises

ImageBusy if a different client or cookie locked it ImageExists if the same client and cookie locked it

metadata_get(self, key)

Get image metadata for the given key.

Parameters

key (str) – metadata key

Returns

str - metadata value

metadata_list(self)

List image metadata.

Returns

MetadataIterator

metadata_remove(self, key)

Remove image metadata for the given key.

Parameters

key (str) – metadata key

metadata_set(self, key, value)

Set image metadata for the given key.

Parameters
  • key (str) – metadata key

  • value (str) – metadata value

mirror_image_demote(self)

Demote the image to secondary for mirroring.

mirror_image_disable(self, force)

Disable mirroring for the image.

Parameters

force (bool) – force disabling

mirror_image_enable(self)

Enable mirroring for the image.

mirror_image_get_info(self)

Get mirror info for the image.

Returns

dict - contains the following keys:

  • global_id (str) - image global id

  • state (int) - mirror state

  • primary (bool) - is image primary

mirror_image_get_instance_id(self)

Get mirror instance id for the image.

Returns

str - instance id

mirror_image_get_status(self)

Get mirror status for the image.

Returns

dict - contains the following keys:

  • name (str) - mirror image name

  • id (str) - mirror image id

  • info (dict) - mirror image info

  • state (int) - status mirror state

  • description (str) - status description

  • last_update (datetime) - last status update time

  • up (bool) - is mirroring agent up

  • remote_statuses (array) -

  • fsid (str) - remote fsid

  • state (int) - status mirror state

  • description (str) - status description

  • last_update (datetime) - last status update time

  • up (bool) - is mirroring agent up

mirror_image_promote(self, force)

Promote the image to primary for mirroring.

Parameters

force (bool) – force promoting

mirror_image_resync(self)

Flag the image to resync.

modify_timestamp(self)

Return the modify timestamp for the image.

old_format(self)

Find out whether the image uses the old RBD format.

Returns

bool - whether the image uses the old RBD format

op_features(self)

Get the op features bitmask of the image.

Returns

int - the op features bitmask of the image

overlap(self)

Get the number of overlapping bytes between the image and its parent image. If open to a snapshot, returns the overlap between the snapshot and the parent image.

Returns

int - the overlap in bytes

Raises

ImageNotFound if the image doesn’t have a parent

parent_id(self)

Get image id of a cloned image’s parent (if any)

Returns

str - the parent id

Raises

ImageNotFound if the image doesn’t have a parent

parent_info(self)

Deprecated. Use get_parent_image_spec instead.

Get information about a cloned image’s parent (if any)

Returns

tuple - (pool name, image name, snapshot name) components of the parent image

Raises

ImageNotFound if the image doesn’t have a parent

protect_snap(self, name)

Mark a snapshot as protected. This means it can’t be deleted until it is unprotected.

Parameters

name (str) – the snapshot to protect

Raises

IOError, ImageNotFound

read(self, offset, length, fadvise_flags=0)

Read data from the image. Raises InvalidArgument if part of the range specified is outside the image.

Parameters
  • offset (int) – the offset to start reading at

  • length (int) – how many bytes to read

  • fadvise_flags (int) – fadvise flags for this read

Returns

str - the data read

Raises

InvalidArgument, IOError

rebuild_object_map(self)

Rebuild the object map for the image HEAD or currently set snapshot

remove_snap(self, name)

Delete a snapshot of the image.

Parameters

name (str) – the name of the snapshot

Raises

IOError, ImageBusy, ImageNotFound

remove_snap2(self, name, flags)

Delete a snapshot of the image.

Parameters
  • name (str) – the name of the snapshot

  • flags – the flags for removal

Raises

IOError, ImageBusy

remove_snap_by_id(self, snap_id)

Delete a snapshot of the image by its id.

Parameters

id – the id of the snapshot

Raises

IOError, ImageBusy

remove_snap_limit(self)

Remove the snapshot limit for an image, essentially setting the limit to the maximum size allowed by the implementation.

rename_snap(self, srcname, dstname)

rename a snapshot of the image.

Parameters
  • srcname (str) – the src name of the snapshot

  • dstname (str) – the dst name of the snapshot

Raises

ImageExists

resize(self, size, allow_shrink=True)

Change the size of the image, allow shrink.

Parameters
  • size (int) – the new size of the image

  • allow_shrink (bool) – permit shrinking

rollback_to_snap(self, name)

Revert the image to its contents at a snapshot. This is a potentially expensive operation, since it rolls back each object individually.

Parameters

name (str) – the snapshot to rollback to

Raises

IOError

set_snap(self, name)

Set the snapshot to read from. Writes will raise ReadOnlyImage while a snapshot is set. Pass None to unset the snapshot (reads come from the current image) , and allow writing again.

Parameters

name (str or None) – the snapshot to read from, or None to unset the snapshot

set_snap_by_id(self, snap_id)

Set the snapshot to read from. Writes will raise ReadOnlyImage while a snapshot is set. Pass None to unset the snapshot (reads come from the current image) , and allow writing again.

Parameters

snap_id (int) – the snapshot to read from, or None to unset the snapshot

set_snap_limit(self, limit)

Set the snapshot limit for an image.

Parameters

limit – the new limit to set

size(self)

Get the size of the image. If open to a snapshot, returns the size of that snapshot.

Returns

int - the size of the image in bytes

snap_get_group_namespace(self, snap_id)

get the group namespace details. :param snap_id: the snapshot id of the group snapshot :type key: int :returns: dict - contains the following keys:

  • pool (int) - pool id

  • name (str) - group name

  • snap_name (str) - group snap name

snap_get_id(self, snap_name)

Get snapshot id by name.

Parameters

snap_name (str) – the snapshot name

Returns

int - snapshot id

Raises

ImageNotFound

snap_get_name(self, snap_id)

Get snapshot name by id.

Parameters

snap_id (int) – the snapshot id

Returns

str - snapshot name

Raises

ImageNotFound

snap_get_namespace_type(self, snap_id)

Get the snapshot namespace type. :param snap_id: the snapshot id of a snap shot :type key: int

snap_get_trash_namespace(self, snap_id)

get the trash namespace details. :param snap_id: the snapshot id of the trash snapshot :type key: int :returns: dict - contains the following keys:

  • original_name (str) - original snap name

sparsify(self, sparse_size)

Reclaim space for zeroed image extents

stat(self)

Get information about the image. Currently parent pool and parent name are always -1 and ‘’.

Returns

dict - contains the following keys:

  • size (int) - the size of the image in bytes

  • obj_size (int) - the size of each object that comprises the image

  • num_objs (int) - the number of objects in the image

  • order (int) - log_2(object_size)

  • block_name_prefix (str) - the prefix of the RADOS objects used to store the image

  • parent_pool (int) - deprecated

  • parent_name (str) - deprecated

See also format() and features().

stripe_count(self)

Return the stripe count used for the image.

stripe_unit(self)

Return the stripe unit used for the image.

unlock(self, cookie)

Release a lock on the image that was locked by this rados client.

unprotect_snap(self, name)

Mark a snapshot unprotected. This allows it to be deleted if it was protected.

Parameters

name (str) – the snapshot to unprotect

Raises

IOError, ImageNotFound

update_features(self, features, enabled)

Update the features bitmask of the image by enabling/disabling a single feature. The feature must support the ability to be dynamically enabled/disabled.

Parameters
  • features (int) – feature bitmask to enable/disable

  • enabled (bool) – whether to enable/disable the feature

Raises

InvalidArgument

watchers_list(self)

List image watchers.

Returns

WatcherIterator

write(self, data, offset, fadvise_flags=0)

Write data to the image. Raises InvalidArgument if part of the write would fall outside the image.

Parameters
  • data (bytes) – the data to be written

  • offset (int) – where to start writing data

  • fadvise_flags (int) – fadvise flags for this write

Returns

int - the number of bytes written

Raises

IncompleteWriteError, LogicError, InvalidArgument, IOError

class rbd.SnapIterator(Image image)

Iterator over snapshot info for an image.

Yields a dictionary containing information about a snapshot.

Keys are:

  • id (int) - numeric identifier of the snapshot

  • size (int) - size of the image at the time of snapshot (in bytes)

  • name (str) - name of the snapshot

  • namespace (int) - enum for snap namespace

  • group (dict) - optional for group namespace snapshots

  • trash (dict) - optional for trash namespace snapshots