[qemu.git] / docs / live-block-ops.txt

LIVE BLOCK OPERATIONS
=====================

High level description of live block operations. Note these are not
supported for use with the raw format at the moment.

Note also that this document is incomplete and it currently only
covers the 'stream' operation. Other operations supported by QEMU such
as 'commit', 'mirror' and 'backup' are not described here yet. Please
refer to the qapi/block-core.json file for an overview of those.

Snapshot live merge
===================

Given a snapshot chain, described in this document in the following
format:

[A] <- [B] <- [C] <- [D] <- [E]

Where the rightmost object ([E] in the example) described is the current
image which the guest OS has write access to. To the left of it is its base
image, and so on accordingly until the leftmost image, which has no
base.

The snapshot live merge operation transforms such a chain into a
smaller one with fewer elements, such as this transformation relative
to the first example:

[A] <- [E]

Data is copied in the right direction with destination being the
rightmost image, but any other intermediate image can be specified
instead. In this example data is copied from [C] into [D], so [D] can
be backed by [B]:

[A] <- [B] <- [D] <- [E]

The operation is implemented in QEMU through image streaming facilities.

The basic idea is to execute 'block_stream virtio0' while the guest is
running. Progress can be monitored using 'info block-jobs'. When the
streaming operation completes it raises a QMP event. 'block_stream'
copies data from the backing file(s) into the active image. When finished,
it adjusts the backing file pointer.

The 'base' parameter specifies an image which data need not be
streamed from. This image will be used as the backing file for the
destination image when the operation is finished.

In the first example above, the command would be:

(qemu) block_stream virtio0 file-A.img

In order to specify a destination image different from the active
(rightmost) one we can use its node name instead.

In the second example above, the command would be:

(qemu) block_stream node-D file-B.img

Live block copy
===============

To copy an in use image to another destination in the filesystem, one
should create a live snapshot in the desired destination, then stream
into that image. Example:

(qemu) snapshot_blkdev ide0-hd0 /new-path/disk.img qcow2

(qemu) block_stream ide0-hd0
Commit	Line	Data
094f1ba1 MT	1	LIVE BLOCK OPERATIONS
	2	=====================
	3
	4	High level description of live block operations. Note these are not
	5	supported for use with the raw format at the moment.
	6
1029641b AG	7	Note also that this document is incomplete and it currently only
	8	covers the 'stream' operation. Other operations supported by QEMU such
	9	as 'commit', 'mirror' and 'backup' are not described here yet. Please
	10	refer to the qapi/block-core.json file for an overview of those.
	11
094f1ba1 MT	12	Snapshot live merge
	13	===================
	14
	15	Given a snapshot chain, described in this document in the following
	16	format:
	17
1029641b	18	[A] <- [B] <- [C] <- [D] <- [E]
094f1ba1	19
1029641b	20	Where the rightmost object ([E] in the example) described is the current
094f1ba1 MT	21	image which the guest OS has write access to. To the left of it is its base
	22	image, and so on accordingly until the leftmost image, which has no
	23	base.
	24
	25	The snapshot live merge operation transforms such a chain into a
	26	smaller one with fewer elements, such as this transformation relative
	27	to the first example:
	28
1029641b AG	29	[A] <- [E]
	30
	31	Data is copied in the right direction with destination being the
	32	rightmost image, but any other intermediate image can be specified
	33	instead. In this example data is copied from [C] into [D], so [D] can
	34	be backed by [B]:
094f1ba1	35
1029641b	36	[A] <- [B] <- [D] <- [E]
094f1ba1 MT	37
	38	The operation is implemented in QEMU through image streaming facilities.
	39
	40	The basic idea is to execute 'block_stream virtio0' while the guest is
	41	running. Progress can be monitored using 'info block-jobs'. When the
	42	streaming operation completes it raises a QMP event. 'block_stream'
	43	copies data from the backing file(s) into the active image. When finished,
	44	it adjusts the backing file pointer.
	45
1029641b AG	46	The 'base' parameter specifies an image which data need not be
	47	streamed from. This image will be used as the backing file for the
	48	destination image when the operation is finished.
	49
	50	In the first example above, the command would be:
	51
	52	(qemu) block_stream virtio0 file-A.img
094f1ba1	53
1029641b AG	54	In order to specify a destination image different from the active
1029641b AG	55	(rightmost) one we can use its node name instead.
094f1ba1	56
1029641b	57	In the second example above, the command would be:
094f1ba1	58
1029641b	59	(qemu) block_stream node-D file-B.img
094f1ba1 MT	60
	61	Live block copy
	62	===============
	63
	64	To copy an in use image to another destination in the filesystem, one
	65	should create a live snapshot in the desired destination, then stream
	66	into that image. Example:
	67
	68	(qemu) snapshot_blkdev ide0-hd0 /new-path/disk.img qcow2
	69
	70	(qemu) block_stream ide0-hd0
	71
	72