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 IOcontext:

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 theimage:

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 datacannot be :type:unicode - Librbd does not know how to deal withcharacters 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 :finallyblock:

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, andImage classes can be used as context managers that close/shutdownautomatically (see PEP 343). Using them as context managers, theabove 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 donot use callbacks.

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

• class rbd.RBD

• This class wraps librbd CRUD functions.

  • clone

  • 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

  • Get a pool-level configuration override.

    • Parameters

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

      • key (str) – key

    • Returns

    • str - value

  • config_list

  • List pool-level config overrides.

    • Returns
    • ConfigPoolIterator

  • config_remove

  • Remove a pool-level configuration override.

    • Parameters

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

      • key (str) – key

    • Returns

    • str - value

  • config_set

  • Get a pool-level configuration override.

    • Parameters

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

      • key (str) – key

      • value (str) – value

  • create

  • 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 thatis accessible by old clients, but can’tuse 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

  • Get features bitmask from str, if str_features is empty, it will returnRBD_FEATURES_DEFAULT.

    • Parameters

    • str_features (str) – feature str

    • Returns

    • int - the features bitmask of the image

    • Raises

    • InvalidArgument

  • features_to_string

  • Convert features bitmask to str.

    • Parameters

    • features (int) – feature bitmask

    • Returns

    • str - the features str of the image

    • Raises

    • InvalidArgument

  • group_create

  • 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

  • List groups.

    • Parameters

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

    • Returns

    • list – a list of groups names

    • Raises

    • FunctionNotSupported

  • group_remove

  • Delete an RBD group. This may take a long time, since it doesnot return until every image in the group has been removedfrom 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

  • 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

  • List image names.

    • Parameters

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

    • Returns

    • list – a list of image names

  • list2

  • Iterate over the images in the pool.

    • Parameters

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

    • Returns

    • ImageIterator

  • migration_abort

  • 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

  • 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

  • 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

  • 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

  • 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

• 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

• 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

• 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

• Get pool mirror mode.

  • Parameters

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

  • Returns

  • int - pool mirror mode

• mirror_mode_set

• Set pool mirror mode.

  • Parameters

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

    • mirror_mode (int) – mirror mode to set

• mirror_peer_add

• 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

• Creates a new RBD mirroring bootstrap token for anexternal cluster.

  • Parameters

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

  • Returns

  • str - bootstrap token

• mirror_peer_bootstrap_import

• Import a bootstrap token from an external cluster toauto-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

• 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

• Iterate over the peers of a pool.

  • Parameters

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

  • Returns

  • MirrorPeerIterator

• mirror_peer_remove

• Remove mirror peer.

  • Parameters

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

    • uuid (str) – peer uuid

• mirror_peer_set_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

• 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

• mirror_peer_set_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

• Get the local cluster’s friendly site name

  • Parameters

  • rados – cluster connection

  • Returns

  • str - local site name

• mirror_site_name_set

• Set the local cluster’s friendly site name

  • Parameters

  • • rados – cluster connection

    • site_name – friendly site name

• namespace_create

• Create an RBD namespace within a pool

  • Parameters

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

    • name (str) – namespace name

• namespace_exists

• 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

• List all namespaces within a pool

  • Parameters

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

  • Returns

  • list - collection of namespace names

• namespace_remove

• Remove an RBD namespace from a pool

  • Parameters

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

    • name (str) – namespace name

• pool_init

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

• pool_metadata_get

• 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

• List pool metadata.

  • Returns
  • PoolMetadataIterator

• pool_metadata_remove

• 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

• 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

• 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

• Delete an RBD image. This may take a long time, since it doesnot return until every object that comprises the image hasbeen deleted. Note that all snapshots must be deleted beforethe image can be removed. If there are snapshots left,ImageHasSnapshots is raised. If the image is stillopen, 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

• 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

• 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 allowedto be removed from trash

- Raises
- 

ImageNotFound

• trash_list

• List all entries from trash.

  • Parameters

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

  • Returns

  • TrashIterator

• trash_move

• 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 deletedfrom trash

  • Raises

  • ImageNotFound

• trash_purge

• 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 aweek 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

• Delete an RBD image from trash. If image deferment time has notexpired 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

• 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

• Get the version number of the librbd C library.

  • Returns
  • a tuple of (major, minor, extra) components of thelibrbd 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 onthe image and interact with snapshots.

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

• accesstimestamp(_self)

