[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.

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

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

[A] -> [B] -> [C] -> [D]

Where the rightmost object ([D] 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] -> [D]

Currently only forward merge with target being the active image is
supported, that is, data copy is performed in the right direction with
destination being the rightmost image.

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 active image when the
operation is finished.

In the example above, the command would be:

(qemu) block_stream virtio0 A


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
	7	Snapshot live merge
	8	===================
	9
	10	Given a snapshot chain, described in this document in the following
	11	format:
	12
	13	[A] -> [B] -> [C] -> [D]
	14
	15	Where the rightmost object ([D] in the example) described is the current
	16	image which the guest OS has write access to. To the left of it is its base
	17	image, and so on accordingly until the leftmost image, which has no
	18	base.
	19
	20	The snapshot live merge operation transforms such a chain into a
	21	smaller one with fewer elements, such as this transformation relative
	22	to the first example:
	23
	24	[A] -> [D]
	25
	26	Currently only forward merge with target being the active image is
	27	supported, that is, data copy is performed in the right direction with
	28	destination being the rightmost image.
	29
	30	The operation is implemented in QEMU through image streaming facilities.
	31
	32	The basic idea is to execute 'block_stream virtio0' while the guest is
	33	running. Progress can be monitored using 'info block-jobs'. When the
	34	streaming operation completes it raises a QMP event. 'block_stream'
	35	copies data from the backing file(s) into the active image. When finished,
	36	it adjusts the backing file pointer.
	37
	38	The 'base' parameter specifies an image which data need not be streamed from.
	39	This image will be used as the backing file for the active image when the
	40	operation is finished.
	41
	42	In the example above, the command would be:
	43
	44	(qemu) block_stream virtio0 A
	45
	46
	47	Live block copy
	48	===============
	49
	50	To copy an in use image to another destination in the filesystem, one
	51	should create a live snapshot in the desired destination, then stream
	52	into that image. Example:
	53
	54	(qemu) snapshot_blkdev ide0-hd0 /new-path/disk.img qcow2
	55
	56	(qemu) block_stream ide0-hd0
	57
	58