1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4 5## 6# = Transactions 7## 8 9{ 'include': 'block-core.json' } 10 11## 12# @Abort: 13# 14# This action can be used to test transaction failure. 15# 16# Since: 1.6 17## 18{ 'struct': 'Abort', 19 'data': { } } 20 21## 22# @ActionCompletionMode: 23# 24# An enumeration of Transactional completion modes. 25# 26# @individual: Do not attempt to cancel any other Actions if any Actions fail 27# after the Transaction request succeeds. All Actions that 28# can complete successfully will do so without waiting on others. 29# This is the default. 30# 31# @grouped: If any Action fails after the Transaction succeeds, cancel all 32# Actions. Actions do not complete until all Actions are ready to 33# complete. May be rejected by Actions that do not support this 34# completion mode. 35# 36# Since: 2.5 37## 38{ 'enum': 'ActionCompletionMode', 39 'data': [ 'individual', 'grouped' ] } 40 41## 42# @TransactionAction: 43# 44# A discriminated record of operations that can be performed with 45# @transaction. Action @type can be: 46# 47# - @abort: since 1.6 48# - @block-dirty-bitmap-add: since 2.5 49# - @block-dirty-bitmap-remove: since 4.2 50# - @block-dirty-bitmap-clear: since 2.5 51# - @block-dirty-bitmap-enable: since 4.0 52# - @block-dirty-bitmap-disable: since 4.0 53# - @block-dirty-bitmap-merge: since 4.0 54# - @blockdev-backup: since 2.3 55# - @blockdev-snapshot: since 2.5 56# - @blockdev-snapshot-internal-sync: since 1.7 57# - @blockdev-snapshot-sync: since 1.1 58# - @drive-backup: since 1.6 59# 60# Since: 1.1 61## 62{ 'union': 'TransactionAction', 63 'data': { 64 'abort': 'Abort', 65 'block-dirty-bitmap-add': 'BlockDirtyBitmapAdd', 66 'block-dirty-bitmap-remove': 'BlockDirtyBitmap', 67 'block-dirty-bitmap-clear': 'BlockDirtyBitmap', 68 'block-dirty-bitmap-enable': 'BlockDirtyBitmap', 69 'block-dirty-bitmap-disable': 'BlockDirtyBitmap', 70 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMerge', 71 'blockdev-backup': 'BlockdevBackup', 72 'blockdev-snapshot': 'BlockdevSnapshot', 73 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternal', 74 'blockdev-snapshot-sync': 'BlockdevSnapshotSync', 75 'drive-backup': 'DriveBackup' 76 } } 77 78## 79# @TransactionProperties: 80# 81# Optional arguments to modify the behavior of a Transaction. 82# 83# @completion-mode: Controls how jobs launched asynchronously by 84# Actions will complete or fail as a group. 85# See @ActionCompletionMode for details. 86# 87# Since: 2.5 88## 89{ 'struct': 'TransactionProperties', 90 'data': { 91 '*completion-mode': 'ActionCompletionMode' 92 } 93} 94 95## 96# @transaction: 97# 98# Executes a number of transactionable QMP commands atomically. If any 99# operation fails, then the entire set of actions will be abandoned and the 100# appropriate error returned. 101# 102# For external snapshots, the dictionary contains the device, the file to use for 103# the new snapshot, and the format. The default format, if not specified, is 104# qcow2. 105# 106# Each new snapshot defaults to being created by QEMU (wiping any 107# contents if the file already exists), but it is also possible to reuse 108# an externally-created file. In the latter case, you should ensure that 109# the new image file has the same contents as the current one; QEMU cannot 110# perform any meaningful check. Typically this is achieved by using the 111# current image file as the backing file for the new image. 112# 113# On failure, the original disks pre-snapshot attempt will be used. 114# 115# For internal snapshots, the dictionary contains the device and the snapshot's 116# name. If an internal snapshot matching name already exists, the request will 117# be rejected. Only some image formats support it, for example, qcow2, rbd, 118# and sheepdog. 119# 120# On failure, qemu will try delete the newly created internal snapshot in the 121# transaction. When an I/O error occurs during deletion, the user needs to fix 122# it later with qemu-img or other command. 123# 124# @actions: List of @TransactionAction; 125# information needed for the respective operations. 126# 127# @properties: structure of additional options to control the 128# execution of the transaction. See @TransactionProperties 129# for additional detail. 130# 131# Returns: nothing on success 132# 133# Errors depend on the operations of the transaction 134# 135# Note: The transaction aborts on the first failure. Therefore, there will be 136# information on only one failed operation returned in an error condition, and 137# subsequent actions will not have been attempted. 138# 139# Since: 1.1 140# 141# Example: 142# 143# -> { "execute": "transaction", 144# "arguments": { "actions": [ 145# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", 146# "snapshot-file": "/some/place/my-image", 147# "format": "qcow2" } }, 148# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", 149# "snapshot-file": "/some/place/my-image2", 150# "snapshot-node-name": "node3432", 151# "mode": "existing", 152# "format": "qcow2" } }, 153# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", 154# "snapshot-file": "/some/place/my-image2", 155# "mode": "existing", 156# "format": "qcow2" } }, 157# { "type": "blockdev-snapshot-internal-sync", "data" : { 158# "device": "ide-hd2", 159# "name": "snapshot0" } } ] } } 160# <- { "return": {} } 161# 162## 163{ 'command': 'transaction', 164 'data': { 'actions': [ 'TransactionAction' ], 165 '*properties': 'TransactionProperties' 166 } 167} 168