• Return the access timestamp for the image.

• aiodiscard(_self, offset, length, oncomplete)

• Asynchronously trim the range from the image. It will be logicallyfilled with zeroes.

• aioflush(_self, oncomplete)

• Asynchronously wait until all writes are fully flushed if caching isenabled.

• aioread(_self, offset, length, oncomplete, fadvise_flags=0)

• Asynchronously read data from the image

Raises InvalidArgument if part of the range specified isoutside the image.

oncomplete will be called with the returned read value aswell 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

• aiowrite(_self, data, offset, oncomplete, fadvise_flags=0)
• Asynchronously write data to the image

Raises InvalidArgument if part of the write would fall outsidethe 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

• blockname_prefix(_self)

• Get the RBD block name prefix

  • Returns
  • str - block name prefix

• breaklock(_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.

• configget(_self, key)

• Get an image-level configuration override.

  • Parameters

  • key (str) – key

  • Returns

  • str - value

• configlist(_self)

• List image-level config overrides.

  • Returns
  • ConfigImageIterator

• configremove(_self, key)

• Remove an image-level configuration override.

  • Parameters
  • key (str) – key

• configset(_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

• createsnap(_self, name)

• Create a snapshot of the image.

  • Parameters

  • name (str) – the name of the snapshot

  • Raises

  • ImageExists

• createtimestamp(_self)

• Return the create timestamp for the image.

• datapool_id(_self)

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

  • Returns
  • int - the pool id

• deepcopy(_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

• diffiterate(_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 forlength 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 beginningof 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 bepropagated to the caller.

Raises InvalidArgument if from_snapshot is afterthe currently set snapshot.

Raises ImageNotFound if from_snapshot is not the nameof 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 filledwith 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.

• getname(_self)

• Get the RBD image name

  • Returns
  • str - image name

• getparent_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

• getsnap_limit(_self)

• Get the snapshot limit for an image.

  • Returns
  • int - the snapshot limit for an image

• getsnap_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

• invalidatecache(_self)

• Drop any cached data for the image.

• isexclusive_lock_owner(_self)

• Get the status of the image exclusive lock.

  • Returns
  • bool - true if the image is exclusively locked

• isprotected_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

• listchildren(_self)

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

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

• listchildren2(_self)

• Iterate over the children of the image or its snapshot.

  • Returns
  • ChildIterator

• listdescendants(_self)

• Iterate over the descendants of the image.

  • Returns
  • ChildIterator

• listlockers(_self)

• List clients that have locked the image and informationabout the lock.

  • Returns

dict - contains the following keys:

  - 

tag - the tag associated with the lock (everyadditional locker must use the same tag)

  - 
    - <code>exclusive</code> - boolean indicating whether the
    - 

lock is exclusive or shared

  - 

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

• listsnaps(_self)

• Iterate over the snapshots of an image.

  • Returns
  • SnapIterator

• lockacquire(_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

• lockbreak(_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

• lockexclusive(_self, cookie)

• Take an exclusive lock on the image.

  • Raises
  • ImageBusy if a different client or cookie locked itImageExists if the same client and cookie locked it

• lockget_owners(_self)

• Iterate over the lock owners of an image.

  • Returns
  • LockOwnerIterator

• lockrelease(_self)

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

• lockshared(_self, cookie, tag)

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

  • Raises
  • ImageBusy if a different client or cookie locked itImageExists if the same client and cookie locked it

• metadataget(_self, key)

• Get image metadata for the given key.

  • Parameters

  • key (str) – metadata key

  • Returns

  • str - metadata value

• metadatalist(_self)

• List image metadata.

  • Returns
  • MetadataIterator

• metadataremove(_self, key)

• Remove image metadata for the given key.

  • Parameters
  • key (str) – metadata key

• metadataset(_self, key, value)

• Set image metadata for the given key.

  • Parameters

  • • key (str) – metadata key

    • value (str) – metadata value

• mirrorimage_create_snapshot(_self)

• Create mirror snapshot.

  • Parameters

  • force (bool) – ignore mirror snapshot limit

  • Returns

  • int - the snapshot Id

• mirrorimage_demote(_self)

• Demote the image to secondary for mirroring.

• mirrorimage_disable(_self, force)

• Disable mirroring for the image.

  • Parameters
  • force (bool) – force disabling

• mirrorimage_enable(_self, mode=RBD_MIRROR_IMAGE_MODE_JOURNAL)

• Enable mirroring for the image.

• mirrorimage_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

• mirrorimage_get_instance_id(_self)

• Get mirror instance id for the image.

  • Returns
  • str - instance id

• mirrorimage_get_mode(_self)

• Get mirror mode for the image.

  • Returns
  • int - mirror mode

• mirrorimage_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

• mirrorimage_promote(_self, force)

• Promote the image to primary for mirroring.

  • Parameters
  • force (bool) – force promoting

• mirrorimage_resync(_self)

• Flag the image to resync.

• modifytimestamp(_self)

• Return the modify timestamp for the image.

• oldformat(_self)

• Find out whether the image uses the old RBD format.

  • Returns
  • bool - whether the image uses the old RBD format

• opfeatures(_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 parentimage. If open to a snapshot, returns the overlap between the snapshotand the parent image.

  • Returns

  • int - the overlap in bytes

  • Raises

  • ImageNotFound if the image doesn’t have a parent

• parentid(_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

• parentinfo(_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) componentsof the parent image

- Raises
- 

ImageNotFound if the image doesn’t have a parent

• protectsnap(_self, name)

• Mark a snapshot as protected. This means it can’t be deleteduntil 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 ifpart 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

• rebuildobject_map(_self)

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

• removesnap(_self, name)

• Delete a snapshot of the image.

  • Parameters

  • name (str) – the name of the snapshot

  • Raises

  • IOError, ImageBusy, ImageNotFound

• removesnap2(_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

• removesnap_by_id(_self, snap_id)

• Delete a snapshot of the image by its id.

  • Parameters

  • id – the id of the snapshot

  • Raises

  • IOError, ImageBusy

• removesnap_limit(_self)

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

• renamesnap(_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

• rollbackto_snap(_self, name)

• Revert the image to its contents at a snapshot. This is apotentially expensive operation, since it rolls back eachobject individually.

  • Parameters

  • name (str) – the snapshot to rollback to

  • Raises

  • IOError

• setsnap(_self, name)

• Set the snapshot to read from. Writes will raise ReadOnlyImagewhile 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

• setsnap_by_id(_self, snap_id)

• Set the snapshot to read from. Writes will raise ReadOnlyImagewhile 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

• setsnap_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 thesize of that snapshot.

  • Returns
  • int - the size of the image in bytes

• snapget_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

• snapget_id(_self, snap_name)

• Get snapshot id by name.

  • Parameters

  • snap_name (str) – the snapshot name

  • Returns

  • int - snapshot id

  • Raises

  • ImageNotFound

• snapget_mirror_non_primary_namespace(_self, snap_id)

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

• primary_mirror_uuid (str) - primary mirror uuid

• primary_snap_id (int) - primary snapshot Id

• copied (bool) - True if snapsho is copied

• last_copied_object_number (int) - last copied object number

• snapget_mirror_primary_namespace(_self, snap_id)
• get the mirror primary namespace details.:param snap_id: the snapshot id of the mirror snapshot:type key: int:returns: dict - contains the following keys:

• demoted (bool) - True if snapshot is in demoted state

• mirror_peer_uuids (list) - mirror peer uuids

• snapget_name(_self, snap_id)

• Get snapshot name by id.

  • Parameters

  • snap_id (int) – the snapshot id

  • Returns

  • str - snapshot name

  • Raises

  • ImageNotFound

• snapget_namespace_type(_self, snap_id)

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

• snapget_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 andparent 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 theimage

  - 

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 usedto store the image

  - 

parent_pool (int) - deprecated

  - 

parent_name (str) - deprecated

See also format() and features().

• stripecount(_self)

• Return the stripe count used for the image.

• stripeunit(_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.

• unprotectsnap(_self, name)

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

  • Parameters

  • name (str) – the snapshot to unprotect

  • Raises

  • IOError, ImageNotFound

• updatefeatures(_self, features, enabled)

• Update the features bitmask of the image by enabling/disablinga single feature. The feature must support the ability to bedynamically enabled/disabled.

  • Parameters

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

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

  • Raises

  • InvalidArgument

• watcherslist(_self)

• List image watchers.

  • Returns
  • WatcherIterator

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

• Write data to the image. Raises InvalidArgument ifpart 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

• mirror_primary (dict) - optional for mirror primary namespace snapshots

• mirror_non_primary (dict) - optional for mirror non-primary namespace snapshots