qemu

transaction.json (7759B)

---

 # -*- Mode: Python -*-
 # vim: filetype=python
 #
 
 ##
 # = Transactions
 ##
 
 { 'include': 'block-core.json' }
 
 ##
 # @Abort:
 #
 # This action can be used to test transaction failure.
 #
 # Since: 1.6
 ##
 { 'struct': 'Abort',
   'data': { } }
 
 ##
 # @ActionCompletionMode:
 #
 # An enumeration of Transactional completion modes.
 #
 # @individual: Do not attempt to cancel any other Actions if any Actions fail
 #              after the Transaction request succeeds. All Actions that
 #              can complete successfully will do so without waiting on others.
 #              This is the default.
 #
 # @grouped: If any Action fails after the Transaction succeeds, cancel all
 #           Actions. Actions do not complete until all Actions are ready to
 #           complete. May be rejected by Actions that do not support this
 #           completion mode.
 #
 # Since: 2.5
 ##
 { 'enum': 'ActionCompletionMode',
   'data': [ 'individual', 'grouped' ] }
 
 ##
 # @TransactionActionKind:
 #
 # @abort: Since 1.6
 # @block-dirty-bitmap-add: Since 2.5
 # @block-dirty-bitmap-remove: Since 4.2
 # @block-dirty-bitmap-clear: Since 2.5
 # @block-dirty-bitmap-enable: Since 4.0
 # @block-dirty-bitmap-disable: Since 4.0
 # @block-dirty-bitmap-merge: Since 4.0
 # @blockdev-backup: Since 2.3
 # @blockdev-snapshot: Since 2.5
 # @blockdev-snapshot-internal-sync: Since 1.7
 # @blockdev-snapshot-sync: since 1.1
 # @drive-backup: Since 1.6
 #
 # Features:
 # @deprecated: Member @drive-backup is deprecated.  Use member
 #              @blockdev-backup instead.
 #
 # Since: 1.1
 ##
 { 'enum': 'TransactionActionKind',
   'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove',
             'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable',
             'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge',
             'blockdev-backup', 'blockdev-snapshot',
             'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync',
             { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] }
 
 ##
 # @AbortWrapper:
 #
 # Since: 1.6
 ##
 { 'struct': 'AbortWrapper',
   'data': { 'data': 'Abort' } }
 
 ##
 # @BlockDirtyBitmapAddWrapper:
 #
 # Since: 2.5
 ##
 { 'struct': 'BlockDirtyBitmapAddWrapper',
   'data': { 'data': 'BlockDirtyBitmapAdd' } }
 
 ##
 # @BlockDirtyBitmapWrapper:
 #
 # Since: 2.5
 ##
 { 'struct': 'BlockDirtyBitmapWrapper',
   'data': { 'data': 'BlockDirtyBitmap' } }
 
 ##
 # @BlockDirtyBitmapMergeWrapper:
 #
 # Since: 4.0
 ##
 { 'struct': 'BlockDirtyBitmapMergeWrapper',
   'data': { 'data': 'BlockDirtyBitmapMerge' } }
 
 ##
 # @BlockdevBackupWrapper:
 #
 # Since: 2.3
 ##
 { 'struct': 'BlockdevBackupWrapper',
   'data': { 'data': 'BlockdevBackup' } }
 
 ##
 # @BlockdevSnapshotWrapper:
 #
 # Since: 2.5
 ##
 { 'struct': 'BlockdevSnapshotWrapper',
   'data': { 'data': 'BlockdevSnapshot' } }
 
 ##
 # @BlockdevSnapshotInternalWrapper:
 #
 # Since: 1.7
 ##
 { 'struct': 'BlockdevSnapshotInternalWrapper',
   'data': { 'data': 'BlockdevSnapshotInternal' } }
 
 ##
 # @BlockdevSnapshotSyncWrapper:
 #
 # Since: 1.1
 ##
 { 'struct': 'BlockdevSnapshotSyncWrapper',
   'data': { 'data': 'BlockdevSnapshotSync' } }
 
 ##
 # @DriveBackupWrapper:
 #
 # Since: 1.6
 ##
 { 'struct': 'DriveBackupWrapper',
   'data': { 'data': 'DriveBackup' } }
 
 ##
 # @TransactionAction:
 #
 # A discriminated record of operations that can be performed with
 # @transaction.
 #
 # Since: 1.1
 ##
 { 'union': 'TransactionAction',
   'base': { 'type': 'TransactionActionKind' },
   'discriminator': 'type',
   'data': {
        'abort': 'AbortWrapper',
        'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
        'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
        'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
        'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
        'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
        'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
        'blockdev-backup': 'BlockdevBackupWrapper',
        'blockdev-snapshot': 'BlockdevSnapshotWrapper',
        'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
        'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
        'drive-backup': 'DriveBackupWrapper'
    } }
 
 ##
 # @TransactionProperties:
 #
 # Optional arguments to modify the behavior of a Transaction.
 #
 # @completion-mode: Controls how jobs launched asynchronously by
 #                   Actions will complete or fail as a group.
 #                   See @ActionCompletionMode for details.
 #
 # Since: 2.5
 ##
 { 'struct': 'TransactionProperties',
   'data': {
        '*completion-mode': 'ActionCompletionMode'
   }
 }
 
 ##
 # @transaction:
 #
 # Executes a number of transactionable QMP commands atomically. If any
 # operation fails, then the entire set of actions will be abandoned and the
 # appropriate error returned.
 #
 # For external snapshots, the dictionary contains the device, the file to use for
 # the new snapshot, and the format.  The default format, if not specified, is
 # qcow2.
 #
 # Each new snapshot defaults to being created by QEMU (wiping any
 # contents if the file already exists), but it is also possible to reuse
 # an externally-created file.  In the latter case, you should ensure that
 # the new image file has the same contents as the current one; QEMU cannot
 # perform any meaningful check.  Typically this is achieved by using the
 # current image file as the backing file for the new image.
 #
 # On failure, the original disks pre-snapshot attempt will be used.
 #
 # For internal snapshots, the dictionary contains the device and the
 # snapshot's name.  If an internal snapshot matching name already exists,
 # the request will be rejected.  Only some image formats support it, for
 # example, qcow2, and rbd,
 #
 # On failure, qemu will try delete the newly created internal snapshot in the
 # transaction.  When an I/O error occurs during deletion, the user needs to fix
 # it later with qemu-img or other command.
 #
 # @actions: List of @TransactionAction;
 #           information needed for the respective operations.
 #
 # @properties: structure of additional options to control the
 #              execution of the transaction. See @TransactionProperties
 #              for additional detail.
 #
 # Returns: nothing on success
 #
 #          Errors depend on the operations of the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there will be
 #       information on only one failed operation returned in an error condition, and
 #       subsequent actions will not have been attempted.
 #
 # Since: 1.1
 #
 # Example:
 #
 # -> { "execute": "transaction",
 #      "arguments": { "actions": [
 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 #                                      "snapshot-file": "/some/place/my-image",
 #                                      "format": "qcow2" } },
 #          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 #                                      "snapshot-file": "/some/place/my-image2",
 #                                      "snapshot-node-name": "node3432",
 #                                      "mode": "existing",
 #                                      "format": "qcow2" } },
 #          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 #                                      "snapshot-file": "/some/place/my-image2",
 #                                      "mode": "existing",
 #                                      "format": "qcow2" } },
 #          { "type": "blockdev-snapshot-internal-sync", "data" : {
 #                                      "device": "ide-hd2",
 #                                      "name": "snapshot0" } } ] } }
 # <- { "return": {} }
 #
 ##
 { 'command': 'transaction',
   'data': { 'actions': [ 'TransactionAction' ],
             '*properties': 'TransactionProperties'
           }
 }