[PATCH 0/4] docs: Fix live backup kbase page and add support for RST notes/warnings to the CSS
You can look at the result here: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/11156282021/artifacts/website/kba... (Sorry for the TLS error, my username has a dot in it and the gitlab.io cert doesn't allow that. No I will not change my username) Peter Krempa (4): kbase: live_full_disk_backup: Fix use of '.. note' directive css: Add style for '.. note:' and '.. warning:' rST roles docs: formatsecret: Convert inline emphasis of a warning to the '.. warning:' role kbase: live_full_disk_backup: Improve the document docs/css/generic.css | 26 ++++++++++++++++++++++++++ docs/formatsecret.rst | 7 ++++--- docs/kbase/live_full_disk_backup.rst | 20 ++++++++++++-------- 3 files changed, 42 insertions(+), 11 deletions(-) -- 2.51.0
From: Peter Krempa <pkrempa@redhat.com> The note was misindented thus breaking the numbered list around. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/live_full_disk_backup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/kbase/live_full_disk_backup.rst b/docs/kbase/live_full_disk_backup.rst index f9dcd2a1bd..c545aa3009 100644 --- a/docs/kbase/live_full_disk_backup.rst +++ b/docs/kbase/live_full_disk_backup.rst @@ -126,7 +126,7 @@ it. base.raw <-- overlay1.qcow2 (live QEMU) - .. note:: + .. note:: Above, if you have QEMU guest agent installed in your virtual machine, use the ``--quiesce`` option with ``virsh snapshot-create-as [...]`` to ensure you have a consistent disk -- 2.51.0
From: Peter Krempa <pkrempa@redhat.com> One of our kbase docs already uses '.. note:' and we could use e.g. '.. warning:' to replace some of emphasiszed paragraphs to make them more prominent. Introduce style for the generated HTML to add some hilight for them. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/css/generic.css | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/css/generic.css b/docs/css/generic.css index df37ceea37..87cd94d9f4 100644 --- a/docs/css/generic.css +++ b/docs/css/generic.css @@ -91,6 +91,32 @@ pre { padding: 1em; } +.admonition-title { + font-size: 110%; + font-weight: bold; +} + +div.admonition, +aside.admonition { + border: 1px solid #999999; +} + +.admonition p { + padding: 0 1em 0 1em; +} + +.note .admonition-title { + margin: 0; + padding: 0.5em 1em 0.5em 1em; + background: #6cb5ac; +} + +.warning .admonition-title { + margin: 0; + padding: 0.5em 1em 0.5em 1em; + background: #ffcc44; +} + a { color: rgb(0, 95, 97); } -- 2.51.0
From: Peter Krempa <pkrempa@redhat.com> This is an example how to hilight very important information in the docs. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst index 606a9cc587..d4e0cb9ddb 100644 --- a/docs/formatsecret.rst +++ b/docs/formatsecret.rst @@ -321,9 +321,10 @@ be omitted if the file contents are base64-encoded. # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file secretinfile --plain Secret value set -**WARNING** The following approach is **insecure** and deprecated. The secret -can also be set via an argument. Note that other users may see the actual secret -in the process listing! The secret must be base64 encoded. +.. warning:: + The following approach is **insecure** and deprecated. The secret + can also be set via an argument. Note that other users may see the actual + secret in the process listing! The secret must be base64 encoded. :: -- 2.51.0
From: Peter Krempa <pkrempa@redhat.com> Changes: - fixed emphasis on the API name and some operations - fixed the output example of some commands - added warning to avoid the snapshot+copy+commit approach as it's a bit dangerous - added --no-metadata to avoid creating snapshot XML Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/kbase/live_full_disk_backup.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/kbase/live_full_disk_backup.rst b/docs/kbase/live_full_disk_backup.rst index c545aa3009..be95d9d2e2 100644 --- a/docs/kbase/live_full_disk_backup.rst +++ b/docs/kbase/live_full_disk_backup.rst @@ -13,7 +13,7 @@ that using libvirt's APIs. This method involves concepts: the notion of `backing chains <backing_chains.html>`_, `QCOW2 overlays <https://www.qemu.org/docs/master/interop/live-block-operations.html#disk-image-backing-chain-notation>`_, -and a special operation called "active block-commit", which allows +and a special operation called *active block-commit*, which allows live-merging an overlay disk image into its backing file. Two kinds of backup: "push" and "pull" @@ -43,7 +43,7 @@ This document covers only the full backups using the "push" mode. Full disk backup using "push" mode ================================== -The below approach uses the modern backup API, virDomainBackupBegin(). +The below approach uses the modern backup API, ``virDomainBackupBegin()``. This requires libvirt-7.2.0 and QEMU-4.2, or higher versions. #. Start the guest:: @@ -92,8 +92,13 @@ This is the alternative in case you cannot use libvirt-7.2.0 and QEMU-4.2 for some reason. But this assumes you're using *at least* QEMU 2.1 and libvirt-1.2.9. +.. warning:: + We strongly suggest that the backup api (``virsh backup-begin``) is used + as it doesn't require deleting files as deleting a wrong file can lead + to data loss. + This backup approach is slightly more involved, and predates the -virDomainBackupBegin() API: Assuming a guest with a single disk image, +``virDomainBackupBegin()`` API: Assuming a guest with a single disk image, create a temporary live QCOW2 overlay (commonly called as "external snapshot") to track the live guest writes. Then backup the original disk image while the guest (live QEMU) keeps writing to the temporary @@ -120,7 +125,7 @@ it. $ virsh snapshot-create-as --domain vm1 overlay1 \ --diskspec vda,file=/var/lib/libvirt/images/overlay1.qcow2 \ - --disk-only + --disk-only --no-metadata The disk image chain looks as follows:: @@ -141,8 +146,7 @@ it. #. Now, take a backup the original image, ``base.raw``, to a different location using ``cp`` or ``rsync``:: - $ cp /var/lib/libvirt/images/base.raw - /export/backups/copy1_base.raw + $ cp /var/lib/libvirt/images/base.raw /export/backups/copy1_base.raw # Or: @@ -156,7 +160,7 @@ it. $ virsh domblklist vm1 Target Source ------------------------------------------------ - vda vda,file=/var/lib/libvirt/images/overlay1.qcow2 + vda /var/lib/libvirt/images/overlay1.qcow2 #. Once the backup of the original image completes, now perform the "active block-commit" to live-merge the contents of -- 2.51.0
On a Wednesday in 2025, Peter Krempa via Devel wrote:
You can look at the result here:
https://pipo.sk.gitlab.io/-/libvirt/-/jobs/11156282021/artifacts/website/kba...
(Sorry for the TLS error, my username has a dot in it and the gitlab.io cert doesn't allow that. No I will not change my username)
Peter Krempa (4): kbase: live_full_disk_backup: Fix use of '.. note' directive css: Add style for '.. note:' and '.. warning:' rST roles docs: formatsecret: Convert inline emphasis of a warning to the '.. warning:' role kbase: live_full_disk_backup: Improve the document
docs/css/generic.css | 26 ++++++++++++++++++++++++++ docs/formatsecret.rst | 7 ++++--- docs/kbase/live_full_disk_backup.rst | 20 ++++++++++++-------- 3 files changed, 42 insertions(+), 11 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa