[Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Kevin Wolf]

People have repeatedly expected that you can do things like snapshotting
an image with qemu-img while a qemu instance is running. Maybe we need
to consider locking the files while they are in use, but having a
warning in the qemu-img manpage is doable for 1.2 and can't hurt anyway.

Signed-off-by: Kevin Wolf <kwolf@redhat.com>
---
 qemu-img.texi |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/qemu-img.texi b/qemu-img.texi
index 77c6d0b..0b363e7 100644
--- a/qemu-img.texi
+++ b/qemu-img.texi
@@ -4,6 +4,14 @@ usage: qemu-img command [command options]
 @c man end
 @end example
 
+@c man begin DESCRIPTION
+qemu-img allows to create, convert and modify images offline. It can handle all
+image formats supported by QEMU.
+
+@b{Warning:} Never use qemu-img to modify images in use by a running virtual
+machine or any other process, this may destroy the image.
+@c man end
+
 @c man begin OPTIONS
 
 The following commands are supported:
-- 
1.7.6.5

Re: [Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Peter Maydell]

On 16 August 2012 10:00, Kevin Wolf <kwolf@redhat.com> wrote:
> People have repeatedly expected that you can do things like snapshotting
> an image with qemu-img while a qemu instance is running. Maybe we need
> to consider locking the files while they are in use, but having a
> warning in the qemu-img manpage is doable for 1.2 and can't hurt anyway.
>
> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> ---
>  qemu-img.texi |    8 ++++++++
>  1 files changed, 8 insertions(+), 0 deletions(-)
>
> diff --git a/qemu-img.texi b/qemu-img.texi
> index 77c6d0b..0b363e7 100644
> --- a/qemu-img.texi
> +++ b/qemu-img.texi
> @@ -4,6 +4,14 @@ usage: qemu-img command [command options]
>  @c man end
>  @end example

Some minor grammar tweaks:

> +@c man begin DESCRIPTION
> +qemu-img allows to create, convert and modify images offline. It can handle all
> +image formats supported by QEMU.

"allows you to".

> +
> +@b{Warning:} Never use qemu-img to modify images in use by a running virtual
> +machine or any other process, this may destroy the image.

";" or ", because".

> +@c man end
> +
>  @c man begin OPTIONS
>
>  The following commands are supported:
> --
> 1.7.6.5

-- PMM

Re: [Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1705 bytes --]

On 08/16/2012 04:00 AM, Peter Maydell wrote:
> On 16 August 2012 10:00, Kevin Wolf <kwolf@redhat.com> wrote:
>> People have repeatedly expected that you can do things like snapshotting
>> an image with qemu-img while a qemu instance is running. Maybe we need
>> to consider locking the files while they are in use,

Sounds like a nice feature bit to add to qcow2v3, where both qemu-img
and qemu check if the locking feature is enabled for an image, as well
as maintain a header bit that is set when the image is open read-write
and refuse to use the image if the lock bit is set.

> but having a
>> warning in the qemu-img manpage is doable for 1.2 and can't hurt anyway.
>>
>> Signed-off-by: Kevin Wolf <kwolf@redhat.com>

> 
>> +
>> +@b{Warning:} Never use qemu-img to modify images in use by a running virtual
>> +machine or any other process, this may destroy the image.
> 
> ";" or ", because".

Is this strong enough?  Remember, with qcow2v3 and qed, the mere act of
opening an image will perform refcount checks that modify the image,
unless you explicitly request otherwise, which means even a query of the
file metadata may result in modifying the image as part of the default
open.  Maybe incorporate some ideas from this attempt:

Never use qemu-img to modify files in use by a running virtual machine
or any other process; this may destroy the image.  Be aware that some
image formats perform modifications even on query operations.  Also, be
aware that querying an image that is being modified by another process
may encounter inconsistent state.

-- 
Eric Blake   eblake@redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 620 bytes --]

Re: [Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Kevin Wolf]

Am 16.08.2012 14:56, schrieb Eric Blake:
> On 08/16/2012 04:00 AM, Peter Maydell wrote:
>> On 16 August 2012 10:00, Kevin Wolf <kwolf@redhat.com> wrote:
>>> People have repeatedly expected that you can do things like snapshotting
>>> an image with qemu-img while a qemu instance is running. Maybe we need
>>> to consider locking the files while they are in use,
> 
> Sounds like a nice feature bit to add to qcow2v3, where both qemu-img
> and qemu check if the locking feature is enabled for an image, as well
> as maintain a header bit that is set when the image is open read-write
> and refuse to use the image if the lock bit is set.

I thought the same. However, then you need some way to override this
mechanism when recovering from a crash etc., so it's not a trivial
addition and it would be user-visible.

>> but having a
>>> warning in the qemu-img manpage is doable for 1.2 and can't hurt anyway.
>>>
>>> Signed-off-by: Kevin Wolf <kwolf@redhat.com>
> 
>>
>>> +
>>> +@b{Warning:} Never use qemu-img to modify images in use by a running virtual
>>> +machine or any other process, this may destroy the image.
>>
>> ";" or ", because".
> 
> Is this strong enough?  Remember, with qcow2v3 and qed, the mere act of
> opening an image will perform refcount checks that modify the image,
> unless you explicitly request otherwise, which means even a query of the
> file metadata may result in modifying the image as part of the default
> open. 

Not for read-only opens. I think qemu-img gets this right meanwhile, so
that images are opened read-only when they are only queried.

(And for qcow2v3 the check only happens with lazy refcounting enabled,
which is not the default)

> Maybe incorporate some ideas from this attempt:
> 
> Never use qemu-img to modify files in use by a running virtual machine
> or any other process; this may destroy the image.  Be aware that some
> image formats perform modifications even on query operations.  Also, be
> aware that querying an image that is being modified by another process
> may encounter inconsistent state.

Adding the last sentence is probably a good idea anyway.

Kevin

Re: [Qemu-devel] [PATCH] Documentation: Warn against qemu-img on active image

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2221 bytes --]

On 08/16/2012 07:35 AM, Kevin Wolf wrote:
> Am 16.08.2012 14:56, schrieb Eric Blake:
>> On 08/16/2012 04:00 AM, Peter Maydell wrote:
>>> On 16 August 2012 10:00, Kevin Wolf <kwolf@redhat.com> wrote:
>>>> People have repeatedly expected that you can do things like snapshotting
>>>> an image with qemu-img while a qemu instance is running. Maybe we need
>>>> to consider locking the files while they are in use,
>>
>> Sounds like a nice feature bit to add to qcow2v3, where both qemu-img
>> and qemu check if the locking feature is enabled for an image, as well
>> as maintain a header bit that is set when the image is open read-write
>> and refuse to use the image if the lock bit is set.
> 
> I thought the same. However, then you need some way to override this
> mechanism when recovering from a crash etc., so it's not a trivial
> addition and it would be user-visible.

Good point.  With fcntl() locking, the lock goes away on crash; but with
file modification locking, the lock can get stuck so you have to provide
overrides; and once you provide overrides, the lock is not quite as
powerful.  So maybe it's best to just leave locking up to management
apps (after all, libvirt already has a lock protocol support, currently
built on sanlock but also with a patch proposed for using fcntl()).

>> Is this strong enough?  Remember, with qcow2v3 and qed, the mere act of
>> opening an image will perform refcount checks that modify the image,
>> unless you explicitly request otherwise, which means even a query of the
>> file metadata may result in modifying the image as part of the default
>> open. 
> 
> Not for read-only opens. I think qemu-img gets this right meanwhile, so
> that images are opened read-only when they are only queried.

Then it might also be worth documenting which actions are read-only
queries vs. potential modifications, in the docs for each action.  (For
example, 'info' is read-only, 'convert' is read-only when creating a
copy although consistency is essential for it to be useful, 'check' is
readonly while 'check -r' is read-write,...)

-- 
Eric Blake   eblake@redhat.com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 620 bytes --]