Commit 37222900 authored by Jeff Cody's avatar Jeff Cody Committed by Kevin Wolf

block: update block commit documentation regarding image truncation

This updates the documentation for commiting snapshot images.
Specifically, this highlights what happens when the base image
is either smaller or larger than the snapshot image being committed.

In the case of the base image being smaller, it is resized to the
larger size of the snapshot image.  In the case of the base image
being larger, it is not resized automatically, but once the commit
has completed it is safe for the user to truncate the base image.
Signed-off-by: default avatarJeff Cody <jcody@redhat.com>
Reviewed-by: default avatarFam Zheng <famz@redhat.com>
Reviewed-by: default avatarEric Blake <eblake@redhat.com>
Signed-off-by: default avatarKevin Wolf <kwolf@redhat.com>
parent 4da83585
......@@ -35,6 +35,11 @@ STEXI
@item commit
@findex commit
Commit changes to the disk images (if -snapshot is used) or backing files.
If the backing file is smaller than the snapshot, then the backing file will be
resized to be the same size as the snapshot. If the snapshot is smaller than
the backing file, the backing file will not be truncated. If you want the
backing file to match the size of the smaller snapshot, you can safely truncate
it yourself once the commit operation successfully completes.
ETEXI
{
......
......@@ -1994,6 +1994,13 @@
# user needs to complete the job with the block-job-complete
# command after getting the ready event. (Since 2.0)
#
# If the base image is smaller than top, then the base image
# will be resized to be the same size as top. If top is
# smaller than the base image, the base will not be
# truncated. If you want the base image size to match the
# size of the smaller top, you can safely truncate it
# yourself once the commit operation successfully completes.
#
#
# @speed: #optional the maximum speed, in bytes per second
#
......
......@@ -142,7 +142,12 @@ it doesn't need to be specified separately in this case.
@item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
Commit the changes recorded in @var{filename} in its base image.
Commit the changes recorded in @var{filename} in its base image or backing file.
If the backing file is smaller than the snapshot, then the backing file will be
resized to be the same size as the snapshot. If the snapshot is smaller than
the backing file, the backing file will not be truncated. If you want the
backing file to match the size of the smaller snapshot, you can safely truncate
it yourself once the commit operation successfully completes.
@item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2}
......
......@@ -966,6 +966,45 @@ EQMP
.mhandler.cmd_new = qmp_marshal_input_block_commit,
},
SQMP
block-commit
------------
Live commit of data from overlay image nodes into backing nodes - i.e., writes
data between 'top' and 'base' into 'base'.
Arguments:
- "device": The device's ID, must be unique (json-string)
- "base": The file name of the backing image to write data into.
If not specified, this is the deepest backing image
(json-string, optional)
- "top": The file name of the backing image within the image chain,
which contains the topmost data to be committed down.
If top == base, that is an error.
If top == active, the job will not be completed by itself,
user needs to complete the job with the block-job-complete
command after getting the ready event. (Since 2.0)
If the base image is smaller than top, then the base image
will be resized to be the same size as top. If top is
smaller than the base image, the base will not be
truncated. If you want the base image size to match the
size of the smaller top, you can safely truncate it
yourself once the commit operation successfully completes.
(json-string)
- "speed": the maximum speed, in bytes per second (json-int, optional)
Example:
-> { "execute": "block-commit", "arguments": { "device": "virtio0",
"top": "/tmp/snap1.qcow2" } }
<- { "return": {} }
EQMP
{
.name = "drive-backup",
.args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment