Re: [PATCH] docs: Better mention of qemu-img amend limitations

[Eric Blake]

Ping^2

On 10/20/20 10:44 AM, Eric Blake wrote:
> On 9/23/20 4:56 PM, Nir Soffer wrote:
>> On Wed, Sep 23, 2020 at 11:38 PM Eric Blake <eblake@redhat.com> wrote:
>>>
>>> Missed during merge resolution of commit bc5ee6da71.
>>>
>>> Signed-off-by: Eric Blake <eblake@redhat.com>
>>> ---
>>>  docs/tools/qemu-img.rst | 4 ++++
>>>  1 file changed, 4 insertions(+)
>>>
>>> diff --git a/docs/tools/qemu-img.rst b/docs/tools/qemu-img.rst
>>> index c35bd6482203..2b5891b54db7 100644
>>> --- a/docs/tools/qemu-img.rst
>>> +++ b/docs/tools/qemu-img.rst
>>> @@ -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?
> 
> 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.
> 

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