From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36521) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YOxQJ-00076Z-4z for qemu-devel@nongnu.org; Fri, 20 Feb 2015 18:55:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YOxQF-00051B-UN for qemu-devel@nongnu.org; Fri, 20 Feb 2015 18:55:55 -0500 Received: from mx1.redhat.com ([209.132.183.28]:41482) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YOxQF-00050G-Lq for qemu-devel@nongnu.org; Fri, 20 Feb 2015 18:55:51 -0500 Message-ID: <54E7C984.2070305@redhat.com> Date: Fri, 20 Feb 2015 16:55:48 -0700 From: Eric Blake MIME-Version: 1.0 References: <1424473645-29161-1-git-send-email-jsnow@redhat.com> <1424473645-29161-20-git-send-email-jsnow@redhat.com> In-Reply-To: <1424473645-29161-20-git-send-email-jsnow@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="LdRO496LjSsm3dNRV8hA2d23ujCAEVELT" Subject: Re: [Qemu-devel] [PATCH v14 19/19] docs: incremental backup documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: John Snow , qemu-devel@nongnu.org Cc: kwolf@redhat.com, famz@redhat.com, armbru@redhat.com, mreitz@redhat.com, vsementsov@parallels.com, stefanha@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --LdRO496LjSsm3dNRV8hA2d23ujCAEVELT Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 02/20/2015 04:07 PM, John Snow wrote: > Signed-off-by: John Snow > --- > docs/bitmaps.md | 253 ++++++++++++++++++++++++++++++++++++++++++++++++= ++++++++ > 1 file changed, 253 insertions(+) > create mode 100644 docs/bitmaps.md >=20 > diff --git a/docs/bitmaps.md b/docs/bitmaps.md > new file mode 100644 > index 0000000..7cda146 > --- /dev/null > +++ b/docs/bitmaps.md > @@ -0,0 +1,253 @@ > +# Dirty Bitmaps No copyright/license? Might be good to add. Also, I'm a fan of reviewing docs before code (does the design make sense in isolation, and then did we implement it) rather than last in the series (we may have faithfully documented our code, but that includes baking in any design flaws that reviewers are now blind to because of reading the code) > +* To create a new bitmap that tracks changes in 32KiB segments: > + > +```json > +{ "execute": "block-dirty-bitmap-add", > + "arguments": { > + "node": "drive0", > + "name": "bitmap0", > + "granularity": "32768" s/"32768"/32768/ (we are using a JSON integer, not string) > + } > +} > +``` > + > +### Deletion > + > +* Can be performed on a disabled bitmap, but not a frozen one. > + > +* Because bitmaps are only unique to the node to which they are attach= ed, > +you must specify the node/drive name here, too. > + > +```json > +{ "execute": "block-dirty-bitmap-remove", > + "arguments": { > + "node": "drive0", > + "name": "bitmap0", > + } No trailing commas in JSON. > +} > +``` > + > +### Enable/Disable: > + > +* Not very useful in current cases, but potentially useful for debuggi= ng in the > +future where we'd like to see what information changed only in a speci= fic > +time period: > + > +* To enable (which is, again, the default state after add) > + > +```json > +{ "execute": "block-dirty-bitmap-enable", > + "arguments": { > + "node": "drive0", > + "name": "bitmap0", > + } and again. > +} > +``` > + > +* To disable: > + > +```json > +{ "execute": "block-dirty-bitmap-disable", > + "arguments": { > + "node": "drive0", > + "name": "bitmap0", > + } > +} > +``` and again. Also, maybe swap these two, since a bitmap defaults to enabled (that is, you would logically use disable first, then enable to re-enable, when testing these out, if there is no way to create an already-disabled bitmap). > + > +### Resetting > + > +* Resetting a bitmap will clear all information it holds. > +* An incremental backup created from an empty bitmap will copy no data= , > +as if nothing has changed. > + > +```json > +{ "execute": "block-dirty-bitmap-clear", > + "arguments": { > + "node": "drive0", > + "name": "bitmap0", > + } I'll quit pointing out broken trailing JSON commas, on the assumption that you'll fix all of them rather than stopping here :) > +} > +``` > + > +## Transactions > + > +### Justification > +Bitmaps can be safely modified when the VM is paused or halted by usin= g > +the basic QMP commands. For instance, you might perform the following = actions: > + > +1. Boot the VM in a paused state. > +2. Create a full drive backup of drive0 > +3. Create a new bitmap attached to drive0 > +4. resume execution of the VM > +5. Incremental backups are ready to be created. Consistency on using trailing '.'? > + > +At this point, the bitmap and drive backup would be correctly in sync,= > +and incremental backups made from this point forward would be correctl= y aligned > +to the full drive backup. > + > +This is not particularly useful if we decide we want to start incremen= tal > +backups after the VM has been running for a while, which will allow us= to > +perform actions like the following: > + > +1. Boot the VM and begin execution > +2. Using transactions, perform the following operations: > + * Create 'bitmap0' > + * Create a full drive backup of drive0 > +3. Incremental backups are now ready to be created. It's unclear whether point 2 is describing two separate transactions, or one transaction with two steps. If it's just one, I'd word it: Using a single transaction, perform the following operations: > + > +The star of the show. > + > +**Nota Bene!** Only incremental backups of entire drives are supported= for now. > +So despite the fact that you can attach a bitmap to any arbitrary node= , they are > +only currently useful when attached to the root node. This is because > +drive-backup only supports drives/devices instead of arbitrary nodes. Maybe it's time to think about adding a node-backup :) But doesn't have to be this series. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --LdRO496LjSsm3dNRV8hA2d23ujCAEVELT Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJU58mEAAoJEKeha0olJ0Nq7SIH/14MQsdVFBzNqmFim1di8NTa uRDqo+cy3GBlDA+EBSIzZZNJHQCkAITl/y0nAQWjxHZKlWgcAIsqKe8iuQ8PIPwe /NySsqDuKGdJcCNoRNvdZTsYA+tesnnH0h2FYkQ8xXlhk/dtx0wIHq2xVio2G6v5 RqpUG+5FefqzLez+2yYELjvaJy021YwirmTib3dbBVUQp14hdwqjfyJ0HYTnQ230 kD0IB1CJilZsH5euGivdk+oKmQZKXdPbLSyqM4pR31XJSfOOeIcUm9o8n+L7s4oy 9p1YvY/Tre0tq5uqNMqFfVDUiOzsqrSK+Bu2wdPyeNzZpPMXexCzyHu/L1+cUuw= =v4Ww -----END PGP SIGNATURE----- --LdRO496LjSsm3dNRV8hA2d23ujCAEVELT--