From nobody Fri Mar 29 15:21:16 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) client-ip=207.211.31.81; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1593091450; cv=none; d=zohomail.com; s=zohoarc; b=gYfN3ip9xEbPUOaid5+w+TNqzReUr4q9RAuhiiFUqvdyG8NE8HbsTMcbqMa2ihSffsZr9UqR4DNzQqCx/WRLsYGRLplE5LtwV46imngQOTy/k2j/jOWh1tdwZIDp+mPdBZ/fIYizR4YTvzvadiHYKLbBIXZ09LJW8hsVDxME3WQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1593091450; h=Content-Type:Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=beZUzI6WNv76cCyFb3Q+B5hb5yJ8AC83CITs2dyM814=; b=G/Gy6OFyA5dU286QUPK2Vq3kGa38iYUdwSF8TNDAlQcXF2EkbpDQnfbujAygpQrGHdHvYbPmIo+pO/+6ILU1cKukorYWbHX1RY4nK0JuB4sKNNsujli5nxQc8kKbjo8rgVcn0LzF/AHWOnWYexYPtpG2fLRr2EMB8wKMsDJHwSI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.81 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-delivery-1.mimecast.com (us-smtp-1.mimecast.com [207.211.31.81]) by mx.zohomail.com with SMTPS id 1593091450757300.9842723706846; Thu, 25 Jun 2020 06:24:10 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-483-1KwfmszJPhe3GGjv7gi-fQ-1; Thu, 25 Jun 2020 09:24:07 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id CFE54800C60; Thu, 25 Jun 2020 13:24:00 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0AE136106A; Thu, 25 Jun 2020 13:23:59 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 0E30C1809547; Thu, 25 Jun 2020 13:23:56 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 05PDNs3A000565 for ; Thu, 25 Jun 2020 09:23:54 -0400 Received: by smtp.corp.redhat.com (Postfix) id 8F8FD7CAA3; Thu, 25 Jun 2020 13:23:54 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.62]) by smtp.corp.redhat.com (Postfix) with ESMTP id D2BF67C214 for ; Thu, 25 Jun 2020 13:23:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1593091449; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=beZUzI6WNv76cCyFb3Q+B5hb5yJ8AC83CITs2dyM814=; b=gwusJcFjku3XJKsa36KZ/hZyF2sNOMf86uX60jXrSgxA+Xqah3NJSauLTJWcywxnpdpCgr 5DTUrtvlL7orKxd46zBEiIKJElT2HQrd8CjKR1dAOBTI+4/dmtERBvoG9rLXaFMiFxATbq hHH4NdIHpAHBU9DnF29rFgUEkizWLII= X-MC-Unique: 1KwfmszJPhe3GGjv7gi-fQ-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [RFC PATCH] docs: backup: Convert XML documentation to RST Date: Thu, 25 Jun 2020 15:23:50 +0200 Message-Id: <791486e02dae1eb4efa84e23176bc6d01f09ef34.1593090840.git.pkrempa@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Switch to the new format for easier extension. Signed-off-by: Peter Krempa --- This was a surprisingly easy conversion done using: pandoc --from html --to rst --toc --columns 80 --standalone formatbackup.h= tml.in -o formatbackup.rst The file generated by pandoc required following manual tweaks: 1) table of contents command needed to be moved after the first heading 2) definition list entries were not separated by an empty line 3) XML examples had one extra line with spaces only (Faithfully ported from html) Here both versions can be compared: https://pipo.sk.gitlab.io/-/libvirt/-/jobs/611434730/artifacts/website/form= atbackup.html https://libvirt.org/formatbackup.html docs/formatbackup.html.in | 191 -------------------------------------- docs/formatbackup.rst | 149 +++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+), 191 deletions(-) delete mode 100644 docs/formatbackup.html.in create mode 100644 docs/formatbackup.rst diff --git a/docs/formatbackup.html.in b/docs/formatbackup.html.in deleted file mode 100644 index 9e69d8f7d3..0000000000 --- a/docs/formatbackup.html.in +++ /dev/null @@ -1,191 +0,0 @@ - - - - -

Backup XML format

- -
    - -

    Backup XML

    - -

    - Creating a backup, whether full or incremental, is done - via virDomainBackupBegin(), which takes an XML - description of the actions to perform, as well as an optional - second XML document describing a - checkpoint to create at the same point in time. See - also a comparison betw= een - the various state capture APIs. -

    -

    - There are two general modes for backups: a push mode (where the - hypervisor writes out the data to the destination file, which - may be local or remote), and a pull mode (where the hypervisor - creates an NBD server that a third-party client can then read as - needed, and which requires the use of temporary storage, - typically local, until the backup is complete). -

    -

    - The instructions for beginning a backup job are provided as - attributes and elements of the - top-level domainbackup element. This element - includes an optional attribute mode which can be - either "push" or "pull" (default - push). virDomainBackupGetXMLDesc() can be used to - see the actual values selected for elements omitted during - creation (for example, learning which port the NBD server is - using in the pull model or what file names libvirt generated - when none were supplied). The following child elements and attributes - are supported: -

    -
    -
    incremental
    -
    An optional element giving the name of an existing - checkpoint of the domain, which will be used to make this - backup an incremental one. In the push model, only changes - since the named checkpoint are written to the destination. In - the pull model, the NBD server uses the - NBD_OPT_SET_META_CONTEXT extension to advertise to the client - which portions of the export contain changes since the named - checkpoint. If omitted, a full backup is performed. -
    -
    server
    -
    Present only for a pull mode backup. Contains the same - attributes as - the protocol - element of a disk attached via NBD in the domain (such as - transport, socket, name, port, or tls), necessary to set up an - NBD server that exposes the content of each disk at the time - the backup is started. -
    -
    disks
    -
    An optional listing of instructions for disks participating - in the backup (if omitted, all disks participate and libvirt - attempts to generate filenames by appending the current - timestamp as a suffix). If the entire element was omitted on - input, then all disks participate in the backup, otherwise, - only the disks explicitly listed which do not also - use backup=3D'no' will participate. On output, this - is the state of each of the domain's disk in relation to the - backup operation. -
    -
    disk
    -
    This sub-element describes the backup properties of a - specific disk, with the following attributes and child - elements: -
    -
    name
    -
    A mandatory attribute which must match - the <target dev=3D'name'/> - of one of - the disk - devices specified for the domain at the time of - the checkpoint.
    -
    backup
    -
    Setting this attribute to yes(default) spec= ifies - that the disk should take part in the backup and using - no excludes the disk from the backup.
    -
    exportname
    -
    Allows modification of the NBD export name for the given= disk. - By default equal to disk target. - Valid only for pull mode backups.
    -
    exportbitmap
    -
    Allows modification of the name of the bitmap describing= dirty - blocks for an incremental backup exported via NBD export n= ame - for the given disk. - Valid only for pull mode backups.
    -
    type
    -
    A mandatory attribute to describe the type of the - disk, except when backup=3D'no' is - used. Valid values include file, or - block. - Similar to a disk declaration for a domain, the choice of = type - controls what additional sub-elements are needed to descri= be - the destination.
    -
    target
    -
    Valid only for push mode backups, this is the - primary sub-element that describes the file name of - the backup destination, similar to - the source sub-element of a domain - disk. An optional sub-element driver can - also be used, with an attribute type to - specify a destination format different from - qcow2. See documentation for scratch below for - additional configuration.
    -
    scratch
    -
    Valid only for pull mode backups, this is the - primary sub-element that describes the file name of - the local scratch file to be used in facilitating the - backup, and is similar to the source - sub-element of a domain disk. Currently only file - and block scratch storage is supported. The - file scratch file is created and deleted by - libvirt in the given location. A block scratch - device must exist prior to starting the backup and is form= atted. - The block device must have enough space for the correspond= ing - disk data including format overhead. - - If VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL fla= g is - used the file for a scratch of file type must - exist with the correct format and size to hold the copy an= d is - used without modification. The file is not deleted after t= he - backup but the contents of the file don't make sense outsi= de - of the backup. The same applies for the block device which - must be formatted appropriately. - - Similarly to the domain - disk - definition scratch and target can - contain seclabel and/or encryption - subelements to configure the corresponding properties. -
    -
    -
    -
    -
    -
    - -

    Examples

    - -

    Use virDomainBackupBegin() to perform a full - backup using push mode. The example lets libvirt pick the - destination and format for 'vda', fully specifies that we want a - raw backup of 'vdb', and omits 'vdc' from the operation. -

    -
    -<domainbackup>
    -  <disks>
    -    <disk name=3D'vda' backup=3D'yes'/>
    -    <disk name=3D'vdb' type=3D'file'>
    -      <target file=3D'/path/to/vdb.backup'/>
    -      <driver type=3D'raw'/>
    -    </disk>
    -    <disk name=3D'vdc' backup=3D'no'/>
    -  </disks>
    -</domainbackup>
    -    
    - -

    If the previous full backup also passed a parameter describing - checkpoint XML that resulted - in a checkpoint named 1525889631, we can make - another call to virDomainBackupBegin() to perform - an incremental backup of just the data changed since that - checkpoint, this time using the following XML to start a pull - model export of the 'vda' and 'vdb' disks, where a third-party - NBD client connecting to '/path/to/server' completes the backup - (omitting 'vdc' from the explicit list has the same effect as - the backup=3D'no' from the previous example): -

    -
    -<domainbackup mode=3D"pull">
    -  <incremental>1525889631</incremental>
    -  <server transport=3D"unix" socket=3D"/path/to/server"/>
    -  <disks>
    -    <disk name=3D'vda' backup=3D'yes' type=3D'file'>
    -      <scratch file=3D'/path/to/file1.scratch'/>
    -    </disk>
    -  </disks>
    -</domainbackup>
    -    
    - - diff --git a/docs/formatbackup.rst b/docs/formatbackup.rst new file mode 100644 index 0000000000..66583f562b --- /dev/null +++ b/docs/formatbackup.rst @@ -0,0 +1,149 @@ +Backup XML format +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. contents:: + +Backup XML +---------- + +Creating a backup, whether full or incremental, is done via +``virDomainBackupBegin()``, which takes an XML description of the actions = to +perform, as well as an optional second XML document `describing a +checkpoint `__ to create at the same point in time.= See +also `a comparison `__ between the various = state +capture APIs. + +There are two general modes for backups: a push mode (where the hypervisor +writes out the data to the destination file, which may be local or remote)= , and +a pull mode (where the hypervisor creates an NBD server that a third-party +client can then read as needed, and which requires the use of temporary st= orage, +typically local, until the backup is complete). + +The instructions for beginning a backup job are provided as attributes and +elements of the top-level ``domainbackup`` element. This element includes = an +optional attribute ``mode`` which can be either "push" or "pull" (default = push). +``virDomainBackupGetXMLDesc()`` can be used to see the actual values selec= ted +for elements omitted during creation (for example, learning which port the= NBD +server is using in the pull model or what file names libvirt generated whe= n none +were supplied). The following child elements and attributes are supported: + +``incremental`` + An optional element giving the name of an existing checkpoint of the do= main, + which will be used to make this backup an incremental one. In the push = model, + only changes since the named checkpoint are written to the destination.= In + the pull model, the NBD server uses the NBD_OPT_SET_META_CONTEXT extens= ion to + advertise to the client which portions of the export contain changes si= nce + the named checkpoint. If omitted, a full backup is performed. + +``server`` + Present only for a pull mode backup. Contains the same attributes as the + ```protocol`` element of a disk `__ at= tached + via NBD in the domain (such as transport, socket, name, port, or tls), + necessary to set up an NBD server that exposes the content of each disk= at + the time the backup is started. + +``disks`` + An optional listing of instructions for disks participating in the back= up (if + omitted, all disks participate and libvirt attempts to generate filenam= es by + appending the current timestamp as a suffix). If the entire element was + omitted on input, then all disks participate in the backup, otherwise, = only + the disks explicitly listed which do not also use ``backup=3D'no'`` will + participate. On output, this is the state of each of the domain's disk = in + relation to the backup operation. + + ``disk`` + This sub-element describes the backup properties of a specific disk,= with + the following attributes and child elements: + + ``name`` + A mandatory attribute which must match the ```` of + one of the `disk devices `__ spe= cified + for the domain at the time of the checkpoint. + + ``backup`` + Setting this attribute to ``yes``\ (default) specifies that the d= isk + should take part in the backup and using ``no`` excludes the disk= from + the backup. + + ``exportname`` + Allows modification of the NBD export name for the given disk. By + default equal to disk target. Valid only for pull mode backups. + + ``exportbitmap`` + Allows modification of the name of the bitmap describing dirty bl= ocks + for an incremental backup exported via NBD export name for the gi= ven + disk. Valid only for pull mode backups. + + ``type`` + A mandatory attribute to describe the type of the disk, except wh= en + ``backup=3D'no'`` is used. Valid values include ``file``, or ``bl= ock``. + Similar to a disk declaration for a domain, the choice of type co= ntrols + what additional sub-elements are needed to describe the destinati= on. + + ``target`` + Valid only for push mode backups, this is the primary sub-element= that + describes the file name of the backup destination, similar to the + ``source`` sub-element of a domain disk. An optional sub-element + ``driver`` can also be used, with an attribute ``type`` to specif= y a + destination format different from qcow2. See documentation for + ``scratch`` below for additional configuration. + + ``scratch`` + Valid only for pull mode backups, this is the primary sub-element= that + describes the file name of the local scratch file to be used in + facilitating the backup, and is similar to the ``source`` sub-ele= ment + of a domain disk. Currently only ``file`` and ``block`` scratch s= torage + is supported. The ``file`` scratch file is created and deleted by + libvirt in the given location. A ``block`` scratch device must ex= ist + prior to starting the backup and is formatted. The block device m= ust + have enough space for the corresponding disk data including format + overhead. If ``VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL`` flag is u= sed + the file for a scratch of ``file`` type must exist with the corre= ct + format and size to hold the copy and is used without modification= . The + file is not deleted after the backup but the contents of the file= don't + make sense outside of the backup. The same applies for the block = device + which must be formatted appropriately. Similarly to the domain + ```disk`` `__ definition ``scrat= ch`` + and ``target`` can contain ``seclabel`` and/or ``encryption`` + subelements to configure the corresponding properties. + +Examples +-------- + +Use ``virDomainBackupBegin()`` to perform a full backup using push mode. T= he +example lets libvirt pick the destination and format for 'vda', fully spec= ifies +that we want a raw backup of 'vdb', and omits 'vdc' from the operation. + +:: + + + + + + + + + + + + +If the previous full backup also passed a parameter describing `checkpoint +XML `__ that resulted in a checkpoint named +``1525889631``, we can make another call to ``virDomainBackupBegin()`` to +perform an incremental backup of just the data changed since that checkpoi= nt, +this time using the following XML to start a pull model export of the 'vda= ' and +'vdb' disks, where a third-party NBD client connecting to '/path/to/server' +completes the backup (omitting 'vdc' from the explicit list has the same e= ffect +as the backup=3D'no' from the previous example): + +:: + + + 1525889631 + + + + + + + --=20 2.26.2