blob: 021e383496c7f41452a478423fb41a5de910b995 [file] [log] [blame]
Markus Armbrusterfa988e32017-08-24 21:14:02 +02001# -*- Mode: Python -*-
Andrea Bolognanif7160f32020-07-29 20:50:24 +02002# vim: filetype=python
Markus Armbrusterfa988e32017-08-24 21:14:02 +02003#
4
5##
6# = Transactions
7##
8
Kevin Wolf2af282e2020-02-24 15:30:08 +01009{ 'include': 'block-core.json' }
Markus Armbrusterfa988e32017-08-24 21:14:02 +020010
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#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020026# @individual: Do not attempt to cancel any other Actions if any
27# Actions fail after the Transaction request succeeds. All
28# Actions that can complete successfully will do so without
29# waiting on others. This is the default.
Markus Armbrusterfa988e32017-08-24 21:14:02 +020030#
Markus Armbrustera937b6a2023-04-28 12:54:29 +020031# @grouped: If any Action fails after the Transaction succeeds, cancel
32# all Actions. Actions do not complete until all Actions are
33# ready to complete. May be rejected by Actions that do not
34# support this completion mode.
Markus Armbrusterfa988e32017-08-24 21:14:02 +020035#
36# Since: 2.5
37##
38{ 'enum': 'ActionCompletionMode',
39 'data': [ 'individual', 'grouped' ] }
40
41##
Markus Armbruster277b51f2021-09-17 16:31:21 +020042# @TransactionActionKind:
43#
44# @abort: Since 1.6
Markus Armbrustera937b6a2023-04-28 12:54:29 +020045#
Markus Armbruster277b51f2021-09-17 16:31:21 +020046# @block-dirty-bitmap-add: Since 2.5
Markus Armbrustera937b6a2023-04-28 12:54:29 +020047#
Markus Armbruster277b51f2021-09-17 16:31:21 +020048# @block-dirty-bitmap-remove: Since 4.2
Markus Armbrustera937b6a2023-04-28 12:54:29 +020049#
Markus Armbruster277b51f2021-09-17 16:31:21 +020050# @block-dirty-bitmap-clear: Since 2.5
Markus Armbrustera937b6a2023-04-28 12:54:29 +020051#
Markus Armbruster277b51f2021-09-17 16:31:21 +020052# @block-dirty-bitmap-enable: Since 4.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +020053#
Markus Armbruster277b51f2021-09-17 16:31:21 +020054# @block-dirty-bitmap-disable: Since 4.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +020055#
Markus Armbruster277b51f2021-09-17 16:31:21 +020056# @block-dirty-bitmap-merge: Since 4.0
Markus Armbrustera937b6a2023-04-28 12:54:29 +020057#
Markus Armbruster277b51f2021-09-17 16:31:21 +020058# @blockdev-backup: Since 2.3
Markus Armbrustera937b6a2023-04-28 12:54:29 +020059#
Markus Armbruster277b51f2021-09-17 16:31:21 +020060# @blockdev-snapshot: Since 2.5
Markus Armbrustera937b6a2023-04-28 12:54:29 +020061#
Markus Armbruster277b51f2021-09-17 16:31:21 +020062# @blockdev-snapshot-internal-sync: Since 1.7
Markus Armbrustera937b6a2023-04-28 12:54:29 +020063#
Markus Armbruster277b51f2021-09-17 16:31:21 +020064# @blockdev-snapshot-sync: since 1.1
Markus Armbrustera937b6a2023-04-28 12:54:29 +020065#
Markus Armbruster277b51f2021-09-17 16:31:21 +020066# @drive-backup: Since 1.6
67#
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +010068# Features:
Markus Armbrustera937b6a2023-04-28 12:54:29 +020069#
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +010070# @deprecated: Member @drive-backup is deprecated. Use member
Markus Armbrustera937b6a2023-04-28 12:54:29 +020071# @blockdev-backup instead.
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +010072#
Markus Armbruster277b51f2021-09-17 16:31:21 +020073# Since: 1.1
74##
75{ 'enum': 'TransactionActionKind',
76 'data': [ 'abort', 'block-dirty-bitmap-add', 'block-dirty-bitmap-remove',
77 'block-dirty-bitmap-clear', 'block-dirty-bitmap-enable',
78 'block-dirty-bitmap-disable', 'block-dirty-bitmap-merge',
79 'blockdev-backup', 'blockdev-snapshot',
80 'blockdev-snapshot-internal-sync', 'blockdev-snapshot-sync',
Vladimir Sementsov-Ogievskiy10841592021-11-04 09:58:11 +010081 { 'name': 'drive-backup', 'features': [ 'deprecated' ] } ] }
Markus Armbruster277b51f2021-09-17 16:31:21 +020082
83##
84# @AbortWrapper:
85#
86# Since: 1.6
87##
88{ 'struct': 'AbortWrapper',
89 'data': { 'data': 'Abort' } }
90
91##
92# @BlockDirtyBitmapAddWrapper:
93#
94# Since: 2.5
95##
96{ 'struct': 'BlockDirtyBitmapAddWrapper',
97 'data': { 'data': 'BlockDirtyBitmapAdd' } }
98
99##
100# @BlockDirtyBitmapWrapper:
101#
102# Since: 2.5
103##
104{ 'struct': 'BlockDirtyBitmapWrapper',
105 'data': { 'data': 'BlockDirtyBitmap' } }
106
107##
108# @BlockDirtyBitmapMergeWrapper:
109#
110# Since: 4.0
111##
112{ 'struct': 'BlockDirtyBitmapMergeWrapper',
113 'data': { 'data': 'BlockDirtyBitmapMerge' } }
114
115##
116# @BlockdevBackupWrapper:
117#
118# Since: 2.3
119##
120{ 'struct': 'BlockdevBackupWrapper',
121 'data': { 'data': 'BlockdevBackup' } }
122
123##
124# @BlockdevSnapshotWrapper:
125#
126# Since: 2.5
127##
128{ 'struct': 'BlockdevSnapshotWrapper',
129 'data': { 'data': 'BlockdevSnapshot' } }
130
131##
132# @BlockdevSnapshotInternalWrapper:
133#
134# Since: 1.7
135##
136{ 'struct': 'BlockdevSnapshotInternalWrapper',
137 'data': { 'data': 'BlockdevSnapshotInternal' } }
138
139##
140# @BlockdevSnapshotSyncWrapper:
141#
142# Since: 1.1
143##
144{ 'struct': 'BlockdevSnapshotSyncWrapper',
145 'data': { 'data': 'BlockdevSnapshotSync' } }
146
147##
148# @DriveBackupWrapper:
149#
150# Since: 1.6
151##
152{ 'struct': 'DriveBackupWrapper',
153 'data': { 'data': 'DriveBackup' } }
154
155##
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200156# @TransactionAction:
157#
158# A discriminated record of operations that can be performed with
Markus Armbruster277b51f2021-09-17 16:31:21 +0200159# @transaction.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200160#
Markus Armbruster89a22732024-02-05 08:47:09 +0100161# @type: the operation to be performed
162#
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200163# Since: 1.1
164##
165{ 'union': 'TransactionAction',
Markus Armbruster277b51f2021-09-17 16:31:21 +0200166 'base': { 'type': 'TransactionActionKind' },
167 'discriminator': 'type',
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200168 'data': {
Markus Armbruster277b51f2021-09-17 16:31:21 +0200169 'abort': 'AbortWrapper',
170 'block-dirty-bitmap-add': 'BlockDirtyBitmapAddWrapper',
171 'block-dirty-bitmap-remove': 'BlockDirtyBitmapWrapper',
172 'block-dirty-bitmap-clear': 'BlockDirtyBitmapWrapper',
173 'block-dirty-bitmap-enable': 'BlockDirtyBitmapWrapper',
174 'block-dirty-bitmap-disable': 'BlockDirtyBitmapWrapper',
175 'block-dirty-bitmap-merge': 'BlockDirtyBitmapMergeWrapper',
176 'blockdev-backup': 'BlockdevBackupWrapper',
177 'blockdev-snapshot': 'BlockdevSnapshotWrapper',
178 'blockdev-snapshot-internal-sync': 'BlockdevSnapshotInternalWrapper',
179 'blockdev-snapshot-sync': 'BlockdevSnapshotSyncWrapper',
180 'drive-backup': 'DriveBackupWrapper'
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200181 } }
182
183##
184# @TransactionProperties:
185#
186# Optional arguments to modify the behavior of a Transaction.
187#
188# @completion-mode: Controls how jobs launched asynchronously by
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200189# Actions will complete or fail as a group. See
190# @ActionCompletionMode for details.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200191#
192# Since: 2.5
193##
194{ 'struct': 'TransactionProperties',
195 'data': {
196 '*completion-mode': 'ActionCompletionMode'
197 }
198}
199
200##
201# @transaction:
202#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200203# Executes a number of transactionable QMP commands atomically. If
204# any operation fails, then the entire set of actions will be
205# abandoned and the appropriate error returned.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200206#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200207# For external snapshots, the dictionary contains the device, the file
208# to use for the new snapshot, and the format. The default format, if
209# not specified, is qcow2.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200210#
211# Each new snapshot defaults to being created by QEMU (wiping any
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200212# contents if the file already exists), but it is also possible to
213# reuse an externally-created file. In the latter case, you should
214# ensure that the new image file has the same contents as the current
215# one; QEMU cannot perform any meaningful check. Typically this is
216# achieved by using the current image file as the backing file for the
217# new image.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200218#
219# On failure, the original disks pre-snapshot attempt will be used.
220#
Markus Armbruster09ec8512021-05-01 09:57:47 +0200221# For internal snapshots, the dictionary contains the device and the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200222# snapshot's name. If an internal snapshot matching name already
223# exists, the request will be rejected. Only some image formats
224# support it, for example, qcow2, and rbd,
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200225#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200226# On failure, qemu will try delete the newly created internal snapshot
227# in the transaction. When an I/O error occurs during deletion, the
228# user needs to fix it later with qemu-img or other command.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200229#
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200230# @actions: List of @TransactionAction; information needed for the
231# respective operations.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200232#
233# @properties: structure of additional options to control the
Markus Armbrustera937b6a2023-04-28 12:54:29 +0200234# execution of the transaction. See @TransactionProperties for
235# additional detail.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200236#
Markus Armbruster2746f062024-02-27 12:39:12 +0100237# Errors:
John Snowb32a6b62024-06-26 18:21:15 -0400238# - Any errors from commands in the transaction
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200239#
John Snowd461c272024-06-26 18:21:16 -0400240# .. note:: The transaction aborts on the first failure. Therefore,
Markus Armbruster01bed0f2024-07-29 08:52:20 +0200241# there will be information on only one failed operation returned
242# in an error condition, and subsequent actions will not have been
John Snowd461c272024-06-26 18:21:16 -0400243# attempted.
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200244#
245# Since: 1.1
246#
John Snow14b48aa2024-07-16 22:13:08 -0400247# .. qmp-example::
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200248#
Markus Armbrusterd23055b2024-02-16 15:58:34 +0100249# -> { "execute": "transaction",
250# "arguments": { "actions": [
251# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
252# "snapshot-file": "/some/place/my-image",
253# "format": "qcow2" } },
254# { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
255# "snapshot-file": "/some/place/my-image2",
256# "snapshot-node-name": "node3432",
257# "mode": "existing",
258# "format": "qcow2" } },
259# { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
260# "snapshot-file": "/some/place/my-image2",
261# "mode": "existing",
262# "format": "qcow2" } },
263# { "type": "blockdev-snapshot-internal-sync", "data" : {
264# "device": "ide-hd2",
265# "name": "snapshot0" } } ] } }
266# <- { "return": {} }
Markus Armbrusterfa988e32017-08-24 21:14:02 +0200267##
268{ 'command': 'transaction',
269 'data': { 'actions': [ 'TransactionAction' ],
270 '*properties': 'TransactionProperties'
271 }
272}