From nobody Mon Feb 9 12:11:34 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.61 as permitted sender) client-ip=205.139.110.61; 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 205.139.110.61 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=1593701201; cv=none; d=zohomail.com; s=zohoarc; b=b6esYhhXyEckbbMHluNWJvhDoIvfSNFVdmZZhC045Pv04nX7IySQGXL/S7ZEcc9VEpl/pTnQs+iHV8MMFypeGjaq/c271YZj9v5+fh20NVHdiXmVASV+9Yll9wx8472nEaRod4ETwHA4iZoTPKNHw2V7mqzzsANSTGBBU1P9tts= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1593701201; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=OIicMJN1lNQ0tFuXeouJ5ea86neB4F4wfbCPnKfK5Kk=; b=lSPsBcLGVMZFoyA1YEvjF4QPpalDNkwYmf+Q1gM735Nhlq8J6LDCdTLUQY4t3OTM/Jkoj+ptDBXCzcGBVgapdnKxTbDb5RTUsqHe9+DpyFwssjezdRCwnxGiiLw7GxmjcLpJm5W13zs4cJdvGyhjdFkKV0YZFDz0BY42rp5iw24= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.61 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-2.mimecast.com [205.139.110.61]) by mx.zohomail.com with SMTPS id 159370120112141.45366816524643; Thu, 2 Jul 2020 07:46:41 -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-368-DA9zvBXDNfuCq_q0ydr5Xg-1; Thu, 02 Jul 2020 10:46:35 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 848E48014D7; Thu, 2 Jul 2020 14:46:29 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6362210190A7; Thu, 2 Jul 2020 14:46:29 +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 34D236C9CE; Thu, 2 Jul 2020 14:46:29 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 062EeSLB011799 for ; Thu, 2 Jul 2020 10:40:28 -0400 Received: by smtp.corp.redhat.com (Postfix) id 58DFD1002397; Thu, 2 Jul 2020 14:40:28 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.18]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9588410013D2 for ; Thu, 2 Jul 2020 14:40:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1593701199; 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: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=OIicMJN1lNQ0tFuXeouJ5ea86neB4F4wfbCPnKfK5Kk=; b=aSsT+Gsz4McFtSHsDqpWi1go/yhluWpf5FTr9nYPXjv6NBciD4/CPuJZXBA6QSO9EQE+3A hz4gkRTiqi0Li7/tmi9656fNxYiwklhSL4QWzuXPWrLzf2PFBV+JwlC/99o1Olb0WGjjka ZW/DRsBshdDjNUjzLyrhKg9stge6+lU= X-MC-Unique: DA9zvBXDNfuCq_q0ydr5Xg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 13/24] docs: backup: Convert XML documentation to RST Date: Thu, 2 Jul 2020 16:39:59 +0200 Message-Id: <2d37c1c7a5c521cc678d710099181dba6268a3f8.1593700474.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 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.84 on 10.5.11.22 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com 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 Reviewed-by: Eric Blake --- 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