Skip to contentSkip to conversation

docs: Better mention of qemu-img amend limitations

PATCH In review Eric Blake 3 participants 6 messages Sep 23, 2020 – Nov 13, 2020

lore
Share & tools
lore

Eric Blake

author
#0 lore raw

PATCH 1/1 docs: Better mention of qemu-img amend limitations

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +4 -0
index c35bd6482203..2b5891b54db7 100644
@@ -265,6 +265,10 @@ Command description:
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.
+
 .. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
 
   Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
Signature · 1 line
2.28.0
#1 lore raw
Quoted 13 lines · Eric Blake

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +0 -0
index c35bd6482203..2b5891b54db7 100644

docs/tools/qemu-img.rst Command description: · line 270

Quoted 6 lines
docs/tools/qemu-img.rst +3 -0
@@ -265,6 +265,10 @@ Command description:
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.

Because of the backing format?

Quoted 8 lines
docs/tools/qemu-img.rst +1 -1
+
 .. option:: bench [-c COUNT] [-d DEPTH] [-f FMT] [--flush-interval=FLUSH_INTERVAL] [-i AIO] [-n] [--no-drain] [-o OFFSET] [--pattern=PATTERN] [-q] [-s BUFFER_SIZE] [-S STEP_SIZE] [-t CACHE] [-w] [-U] FILENAME
 
   Run a simple sequential I/O benchmark on the specified image. If ``-w`` is
--

2.28.0

author
#2 lore raw
Quoted 17 lines · Nir Soffer
Quoted 16 lines · Eric Blake

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +0 -0
index c35bd6482203..2b5891b54db7 100644
@@ -265,6 +265,10 @@ Command description:
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 
Quoted 5 lines

docs/tools/qemu-img.rst Command description: · line 270

Quoted 3 lines
docs/tools/qemu-img.rst +3 -0
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.

Because of the backing format?

Sorry for not answering this earlier (and now this serves as a ping for the patch):

Consider if you have:

Base.raw <- Overlay.qcow2

and want to rebase it to:

Base.qcow2 <- Overlay.qcow2

where Base.raw and Base.qcow2 contain identical guest-visible content. The problem at hand is that 'qemu-amend' needs to know what the backing format is both before the rebase (to know how to properly read the existing image) and after the rebase (to ensure that future opens of Overlay.qcow2 still properly read the backing format). But there is no obvious command-line spelling to specify the difference between the backing format pre-amend and the backing format post-amend. Maybe we could add that, but I felt it was easier to just document that instead of trying to amend the image (which involves multiple steps, and may require upgrading/downgrading between v2 and v3, which in turn may affect decisions on efficiency of representing regions of zero) at the same time as the backing file/format, it's easier to just update the backing file/format with a stand-alone command.

I can add that to the commit message, if the patch itself is reasonable.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
author
#3 lore raw

Ping^2

Quoted 51 lines · Eric Blake
Quoted 17 lines · Nir Soffer
Quoted 16 lines · Eric Blake

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +0 -0
index c35bd6482203..2b5891b54db7 100644
@@ -265,6 +265,10 @@ Command description:
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 
Quoted 5 lines

docs/tools/qemu-img.rst Command description: · line 270

Quoted 3 lines
docs/tools/qemu-img.rst +3 -0
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.

Because of the backing format?

Sorry for not answering this earlier (and now this serves as a ping for the patch):

Consider if you have:

Base.raw <- Overlay.qcow2

and want to rebase it to:

Base.qcow2 <- Overlay.qcow2

where Base.raw and Base.qcow2 contain identical guest-visible content. The problem at hand is that 'qemu-amend' needs to know what the backing format is both before the rebase (to know how to properly read the existing image) and after the rebase (to ensure that future opens of Overlay.qcow2 still properly read the backing format). But there is no obvious command-line spelling to specify the difference between the backing format pre-amend and the backing format post-amend. Maybe we could add that, but I felt it was easier to just document that instead of trying to amend the image (which involves multiple steps, and may require upgrading/downgrading between v2 and v3, which in turn may affect decisions on efficiency of representing regions of zero) at the same time as the backing file/format, it's easier to just update the backing file/format with a stand-alone command.

I can add that to the commit message, if the patch itself is reasonable.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#4 lore raw
In reply to Eric Blake

Am 23.09.2020 um 22:37 hat Eric Blake geschrieben:

docs/tools/qemu-img.rst Command description:

Quoted 12 lines

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +0 -0
index c35bd6482203..2b5891b54db7 100644
@@ -265,6 +265,10 @@ Command description:

Adding a little more context:

docs/tools/qemu-img.rst Command description: · line 271

Quoted 11 lines
docs/tools/qemu-img.rst +4 -0
   The set of options that can be amended are dependent on the image
   format, but note that amending the backing chain relationship should
   instead be performed with ``qemu-img rebase``.
 
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
 
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.
+

I think the problem is your local conflict resolution. This patch would duplicate the paragraph.

Kevin

author
#5 lore raw
Quoted 23 lines · Kevin Wolf

Am 23.09.2020 um 22:37 hat Eric Blake geschrieben:

docs/tools/qemu-img.rst Command description:

Quoted 12 lines

Missed during merge resolution of commit bc5ee6da71.

---
 docs/tools/qemu-img.rst | 4 ++++
 1 file changed, 4 insertions(+)
docs/tools/qemu-img.rst +0 -0
index c35bd6482203..2b5891b54db7 100644
@@ -265,6 +265,10 @@ Command description:

Adding a little more context:

Quoted 7 lines
docs/tools/qemu-img.rst +0 -0
   The set of options that can be amended are dependent on the image
   format, but note that amending the backing chain relationship should
   instead be performed with ``qemu-img rebase``.
 
   --force allows some unsafe operations. Currently for -f luks, it allows to
   erase the last encryption key, and to overwrite an active encryption key.
Quoted 7 lines

docs/tools/qemu-img.rst Command description: · line 271

Quoted 4 lines
docs/tools/qemu-img.rst +4 -0
+  The set of options that can be amended are dependent on the image
+  format, but note that amending the backing chain relationship should
+  instead be performed with ``qemu-img rebase``.
+

I think the problem is your local conflict resolution. This patch would duplicate the paragraph.

D'oh. Thanks for spotting that, patch withdrawn.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org