[PATCH 00/17] docs: Convert some pages to rST and clean up (part 1)
Peter Krempa (17): docs: Remove 'virshcmdref' page docs: Drop 'devguide' page docs: formatsnapshot: Convert to 'rst' docs: Convert 'goals' to rST docs: Convert 'strategy' to rST docs: Convert 'contribute' page to rST docs: Convert 'bugs' page to rST docs: Convert 'errors' page to rST docs: Convert 'support' page to rST docs: Convert 'securityprocess' page to rST docs: securityprocess: Don't claim that we have maint branches docs: Convert 'governance' page to rST docs: page.xsl: Update anchor to the 'Code of conduct' paragraph docs: Convert 'drivers' page to rST docs: Convert 'formatsecret' page to rST docs: formatsecret: Drop few unneeded empty lines docs: meson: Restore alphabetical order docs/bugs.html.in | 161 ----------- docs/bugs.rst | 125 ++++++++ docs/contribute.html.in | 143 --------- docs/contribute.rst | 105 +++++++ docs/devguide.html.in | 42 --- docs/drivers.html.in | 44 --- docs/drivers.rst | 31 ++ docs/errors.html.in | 84 ------ docs/errors.rst | 109 +++++++ docs/formatsecret.html.in | 414 --------------------------- docs/formatsecret.rst | 332 +++++++++++++++++++++ docs/formatsnapshot.html.in | 352 ----------------------- docs/formatsnapshot.rst | 297 +++++++++++++++++++ docs/formatstorageencryption.html.in | 2 +- docs/goals.html.in | 64 ----- docs/goals.rst | 56 ++++ docs/governance.html.in | 298 ------------------- docs/governance.rst | 232 +++++++++++++++ docs/meson.build | 32 +-- docs/page.xsl | 2 +- docs/securityprocess.html.in | 119 -------- docs/securityprocess.rst | 91 ++++++ docs/strategy.html.in | 133 --------- docs/strategy.rst | 105 +++++++ docs/support.html.in | 258 ----------------- docs/support.rst | 207 ++++++++++++++ docs/virshcmdref.html.in | 75 ----- 27 files changed, 1707 insertions(+), 2206 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst delete mode 100644 docs/contribute.html.in create mode 100644 docs/contribute.rst delete mode 100644 docs/devguide.html.in delete mode 100644 docs/drivers.html.in create mode 100644 docs/drivers.rst delete mode 100644 docs/errors.html.in create mode 100644 docs/errors.rst delete mode 100644 docs/formatsecret.html.in create mode 100644 docs/formatsecret.rst delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst delete mode 100644 docs/goals.html.in create mode 100644 docs/goals.rst delete mode 100644 docs/governance.html.in create mode 100644 docs/governance.rst delete mode 100644 docs/securityprocess.html.in create mode 100644 docs/securityprocess.rst delete mode 100644 docs/strategy.html.in create mode 100644 docs/strategy.rst delete mode 100644 docs/support.html.in create mode 100644 docs/support.rst delete mode 100644 docs/virshcmdref.html.in -- 2.35.1
The page isn't linked from anywhere and the project was archived. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 1 - docs/virshcmdref.html.in | 75 ---------------------------------------- 2 files changed, 76 deletions(-) delete mode 100644 docs/virshcmdref.html.in diff --git a/docs/meson.build b/docs/meson.build index 7e070d68ad..e348e64b8e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -76,7 +76,6 @@ docs_html_in_files = [ 'testtck', 'tlscerts', 'uri', - 'virshcmdref', 'windows', ] diff --git a/docs/virshcmdref.html.in b/docs/virshcmdref.html.in deleted file mode 100644 index f5993fabce..0000000000 --- a/docs/virshcmdref.html.in +++ /dev/null @@ -1,75 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Virsh Command Reference</h1> - - <ul id="toc"></ul> - - <h2><a id="description">Description</a></h2> - - <p> - The new <b>Virsh Command Reference</b>, for documenting the commands - in virsh, has recently been started. Only covering the Virtual - Networking commands initially, it will expand to cover all virsh - commands over time. - </p> - - <p> - If you would like to assist, content contributions are gladly accepted. - Please email <a href="mailto:jclift@redhat.com">Justin Clift</a> - directly, or get in contact through any of the - <a href="contact.html">official libvirt mailing lists</a>. - </p> - - <h2><a id="viewing">Viewing Online</a></h2> - - <p> - The latest version can be viewed directly online: - </p> - - <ul> - <li> - <a href="https://libvirt.org/sources/virshcmdref/html/">Standard HTML format, multiple pages</a> - </li> - <li> - <a href="https://libvirt.org/sources/virshcmdref/html-single/">HTML format, one long page</a> - </li> - </ul> - - <h2><a id="downloading">Downloading</a></h2> - - <p> - The latest version of the Virsh Command Reference can be downloaded: - </p> - - <ul> - <li> - Standard HTML format, multiple pages - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.tar.gz">.tar.gz</a>) - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.tar.bz2">.tar.bz2</a>) - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-multi-page.zip">.zip</a>) - </li> - <li> - HTML format, one long page - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.tar.gz">.tar.gz</a>) - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.tar.bz2">.tar.bz2</a>) - (<a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1-html-single.zip">.zip</a>) - </li> - <li> - <a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1.pdf">PDF format</a> - </li> - <li> - <a href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Reference-0.8.7-1.epub">ePub format</a> - </li> - </ul> - - <h2><a id="git">DocBook source GIT repository</a></h2> - <p> - The DocBook source is archived in a <a - href="https://git-scm.com/">git</a> repository available on - <a href="https://gitlab.com/libvirt/libvirt-virshcmdref">gitlab.com</a>. - </p> - - </body> -</html> -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
The page isn't linked from anywhere and the project was archived.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 1 - docs/virshcmdref.html.in | 75 ---------------------------------------- 2 files changed, 76 deletions(-) delete mode 100644 docs/virshcmdref.html.in
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
The page is not referenced from anywhere and contains dead links for the output and links to old repos. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/devguide.html.in | 42 ------------------------------------------ docs/meson.build | 1 - 2 files changed, 43 deletions(-) delete mode 100644 docs/devguide.html.in diff --git a/docs/devguide.html.in b/docs/devguide.html.in deleted file mode 100644 index 2668e6f29e..0000000000 --- a/docs/devguide.html.in +++ /dev/null @@ -1,42 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>libvirt Application Development Guides</h1> - - <p> - The libvirt API is accessible from a number of programming languages. - At this time, there are application development guides available - which cover the C API and the Python API. Of the two, the Python guide - is currently the more comprehensive document. - </p> - - <ul> - <li><a href="https://libvirt.org/docs/libvirt-appdev-guide/en-US/html/">Application Development Guide (C language) HTML</a></li> - <li><a href="https://libvirt.org/docs/libvirt-appdev-guide/en-US/pdf/">Application Development Guide (C language) PDF</a></li> - <li><a href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/html/">Application Development Guide (Python language) HTML</a></li> - <li><a href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/pdf/">Application Development Guide (Python language) PDF</a></li> - </ul> - - <h2>Contributing content</h2> - - <p> - These guides are written in DocBook and published with the - publican tool, which is also used for Fedora and Red Hat - documentation. The original content is provided in GIT and - any contributions to the guide are welcome. - </p> - - <pre> -# C language -$ git clone <a href="https://libvirt.org/git/?p=libvirt-appdev-guide.git">https://libvirt.org/git/libvirt-appdev-guide.git</a> - -# Python language -$ git clone <a href="https://libvirt.org/git/?p=libvirt-appdev-guide-python.git">https://libvirt.org/git/libvirt-appdev-guide-python.git</a> - -# Publican Style/Theme -$ git clone <a href="https://libvirt.org/git/?p=libvirt-publican.git">https://libvirt.org/git/libvirt-publican.git</a> - </pre> - - </body> -</html> diff --git a/docs/meson.build b/docs/meson.build index e348e64b8e..3caaa76735 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files = [ 'contribute', 'csharp', 'dbus', - 'devguide', 'docs', 'downloads', 'drivers', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
The page is not referenced from anywhere and contains dead links for the output and links to old repos.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/devguide.html.in | 42 ------------------------------------------ docs/meson.build | 1 - 2 files changed, 43 deletions(-) delete mode 100644 docs/devguide.html.in
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.html.in | 352 ------------------------------------ docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 298 insertions(+), 353 deletions(-) delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in deleted file mode 100644 index e481284aa8..0000000000 --- a/docs/formatsnapshot.html.in +++ /dev/null @@ -1,352 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Snapshot XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="SnapshotAttributes">Snapshot XML</a></h2> - - <p> - Snapshots are one form - of <a href="kbase/domainstatecapture.html">domain state - capture</a>. There are several types of snapshots: - </p> - <dl> - <dt>disk snapshot</dt> - <dd>Contents of disks (whether a subset or all disks associated - with the domain) are saved at a given point of time, and can - be restored back to that state. On a running guest, a disk - snapshot is likely to be only crash-consistent rather than - clean (that is, it represents the state of the disk on a - sudden power outage, and may need fsck or journal replays to - be made consistent); on an inactive guest, a disk snapshot is - clean if the disks were clean when the guest was last shut - down. Disk snapshots exist in two forms: internal (file - formats such as qcow2 track both the snapshot and changes - since the snapshot in a single file) and external (the - snapshot is one file, and the changes since the snapshot are - in another file).</dd> - <dt>memory state (or VM state)</dt> - <dd>Tracks only the state of RAM and all other resources in use - by the VM. If the disks are unmodified between the time a VM - state snapshot is taken and restored, then the guest will - resume in a consistent state; but if the disks are modified - externally in the meantime, this is likely to lead to data - corruption.</dd> - <dt>full system</dt> - <dd>A combination of disk snapshots for all disks as well as VM - memory state, which can be used to resume the guest from where it - left off with symptoms similar to hibernation (that is, TCP - connections in the guest may have timed out, but no files or - processes are lost).</dd> - </dl> - - <p> - Libvirt can manage all three types of snapshots. For now, VM - state (memory) snapshots are created only by - the <code>virDomainSave()</code>, <code>virDomainSaveFlags</code>, - and <code>virDomainManagedSave()</code> functions, and restored - via the <code>virDomainRestore()</code>, - <code>virDomainRestoreFlags()</code>, <code>virDomainCreate()</code>, - and <code>virDomainCreateWithFlags()</code> functions (as well - as via domain autostart). With managed snapshots, libvirt - tracks all information internally; with save images, the user - tracks the snapshot file, but libvirt provides functions such - as <code>virDomainSaveImageGetXMLDesc()</code> to work with - those files. - </p> - <p>Full system snapshots are created - by <code>virDomainSnapshotCreateXML()</code> with no flags, while - disk snapshots are created by the same function with - the <code>VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY</code> - flag. Regardless of the flags provided, restoration of the - snapshot is handled by - the <code>virDomainRevertToSnapshot()</code> function. For - these types of snapshots, libvirt tracks each snapshot as a - separate <code>virDomainSnapshotPtr</code> object, and maintains - a tree relationship of which snapshots descended from an earlier - point in time. - </p> - - <p> - Attributes of libvirt snapshots are stored as child elements of - the <code>domainsnapshot</code> element. At snapshot creation - time, normally only the <code>name</code>, <code>description</code>, - and <code>disks</code> elements are settable; the rest of the - fields are ignored on creation, and will be filled in by - libvirt in for informational purposes - by <code>virDomainSnapshotGetXMLDesc()</code>. However, when - redefining a snapshot (<span class="since">since 0.9.5</span>), - with the <code>VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE</code> flag - of <code>virDomainSnapshotCreateXML()</code>, all of the XML - described here is relevant on input, even the fields that are - normally described as readonly for output. - </p> - <p> - Snapshots are maintained in a hierarchy. A domain can have a - current snapshot, which is the most recent snapshot compared to - the current state of the domain (although a domain might have - snapshots without a current snapshot, if snapshots have been - deleted in the meantime). Creating or reverting to a snapshot - sets that snapshot as current, and the prior current snapshot is - the parent of the new snapshot. Branches in the hierarchy can - be formed by reverting to a snapshot with a child, then creating - another snapshot. For now, the creation of external snapshots - when checkpoints exist is forbidden, although future work will - make it possible to integrate these two concepts. - </p> - <p> - The top-level <code>domainsnapshot</code> element may contain - the following elements: - </p> - <dl> - <dt><code>name</code></dt> - <dd>The optional name for this snapshot. If the name is - omitted, libvirt will create a name based on the time of the - creation. - </dd> - <dt><code>description</code></dt> - <dd>An optional human-readable description of the snapshot. If - the description is omitted when initially creating the - snapshot, then this field will be empty. - </dd> - <dt><code>memory</code></dt> - <dd>On input, this is an optional request for how to handle VM - memory state. For an offline domain or a disk-only snapshot, - attribute <code>snapshot</code> must be <code>no</code>, since - there is no VM state saved; otherwise, the attribute can - be <code>internal</code> if the memory state is piggy-backed with - other internal disk state, or <code>external</code> along with - a second attribute <code>file</code> giving the absolute path - of the file holding the VM memory state. <span class="since">Since - 1.0.1</span> - </dd> - <dt><code>disks</code></dt> - <dd>On input, this is an optional listing of specific - instructions for disk snapshots; it is needed when making a - snapshot of only a subset of the disks associated with a - domain, or when overriding the domain defaults for how to - snapshot each disk, or for providing specific control over - what file name is created in an external snapshot. On output, - this is fully populated to show the state of each disk in the - snapshot, including any properties that were generated by the - hypervisor defaults. For full system snapshots, this field is - ignored on input and omitted on output (a full system snapshot - implies that all disks participate in the snapshot process). - This element has a list of <code>disk</code> - sub-elements, describing anywhere from zero to all of the - disks associated with the domain. <span class="since">Since - 0.9.5</span> - <dl> - <dt><code>disk</code></dt> - <dd>This sub-element describes the snapshot properties of a - specific disk. The attribute <code>name</code> is - mandatory, and must match either the <code><target - dev='name'/></code> (recommended) or an unambiguous - <code><source file='name'/></code> of one of - the <a href="formatdomain.html#elementsDisks">disk - devices</a> specified for the domain at the time of the - snapshot. The attribute <code>snapshot</code> is - optional, and the possible values are the same as the - <code>snapshot</code> attribute for - <a href="formatdomain.html#elementsDisks">disk devices</a> - (<code>no</code>, <code>internal</code>, - or <code>external</code>). Some hypervisors like ESX - require that if specified, the snapshot mode must not - override any snapshot mode attached to the corresponding - domain disk, while others like qemu allow this field to - override the domain default. - - <dl> - <dt><code>source</code></dt> - <dd>If the snapshot mode is external (whether specified - or inherited), then there is an optional sub-element - <code>source</code>, with an attribute <code>file</code> - giving the name of the new file. - If <code>source</code> is not - given and the disk is backed by a local image file (not - a block device or remote storage), a file name is - generated that consists of the existing file name - with anything after the trailing dot replaced by the - snapshot name. Remember that with external - snapshots, the original file name becomes the read-only - snapshot, and the new file name contains the read-write - delta of all disk changes since the snapshot. - <p/> - The <code>source</code> element also may contain the - <code>seclabel</code> element (described in the - <a href="formatdomain.html#seclabel">domain XML documentation</a>) - which can be used to override the domain security labeling policy - for <code>source</code>. - </dd> - <dt><code>driver</code></dt> - <dd>An optional sub-element <code>driver</code>, - with an attribute <code>type</code> giving the driver type (such - as qcow2), of the new file created by the external - snapshot of the new file. - - Optionally <code>metadata_cache</code> sub-element can be used - with same semantics as the identically named subelement of the - domain definition disk's driver. - </dd> - <dt><code>seclabel</code></dt> - </dl> - - <span class="since">Since 1.2.2</span> the <code>disk</code> element - supports an optional attribute <code>type</code> if the - <code>snapshot</code> attribute is set to <code>external</code>. - This attribute specifies the snapshot target storage type and allows - to overwrite the default <code>file</code> type. The <code>type</code> - attribute along with the format of the <code>source</code> - sub-element is identical to the <code>source</code> element used in - domain disk definitions. See the - <a href="formatdomain.html#elementsDisks">disk devices</a> section - documentation for further information. - - Libvirt currently supports the <code>type</code> element in the qemu - driver and supported values are <code>file</code>, <code>block</code> - and <code>network</code> with a protocol of <code>gluster</code> - <span class="since">(since 1.2.2)</span>. - </dd> - </dl> - </dd> - <dt><code>creationTime</code></dt> - <dd>A readonly representation of the time this snapshot was - created. The time is specified in seconds since the Epoch, - UTC (i.e. Unix time). - </dd> - <dt><code>state</code></dt> - <dd>A readonly representation of the state of the domain at the - time this snapshot was taken. If a full system snapshot was - created, then this is the state of the domain at that - time. When the domain is reverted to this snapshot, the - domain's state will default to this state, unless overridden - by <code>virDomainRevertToSnapshot()</code> flags to revert to - a running or paused state. Additionally, this field can be the - value "disk-snapshot" (<span class="since">since 0.9.5</span>) - when it represents only a disk snapshot (no VM memory state), - and reverting to this snapshot will default to an inactive - guest. - </dd> - <dt><code>parent</code></dt> - <dd>Readonly, present only if this snapshot has a parent. The - parent name is given by the sub-element <code>name</code>. The - parent relationship allows tracking a tree of related snapshots. - </dd> - <dt><code>domain</code></dt> - <dd>A readonly representation of the domain that this snapshot - was taken against. Older versions of libvirt stored only a - single child element, uuid; reverting to a snapshot like this - is risky if the current state of the domain differs from the - state that the domain was created in, and requires the use of - the <code>VIR_DOMAIN_SNAPSHOT_REVERT_FORCE</code> flag - in <code>virDomainRevertToSnapshot()</code>. Newer versions - of libvirt (<span class="since">since 0.9.5</span>) store the - entire inactive <a href="formatdomain.html">domain - configuration</a> at the time of the snapshot - (<span class="since">since 0.9.5</span>). The domain will have - security-sensitive information omitted - unless the flag <code>VIR_DOMAIN_SNAPSHOT_XML_SECURE</code> is - provided on a read-write connection. - </dd> - <dt><code>cookie</code></dt> - <dd>An optional readonly representation of a save image cookie - containing additional data libvirt may need to properly - restore a domain from an active snapshot when such data cannot - be stored directly in the <code>domain</code> to maintain - compatibility with older libvirt or hypervisor. - </dd> - </dl> - - <h2><a id="example">Examples</a></h2> - - <p>Using this XML to create a disk snapshot of just vda on a qemu - domain with two disks:</p> - <pre> -<domainsnapshot> - <description>Snapshot of OS install and updates</description> - <disks> - <disk name='vda'> - <source file='/path/to/new'/> - </disk> - <disk name='vdb' snapshot='no'/> - <disk name='vdc'> - <source file='/path/to/newc'> - <seclabel model='dac' relabel='no'/> - </source> - </disk> - </disks> -</domainsnapshot></pre> - - <p>will result in XML similar to this from - <code>virDomainSnapshotGetXMLDesc()</code>:</p> - <pre> -<domainsnapshot> - <name>1270477159</name> - <description>Snapshot of OS install and updates</description> - <state>running</state> - <creationTime>1270477159</creationTime> - <parent> - <name>bare-os-install</name> - </parent> - <memory snapshot='no'/> - <disks> - <disk name='vda' snapshot='external'> - <driver type='qcow2'/> - <b><source file='/path/to/new'/></b> - </disk> - <disk name='vdb' snapshot='no'/> - </disks> - <domain> - <name>fedora</name> - <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid> - <memory>1048576</memory> - ... - <devices> - <disk type='file' device='disk'> - <driver name='qemu' type='raw'/> - <b><source file='/path/to/old'/></b> - <target dev='vda' bus='virtio'/> - </disk> - <disk type='file' device='disk' snapshot='external'> - <driver name='qemu' type='raw'/> - <source file='/path/to/old2'/> - <target dev='vdb' bus='virtio'/> - </disk> - ... - </devices> - </domain> -</domainsnapshot></pre> - - <p>With that snapshot created, <code>/path/to/old</code> is the - read-only backing file to the new active - file <code>/path/to/new</code>. The <code><domain></code> - element within the snapshot xml records the state of the domain - just before the snapshot; a call - to <code>virDomainGetXMLDesc()</code> will show that the domain - has been changed to reflect the snapshot: - </p> - <pre> -<domain> - <name>fedora</name> - <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid> - <memory>1048576</memory> - ... - <devices> - <disk type='file' device='disk'> - <driver name='qemu' type='qcow2'/> - <b><source file='/path/to/new'/></b> - <target dev='vda' bus='virtio'/> - </disk> - <disk type='file' device='disk' snapshot='external'> - <driver name='qemu' type='raw'/> - <source file='/path/to/old2'/> - <target dev='vdb' bus='virtio'/> - </disk> - ... - </devices> -</domain></pre> - </body> -</html> diff --git a/docs/formatsnapshot.rst b/docs/formatsnapshot.rst new file mode 100644 index 0000000000..0ad397316c --- /dev/null +++ b/docs/formatsnapshot.rst @@ -0,0 +1,297 @@ +.. role:: since + +=================== +Snapshot XML format +=================== + +.. contents:: + +Snapshot XML +------------ + +Snapshots are one form of `domain state +capture <kbase/domainstatecapture.html>`__. There are several types of +snapshots: + +disk snapshot + Contents of disks (whether a subset or all disks associated with the domain) + are saved at a given point of time, and can be restored back to that state. + On a running guest, a disk snapshot is likely to be only crash-consistent + rather than clean (that is, it represents the state of the disk on a sudden + power outage, and may need fsck or journal replays to be made consistent); on + an inactive guest, a disk snapshot is clean if the disks were clean when the + guest was last shut down. Disk snapshots exist in two forms: internal (file + formats such as qcow2 track both the snapshot and changes since the snapshot + in a single file) and external (the snapshot is one file, and the changes + since the snapshot are in another file). +memory state (or VM state) + Tracks only the state of RAM and all other resources in use by the VM. If the + disks are unmodified between the time a VM state snapshot is taken and + restored, then the guest will resume in a consistent state; but if the disks + are modified externally in the meantime, this is likely to lead to data + corruption. +full system + A combination of disk snapshots for all disks as well as VM memory state, + which can be used to resume the guest from where it left off with symptoms + similar to hibernation (that is, TCP connections in the guest may have timed + out, but no files or processes are lost). + +Libvirt can manage all three types of snapshots. For now, VM state (memory) +snapshots are created only by the ``virDomainSave()``, ``virDomainSaveFlags``, +and ``virDomainManagedSave()`` functions, and restored via the +``virDomainRestore()``, ``virDomainRestoreFlags()``, ``virDomainCreate()``, and +``virDomainCreateWithFlags()`` functions (as well as via domain autostart). With +managed snapshots, libvirt tracks all information internally; with save images, +the user tracks the snapshot file, but libvirt provides functions such as +``virDomainSaveImageGetXMLDesc()`` to work with those files. + +Full system snapshots are created by ``virDomainSnapshotCreateXML()`` with no +flags, while disk snapshots are created by the same function with the +``VIR_DOMAIN_SNAPSHOT_CREATE_DISK_ONLY`` flag. Regardless of the flags provided, +restoration of the snapshot is handled by the ``virDomainRevertToSnapshot()`` +function. For these types of snapshots, libvirt tracks each snapshot as a +separate ``virDomainSnapshotPtr`` object, and maintains a tree relationship of +which snapshots descended from an earlier point in time. + +Attributes of libvirt snapshots are stored as child elements of the +``domainsnapshot`` element. At snapshot creation time, normally only the +``name``, ``description``, and ``disks`` elements are settable; the rest of the +fields are ignored on creation, and will be filled in by libvirt in for +informational purposes by ``virDomainSnapshotGetXMLDesc()``. However, when +redefining a snapshot ( :since:`since 0.9.5` ), with the +``VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE`` flag of +``virDomainSnapshotCreateXML()``, all of the XML described here is relevant on +input, even the fields that are normally described as readonly for output. + +Snapshots are maintained in a hierarchy. A domain can have a current snapshot, +which is the most recent snapshot compared to the current state of the domain +(although a domain might have snapshots without a current snapshot, if snapshots +have been deleted in the meantime). Creating or reverting to a snapshot sets +that snapshot as current, and the prior current snapshot is the parent of the +new snapshot. Branches in the hierarchy can be formed by reverting to a snapshot +with a child, then creating another snapshot. For now, the creation of external +snapshots when checkpoints exist is forbidden, although future work will make it +possible to integrate these two concepts. + +The top-level ``domainsnapshot`` element may contain the following elements: + +``name`` + + The optional name for this snapshot. If the name is omitted, libvirt will + create a name based on the time of the creation. + +``description`` + + An optional human-readable description of the snapshot. If the description + is omitted when initially creating the snapshot, then this field will be + empty. + +``memory`` + + On input, this is an optional request for how to handle VM memory state. For + an offline domain or a disk-only snapshot, attribute ``snapshot`` must be + ``no``, since there is no VM state saved; otherwise, the attribute can be + ``internal`` if the memory state is piggy-backed with other internal disk + state, or ``external`` along with a second attribute ``file`` giving the + absolute path of the file holding the VM memory state. :since:`Since 1.0.1` + +``disks`` + + On input, this is an optional listing of specific instructions for disk + snapshots; it is needed when making a snapshot of only a subset of the disks + associated with a domain, or when overriding the domain defaults for how to + snapshot each disk, or for providing specific control over what file name is + created in an external snapshot. On output, this is fully populated to show + the state of each disk in the snapshot, including any properties that were + generated by the hypervisor defaults. For full system snapshots, this field + is ignored on input and omitted on output (a full system snapshot implies + that all disks participate in the snapshot process). This element has a list + of ``disk`` sub-elements, describing anywhere from zero to all of the disks + associated with the domain. :since:`Since 0.9.5` + + ``disk`` + + This sub-element describes the snapshot properties of a specific disk. + The attribute ``name`` is mandatory, and must match either the ``<target + dev='name'/>`` (recommended) or an unambiguous ``<source file='name'/>`` + of one of the `disk devices <formatdomain.html#elementsDisks>`__ + specified for the domain at the time of the snapshot. The attribute + ``snapshot`` is optional, and the possible values are the same as the + ``snapshot`` attribute for `disk devices + <formatdomain.html#elementsDisks>`__ (``no``, ``internal``, or + ``external``). Some hypervisors like ESX require that if specified, the + snapshot mode must not override any snapshot mode attached to the + corresponding domain disk, while others like qemu allow this field to + override the domain default. + + ``source`` + + If the snapshot mode is external (whether specified or inherited), + then there is an optional sub-element ``source``, with an attribute + ``file`` giving the name of the new file. If ``source`` is not given + and the disk is backed by a local image file (not a block device or + remote storage), a file name is generated that consists of the + existing file name with anything after the trailing dot replaced by + the snapshot name. Remember that with external snapshots, the original + file name becomes the read-only snapshot, and the new file name + contains the read-write delta of all disk changes since the snapshot. + + The ``source`` element also may contain the ``seclabel`` element + (described in the `domain XML documentation + <formatdomain.html#seclabel>`__) which can be used to override the + domain security labeling policy for ``source``. + + ``driver`` + + An optional sub-element ``driver``, with an attribute ``type`` giving + the driver type (such as qcow2), of the new file created by the + external snapshot of the new file. Optionally ``metadata_cache`` + sub-element can be used with same semantics as the identically named + subelement of the domain definition disk's driver. + + ``seclabel`` + + :since:`Since 1.2.2` the ``disk`` element supports an optional attribute + ``type`` if the ``snapshot`` attribute is set to ``external``. This + attribute specifies the snapshot target storage type and allows to + overwrite the default ``file`` type. The ``type`` attribute along with + the format of the ``source`` sub-element is identical to the ``source`` + element used in domain disk definitions. See the `disk devices + <formatdomain.html#elementsDisks>`__ section documentation for further + information. Libvirt currently supports the ``type`` element in the qemu + driver and supported values are ``file``, ``block`` and ``network`` with + a protocol of ``gluster`` :since:`(since 1.2.2)` . + +``creationTime`` + + A readonly representation of the time this snapshot was created. The time is + specified in seconds since the Epoch, UTC (i.e. Unix time). + +``state`` + + A readonly representation of the state of the domain at the time this + snapshot was taken. If a full system snapshot was created, then this is the + state of the domain at that time. When the domain is reverted to this + snapshot, the domain's state will default to this state, unless overridden + by ``virDomainRevertToSnapshot()`` flags to revert to a running or paused + state. Additionally, this field can be the value "disk-snapshot" ( + :since:`since 0.9.5`) when it represents only a disk snapshot (no VM memory + state), and reverting to this snapshot will default to an inactive guest. + +``parent`` + + Readonly, present only if this snapshot has a parent. The parent name is + given by the sub-element ``name``. The parent relationship allows tracking a + tree of related snapshots. + +``domain`` + + A readonly representation of the domain that this snapshot was taken + against. Older versions of libvirt stored only a single child element, + uuid; reverting to a snapshot like this is risky if the current state of the + domain differs from the state that the domain was created in, and requires + the use of the ``VIR_DOMAIN_SNAPSHOT_REVERT_FORCE`` flag in + ``virDomainRevertToSnapshot()``. Newer versions of libvirt ( :since:`since + 0.9.5` ) store the entire inactive `domain configuration + <formatdomain.html>`__ at the time of the snapshot ( :since:`since 0.9.5` ). + The domain will have security-sensitive information omitted unless the flag + ``VIR_DOMAIN_SNAPSHOT_XML_SECURE`` is provided on a read-write connection. + +``cookie`` + + An optional readonly representation of a save image cookie containing + additional data libvirt may need to properly restore a domain from an active + snapshot when such data cannot be stored directly in the ``domain`` to + maintain compatibility with older libvirt or hypervisor. + +Examples +-------- + +Using this XML to create a disk snapshot of just vda on a qemu domain with two +disks: + +:: + + <domainsnapshot> + <description>Snapshot of OS install and updates</description> + <disks> + <disk name='vda'> + <source file='/path/to/new'/> + </disk> + <disk name='vdb' snapshot='no'/> + <disk name='vdc'> + <source file='/path/to/newc'> + <seclabel model='dac' relabel='no'/> + </source> + </disk> + </disks> + </domainsnapshot> + +will result in XML similar to this from ``virDomainSnapshotGetXMLDesc()``: + +:: + + <domainsnapshot> + <name>1270477159</name> + <description>Snapshot of OS install and updates</description> + <state>running</state> + <creationTime>1270477159</creationTime> + <parent> + <name>bare-os-install</name> + </parent> + <memory snapshot='no'/> + <disks> + <disk name='vda' snapshot='external'> + <driver type='qcow2'/> + <source file='/path/to/new'/> + </disk> + <disk name='vdb' snapshot='no'/> + </disks> + <domain> + <name>fedora</name> + <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid> + <memory>1048576</memory> + ... + <devices> + <disk type='file' device='disk'> + <driver name='qemu' type='raw'/> + <source file='/path/to/old'/> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='file' device='disk' snapshot='external'> + <driver name='qemu' type='raw'/> + <source file='/path/to/old2'/> + <target dev='vdb' bus='virtio'/> + </disk> + ... + </devices> + </domain> + </domainsnapshot> + +With that snapshot created, ``/path/to/old`` is the read-only backing file to +the new active file ``/path/to/new``. The ``<domain>`` element within the +snapshot xml records the state of the domain just before the snapshot; a call to +``virDomainGetXMLDesc()`` will show that the domain has been changed to reflect +the snapshot: + +:: + + <domain> + <name>fedora</name> + <uuid>93a5c045-6457-2c09-e56c-927cdf34e178</uuid> + <memory>1048576</memory> + ... + <devices> + <disk type='file' device='disk'> + <driver name='qemu' type='qcow2'/> + <source file='/path/to/new'/> + <target dev='vda' bus='virtio'/> + </disk> + <disk type='file' device='disk' snapshot='external'> + <driver name='qemu' type='raw'/> + <source file='/path/to/old2'/> + <target dev='vdb' bus='virtio'/> + </disk> + ... + </devices> + </domain> diff --git a/docs/meson.build b/docs/meson.build index 3caaa76735..adb7ac091e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -51,7 +51,6 @@ docs_html_in_files = [ 'formatnode', 'formatnwfilter', 'formatsecret', - 'formatsnapshot', 'formatstoragecaps', 'formatstorageencryption', 'goals', @@ -99,6 +98,7 @@ docs_rst_files = [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatsnapshot', 'formatstorage', 'glib-adoption', 'hacking', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.html.in | 352 ------------------------------------ docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 298 insertions(+), 353 deletions(-) delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst
diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in deleted file mode 100644 index e481284aa8..0000000000 --- a/docs/formatsnapshot.html.in +++ /dev/null @@ -1,352 +0,0 @@ - <dl> - <dt><code>source</code></dt> - <dd>If the snapshot mode is external (whether specified - or inherited), then there is an optional sub-element - <code>source</code>, with an attribute <code>file</code> - giving the name of the new file. - If <code>source</code> is not - given and the disk is backed by a local image file (not - a block device or remote storage), a file name is - generated that consists of the existing file name - with anything after the trailing dot replaced by the - snapshot name. Remember that with external - snapshots, the original file name becomes the read-only - snapshot, and the new file name contains the read-write - delta of all disk changes since the snapshot. - <p/> - The <code>source</code> element also may contain the - <code>seclabel</code> element (described in the - <a href="formatdomain.html#seclabel">domain XML documentation</a>) - which can be used to override the domain security labeling policy - for <code>source</code>. - </dd> - <dt><code>driver</code></dt> - <dd>An optional sub-element <code>driver</code>, - with an attribute <code>type</code> giving the driver type (such - as qcow2), of the new file created by the external - snapshot of the new file. - - Optionally <code>metadata_cache</code> sub-element can be used - with same semantics as the identically named subelement of the - domain definition disk's driver. - </dd> - <dt><code>seclabel</code></dt> - </dl> -
Having just the 'seclabel' term here without a definition looks strange. But your conversion is faithful. Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
On Mon, Mar 07, 2022 at 18:56:22 +0100, Ján Tomko wrote:
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsnapshot.html.in | 352 ------------------------------------ docs/formatsnapshot.rst | 297 ++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 298 insertions(+), 353 deletions(-) delete mode 100644 docs/formatsnapshot.html.in create mode 100644 docs/formatsnapshot.rst
diff --git a/docs/formatsnapshot.html.in b/docs/formatsnapshot.html.in deleted file mode 100644 index e481284aa8..0000000000 --- a/docs/formatsnapshot.html.in +++ /dev/null @@ -1,352 +0,0 @@
[...]
- <dt><code>driver</code></dt> - <dd>An optional sub-element <code>driver</code>, - with an attribute <code>type</code> giving the driver type (such - as qcow2), of the new file created by the external - snapshot of the new file. - - Optionally <code>metadata_cache</code> sub-element can be used - with same semantics as the identically named subelement of the - domain definition disk's driver. - </dd> - <dt><code>seclabel</code></dt> - </dl> -
Having just the 'seclabel' term here without a definition looks strange.
But your conversion is faithful.
Well, my conversion is to a large extent automated so the content itself in terms of actual text will not be impacted. In few cases I need to fix nesting of some definition lists and add anchors which are used, so the content is unlikely to diverge. I'll post a follow up to address this.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/goals.html.in | 64 ---------------------------------------------- docs/goals.rst | 56 ++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 57 insertions(+), 65 deletions(-) delete mode 100644 docs/goals.html.in create mode 100644 docs/goals.rst diff --git a/docs/goals.html.in b/docs/goals.html.in deleted file mode 100644 index f1639338ad..0000000000 --- a/docs/goals.html.in +++ /dev/null @@ -1,64 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Terminology and goals</h1> - <p>To avoid ambiguity about the terms used, here are the definitions - for some of the specific concepts used in libvirt documentation:</p> - <ul> - <li>a <strong>node</strong> is a single physical machine</li> - <li>an <strong>hypervisor</strong> is a layer of software allowing to - virtualize a node in a set of virtual machines with possibly different - configurations than the node itself</li> - <li>a <strong>domain</strong> is an instance of an operating system - (or subsystem in the case of container virtualization) running on a - virtualized machine provided by the hypervisor</li> - </ul> - <p>Now we can define the goal of libvirt: <b> to provide a common and - stable layer sufficient to securely manage domains on a node, possibly - remote</b>.</p> - <p> As a result, libvirt should provide all APIs needed to do the - management, such as: provision, create, modify, monitor, control, migrate - and stop the domains - within the limits of the support of the hypervisor - for those operations. - Not all hypervisors provide the same operations; but if an operation is - useful for domain management of even one specific hypervisor it is worth - providing in libvirt. - Multiple nodes - may be accessed with libvirt simultaneously, but the APIs are limited to - single node operations. Node resource operations which are needed - for the management and provisioning of domains are also in the scope of - the libvirt API, such as interface setup, firewall rules, storage management - and general provisioning APIs. Libvirt will also provide the state - monitoring APIs needed to implement management policies, obviously - checking domain state but also exposing local node resource consumption. - </p> - <p>This implies the following sub-goals:</p> - <ul> - <li>All API can be carried remotely though secure APIs</li> - <li>While most API will be generic in term of hypervisor or Host OS, - some API may be targeted to a single virtualization environment - as long as the semantic for the operations from a domain management - perspective is clear</li> - <li>the API should allow to do efficiently and cleanly all the operations - needed to manage domains on a node, including resource provisioning and - setup</li> - <li>the API will not try to provide high level virtualization policies or - multi-nodes management features like load balancing, but the API should be - sufficient so they can be implemented on top of libvirt</li> - <li>stability of the API is a big concern, libvirt should isolate - applications from the frequent changes expected at the lower level of the - virtualization framework</li> - <li>the node being managed may be on a different physical machine than - the management program using libvirt, to this effect libvirt supports - remote access, but should only do so by using secure protocols.</li> - <li>libvirt will provide APIs to enumerate, monitor and use the resources - available on the managed node, including CPUs, memory, storage, networking, - and NUMA partitions.</li> - </ul> - <p>So libvirt is intended to be a building block for higher level - management tools and for applications focusing on virtualization of a - single node (the only exception being domain migration between node - capabilities which involves more than one node).</p> - </body> -</html> diff --git a/docs/goals.rst b/docs/goals.rst new file mode 100644 index 0000000000..7385f27b61 --- /dev/null +++ b/docs/goals.rst @@ -0,0 +1,56 @@ +===================== +Terminology and goals +===================== + +To avoid ambiguity about the terms used, here are the definitions for some of +the specific concepts used in libvirt documentation: + +- a **node** is a single physical machine +- an **hypervisor** is a layer of software allowing to virtualize a node in a + set of virtual machines with possibly different configurations than the node + itself +- a **domain** is an instance of an operating system (or subsystem in the case + of container virtualization) running on a virtualized machine provided by the + hypervisor + +Now we can define the goal of libvirt: **to provide a common and stable layer +sufficient to securely manage domains on a node, possibly remote**. + +As a result, libvirt should provide all APIs needed to do the management, such +as: provision, create, modify, monitor, control, migrate and stop the domains - +within the limits of the support of the hypervisor for those operations. Not all +hypervisors provide the same operations; but if an operation is useful for +domain management of even one specific hypervisor it is worth providing in +libvirt. Multiple nodes may be accessed with libvirt simultaneously, but the +APIs are limited to single node operations. Node resource operations which are +needed for the management and provisioning of domains are also in the scope of +the libvirt API, such as interface setup, firewall rules, storage management and +general provisioning APIs. Libvirt will also provide the state monitoring APIs +needed to implement management policies, obviously checking domain state but +also exposing local node resource consumption. + +This implies the following sub-goals: + +- All API can be carried remotely though secure APIs +- While most API will be generic in term of hypervisor or Host OS, some API may + be targeted to a single virtualization environment as long as the semantic + for the operations from a domain management perspective is clear +- the API should allow to do efficiently and cleanly all the operations needed + to manage domains on a node, including resource provisioning and setup +- the API will not try to provide high level virtualization policies or + multi-nodes management features like load balancing, but the API should be + sufficient so they can be implemented on top of libvirt +- stability of the API is a big concern, libvirt should isolate applications + from the frequent changes expected at the lower level of the virtualization + framework +- the node being managed may be on a different physical machine than the + management program using libvirt, to this effect libvirt supports remote + access, but should only do so by using secure protocols. +- libvirt will provide APIs to enumerate, monitor and use the resources + available on the managed node, including CPUs, memory, storage, networking, + and NUMA partitions. + +So libvirt is intended to be a building block for higher level management tools +and for applications focusing on virtualization of a single node (the only +exception being domain migration between node capabilities which involves more +than one node). diff --git a/docs/meson.build b/docs/meson.build index adb7ac091e..afed104014 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -53,7 +53,6 @@ docs_html_in_files = [ 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', - 'goals', 'governance', 'hooks', 'index', @@ -101,6 +100,7 @@ docs_rst_files = [ 'formatsnapshot', 'formatstorage', 'glib-adoption', + 'goals', 'hacking', 'libvirt-go', 'libvirt-go-xml', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/goals.html.in | 64 ---------------------------------------------- docs/goals.rst | 56 ++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 57 insertions(+), 65 deletions(-) delete mode 100644 docs/goals.html.in create mode 100644 docs/goals.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/strategy.html.in | 133 ------------------------------------------ docs/strategy.rst | 105 +++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 134 deletions(-) delete mode 100644 docs/strategy.html.in create mode 100644 docs/strategy.rst diff --git a/docs/meson.build b/docs/meson.build index afed104014..a719c268f6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -66,7 +66,6 @@ docs_html_in_files = [ 'remote', 'securityprocess', 'storage', - 'strategy', 'support', 'testapi', 'testsuites', @@ -110,6 +109,7 @@ docs_rst_files = [ 'pci-addresses', 'platforms', 'programming-languages', + 'strategy', 'styleguide', 'submitting-patches', ] diff --git a/docs/strategy.html.in b/docs/strategy.html.in deleted file mode 100644 index 70b706b6de..0000000000 --- a/docs/strategy.html.in +++ /dev/null @@ -1,133 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Project Strategy</h1> - - <p> - This document attempts to outline the libvirt project strategy for - the near future. Think of this as a high level vision or to-do list - setting the direction for the project and its developers to take. - </p> - - <h2>Language consolidation</h2> - - <p> - At time of writing libvirt uses the following languages: - </p> - - <dl> - <dt>C</dt> - <dd>The core libvirt library, daemons, and helper tools are all written - in the C language.</dd> - <dt>Python</dt> - <dd>Various supporting build/test scripts are written in Python, with - compatibility for Python 3.</dd> - <dt>Perl</dt> - <dd>Various supporting build/test scripts are written in Perl. It is - also used for many syntax-check inline rules</dd> - <dt>Shell</dt> - <dd>Shell is used for some simple build/test scripts. At runtime - libvirt avoids shell except when using SSH tunnels to a remote - host</dd> - <dt>XSLT</dt> - <dd>The website uses XSLT for its templating system. The API - documentation is also autogenerated from an XML description - using XSLT</dd> - <dt>HTML</dt> - <dd>The website documentation is all written in plain HTML. Some HTML - is also auto-generated for API documentation</dd> - <dt>Meson</dt> - <dd>The core build system uses the new Meson build system</dd> - <dt>make</dt> - <dd>The syntax-check uses make recipes</dd> - <dt>awk/sed</dt> - <dd>A number of the syntax-check inline rules involve use of awk/sed - scripts</dd> - <dt>POD</dt> - <dd>The command line manual pages are typically written in Perl's POD - format, and converted to troff</dd> - </dl> - - <p> - The wide range of languages used present a knowledge burden for - developers involved in libvirt, especially when there are multiple - languages all used in the same problem spaces. This is most notable - in the build system which uses a combination of Meson, shell, awk, - sed, Perl and Python, with debugging requiring - understanding of the interactions between many languages. The - popularity of Perl has declined, while Python has become - more popular. This directly influences the amount and quality of - contributions that can be expected for programs written in the - respective languages. - </p> - <p> - The C language has served libvirt well over the years, but its age shows - giving rise to limitations which negatively impact the project in terms - of code quality, reliability, and efficiency of development. Most notably - its lack of memory safety means that many code bugs become trivially - exploitable security flaws or denial of service. The lack of a high - level portable runtime results in a lot of effort being spent to - ensure cross platform portability. The modern languages Rust and Go - provide viable options for low level systems programming, in a way that - is not practical with other common languages such as Python and Java. - There is thus a desire to make use of either Rust or Go, or a combination - of both, to incrementally replace existing use of C, and also for - greenfield development. - </p> - <p> - With this in mind the libvirt project has set a vision for language - usage in the future: - </p> - - <dl> - <dt>C</dt> - <dd>Large parts of the core libvirt library, daemons, and helper tools - will continue to make use in the C language. Integration of other - languages will be an incremental, targeted process where they can - bring the greatest benefit.</dd> - <dt>Rust / Go</dt> - <dd>Parts of the core libvirt library, daemons and helper tools are to - leverage Rust or Go or both to replace C.</dd> - <dt>Meson</dt> - <dd>The core build system is to be written in Meson.</dd> - <dt>Python</dt> - <dd>Various supporting build/test scripts are written in Python 3 - compatible mode only.</dd> - <dt>reStructuredText</dt> - <dd>The website and command man pages are to be written in RST, using - Sphinx as the engine to convert to end user formats like HTML, troff, - etc</dd> - </dl> - - <p> - Some notable points from the above. Whether the core library / daemons - will use Rust or Go internally is still to be decided based on more - detailed evaluation to identify the best fit. The need to link and embed - this functionality in other processes has complex interactions both at a - technical and non-technical level. For standalone helper tools, either - language is viable, but there are fewer concerns around interactions with - other in-process code from 3rd parties. Thus a different decision may be - made for daemons/libraries vs tools. Any rewrite proposed for existing - functionality will have to weigh up the benefits of the new code, - against the risk of introducing regressions with respect to the previous - code. - </p> - - <p> - Using the RST format for documentation allows for the use of XSLT to be - eliminated from the build process. RST and the Sphinx toolkit are widely - used, as seen by the huge repository of content on - <a href="https://readthedocs.org/">Read The Docs</a>. - The ability to embed raw HTML in the RST docs will greatly facilitate its - adoption, avoiding the need for a big bang conversion of existing content. - Given the desire to eliminate Perl usage, replacing the use of POD - documentation for manual pages is an obvious followup task. RST is the - obvious choice to achieve alignment with the website, allowing the man - pages to be easily published online with other docs. It is further - anticipated that the current API docs generator which uses XSLT to - convert the XML API description would be converted to something which - generates RST using Python instead of XSLT. - </p> - </body> -</html> diff --git a/docs/strategy.rst b/docs/strategy.rst new file mode 100644 index 0000000000..093764b645 --- /dev/null +++ b/docs/strategy.rst @@ -0,0 +1,105 @@ +================ +Project Strategy +================ + +This document attempts to outline the libvirt project strategy for the near +future. Think of this as a high level vision or to-do list setting the direction +for the project and its developers to take. + +Language consolidation +---------------------- + +At time of writing libvirt uses the following languages: + +C + The core libvirt library, daemons, and helper tools are all written in the C + language. +Python + Various supporting build/test scripts are written in Python, with + compatibility for Python 3. +Perl + Various supporting build/test scripts are written in Perl. It is also used + for many syntax-check inline rules +Shell + Shell is used for some simple build/test scripts. At runtime libvirt avoids + shell except when using SSH tunnels to a remote host +XSLT + The website uses XSLT for its templating system. The API documentation is + also autogenerated from an XML description using XSLT +HTML + The website documentation is all written in plain HTML. Some HTML is also + auto-generated for API documentation +Meson + The core build system uses the new Meson build system +make + The syntax-check uses make recipes +awk/sed + A number of the syntax-check inline rules involve use of awk/sed scripts +POD + The command line manual pages are typically written in Perl's POD format, and + converted to troff + +The wide range of languages used present a knowledge burden for developers +involved in libvirt, especially when there are multiple languages all used in +the same problem spaces. This is most notable in the build system which uses a +combination of Meson, shell, awk, sed, Perl and Python, with debugging requiring +understanding of the interactions between many languages. The popularity of Perl +has declined, while Python has become more popular. This directly influences the +amount and quality of contributions that can be expected for programs written in +the respective languages. + +The C language has served libvirt well over the years, but its age shows giving +rise to limitations which negatively impact the project in terms of code +quality, reliability, and efficiency of development. Most notably its lack of +memory safety means that many code bugs become trivially exploitable security +flaws or denial of service. The lack of a high level portable runtime results in +a lot of effort being spent to ensure cross platform portability. The modern +languages Rust and Go provide viable options for low level systems programming, +in a way that is not practical with other common languages such as Python and +Java. There is thus a desire to make use of either Rust or Go, or a combination +of both, to incrementally replace existing use of C, and also for greenfield +development. + +With this in mind the libvirt project has set a vision for language usage in the +future: + +C + Large parts of the core libvirt library, daemons, and helper tools will + continue to make use in the C language. Integration of other languages will + be an incremental, targeted process where they can bring the greatest + benefit. +Rust / Go + Parts of the core libvirt library, daemons and helper tools are to leverage + Rust or Go or both to replace C. +Meson + The core build system is to be written in Meson. +Python + Various supporting build/test scripts are written in Python 3 compatible mode + only. +reStructuredText + The website and command man pages are to be written in RST, using Sphinx as + the engine to convert to end user formats like HTML, troff, etc + +Some notable points from the above. Whether the core library / daemons will use +Rust or Go internally is still to be decided based on more detailed evaluation +to identify the best fit. The need to link and embed this functionality in other +processes has complex interactions both at a technical and non-technical level. +For standalone helper tools, either language is viable, but there are fewer +concerns around interactions with other in-process code from 3rd parties. Thus a +different decision may be made for daemons/libraries vs tools. Any rewrite +proposed for existing functionality will have to weigh up the benefits of the +new code, against the risk of introducing regressions with respect to the +previous code. + +Using the RST format for documentation allows for the use of XSLT to be +eliminated from the build process. RST and the Sphinx toolkit are widely used, +as seen by the huge repository of content on `Read The +Docs <https://readthedocs.org/>`__. The ability to embed raw HTML in the RST +docs will greatly facilitate its adoption, avoiding the need for a big bang +conversion of existing content. Given the desire to eliminate Perl usage, +replacing the use of POD documentation for manual pages is an obvious followup +task. RST is the obvious choice to achieve alignment with the website, allowing +the man pages to be easily published online with other docs. It is further +anticipated that the current API docs generator which uses XSLT to convert the +XML API description would be converted to something which generates RST using +Python instead of XSLT. -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/strategy.html.in | 133 ------------------------------------------ docs/strategy.rst | 105 +++++++++++++++++++++++++++++++++ 3 files changed, 106 insertions(+), 134 deletions(-) delete mode 100644 docs/strategy.html.in create mode 100644 docs/strategy.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/contribute.html.in | 143 ---------------------------------------- docs/contribute.rst | 105 +++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 106 insertions(+), 144 deletions(-) delete mode 100644 docs/contribute.html.in create mode 100644 docs/contribute.rst diff --git a/docs/contribute.html.in b/docs/contribute.html.in deleted file mode 100644 index 790114a56d..0000000000 --- a/docs/contribute.html.in +++ /dev/null @@ -1,143 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Contributing to libvirt</h1> - - <p> - This page provides guidance on how to contribute to the - libvirt project. - </p> - - <ul id="toc"></ul> - - <h2><a id="skills">Contributions required</a></h2> - - <p> - The libvirt project is always looking for new contributors to - participate in ongoing activities. While code development is a - major part of the project, assistance is needed in many other - areas including documentation writing, bug triage, testing, - application integration, website / wiki content management, - translation, branding, social media and more. The only - requirement is an interest in virtualization and desire to - help. - </p> - - <p> - The following is a non-exhaustive list of areas in which - people can contribute to libvirt. If you have ideas for - other contributions feel free to follow them. - </p> - - <ul> - <li><strong>Software development</strong>. The official upstream code are - kept in various <a href="https://gitlab.com/libvirt/">Git repositories</a>. - The core library / daemon (and thus the bulk of coding) is written in C, - but there are language bindings written in Python, Perl, Java, Ruby, - Php, OCaml and Go. There are also higher level wrappers - mapping libvirt into other object frameworks, such GLib, - CIM and SNMP. For those interested in working on the core parts of - libvirt, the <a href="hacking.html">contributor guidelines</a> are - mandatory reading</li> - <li><strong>Translation</strong>. All the libvirt modules aim to support - translations where appropriate. All translation is - handling outside of the normal libvirt review process, - using the <a href="https://translate.fedoraproject.org/projects/libvirt/libvirt">Fedora - instance</a> of the Weblate tool. Thus people wishing - to contribute to translation should join the Fedora - translation team</li> - <li><strong>Documentation</strong>. There are docbook guides on various - aspects of libvirt, particularly application development - guides for the C library and Python, and a virsh command - reference. There is thus scope for work by people who are - familiar with using or developing against libvirt, to - write further content for these guides. There is also a - need for people to review existing content for copy editing - and identifying gaps in the docs</li> - <li><strong>Website / wiki curation</strong>. The bulk of the website is - maintained in the primary GIT repository, while the wiki - site uses mediawiki. In both cases there is a need for - people to both write new content and curate existing - content to identify outdated information, improve its - organization and target gaps.</li> - <li><strong>Testing</strong>. There are a number of tests suites that can run - automated tests against libvirt. The coverage of the tests - is never complete, so there is a need for people to create - new test suites and / or provide environments to actually - run the tests in a variety of deployment scenarios.</li> - <li><strong>Code analysis</strong>. The libvirt project has access to the coverity - tool to run static analysis against the codebase, however, - there are other types of code analysis that can be useful. - In particular fuzzing of the inputs can be very effective - at identifying problematic edge cases.</li> - <li><strong>Security handling</strong>. Downstream (operating system) vendors - who distribute libvirt may wish to propose a person to - be part of the security handling team, to get early access - to information about forthcoming vulnerability fixes.</li> - <li><strong>Evangelism</strong>. Work done by the project is of no benefit - unless the (potential) user community knows that it - exists. Thus it is critically important to the health - and future growth of the project, that there are a people - who evangelize the work created by the project. This can - take many forms, writing blog posts (about usage of features, - personal user experiences, areas for future work, and more), - syndicating docs and blogs via social media, giving user - group and/or conference talks about libvirt.</li> - <li><strong>User assistance</strong>. Since documentation - is never perfect, there are inevitably cases where users - will struggle to attain a deployment goal they have, or - run into trouble with managing an existing deployment. - While some users may be able to contact a software vendor - to obtain support, it is common to rely on community help - forums such as <a href="contact.html#email">libvirt users - mailing list</a>, or sites such as - <a href="https://stackoverflow.com/questions/tagged/libvirt">stackoverflow.</a> - People who are familiar with libvirt and have ability & - desire to help other users are encouraged to participate in - these help forums.</li> - </ul> - - <h2><a id="comms">Communication</a></h2> - - <p> - For full details on contacting other project contributors - read the <a href="contact.html">contact</a> page. There - are two main channels that libvirt uses for communication - between contributors: - </p> - - <h3><a id="email">Mailing lists</a></h3> - - <p> - The project has a number of - <a href="contact.html#email">mailing lists</a> for - general communication between contributors. - In general any design discussions and review - of contributions will take place on the mailing - lists, so it is important for all contributors - to follow the traffic. - </p> - - <h3><a id="irc">Instant messaging / chat</a></h3> - - <p> - Contributors to libvirt are encouraged to join the - <a href="contact.html#irc">IRC channel</a> used by - the project, where they can have live conversations - with others members. - </p> - - <h2><a id="outreach">Student / outreach coding programs</a></h2> - - <p> - Since 2016, the libvirt project directly participates as an - organization in the <a href="https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas">Google Summer of Code program</a>. Prior to - this the project had a number of students in the program - via a joint application with the QEMU project. People are - encouraged to look at both the libvirt and QEMU programs - to identify potentially interesting projects to work on. - </p> - - </body> -</html> diff --git a/docs/contribute.rst b/docs/contribute.rst new file mode 100644 index 0000000000..c95c8b59d2 --- /dev/null +++ b/docs/contribute.rst @@ -0,0 +1,105 @@ +======================= +Contributing to libvirt +======================= + +This page provides guidance on how to contribute to the libvirt project. + +.. contents:: + +Contributions required +---------------------- + +The libvirt project is always looking for new contributors to participate in +ongoing activities. While code development is a major part of the project, +assistance is needed in many other areas including documentation writing, bug +triage, testing, application integration, website / wiki content management, +translation, branding, social media and more. The only requirement is an +interest in virtualization and desire to help. + +The following is a non-exhaustive list of areas in which people can contribute +to libvirt. If you have ideas for other contributions feel free to follow them. + +- **Software development**. The official upstream code are kept in various `Git + repositories <https://gitlab.com/libvirt/>`__. The core library / daemon (and + thus the bulk of coding) is written in C, but there are language bindings + written in Python, Perl, Java, Ruby, Php, OCaml and Go. There are also higher + level wrappers mapping libvirt into other object frameworks, such GLib, CIM + and SNMP. For those interested in working on the core parts of libvirt, the + `contributor guidelines <hacking.html>`__ are mandatory reading +- **Translation**. All the libvirt modules aim to support translations where + appropriate. All translation is handling outside of the normal libvirt review + process, using the `Fedora + instance <https://translate.fedoraproject.org/projects/libvirt/libvirt>`__ of + the Weblate tool. Thus people wishing to contribute to translation should + join the Fedora translation team +- **Documentation**. There are docbook guides on various aspects of libvirt, + particularly application development guides for the C library and Python, and + a virsh command reference. There is thus scope for work by people who are + familiar with using or developing against libvirt, to write further content + for these guides. There is also a need for people to review existing content + for copy editing and identifying gaps in the docs +- **Website / wiki curation**. The bulk of the website is maintained in the + primary GIT repository, while the wiki site uses mediawiki. In both cases + there is a need for people to both write new content and curate existing + content to identify outdated information, improve its organization and target + gaps. +- **Testing**. There are a number of tests suites that can run automated tests + against libvirt. The coverage of the tests is never complete, so there is a + need for people to create new test suites and / or provide environments to + actually run the tests in a variety of deployment scenarios. +- **Code analysis**. The libvirt project has access to the coverity tool to run + static analysis against the codebase, however, there are other types of code + analysis that can be useful. In particular fuzzing of the inputs can be very + effective at identifying problematic edge cases. +- **Security handling**. Downstream (operating system) vendors who distribute + libvirt may wish to propose a person to be part of the security handling + team, to get early access to information about forthcoming vulnerability + fixes. +- **Evangelism**. Work done by the project is of no benefit unless the + (potential) user community knows that it exists. Thus it is critically + important to the health and future growth of the project, that there are a + people who evangelize the work created by the project. This can take many + forms, writing blog posts (about usage of features, personal user + experiences, areas for future work, and more), syndicating docs and blogs via + social media, giving user group and/or conference talks about libvirt. +- **User assistance**. Since documentation is never perfect, there are + inevitably cases where users will struggle to attain a deployment goal they + have, or run into trouble with managing an existing deployment. While some + users may be able to contact a software vendor to obtain support, it is + common to rely on community help forums such as `libvirt users mailing + list <contact.html#email>`__, or sites such as + `stackoverflow. <https://stackoverflow.com/questions/tagged/libvirt>`__ + People who are familiar with libvirt and have ability & desire to help other + users are encouraged to participate in these help forums. + +Communication +------------- + +For full details on contacting other project contributors read the +`contact <contact.html>`__ page. There are two main channels that libvirt uses +for communication between contributors: + +Mailing lists +~~~~~~~~~~~~~ + +The project has a number of `mailing lists <contact.html#email>`__ for general +communication between contributors. In general any design discussions and review +of contributions will take place on the mailing lists, so it is important for +all contributors to follow the traffic. + +Instant messaging / chat +~~~~~~~~~~~~~~~~~~~~~~~~ + +Contributors to libvirt are encouraged to join the `IRC +channel <contact.html#irc>`__ used by the project, where they can have live +conversations with others members. + +Student / outreach coding programs +---------------------------------- + +Since 2016, the libvirt project directly participates as an organization in the +`Google Summer of Code +program <https://wiki.libvirt.org/page/Google_Summer_of_Code_Ideas>`__. Prior to +this the project had a number of students in the program via a joint application +with the QEMU project. People are encouraged to look at both the libvirt and +QEMU programs to identify potentially interesting projects to work on. diff --git a/docs/meson.build b/docs/meson.build index a719c268f6..bee7b3e6fc 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -22,7 +22,6 @@ docs_html_in_files = [ 'bugs', 'cgroups', 'contact', - 'contribute', 'csharp', 'dbus', 'docs', @@ -89,6 +88,7 @@ docs_rst_files = [ 'coding-style', 'committer-guidelines', 'compiling', + 'contribute', 'daemons', 'developer-tooling', 'drvqemu', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/contribute.html.in | 143 ---------------------------------------- docs/contribute.rst | 105 +++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 106 insertions(+), 144 deletions(-) delete mode 100644 docs/contribute.html.in create mode 100644 docs/contribute.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Special care is given to preserve the 'quality' anchor in the 'bugs' page as we link to it directly from the gitlab issue template. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/bugs.html.in | 161 ---------------------------------------------- docs/bugs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 126 insertions(+), 162 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst diff --git a/docs/bugs.html.in b/docs/bugs.html.in deleted file mode 100644 index 400c423518..0000000000 --- a/docs/bugs.html.in +++ /dev/null @@ -1,161 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - - <h1>Bug reporting</h1> - - <ul id="toc"></ul> - - <h2><a id="security">Security Issues</a></h2> - - <p> - If you think that an issue with libvirt may have security - implications, <strong>please do not</strong> publicly - report it in the bug tracker, mailing lists, or irc. Libvirt - has <a href="securityprocess.html">a dedicated process for handling (potential) security issues</a> - that should be used instead. So if your issue has security - implications, ignore the rest of this page and follow the - <a href="securityprocess.html">security process</a> instead. - </p> - - <h2><a id="bugtracking">Bug Tracking</a></h2> - - <p> - If you are using libvirt binaries from a Linux distribution - check below for distribution specific bug reporting policies - first. - </p> - - <h2><a id="general">General libvirt bug reports</a></h2> - - <p> - Bugs in upstream libvirt code should be reported as issues in the - appropriate <a href="https://gitlab.com/libvirt">project on GitLab.</a> - Before submitting a ticket, check the existing tickets to see if - the bug/feature is already tracked. - </p> - <p> - It's always a good idea to file bug reports, as the process of - filing the report always makes it easier to describe the - problem, and the bug number provides a quick way of referring to - the problem. However, not everybody in the community pays frequent - attention to issues, so after you file a bug, asking questions - and submitting patches on <a href="contact.html">the libvirt - mailing lists</a> will increase your bug's visibility and - encourage people to think about your problem. Don't hesitate to - ask questions on the list, as others may know of existing - solutions or be interested in collaborating with you on finding - a solution. Patches are always appreciated, and it's likely - that someone else has the same problem you do! - </p> - <p> - If you decide to write code, though, before you begin please - read the <a href="hacking.html">contributor guidelines</a>, - especially the first point: "Discuss any large changes on the - mailing list first. Post patches early and listen to feedback." - Few development experiences are more discouraging than spending - a bunch of time writing a patch only to have someone point out a - better approach on list. - </p> - - <ul> - <li><a href="https://gitlab.com/libvirt/libvirt/-/issues">View libvirt.git tickets</a></li> - <li><a href="https://gitlab.com/libvirt/libvirt/-/issues/new">New libvirt.git ticket</a></li> - </ul> - - <p> - Note bugs in language bindings and other sub-projects should be - reported to their corresponding git repository rather than the - main libvirt.git linked above. - </p> - - <h2><a id="distribution">Linux Distribution specific bug reports</a></h2> - <ul> - <li> - If you are using binaries from <strong>Fedora</strong>, enter - tickets against the <code>Fedora</code> product and - the <code>libvirt</code> component. - <ul> - <li><a href="https://bugzilla.redhat.com/buglist.cgi?component=libvirt&product=Fedora">View Fedora libvirt tickets</a></li> - <li><a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt">New Fedora libvirt ticket</a></li> - </ul> - </li> - <li> - <p> - If you are using binaries from <strong>Red Hat Enterprise - Linux</strong>, enter tickets against the Red Hat Enterprise - Linux product that you're using (e.g., Red Hat Enterprise - Linux 6) and the <code>libvirt</code> component. Red Hat - bugzilla has <a href="https://bugzilla.redhat.com">additional guidance</a> about getting support if - you are a Red Hat customer. - </p> - </li> - <li> - <p> - If you are using binaries from another Linux distribution - first follow their own bug reporting guidelines. - </p> - </li> - <li> - <p> - Finally, if you are a contributor to another Linux - distribution and would like to have your procedure for - filing bugs mentioned here, please mail the libvirt - development list. - </p> - </li> - </ul> - - - <h2><a id="quality">How to file high quality bug reports</a></h2> - - <p> - To increase the likelihood of your bug report being addressed it is - important to provide as much information as possible. When filing - libvirt bugs use this checklist to see if you are providing enough - information: - </p> - - <ul> - <li>The version number of the libvirt build, or SHA1 of the GIT - commit</li> - <li>The hardware architecture being used</li> - <li>The name of the hypervisor (Xen, QEMU, KVM)</li> - <li>The XML config of the guest domain if relevant</li> - <li>For Xen hypervisor, the domain logfiles from /var/log/xen and - /var/log/libvirt/libxl</li> - <li>For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu</li> - </ul> - - <p> - If the bug leads to a tool linked to libvirt crash, then the best - is to provide a backtrace along with the scenario used to get the - crash, the simplest is to run the program under gdb, reproduce the - steps leading to the crash and then issue a gdb "bt -a" command to - get the stack trace, attach it to the bug. Note that for the - data to be really useful libvirt debug information must be present - for example by installing libvirt debuginfo package on Fedora or - Red Hat Enterprise Linux (with debuginfo-install libvirt) prior - to running gdb.</p> - <p> - It may also happen that the libvirt daemon itself crashes or gets stuck, - in the first case run it (as root) under gdb, and reproduce the sequence - leading to the crash, similarly to a normal program provide the - "bt" backtrace information to where gdb will have stopped.<br/> - But if libvirtd gets stuck, for example seems to stop processing - commands, try to attach to the faulty daemon and issue a gdb command - "thread apply all bt" to show all the threads backtraces, as in:</p> - <pre> # ps -o etime,pid `pgrep libvirt` -... note the process id from the output -# gdb /usr/sbin/libvirtd -.... some information about gdb and loading debug data -(gdb) attach $the_daemon_process_id -.... -(gdb) thread apply all bt -.... information to attach to the bug -(gdb) -</pre> - - </body> -</html> diff --git a/docs/bugs.rst b/docs/bugs.rst new file mode 100644 index 0000000000..152d734592 --- /dev/null +++ b/docs/bugs.rst @@ -0,0 +1,125 @@ +.. role:: anchor(raw) + :format: html + +============= +Bug reporting +============= + +.. contents:: + +Security Issues +--------------- + +If you think that an issue with libvirt may have security implications, **please +do not** publicly report it in the bug tracker, mailing lists, or irc. Libvirt +has `a dedicated process for handling (potential) security +issues <securityprocess.html>`__ that should be used instead. So if your issue +has security implications, ignore the rest of this page and follow the `security +process <securityprocess.html>`__ instead. + +Bug Tracking +------------ + +If you are using libvirt binaries from a Linux distribution check below for +distribution specific bug reporting policies first. + +General libvirt bug reports +--------------------------- + +Bugs in upstream libvirt code should be reported as issues in the appropriate +`project on GitLab. <https://gitlab.com/libvirt>`__ Before submitting a ticket, +check the existing tickets to see if the bug/feature is already tracked. + +It's always a good idea to file bug reports, as the process of filing the report +always makes it easier to describe the problem, and the bug number provides a +quick way of referring to the problem. However, not everybody in the community +pays frequent attention to issues, so after you file a bug, asking questions and +submitting patches on `the libvirt mailing lists <contact.html>`__ will increase +your bug's visibility and encourage people to think about your problem. Don't +hesitate to ask questions on the list, as others may know of existing solutions +or be interested in collaborating with you on finding a solution. Patches are +always appreciated, and it's likely that someone else has the same problem you +do! + +If you decide to write code, though, before you begin please read the +`contributor guidelines <hacking.html>`__, especially the first point: "Discuss +any large changes on the mailing list first. Post patches early and listen to +feedback." Few development experiences are more discouraging than spending a +bunch of time writing a patch only to have someone point out a better approach +on list. + +- `View libvirt.git tickets <https://gitlab.com/libvirt/libvirt/-/issues>`__ +- `New libvirt.git ticket <https://gitlab.com/libvirt/libvirt/-/issues/new>`__ + +Note bugs in language bindings and other sub-projects should be reported to +their corresponding git repository rather than the main libvirt.git linked +above. + +Linux Distribution specific bug reports +--------------------------------------- + +- If you are using binaries from **Fedora**, enter tickets against the + ``Fedora`` product and the ``libvirt`` component. + + - `View Fedora libvirt + tickets <https://bugzilla.redhat.com/buglist.cgi?component=libvirt&product=Fedora>`__ + - `New Fedora libvirt + ticket <https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt>`__ + +- If you are using binaries from **Red Hat Enterprise Linux**, enter tickets + against the Red Hat Enterprise Linux product that you're using (e.g., Red Hat + Enterprise Linux 6) and the ``libvirt`` component. Red Hat bugzilla has + `additional guidance <https://bugzilla.redhat.com>`__ about getting support + if you are a Red Hat customer. + +- If you are using binaries from another Linux distribution first follow their + own bug reporting guidelines. + +- Finally, if you are a contributor to another Linux distribution and would + like to have your procedure for filing bugs mentioned here, please mail the + libvirt development list. + +:anchor:`<a id="quality"/>` + +How to file high quality bug reports +------------------------------------ + +To increase the likelihood of your bug report being addressed it is important to +provide as much information as possible. When filing libvirt bugs use this +checklist to see if you are providing enough information: + +- The version number of the libvirt build, or SHA1 of the GIT commit +- The hardware architecture being used +- The name of the hypervisor (Xen, QEMU, KVM) +- The XML config of the guest domain if relevant +- For Xen hypervisor, the domain logfiles from /var/log/xen and + /var/log/libvirt/libxl +- For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu + +If the bug leads to a tool linked to libvirt crash, then the best is to provide +a backtrace along with the scenario used to get the crash, the simplest is to +run the program under gdb, reproduce the steps leading to the crash and then +issue a gdb "bt -a" command to get the stack trace, attach it to the bug. Note +that for the data to be really useful libvirt debug information must be present +for example by installing libvirt debuginfo package on Fedora or Red Hat +Enterprise Linux (with debuginfo-install libvirt) prior to running gdb. + +| It may also happen that the libvirt daemon itself crashes or gets stuck, in + the first case run it (as root) under gdb, and reproduce the sequence leading + to the crash, similarly to a normal program provide the "bt" backtrace + information to where gdb will have stopped. +| But if libvirtd gets stuck, for example seems to stop processing commands, try + to attach to the faulty daemon and issue a gdb command "thread apply all bt" + to show all the threads backtraces, as in: + +:: + + # ps -o etime,pid `pgrep libvirt` + ... note the process id from the output + # gdb /usr/sbin/libvirtd + .... some information about gdb and loading debug data + (gdb) attach $the_daemon_process_id + .... + (gdb) thread apply all bt + .... information to attach to the bug + (gdb) diff --git a/docs/meson.build b/docs/meson.build index bee7b3e6fc..e92ce6bd9e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'bugs', 'cgroups', 'contact', 'csharp', @@ -84,6 +83,7 @@ docs_rst_files = [ 'auth', 'bindings', 'best-practices', + 'bugs', 'ci', 'coding-style', 'committer-guidelines', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Special care is given to preserve the 'quality' anchor in the 'bugs' page as we link to it directly from the gitlab issue template.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/bugs.html.in | 161 ---------------------------------------------- docs/bugs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 126 insertions(+), 162 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/errors.html.in | 84 ---------------------------------- docs/errors.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 110 insertions(+), 85 deletions(-) delete mode 100644 docs/errors.html.in create mode 100644 docs/errors.rst diff --git a/docs/errors.html.in b/docs/errors.html.in deleted file mode 100644 index ea4272822f..0000000000 --- a/docs/errors.html.in +++ /dev/null @@ -1,84 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1 >Handling of errors</h1> - <p>The main goals of libvirt when it comes to error handling are:</p> - <ul> - <li>provide as much detail as possible</li> - <li>provide the information as soon as possible</li> - <li>dont force the library user into one style of error handling</li> - </ul> - <p>As result the library provide both synchronous, callback based and -asynchronous error reporting. When an error happens in the library code the -error is logged, allowing to retrieve it later and if the user registered an -error callback it will be called synchronously. Once the call to libvirt ends -the error can be detected by the return value and the full information for -the last logged error can be retrieved.</p> - <p>To avoid as much as possible troubles with a global variable in a -multithreaded environment, libvirt will associate when possible the errors to -the current connection they are related to, that way the error is stored in a -dynamic structure which can be made thread specific. Error callback can be -set specifically to a connection with</p> - <p>So error handling in the code is the following:</p> - <ol> - <li>if the error can be associated to a connection for example when failing - to look up a domain - <ol><li>if there is a callback associated to the connection set with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>, - call it with the error information</li><li>otherwise if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>, - call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a> - which is the default error function of the library issuing the error - on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virConnGetLastError">virConnGetLastError</a></li></ol></li> - <li>otherwise like when failing to create a hypervisor connection: - <ol><li>if there is a global callback set with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a>, - call it with the error information</li><li>otherwise call <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a> - which is the default error function of the library issuing the error - on stderr</li><li>save the error in the connection for later retrieval with <a href="html/libvirt-virterror.html#virGetLastError">virGetLastError</a></li></ol></li> - </ol> - <p>In all cases the error information is provided as a <a href="html/libvirt-virterror.html#virErrorPtr">virErrorPtr</a> pointer to -read-only structure <a href="html/libvirt-virterror.html#virError">virError</a> containing the -following fields:</p> - <ul> - <li>code: an error number from the <a href="html/libvirt-virterror.html#virErrorNumber">virErrorNumber</a> - enum</li> - <li>domain: an enum indicating which part of libvirt raised the error see - <a href="html/libvirt-virterror.html#virErrorDomain">virErrorDomain</a></li> - <li>level: the error level, usually VIR_ERR_ERROR, though there is room for - warnings like VIR_ERR_WARNING</li> - <li>message: the full human-readable formatted string of the error</li> - <li>conn: if available a pointer to the <a href="html/libvirt-libvirt-host.html#virConnectPtr">virConnectPtr</a> - connection to the hypervisor where this happened</li> - <li>dom: if available a pointer to the <a href="html/libvirt-libvirt-domain.html#virDomainPtr">virDomainPtr</a> domain - targeted in the operation</li> - </ul> - <p>and then extra raw information about the error which may be initialized -to 0 or NULL if unused</p> - <ul> - <li>str1, str2, str3: string information, usually str1 is the error - message format</li> - <li>int1, int2: integer information</li> - </ul> - <p>So usually, setting up specific error handling with libvirt consist of -registering a handler with <a href="html/libvirt-virterror.html#virSetErrorFunc">virSetErrorFunc</a> or -with <a href="html/libvirt-virterror.html#virConnSetErrorFunc">virConnSetErrorFunc</a>, -check the value of the code value, take appropriate action, if needed let -libvirt print the error on stderr by calling <a href="html/libvirt-virterror.html#virDefaultErrorFunc">virDefaultErrorFunc</a>. -For asynchronous error handing, set such a function doing nothing to avoid -the error being reported on stderr, and call virConnGetLastError or -virGetLastError when an API call returned an error value. It can be a good -idea to use <a href="html/libvirt-virterror.html#virResetLastError">virResetError</a> or <a href="html/libvirt-virterror.html#virConnResetLastError">virConnResetLastError</a> -once an error has been processed fully.</p> - <p>At the python level, there only a global reporting callback function at -this point, see the error.py example about it:</p> - <pre>def handler(ctxt, err): - global errno - - #print "handler(%s, %s)" % (ctxt, err) - errno = err - -libvirt.registerErrorHandler(handler, 'context') </pre> - <p>the second argument to the registerErrorHandler function is passed as the -first argument of the callback like in the C version. The error is a tuple -containing the same field as a virError in C, but cast to Python.</p> - </body> -</html> diff --git a/docs/errors.rst b/docs/errors.rst new file mode 100644 index 0000000000..07c0fb1fc0 --- /dev/null +++ b/docs/errors.rst @@ -0,0 +1,109 @@ +================== +Handling of errors +================== + +The main goals of libvirt when it comes to error handling are: + +- provide as much detail as possible +- provide the information as soon as possible +- dont force the library user into one style of error handling + +As result the library provide both synchronous, callback based and asynchronous +error reporting. When an error happens in the library code the error is logged, +allowing to retrieve it later and if the user registered an error callback it +will be called synchronously. Once the call to libvirt ends the error can be +detected by the return value and the full information for the last logged error +can be retrieved. + +To avoid as much as possible troubles with a global variable in a multithreaded +environment, libvirt will associate when possible the errors to the current +connection they are related to, that way the error is stored in a dynamic +structure which can be made thread specific. Error callback can be set +specifically to a connection with + +So error handling in the code is the following: + +#. if the error can be associated to a connection for example when failing to + look up a domain + + #. if there is a callback associated to the connection set with + `virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, + call it with the error information + #. otherwise if there is a global callback set with + `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it + with the error information + #. otherwise call + `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__ + which is the default error function of the library issuing the error on + stderr + #. save the error in the connection for later retrieval with + `virConnGetLastError <html/libvirt-virterror.html#virConnGetLastError>`__ + +#. otherwise like when failing to create a hypervisor connection: + + #. if there is a global callback set with + `virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__, call it + with the error information + #. otherwise call + `virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__ + which is the default error function of the library issuing the error on + stderr + #. save the error in the connection for later retrieval with + `virGetLastError <html/libvirt-virterror.html#virGetLastError>`__ + +In all cases the error information is provided as a +`virErrorPtr <html/libvirt-virterror.html#virErrorPtr>`__ pointer to read-only +structure `virError <html/libvirt-virterror.html#virError>`__ containing the +following fields: + +- code: an error number from the + `virErrorNumber <html/libvirt-virterror.html#virErrorNumber>`__ enum +- domain: an enum indicating which part of libvirt raised the error see + `virErrorDomain <html/libvirt-virterror.html#virErrorDomain>`__ +- level: the error level, usually VIR_ERR_ERROR, though there is room for + warnings like VIR_ERR_WARNING +- message: the full human-readable formatted string of the error +- conn: if available a pointer to the + `virConnectPtr <html/libvirt-libvirt-host.html#virConnectPtr>`__ connection + to the hypervisor where this happened +- dom: if available a pointer to the + `virDomainPtr <html/libvirt-libvirt-domain.html#virDomainPtr>`__ domain + targeted in the operation + +and then extra raw information about the error which may be initialized to 0 or +NULL if unused + +- str1, str2, str3: string information, usually str1 is the error message + format +- int1, int2: integer information + +So usually, setting up specific error handling with libvirt consist of +registering a handler with +`virSetErrorFunc <html/libvirt-virterror.html#virSetErrorFunc>`__ or with +`virConnSetErrorFunc <html/libvirt-virterror.html#virConnSetErrorFunc>`__, check +the value of the code value, take appropriate action, if needed let libvirt +print the error on stderr by calling +`virDefaultErrorFunc <html/libvirt-virterror.html#virDefaultErrorFunc>`__. For +asynchronous error handing, set such a function doing nothing to avoid the error +being reported on stderr, and call virConnGetLastError or virGetLastError when +an API call returned an error value. It can be a good idea to use +`virResetError <html/libvirt-virterror.html#virResetLastError>`__ or +`virConnResetLastError <html/libvirt-virterror.html#virConnResetLastError>`__ +once an error has been processed fully. + +At the python level, there only a global reporting callback function at this +point, see the error.py example about it: + +:: + + def handler(ctxt, err): + global errno + + #print "handler(%s, %s)" % (ctxt, err) + errno = err + + libvirt.registerErrorHandler(handler, 'context') + +the second argument to the registerErrorHandler function is passed as the first +argument of the callback like in the C version. The error is a tuple containing +the same field as a virError in C, but cast to Python. diff --git a/docs/meson.build b/docs/meson.build index e92ce6bd9e..d0c1217351 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -39,7 +39,6 @@ docs_html_in_files = [ 'drvvirtuozzo', 'drvvmware', 'drvxen', - 'errors', 'firewall', 'formatcaps', 'formatdomaincaps', @@ -93,6 +92,7 @@ docs_rst_files = [ 'developer-tooling', 'drvqemu', 'drvch', + 'errors', 'formatbackup', 'formatcheckpoint', 'formatdomain', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/errors.html.in | 84 ---------------------------------- docs/errors.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 110 insertions(+), 85 deletions(-) delete mode 100644 docs/errors.html.in create mode 100644 docs/errors.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/support.html.in | 258 ------------------------------------------- docs/support.rst | 207 ++++++++++++++++++++++++++++++++++ 3 files changed, 208 insertions(+), 259 deletions(-) delete mode 100644 docs/support.html.in create mode 100644 docs/support.rst diff --git a/docs/meson.build b/docs/meson.build index d0c1217351..b3432cc6f6 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -63,7 +63,6 @@ docs_html_in_files = [ 'remote', 'securityprocess', 'storage', - 'support', 'testapi', 'testsuites', 'testtck', @@ -112,6 +111,7 @@ docs_rst_files = [ 'strategy', 'styleguide', 'submitting-patches', + 'support', ] # list of web targets to build for docs/web rule diff --git a/docs/support.html.in b/docs/support.html.in deleted file mode 100644 index 38f2f906e0..0000000000 --- a/docs/support.html.in +++ /dev/null @@ -1,258 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Support guarantees</h1> - - <ul id="toc"></ul> - - <p> - This document will outline the support status / guarantees around the - very interfaces that libvirt exposes to applications and/or system - administrators. The intent is to help users understand what features they - can rely upon in particular scenarios, and whether they are likely to - suffer disruption during upgrades. - </p> - - <h2><a id="publicAPI">Primary public API</a></h2> - - <p> - The main public API provided by <code>libvirt.so</code> and described - in <code>libvirt/libvirt.h</code> exposes the primary hypervisor - agnostic management interface of libvirt. This API has the strongest - guarantee of any part of libvirt with a promise to keep backwards - compatibility forever. Specific details are as follows: - </p> - - <dl> - <dt>Functions</dt> - <dd>Functions will never be removed from the public API, and will - never have parameters added, removed or changed in their signature. - IOW they will be ABI compatible forever. The semantics implied by - a specific set of parameters passed to the function will remain - unchanged. Where a parameter accepts a bitset of feature flags, or - an enumerated value, further flags / enum values may be supported - in the future. Where a parameter accepts one of a set of related - constants, further constants may be supported in the future. - </dd> - <dt>Struct types</dt> - <dd>Once defined in a release, struct definitions will never have any - fields add, removed or changed in any way. Their size and layout is - fixed forever. If a struct name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the struct name. - </dd> - <dt>Union types</dt> - <dd>Once defined in a release, union definitions will never have any - existing fields removed or changed. New union choices may be added, - provided that they don't change the size of the existing union - definition. If a struct name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the struct name. - </dd> - <dt>Type definitions</dt> - <dd>Most custom data types used in the APIs have corresponding typedefs - provided for their stable names. The typedefs should always be used - in preference to the underlying data type name, as the latter are not - guaranteed to be stable. - </dd> - <dt>Enumerations</dt> - <dd>Once defined in a release, existing enumeration values will never - be removed or renamed. New enumeration values may be introduced at - any time. Every enumeration will have a '_LAST' value which indicates - the current highest enumeration value, which may increase with new - releases. If an enumeration name starts with an underscore, it is - considered acceptable to rename it. Applications should thus always - use the corresponding typedef in preference to the enum name. - </dd> - <dt>Constants</dt> - <dd>Once defined in a release, existing constants will never be removed - or have their value changed. Most constants are grouped into related - sets, and within each set, new constants may be introduced. APIs which - use the constants may thus accept or return new constant values over - time. - </dd> - <dt>Symbol versions</dt> - <dd>Where the platform library format permits, APIs defined in libvirt.so - library will have version information associated. Each API will be - tagged with the version in which it was introduced, and this won't - be changed thereafter. - </dd> - </dl> - - <h2><a id="hvAPI">Hypervisor specific APIs</a></h2> - - <p> - A number of hypervisor drivers provide additional libraries with hypervisor - specific APIs, extending the core libvirt API. These add-on libraries follow - the same general principles described above, however, they are <strong>not</strong> - guaranteed to be preserved forever. The project reserves the right to remove - hypervisor specific APIs in any new release, or to change their semantics. - That said the project will endeavour to maintain API compatibility for as long - as is practical. - </p> - - <p> - Use of some hypervisor specific APIs may result in the running guest being - marked as "tainted" if the API is at risk of having unexpected interactions - with normal libvirt operations. An application which chooses to make use of - hypervisor specific APIs should validate their operation with each new release - of libvirt and each new release of the underlying hypervisor. The semantics - may change in unexpected ways, or have unforeseen interactions with libvirt's - operation. - </p> - - <h2><a id="apierrors">Error reporting</a></h2> - - <p> - Most API calls are subject to failure and so will report error codes and - messages. Libvirt defines error codes for a wide variety of scenarios, some - represent very specific problems, while others are general purpose for - broad classes of problem. Over time the error codes reported are liable - to change, usually changing from a generic error to a more specific error. - Thus applications should be careful about checking for & taking action - upon specific error codes, as their behaviour may change across releases. - </p> - - <h2><a id="xmlschema">XML schemas</a></h2> - - <p> - The main objects exposed via the primary libvirt public API are usually - configured via XML documents following specific schemas. The XML schemas - are considered to be stable formats, whose compatibility will be maintained - forever. Specific details are as follows: - </p> - - <dl> - <dt>Attributes</dt> - <dd>Attributes defined on an XML element will never be removed or - renamed. New attributes may be defined. If the set of valid values - for an attribute are determined by an enumeration, the permitted - values will never be removed or renamed, only new values defined. - None the less, specific hypervisors may reject usage of certain - values according to their feature set. - </dd> - <dt>Elements</dt> - <dd>Elements defined will never be removed or renamed. New child - elements may be defined at any time. In places where only a - single instance of a named XML element is used, future versions - may be extended to permit multiple instances of the named XML - element to be used. An element which currently has no content - may later gain child elements. - </dd> - </dl> - - <p> - Some hypervisor drivers may choose to allow use of hypervisor specific - extensions to the XML documents. These extensions will always be - contained within a hypervisor specific XML namespace. There is generally - no guarantee of long term support for the hypervisor specific extensions - across releases, though the project will endeavour to preserve them as - long as is possible. Applications choosing to use hypervisor specific - extensions should validate their operation against new libvirt or - hypervisor releases. - </p> - - <h2><a id="configfiles">Configuration files</a></h2> - - <p> - A number of programs / daemons provided libvirt rely on host filesystem - configuration files. These configuration files are accompanied by augeas - lens for easy manipulation by applications. There is in general no - guarantee that parameters available in the configuration file will be - preserved across releases, though the project will endeavour to preserve - them as long as is possible. If a configuration option is dropped from - the file, the augeas lens will retain the ability to read that configuration - parameter, so that it is able to read & update historically modified - files. - - The default configuration files ship with all parameters commented out - such that a deployment relies on the built-in defaults of the application - in question. There is no guarantee that the defaults will remain the same - across releases. A deployment that expects a particular value for a - configuration parameter should consider defining it explicitly, instead - of relying on the defaults. - </p> - - <h2><a id="hvdrivers">Hypervisor drivers</a></h2> - - <p> - The libvirt project provides support for a wide variety of hypervisor - drivers. These drivers target certain versions of the hypervisor's - underlying management APIs. In general libvirt aims to work with any - hypervisor version that is still broadly supported by its vendor. - When a vendor discontinues support for a particular hypervisor - version it will be dropped by libvirt. Libvirt may choose to drop - support for a particular hypervisor version prior to the vendor - ending support, if it deems that the likely usage is too small to - justify the ongoing maintenance cost. - </p> - <p> - Each hypervisor release will implement a distinct subset of features - that can be expressed in the libvirt APIs and XML formats. While the - XML schema syntax will be stable across releases, libvirt is unable - to promise that it will always be able to support usage of the same - features across hypervisor releases. Where a hypervisor changes the - way a feature is implemented, the project will endeavour to adapt - to the new implementation to provide the same semantics. In cases - where the feature is discontinued by the hypervisor, libvirt will - return an error indicating it is not supported. Likewise libvirt will - make reasonable efforts to keep API calls working across hypervisor - releases even if the underlying implementation changes. In cases where - this is impossible, a suitable error will be reported. The list of - APIs which have implementations <a href="hvsupport.html">is detailed separately</a>. - </p> - - <h2><a id="rpcproto">RPC protocol</a></h2> - - <p> - For some hypervisor drivers, the libvirt.so library communicates with - separate libvirt daemons to perform work. This communication takes - place over a binary RPC protocol defined by libvirt. The protocol uses - the XDR format for data encoding, and the message packet format is - defined in libvirt source code. - </p> - <p> - Applications are encouraged to use the primary libvirt.so library which - transparently talks to the daemons, so that they are not exposed to the - hypervisor driver specific details. None the less, the RPC protocol - associated with the libvirtd is considered to be a long term stable ABI. - It will only ever have new messages added to it, existing messages will - not be removed, nor have their contents changed. Thus if an application - does wish to provide its own client side implementation of the RPC - protocol this is supported, with the caveat that the application will - loose the ability to work with certain hypervisors libvirt supports. - The project reserves the right to define new authentication and encryption - options for the protocol, and the defaults used in this area may change - over time. This is particularly true of the TLS ciphers permitted. Thus - applications choosing to implement the RPC protocol must be prepared to - track support for new security options. If defaults are changed, however, - it will generally be possible to reconfigure the daemon to use the old - defaults, albeit with possible implications for system security. - </p> - - <p> - Other daemons besides, libvirtd, also use the same RPC protocol, but - with different message types defined. These RPC protocols are all - considered to be private implementations that are liable to change - at any time. Applications must not attempt to talk to these other - daemons directly. - </p> - - <h2><a id="virsh">virsh client</a></h2> - - <p> - The virsh program provides a simple client to interact with an arbitrary libvirt - hypervisor connection. Since it uses the primary public API of libvirt, it should - generally inherit the guarantees associated with that API, and with the hypervisor - driver. The commands that virsh exposes, and the arguments they accept are all - considered to be long term stable. Existing commands and arguments will not be - removed or renamed. New commands and arguments may be added in new releases. - The text output format produced by virsh commands is not generally guaranteed to - be stable if it contains compound data (eg formatted tables or lists). Commands - which output single data items (ie an object name, or an XML document), can be - treated as having stable format. - </p> - - </body> -</html> diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 0000000000..f285f63c55 --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,207 @@ +================== +Support guarantees +================== + +.. contents:: + +This document will outline the support status / guarantees around the very +interfaces that libvirt exposes to applications and/or system administrators. +The intent is to help users understand what features they can rely upon in +particular scenarios, and whether they are likely to suffer disruption during +upgrades. + +Primary public API +------------------ + +The main public API provided by ``libvirt.so`` and described in +``libvirt/libvirt.h`` exposes the primary hypervisor agnostic management +interface of libvirt. This API has the strongest guarantee of any part of +libvirt with a promise to keep backwards compatibility forever. Specific details +are as follows: + +Functions + Functions will never be removed from the public API, and will never have + parameters added, removed or changed in their signature. IOW they will be ABI + compatible forever. The semantics implied by a specific set of parameters + passed to the function will remain unchanged. Where a parameter accepts a + bitset of feature flags, or an enumerated value, further flags / enum values + may be supported in the future. Where a parameter accepts one of a set of + related constants, further constants may be supported in the future. +Struct types + Once defined in a release, struct definitions will never have any fields add, + removed or changed in any way. Their size and layout is fixed forever. If a + struct name starts with an underscore, it is considered acceptable to rename + it. Applications should thus always use the corresponding typedef in + preference to the struct name. +Union types + Once defined in a release, union definitions will never have any existing + fields removed or changed. New union choices may be added, provided that they + don't change the size of the existing union definition. If a struct name + starts with an underscore, it is considered acceptable to rename it. + Applications should thus always use the corresponding typedef in preference + to the struct name. +Type definitions + Most custom data types used in the APIs have corresponding typedefs provided + for their stable names. The typedefs should always be used in preference to + the underlying data type name, as the latter are not guaranteed to be stable. +Enumerations + Once defined in a release, existing enumeration values will never be removed + or renamed. New enumeration values may be introduced at any time. Every + enumeration will have a '_LAST' value which indicates the current highest + enumeration value, which may increase with new releases. If an enumeration + name starts with an underscore, it is considered acceptable to rename it. + Applications should thus always use the corresponding typedef in preference + to the enum name. +Constants + Once defined in a release, existing constants will never be removed or have + their value changed. Most constants are grouped into related sets, and within + each set, new constants may be introduced. APIs which use the constants may + thus accept or return new constant values over time. +Symbol versions + Where the platform library format permits, APIs defined in libvirt.so library + will have version information associated. Each API will be tagged with the + version in which it was introduced, and this won't be changed thereafter. + +Hypervisor specific APIs +------------------------ + +A number of hypervisor drivers provide additional libraries with hypervisor +specific APIs, extending the core libvirt API. These add-on libraries follow the +same general principles described above, however, they are **not** guaranteed to +be preserved forever. The project reserves the right to remove hypervisor +specific APIs in any new release, or to change their semantics. That said the +project will endeavour to maintain API compatibility for as long as is +practical. + +Use of some hypervisor specific APIs may result in the running guest being +marked as "tainted" if the API is at risk of having unexpected interactions with +normal libvirt operations. An application which chooses to make use of +hypervisor specific APIs should validate their operation with each new release +of libvirt and each new release of the underlying hypervisor. The semantics may +change in unexpected ways, or have unforeseen interactions with libvirt's +operation. + +Error reporting +--------------- + +Most API calls are subject to failure and so will report error codes and +messages. Libvirt defines error codes for a wide variety of scenarios, some +represent very specific problems, while others are general purpose for broad +classes of problem. Over time the error codes reported are liable to change, +usually changing from a generic error to a more specific error. Thus +applications should be careful about checking for & taking action upon specific +error codes, as their behaviour may change across releases. + +XML schemas +----------- + +The main objects exposed via the primary libvirt public API are usually +configured via XML documents following specific schemas. The XML schemas are +considered to be stable formats, whose compatibility will be maintained forever. +Specific details are as follows: + +Attributes + Attributes defined on an XML element will never be removed or renamed. New + attributes may be defined. If the set of valid values for an attribute are + determined by an enumeration, the permitted values will never be removed or + renamed, only new values defined. None the less, specific hypervisors may + reject usage of certain values according to their feature set. +Elements + Elements defined will never be removed or renamed. New child elements may be + defined at any time. In places where only a single instance of a named XML + element is used, future versions may be extended to permit multiple instances + of the named XML element to be used. An element which currently has no + content may later gain child elements. + +Some hypervisor drivers may choose to allow use of hypervisor specific +extensions to the XML documents. These extensions will always be contained +within a hypervisor specific XML namespace. There is generally no guarantee of +long term support for the hypervisor specific extensions across releases, though +the project will endeavour to preserve them as long as is possible. Applications +choosing to use hypervisor specific extensions should validate their operation +against new libvirt or hypervisor releases. + +Configuration files +------------------- + +A number of programs / daemons provided libvirt rely on host filesystem +configuration files. These configuration files are accompanied by augeas lens +for easy manipulation by applications. There is in general no guarantee that +parameters available in the configuration file will be preserved across +releases, though the project will endeavour to preserve them as long as is +possible. If a configuration option is dropped from the file, the augeas lens +will retain the ability to read that configuration parameter, so that it is able +to read & update historically modified files. The default configuration files +ship with all parameters commented out such that a deployment relies on the +built-in defaults of the application in question. There is no guarantee that the +defaults will remain the same across releases. A deployment that expects a +particular value for a configuration parameter should consider defining it +explicitly, instead of relying on the defaults. + +Hypervisor drivers +------------------ + +The libvirt project provides support for a wide variety of hypervisor drivers. +These drivers target certain versions of the hypervisor's underlying management +APIs. In general libvirt aims to work with any hypervisor version that is still +broadly supported by its vendor. When a vendor discontinues support for a +particular hypervisor version it will be dropped by libvirt. Libvirt may choose +to drop support for a particular hypervisor version prior to the vendor ending +support, if it deems that the likely usage is too small to justify the ongoing +maintenance cost. + +Each hypervisor release will implement a distinct subset of features that can be +expressed in the libvirt APIs and XML formats. While the XML schema syntax will +be stable across releases, libvirt is unable to promise that it will always be +able to support usage of the same features across hypervisor releases. Where a +hypervisor changes the way a feature is implemented, the project will endeavour +to adapt to the new implementation to provide the same semantics. In cases where +the feature is discontinued by the hypervisor, libvirt will return an error +indicating it is not supported. Likewise libvirt will make reasonable efforts to +keep API calls working across hypervisor releases even if the underlying +implementation changes. In cases where this is impossible, a suitable error will +be reported. The list of APIs which have implementations `is detailed +separately <hvsupport.html>`__. + +RPC protocol +------------ + +For some hypervisor drivers, the libvirt.so library communicates with separate +libvirt daemons to perform work. This communication takes place over a binary +RPC protocol defined by libvirt. The protocol uses the XDR format for data +encoding, and the message packet format is defined in libvirt source code. + +Applications are encouraged to use the primary libvirt.so library which +transparently talks to the daemons, so that they are not exposed to the +hypervisor driver specific details. None the less, the RPC protocol associated +with the libvirtd is considered to be a long term stable ABI. It will only ever +have new messages added to it, existing messages will not be removed, nor have +their contents changed. Thus if an application does wish to provide its own +client side implementation of the RPC protocol this is supported, with the +caveat that the application will loose the ability to work with certain +hypervisors libvirt supports. The project reserves the right to define new +authentication and encryption options for the protocol, and the defaults used in +this area may change over time. This is particularly true of the TLS ciphers +permitted. Thus applications choosing to implement the RPC protocol must be +prepared to track support for new security options. If defaults are changed, +however, it will generally be possible to reconfigure the daemon to use the old +defaults, albeit with possible implications for system security. + +Other daemons besides, libvirtd, also use the same RPC protocol, but with +different message types defined. These RPC protocols are all considered to be +private implementations that are liable to change at any time. Applications must +not attempt to talk to these other daemons directly. + +virsh client +------------ + +The virsh program provides a simple client to interact with an arbitrary libvirt +hypervisor connection. Since it uses the primary public API of libvirt, it +should generally inherit the guarantees associated with that API, and with the +hypervisor driver. The commands that virsh exposes, and the arguments they +accept are all considered to be long term stable. Existing commands and +arguments will not be removed or renamed. New commands and arguments may be +added in new releases. The text output format produced by virsh commands is not +generally guaranteed to be stable if it contains compound data (eg formatted +tables or lists). Commands which output single data items (ie an object name, or +an XML document), can be treated as having stable format. -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/support.html.in | 258 ------------------------------------------- docs/support.rst | 207 ++++++++++++++++++++++++++++++++++ 3 files changed, 208 insertions(+), 259 deletions(-) delete mode 100644 docs/support.html.in create mode 100644 docs/support.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/securityprocess.html.in | 119 ----------------------------------- docs/securityprocess.rst | 91 +++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 120 deletions(-) delete mode 100644 docs/securityprocess.html.in create mode 100644 docs/securityprocess.rst diff --git a/docs/meson.build b/docs/meson.build index b3432cc6f6..ab020ab090 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -61,7 +61,6 @@ docs_html_in_files = [ 'php', 'python', 'remote', - 'securityprocess', 'storage', 'testapi', 'testsuites', @@ -108,6 +107,7 @@ docs_rst_files = [ 'pci-addresses', 'platforms', 'programming-languages', + 'securityprocess', 'strategy', 'styleguide', 'submitting-patches', diff --git a/docs/securityprocess.html.in b/docs/securityprocess.html.in deleted file mode 100644 index 0e4802a1de..0000000000 --- a/docs/securityprocess.html.in +++ /dev/null @@ -1,119 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - - <h1>Security Process</h1> - - <ul id="toc"></ul> - - <p> - The libvirt project believes in responsible disclosure of - security problems, to allow vendors time to prepare and - distribute patches for problems ahead of their publication. - This page describes how the process works and how to report - potential security issues. - </p> - - <h2><a id="reporting">Reporting security issues</a></h2> - - <p> - In the event that a bug in libvirt is found which is - believed to have (potential) security implications there - is a dedicated contact to which a bug report / notification - should be directed. Send an email with as many details of - the problem as possible (ideally with steps to reproduce) - to the following email address: - </p> - - <pre> -<a href="mailto:libvirt-security@redhat.com">libvirt-security@redhat.com</a></pre> - - <p> - NB. while this email address is backed by a mailing list, it - is invitation only and moderated for non-members. As such you - will receive an auto-reply indicating the report is held for - moderation. Postings by non-members will be approved by a - moderator and the reporter copied on any replies. - </p> - - <h2><a id="secnotice">Security notices</a></h2> - - <p> - Information for all historical security issues is maintained in - machine parsable format in the - <a href="https://gitlab.com/libvirt/libvirt-security-notice">libvirt-security-notice GIT repository</a> and - <a href="https://security.libvirt.org">published online</a> - in text, HTML and XML formats. Security notices are published - on the <a href="https://libvirt.org/contact.html#email">libvirt-announce mailing list</a> - when any embargo is lifted, or as soon as triaged if already - public knowledge. - </p> - - <h2><a id="seclist">Security team</a></h2> - - <p> - The libvirt security team is made up of a subset of the libvirt - core development team which covers the various distro maintainers - of libvirt, along with nominated security engineers representing - the various vendors who distribute libvirt. The team is responsible - for analysing incoming reports from users to identify whether a - security problem exists and its severity. It then works to produce - a fix for all official stable branches of libvirt and coordinate - embargo dates between vendors to allow simultaneous release of the - fix by all affected parties. - </p> - - <p> - If you are a security representative of a vendor distributing - libvirt and would like to join the security team, send an email - to the afore-mentioned security address. Typically an existing - member of the security team will have to vouch for your credentials - before membership is approved. All members of the security team - are <strong>required to respect the embargo policy</strong> - described below. - </p> - - <h2><a id="embargo">Publication embargo policy</a></h2> - - <p> - The libvirt security team operates a policy of - <a href="https://en.wikipedia.org/wiki/Responsible_disclosure">responsible disclosure</a>. - As such any security issue reported, that is not already publicly disclosed - elsewhere, will have an embargo date assigned. Members of the security team agree - not to publicly disclose any details of the security issue until the embargo - date expires. - </p> - - <p> - The general aim of the team is to have embargo dates which - are two weeks or less in duration. If a problem is identified - with a proposed patch for a security issue, requiring further - investigation and bug fixing, the embargo clock may be restarted. - In exceptional circumstances longer initial embargoes may be - negotiated by mutual agreement between members of the security - team and other relevant parties to the problem. Any such extended - embargoes will aim to be at most one month in duration. - </p> - - - <h2><a id="cve">CVE allocation</a></h2> - - <p> - The libvirt security team will associate each security issue with - a CVE number. The CVE numbers will usually be allocated by one of - the vendor security engineers on the security team. - </p> - - <h2><a id="branches">Branch fixing policy</a></h2> - - <p> - The libvirt community maintains one or more stable release branches - at any given point in time. The security team will aim to publish - fixes for GIT master (which will become the next major release) and - each currently maintained stable release branch. The distro maintainers - will be responsible for backporting the officially published fixes to - other release branches where applicable. - </p> - </body> -</html> diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst new file mode 100644 index 0000000000..adddbf76b0 --- /dev/null +++ b/docs/securityprocess.rst @@ -0,0 +1,91 @@ +================ +Security Process +================ + +.. contents:: + +The libvirt project believes in responsible disclosure of security problems, to +allow vendors time to prepare and distribute patches for problems ahead of their +publication. This page describes how the process works and how to report +potential security issues. + +Reporting security issues +------------------------- + +In the event that a bug in libvirt is found which is believed to have +(potential) security implications there is a dedicated contact to which a bug +report / notification should be directed. Send an email with as many details of +the problem as possible (ideally with steps to reproduce) to the following email +address: + +:: + + libvirt-security@redhat.com + +NB. while this email address is backed by a mailing list, it is invitation only +and moderated for non-members. As such you will receive an auto-reply indicating +the report is held for moderation. Postings by non-members will be approved by a +moderator and the reporter copied on any replies. + +Security notices +---------------- + +Information for all historical security issues is maintained in machine parsable +format in the `libvirt-security-notice GIT +repository <https://gitlab.com/libvirt/libvirt-security-notice>`__ and +`published online <https://security.libvirt.org>`__ in text, HTML and XML +formats. Security notices are published on the `libvirt-announce mailing +list <https://libvirt.org/contact.html#email>`__ when any embargo is lifted, or +as soon as triaged if already public knowledge. + +Security team +------------- + +The libvirt security team is made up of a subset of the libvirt core development +team which covers the various distro maintainers of libvirt, along with +nominated security engineers representing the various vendors who distribute +libvirt. The team is responsible for analysing incoming reports from users to +identify whether a security problem exists and its severity. It then works to +produce a fix for all official stable branches of libvirt and coordinate embargo +dates between vendors to allow simultaneous release of the fix by all affected +parties. + +If you are a security representative of a vendor distributing libvirt and would +like to join the security team, send an email to the afore-mentioned security +address. Typically an existing member of the security team will have to vouch +for your credentials before membership is approved. All members of the security +team are **required to respect the embargo policy** described below. + +Publication embargo policy +-------------------------- + +The libvirt security team operates a policy of `responsible +disclosure <https://en.wikipedia.org/wiki/Responsible_disclosure>`__. As such +any security issue reported, that is not already publicly disclosed elsewhere, +will have an embargo date assigned. Members of the security team agree not to +publicly disclose any details of the security issue until the embargo date +expires. + +The general aim of the team is to have embargo dates which are two weeks or less +in duration. If a problem is identified with a proposed patch for a security +issue, requiring further investigation and bug fixing, the embargo clock may be +restarted. In exceptional circumstances longer initial embargoes may be +negotiated by mutual agreement between members of the security team and other +relevant parties to the problem. Any such extended embargoes will aim to be at +most one month in duration. + +CVE allocation +-------------- + +The libvirt security team will associate each security issue with a CVE number. +The CVE numbers will usually be allocated by one of the vendor security +engineers on the security team. + +Branch fixing policy +-------------------- + +The libvirt community maintains one or more stable release branches at any given +point in time. The security team will aim to publish fixes for GIT master (which +will become the next major release) and each currently maintained stable release +branch. The distro maintainers will be responsible for backporting the +officially published fixes to other release branches where applicable. -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 2 +- docs/securityprocess.html.in | 119 ----------------------------------- docs/securityprocess.rst | 91 +++++++++++++++++++++++++++ 3 files changed, 92 insertions(+), 120 deletions(-) delete mode 100644 docs/securityprocess.html.in create mode 100644 docs/securityprocess.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..e1dc626f68 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,8 @@ engineers on the security team. Branch fixing policy -------------------- -The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the -officially published fixes to other release branches where applicable. +The security team will aim to publish fixes for GIT master (which will become +the next major release) and each currently maintained stable release branch, if +there's any. +The distro maintainers will be responsible for backporting the officially +published fixes to other release branches where applicable. -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
The 'Branch fixing policy' paragraph claims that we have at least one actively maintained stable branch which isn't currently the case.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/securityprocess.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/securityprocess.rst b/docs/securityprocess.rst index adddbf76b0..e1dc626f68 100644 --- a/docs/securityprocess.rst +++ b/docs/securityprocess.rst @@ -84,8 +84,8 @@ engineers on the security team. Branch fixing policy --------------------
-The libvirt community maintains one or more stable release branches at any given -point in time. The security team will aim to publish fixes for GIT master (which -will become the next major release) and each currently maintained stable release -branch. The distro maintainers will be responsible for backporting the -officially published fixes to other release branches where applicable. +The security team will aim to publish fixes for GIT master (which will become +the next major release) and each currently maintained stable release branch, if +there's any.
Maybe you can drop the mention of stable releases completely. The last one was in 2017 if https://wiki.libvirt.org/page/Maintenance_Releases is to be trusted. Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
+The distro maintainers will be responsible for backporting the officially +published fixes to other release branches where applicable. -- 2.35.1
Extra care is taken to preserve the 'codeofconduct' anchor which is used in our page template. Upcoming patch will change that but we'll retain the anchor. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/governance.html.in | 298 ---------------------------------------- docs/governance.rst | 232 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 233 insertions(+), 299 deletions(-) delete mode 100644 docs/governance.html.in create mode 100644 docs/governance.rst diff --git a/docs/governance.html.in b/docs/governance.html.in deleted file mode 100644 index 61ab52c858..0000000000 --- a/docs/governance.html.in +++ /dev/null @@ -1,298 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Project governance</h1> - - <ul id="toc"></ul> - - <p> - The libvirt project operates as a meritocratic, consensus-based community. - Anyone with an interest in the project can join the community, contributing - to the ongoing development of the project's work. This pages describes how - that participation takes place and how contributors earn merit, and thus - influence, within the community. - </p> - - <h2><a id="codeofconduct">Code of conduct</a></h2> - - <p> - The libvirt project community covers people from a wide variety of - countries, backgrounds and positions. This global diversity is a great - strength of the project, but can also lead to communication issues, - which may in turn cause unhappiness. To maximise happiness of the - project community taken as a whole, all members (whether users, - contributors or committers) are expected to abide by the project's - code of conduct. At a high level the code can be summarized as - <em>"be excellent to each other"</em>. Expanding on this: - </p> - - <ul> - <li><strong>Be respectful:</strong> disagreements between people are to - be expected and are usually the sign of healthy debate and engagement. - Disagreements can lead to frustration and even anger for some members. - Turning to personal insults, intimidation or threatening behaviour does - not improve the situation though. Participants should thus take care to - ensure all communications / interactions stay professional at all times.</li> - - <li><strong>Be considerate:</strong> remember that the community has members - with a diverse background many of whom have English as a second language. - What might appear impolite, may simply be a result of a lack of knowledge - of the English language. Bear in mind that actions will have an impact - on other community members and the project as a whole, so take potential - consequences into account before pursuing a course of action.</li> - - <li><strong>Be forgiving:</strong> humans are fallible and as such prone - to make mistakes and inexplicably change their positions at times. Don't - assume that other members are acting with malicious intent. Be prepared - to forgive people who make mistakes and assist each other in learning - from them. Playing a blame game doesn't help anyone.</li> - </ul> - - <h2><a id="roles">Roles and responsibilities</a></h2> - - <h3><a href="users">Users</a></h3> - - <p> - The users are anyone who has a need for the output of the project. - There are no rules or requirements to become a user of libvirt. Even - if the software does not yet work on their OS platform, a person can - be considered a potential future user and welcomed to participate. - </p> - - <p> - Participation by users is key to ensuring the project moves in the - right direction, satisfying their real world needs. Users are - encouraged to participate in the broader libvirt community in any - number of ways: - </p> - - <ul> - <li>Evangelism: spread the word about what libvirt is doing, how it - helps solve your problems. This can be via blog articles, social - media postings, video blogs, user group / conference presentations - and any other method of disseminating information</li> - <li>Feedback: let the developers know about what does and does not - work with the project. Talk to developers on the project's - IRC channel and mailing list, or find them at conferences. Tell - them what gaps the project has or where they should look for - future development</li> - <li>Moral support: developers live for recognition of the positive - impact their work has on users' lives. Give thanks to the developers - when evangelising the project, or when meeting them at user groups, - conferences, etc.</li> - </ul> - - <p> - The above is not an exhaustive list of things users can do to - participate in the project. Further ideas and suggestions are - welcome. Users are encouraged to take their participation - further and become contributors to the project in any of the - ways listed in the next section. - </p> - - <h3><a id="contributors">Contributors</a></h3> - - <p> - The contributors are community members who have some concrete impact - to the ongoing development of the project. There are many ways in which - members can contribute, with no requirement to be a software engineer. - Many users can in fact consider themselves contributors merely by - engaging in evangelism for the project. - </p> - - <ul> - <li>Bug reporting: improve the quality of the project by reporting - any problems found either to the project's own bug tracker, or to - that of the OS vendor shipping the libvirt code.</li> - <li>User help: join the <a href="contact.html">IRC channel or mailing list</a> - to assist or advice other users in troubleshooting the problems they face.</li> - <li>Feature requests: help set the direction for future work by - reporting details of features which are missing to the project's - own bug tracker or mailing lists.</li> - <li>Graphical design: contribute to the development of the project's - websites / wiki brand with improved graphics, styling or layout.</li> - <li>Code development: write and submit patches to address bugs or implement - new features</li> - <li>Architectural design: improve the usefulness of the project - by providing feedback on the design of proposed features, to - ensure they satisfy the broadest applicable needs and survive - the long term</li> - <li>Code review: look at patches which are submitted and critique - the code to identify bugs, potential design problems or other - issues which should be addressed before the code is accepted</li> - <li>Documentation: contribute to content on personal blogs, the - website, wiki, code comments, or any of the formal documentation - efforts.</li> - <li>Translation: join the Fedora transifex community to improve the - quality of translations needed by the libvirt project.</li> - <li>Testing: try proposed patches or release candidates and report - whether the build passes and the changes work as expected.</li> - </ul> - - <p> - The above is not an exhaustive list of things members can do to - contribute to the project. Further ideas and suggestions are - welcome. - </p> - - <p> - There are no special requirements to becoming a contributor other - than having the interest and ability to provide a contribution. The - libvirt project <strong>does not require</strong> any - <em>"Contributor License Agreement"</em> - to be signed prior to engagement with the community. However for - contributing patches, providing a 'Signed-off-by' line with the - author's legal name and e-mail address to demonstrate agreement - and compliance with the <a href="https://developercertificate.org/"> - Developer Certificate of Origin</a> is required. - </p> - - <p> - In making a non-patch contribution to the project, the community - member is implicitly stating that they accept the terms of the license - under which the work they are contributing to is distributed. They are - also implicitly stating that they have the legal right to make the - contribution, if doing so on behalf of a broader organization / - company. Most of the project's code is distributed under the GNU - Lesser General Public License, version 2.1 or later. Details of the - exact license under which contributions will be presumed to be - covered are found in the source repositories, or website in question. - </p> - - <h3><a id="committers">Committers</a></h3> - - <p> - The committers are the subset of contributors who have direct access - to commit code to the project's primary source code repositories, which - are currently using the GIT software. The committers are chosen based - on the quality of their contributions over a period of time. This includes - both the quality of code they submit, as well as the quality of reviews - they provide on other contributors' submissions and a demonstration that - they understand day-to-day operation of the project and its goals. There - is no minimum level of contribution required in order to become a committer, - though 2-3 months worth of quality contribution would be a rough guide. - </p> - - <p> - There are no special requirements to becoming a committer other than to - have shown a willingness and ability to contribute to the project over - an extended period of time. Proposals for elevating contributors to - committers are typically made by existing committers, though contributors - are also welcome to make proposals. The decision to approve the elevation - of a contributor to a committer is made through "rough consensus" between - the existing committers. - </p> - - <p> - The aim in elevating contributors to committers is to ensure that there - is a broad base of experience and expertize across all areas of the - project's work. Committers are not required to have knowledge across - all areas of the project's work. While an approved committer has the - technical ability to commit code to any area of the project, by convention - they will only commit to areas they feel themselves to be qualified to - evaluate the contribution. If in doubt, committers will defer to the - opinion of other committers with greater expertize in an area. - </p> - - <p> - The committers hold the ultimate control over what contributions are - accepted by the project, however, this does not mean they have the - right to do whatever they want. Where there is debate and disagreement - between contributors, committers are expected to look at the issues with - an unbiased point of view and help achieve a "rough consensus". If the - committer has a conflict of interest in the discussion, for example due - to their position of employment, they are expected to put the needs of - the community project first. If they cannot put the community project - first, they must declare their conflict of interest, and allow other - non-conflicted committers to make any final decision. - </p> - - <p> - The committers are expected to monitor contributions to areas of the - project where they have expertize and ensure that either some form of - feedback is provided to the contributor, or to accept their contribution. - There is no formal minimum level of approval required to accept a - contribution. Positive review by any committer experienced in the area - of work is considered to be enough to justify acceptance in normal - circumstances. Where one committer explicitly rejects a contribution, - however, other committers should not override that rejection without - first establishing a "rough consensus" amongst the broader group of - committers. - </p> - - <p> - Being a committer is a privilege, not a right. In exceptional - circumstances, the privilege may be removed from an active - contributor. Such decisions will be taken based on "rough - consensus" amongst other committers. In the event that a committer - is no longer able to participate in the project, after some period - of inactivity passes, they may be asked to confirm that they wish - to retain their role as a committer. - </p> - - <h3><a id="secteam">Security team</a></h3> - - <p> - The security team consists of a subset of the project committers - along with representatives from vendors shipping the project's - software. The subset of project committers is chosen to be the - minimal size necessary to provide expertise spanning most of - the project's work. Further project committers may be requested - to engage in resolving specific security issues on a case by - case basis. Any vendor who is shipping the project's software - may submit a request for one or more of their representatives - to join the security team. Such requests must by approved by - existing members of the team vouching for the integrity of - the nominated person or organization. - </p> - - <p> - Members of the security team are responsible for triaging and - resolving any security issues that are reported to the project. - They are expected to abide by the project's documented - <a href="securityprocess.html">security process</a>. In particular - they must respect any embargo period agreed amongst the team - before disclosing a private issue. - </p> - - <h2><a id="roughconsensus">Rough consensus</a></h2> - - <p> - A core concept for governance of the project described above is - that of "rough consensus". To expand on this, it is a process - of decision making that involves the following steps - </p> - - <ul> - <li>Proposal</li> - <li>Discussion</li> - <li>Vote (exceptional circumstances only)</li> - <li>Decision</li> - </ul> - - <p> - To put this into words, any contributor is welcome to make a proposal - for consideration. Any contributor may participate in the discussions - around the proposal. The discussion will usually result in agreement - between the interested parties, or at least agreement between the - committers. Only in the very exceptional circumstance where there - is disagreement between committers, would a vote be considered. - Even in these exceptional circumstances, it is usually found to be - obvious what the majority opinion of the committers is. In the event - that even a formal vote is tied, the committers will have to hold - ongoing discussions until the stalemate is resolved or the proposal - withdrawn. - </p> - - <p> - The overall goal of the "rough consensus" process is to ensure that - decisions can be made within the project, with a minimum level of - bureaucracy and process. Implicit in this is that any person who does - not explicitly reject to a proposal is assumed to be supportive, or - at least agnostic. - </p> - - - </body> -</html> diff --git a/docs/governance.rst b/docs/governance.rst new file mode 100644 index 0000000000..df90ce678d --- /dev/null +++ b/docs/governance.rst @@ -0,0 +1,232 @@ +.. role:: anchor(raw) + :format: html + +================== +Project governance +================== + +.. contents:: + +The libvirt project operates as a meritocratic, consensus-based community. +Anyone with an interest in the project can join the community, contributing to +the ongoing development of the project's work. This pages describes how that +participation takes place and how contributors earn merit, and thus influence, +within the community. + +:anchor:`<a id="codeofconduct"/>` + +Code of conduct +--------------- + +The libvirt project community covers people from a wide variety of countries, +backgrounds and positions. This global diversity is a great strength of the +project, but can also lead to communication issues, which may in turn cause +unhappiness. To maximise happiness of the project community taken as a whole, +all members (whether users, contributors or committers) are expected to abide by +the project's code of conduct. At a high level the code can be summarized as +*"be excellent to each other"*. Expanding on this: + +- **Be respectful:** disagreements between people are to be expected and are + usually the sign of healthy debate and engagement. Disagreements can lead to + frustration and even anger for some members. Turning to personal insults, + intimidation or threatening behaviour does not improve the situation though. + Participants should thus take care to ensure all communications / + interactions stay professional at all times. +- **Be considerate:** remember that the community has members with a diverse + background many of whom have English as a second language. What might appear + impolite, may simply be a result of a lack of knowledge of the English + language. Bear in mind that actions will have an impact on other community + members and the project as a whole, so take potential consequences into + account before pursuing a course of action. +- **Be forgiving:** humans are fallible and as such prone to make mistakes and + inexplicably change their positions at times. Don't assume that other members + are acting with malicious intent. Be prepared to forgive people who make + mistakes and assist each other in learning from them. Playing a blame game + doesn't help anyone. + +Roles and responsibilities +-------------------------- + +Users +~~~~~ + +The users are anyone who has a need for the output of the project. There are no +rules or requirements to become a user of libvirt. Even if the software does not +yet work on their OS platform, a person can be considered a potential future +user and welcomed to participate. + +Participation by users is key to ensuring the project moves in the right +direction, satisfying their real world needs. Users are encouraged to +participate in the broader libvirt community in any number of ways: + +- Evangelism: spread the word about what libvirt is doing, how it helps solve + your problems. This can be via blog articles, social media postings, video + blogs, user group / conference presentations and any other method of + disseminating information +- Feedback: let the developers know about what does and does not work with the + project. Talk to developers on the project's IRC channel and mailing list, or + find them at conferences. Tell them what gaps the project has or where they + should look for future development +- Moral support: developers live for recognition of the positive impact their + work has on users' lives. Give thanks to the developers when evangelising the + project, or when meeting them at user groups, conferences, etc. + +The above is not an exhaustive list of things users can do to participate in the +project. Further ideas and suggestions are welcome. Users are encouraged to take +their participation further and become contributors to the project in any of the +ways listed in the next section. + +Contributors +~~~~~~~~~~~~ + +The contributors are community members who have some concrete impact to the +ongoing development of the project. There are many ways in which members can +contribute, with no requirement to be a software engineer. Many users can in +fact consider themselves contributors merely by engaging in evangelism for the +project. + +- Bug reporting: improve the quality of the project by reporting any problems + found either to the project's own bug tracker, or to that of the OS vendor + shipping the libvirt code. +- User help: join the `IRC channel or mailing list <contact.html>`__ to assist + or advice other users in troubleshooting the problems they face. +- Feature requests: help set the direction for future work by reporting details + of features which are missing to the project's own bug tracker or mailing + lists. +- Graphical design: contribute to the development of the project's websites / + wiki brand with improved graphics, styling or layout. +- Code development: write and submit patches to address bugs or implement new + features +- Architectural design: improve the usefulness of the project by providing + feedback on the design of proposed features, to ensure they satisfy the + broadest applicable needs and survive the long term +- Code review: look at patches which are submitted and critique the code to + identify bugs, potential design problems or other issues which should be + addressed before the code is accepted +- Documentation: contribute to content on personal blogs, the website, wiki, + code comments, or any of the formal documentation efforts. +- Translation: join the Fedora transifex community to improve the quality of + translations needed by the libvirt project. +- Testing: try proposed patches or release candidates and report whether the + build passes and the changes work as expected. + +The above is not an exhaustive list of things members can do to contribute to +the project. Further ideas and suggestions are welcome. + +There are no special requirements to becoming a contributor other than having +the interest and ability to provide a contribution. The libvirt project **does +not require** any *"Contributor License Agreement"* to be signed prior to +engagement with the community. However for contributing patches, providing a +'Signed-off-by' line with the author's legal name and e-mail address to +demonstrate agreement and compliance with the `Developer Certificate of +Origin <https://developercertificate.org/>`__ is required. + +In making a non-patch contribution to the project, the community member is +implicitly stating that they accept the terms of the license under which the +work they are contributing to is distributed. They are also implicitly stating +that they have the legal right to make the contribution, if doing so on behalf +of a broader organization / company. Most of the project's code is distributed +under the GNU Lesser General Public License, version 2.1 or later. Details of +the exact license under which contributions will be presumed to be covered are +found in the source repositories, or website in question. + +Committers +~~~~~~~~~~ + +The committers are the subset of contributors who have direct access to commit +code to the project's primary source code repositories, which are currently +using the GIT software. The committers are chosen based on the quality of their +contributions over a period of time. This includes both the quality of code they +submit, as well as the quality of reviews they provide on other contributors' +submissions and a demonstration that they understand day-to-day operation of the +project and its goals. There is no minimum level of contribution required in +order to become a committer, though 2-3 months worth of quality contribution +would be a rough guide. + +There are no special requirements to becoming a committer other than to have +shown a willingness and ability to contribute to the project over an extended +period of time. Proposals for elevating contributors to committers are typically +made by existing committers, though contributors are also welcome to make +proposals. The decision to approve the elevation of a contributor to a committer +is made through "rough consensus" between the existing committers. + +The aim in elevating contributors to committers is to ensure that there is a +broad base of experience and expertize across all areas of the project's work. +Committers are not required to have knowledge across all areas of the project's +work. While an approved committer has the technical ability to commit code to +any area of the project, by convention they will only commit to areas they feel +themselves to be qualified to evaluate the contribution. If in doubt, committers +will defer to the opinion of other committers with greater expertize in an area. + +The committers hold the ultimate control over what contributions are accepted by +the project, however, this does not mean they have the right to do whatever they +want. Where there is debate and disagreement between contributors, committers +are expected to look at the issues with an unbiased point of view and help +achieve a "rough consensus". If the committer has a conflict of interest in the +discussion, for example due to their position of employment, they are expected +to put the needs of the community project first. If they cannot put the +community project first, they must declare their conflict of interest, and allow +other non-conflicted committers to make any final decision. + +The committers are expected to monitor contributions to areas of the project +where they have expertize and ensure that either some form of feedback is +provided to the contributor, or to accept their contribution. There is no formal +minimum level of approval required to accept a contribution. Positive review by +any committer experienced in the area of work is considered to be enough to +justify acceptance in normal circumstances. Where one committer explicitly +rejects a contribution, however, other committers should not override that +rejection without first establishing a "rough consensus" amongst the broader +group of committers. + +Being a committer is a privilege, not a right. In exceptional circumstances, the +privilege may be removed from an active contributor. Such decisions will be +taken based on "rough consensus" amongst other committers. In the event that a +committer is no longer able to participate in the project, after some period of +inactivity passes, they may be asked to confirm that they wish to retain their +role as a committer. + +Security team +~~~~~~~~~~~~~ + +The security team consists of a subset of the project committers along with +representatives from vendors shipping the project's software. The subset of +project committers is chosen to be the minimal size necessary to provide +expertise spanning most of the project's work. Further project committers may be +requested to engage in resolving specific security issues on a case by case +basis. Any vendor who is shipping the project's software may submit a request +for one or more of their representatives to join the security team. Such +requests must by approved by existing members of the team vouching for the +integrity of the nominated person or organization. + +Members of the security team are responsible for triaging and resolving any +security issues that are reported to the project. They are expected to abide by +the project's documented `security process <securityprocess.html>`__. In +particular they must respect any embargo period agreed amongst the team before +disclosing a private issue. + +Rough consensus +--------------- + +A core concept for governance of the project described above is that of "rough +consensus". To expand on this, it is a process of decision making that involves +the following steps + +- Proposal +- Discussion +- Vote (exceptional circumstances only) +- Decision + +To put this into words, any contributor is welcome to make a proposal for +consideration. Any contributor may participate in the discussions around the +proposal. The discussion will usually result in agreement between the interested +parties, or at least agreement between the committers. Only in the very +exceptional circumstance where there is disagreement between committers, would a +vote be considered. Even in these exceptional circumstances, it is usually found +to be obvious what the majority opinion of the committers is. In the event that +even a formal vote is tied, the committers will have to hold ongoing discussions +until the stalemate is resolved or the proposal withdrawn. + +The overall goal of the "rough consensus" process is to ensure that decisions +can be made within the project, with a minimum level of bureaucracy and process. +Implicit in this is that any person who does not explicitly reject to a proposal +is assumed to be supportive, or at least agnostic. diff --git a/docs/meson.build b/docs/meson.build index ab020ab090..08c324a74b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -50,7 +50,6 @@ docs_html_in_files = [ 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', - 'governance', 'hooks', 'index', 'internals', @@ -98,6 +97,7 @@ docs_rst_files = [ 'formatstorage', 'glib-adoption', 'goals', + 'governance', 'hacking', 'libvirt-go', 'libvirt-go-xml', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Extra care is taken to preserve the 'codeofconduct' anchor which is used in our page template. Upcoming patch will change that but we'll retain the anchor.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/governance.html.in | 298 ---------------------------------------- docs/governance.rst | 232 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 233 insertions(+), 299 deletions(-) delete mode 100644 docs/governance.html.in create mode 100644 docs/governance.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Use the anchor name as generated by rst2html. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/page.xsl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/page.xsl b/docs/page.xsl index 72a6fa0842..a6a270896c 100644 --- a/docs/page.xsl +++ b/docs/page.xsl @@ -187,7 +187,7 @@ </div> </xsl:if> <div id="conduct"> - Participants in the libvirt project agree to abide by <a href="{$href_base}governance.html#codeofconduct">the project code of conduct</a> + Participants in the libvirt project agree to abide by <a href="{$href_base}governance.html#code-of-conduct">the project code of conduct</a> </div> <br class="clear"/> </div> -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Use the anchor name as generated by rst2html.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/page.xsl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drivers.html.in | 44 -------------------------------------------- docs/drivers.rst | 31 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 32 insertions(+), 45 deletions(-) delete mode 100644 docs/drivers.html.in create mode 100644 docs/drivers.rst diff --git a/docs/drivers.html.in b/docs/drivers.html.in deleted file mode 100644 index 824604998e..0000000000 --- a/docs/drivers.html.in +++ /dev/null @@ -1,44 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Internal drivers</h1> - - <ul> - <li><a href="#hypervisor">Hypervisor drivers</a></li> - <li><a href="storage.html">Storage drivers</a></li> - <li><a href="drvnodedev.html">Node device driver</a></li> - <li><a href="drvsecret.html">Secret driver</a></li> - </ul> - - <p> - The libvirt public API delegates its implementation to one or - more internal drivers, depending on the <a href="uri.html">connection URI</a> - passed when initializing the library. There is always a hypervisor driver - active, and if the libvirt daemon is available there will usually be a - network and storage driver active. - </p> - - <h2><a id="hypervisor">Hypervisor drivers</a></h2> - - <p> - The hypervisor drivers currently supported by libvirt are: - </p> - - <ul> - <li><strong><a href="drvlxc.html">LXC</a></strong> - Linux Containers</li> - <li><strong><a href="drvopenvz.html">OpenVZ</a></strong></li> - <li><strong><a href="drvqemu.html">QEMU</a></strong></li> - <li><strong><a href="drvtest.html">Test</a></strong> - Used for testing</li> - <li><strong><a href="drvvbox.html">VirtualBox</a></strong></li> - <li><strong><a href="drvesx.html">VMware ESX</a></strong></li> - <li><strong><a href="drvvmware.html">VMware Workstation/Player</a></strong></li> - <li><strong><a href="drvxen.html">Xen</a></strong></li> - <li><strong><a href="drvhyperv.html">Microsoft Hyper-V</a></strong></li> - <li><strong><a href="drvvirtuozzo.html">Virtuozzo</a></strong></li> - <li><strong><a href="drvbhyve.html">Bhyve</a></strong> - The BSD Hypervisor</li> - <li><strong><a href="drvch.html">Cloud Hypervisor</a></strong></li> - </ul> - - </body> -</html> diff --git a/docs/drivers.rst b/docs/drivers.rst new file mode 100644 index 0000000000..b72266e876 --- /dev/null +++ b/docs/drivers.rst @@ -0,0 +1,31 @@ +================ +Internal drivers +================ + +- `Hypervisor drivers <#hypervisor-drivers>`__ +- `Storage drivers <storage.html>`__ +- `Node device driver <drvnodedev.html>`__ +- `Secret driver <drvsecret.html>`__ + +The libvirt public API delegates its implementation to one or more internal +drivers, depending on the `connection URI <uri.html>`__ passed when initializing +the library. There is always a hypervisor driver active, and if the libvirt +daemon is available there will usually be a network and storage driver active. + +Hypervisor drivers +------------------ + +The hypervisor drivers currently supported by libvirt are: + +- `LXC <drvlxc.html>`__ - Linux Containers +- `OpenVZ <drvopenvz.html>`__ +- `QEMU <drvqemu.html>`__ +- `Test <drvtest.html>`__ - Used for testing +- `VirtualBox <drvvbox.html>`__ +- `VMware ESX <drvesx.html>`__ +- `VMware Workstation/Player <drvvmware.html>`__ +- `Xen <drvxen.html>`__ +- `Microsoft Hyper-V <drvhyperv.html>`__ +- `Virtuozzo <drvvirtuozzo.html>`__ +- `Bhyve <drvbhyve.html>`__ - The BSD Hypervisor +- `Cloud Hypervisor <drvch.html>`__ diff --git a/docs/meson.build b/docs/meson.build index 08c324a74b..fce6533301 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -25,7 +25,6 @@ docs_html_in_files = [ 'dbus', 'docs', 'downloads', - 'drivers', 'drvbhyve', 'drvesx', 'drvhyperv', @@ -87,6 +86,7 @@ docs_rst_files = [ 'contribute', 'daemons', 'developer-tooling', + 'drivers', 'drvqemu', 'drvch', 'errors', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/drivers.html.in | 44 -------------------------------------------- docs/drivers.rst | 31 +++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 32 insertions(+), 45 deletions(-) delete mode 100644 docs/drivers.html.in create mode 100644 docs/drivers.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Also update the link from 'formatstorageencryption' to the 'usage-type-volume' anchor. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.html.in | 414 --------------------------- docs/formatsecret.rst | 337 ++++++++++++++++++++++ docs/formatstorageencryption.html.in | 2 +- docs/meson.build | 2 +- 4 files changed, 339 insertions(+), 416 deletions(-) delete mode 100644 docs/formatsecret.html.in create mode 100644 docs/formatsecret.rst diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in deleted file mode 100644 index 9dc9cdf288..0000000000 --- a/docs/formatsecret.html.in +++ /dev/null @@ -1,414 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml"> - <body> - <h1>Secret XML format</h1> - - <ul id="toc"></ul> - - <h2><a id="SecretAttributes">Secret XML</a></h2> - - <p> - Secrets stored by libvirt may have attributes associated with them, using - the <code>secret</code> element. The <code>secret</code> element has two - optional attributes, each with values '<code>yes</code>' and - '<code>no</code>', and defaulting to '<code>no</code>': - </p> - <dl> - <dt><code>ephemeral</code></dt> - <dd>This secret must only be kept in memory, never stored persistently. - </dd> - <dt><code>private</code></dt> - <dd>The value of the secret must not be revealed to any caller of libvirt, - nor to any other node. - </dd> - </dl> - <p> - The top-level <code>secret</code> element may contain the following - elements: - </p> - <dl> - <dt><code>uuid</code></dt> - <dd> - An unique identifier for this secret (not necessarily in the UUID - format). If omitted when defining a new secret, a random UUID is - generated. - </dd> - <dt><code>description</code></dt> - <dd>A human-readable description of the purpose of the secret. - </dd> - <dt><code>usage</code></dt> - <dd> - Specifies what this secret is used for. A mandatory - <code>type</code> attribute specifies the usage category, currently - only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>, - <code>tls</code>, and <code>vtpm</code> are defined. Specific usage - categories are described below. - </dd> - </dl> - - <h3><a id="VolumeUsageType">Usage type "volume"</a></h3> - - <p> - This secret is associated with a volume, whether the format is either - for a "luks" encrypted volume. Each volume will have a - unique secret associated with it and it is safe to delete the - secret after the volume is deleted. The - <code><usage type='volume'></code> element must contain a - single <code>volume</code> element that specifies the path of the volume - this secret is associated with. For example, create a volume-secret.xml - file as follows: - </p> - - <pre> -<secret ephemeral='no' private='yes'> - <description>Super secret name of my first puppy</description> - <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> - <usage type='volume'> - <volume>/var/lib/libvirt/images/puppyname.img</volume> - </usage> -</secret> - </pre> - - <p> - Define the secret and set the passphrase as follows: - </p> - <pre> -# virsh secret-define volume-secret.xml -Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created - </pre> - - <p> - See <a href="#settingSecrets">virsh secret-set-value</a> on how - to set the value of the secret. - </p> - - <p> - The volume type secret can be supplied either in volume XML during - creation of a <a href="formatstorage.html#StorageVol">storage volume</a> - in order to provide the passphrase to encrypt the volume or in - domain XML <a href="formatdomain.html#elementsDisks">disk device</a> - in order to provide the passphrase to decrypt the volume, - <span class="since">since 2.1.0</span>. An example follows: - </p> - <pre> -# cat luks-secret.xml -<secret ephemeral='no' private='yes'> - <description>LUKS Sample Secret</description> - <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid> - <usage type='volume'> - <volume>/var/lib/libvirt/images/luks-sample.img</volume> - </usage> -</secret> - -# virsh secret-define luks-secret.xml -Secret f52a81b2-424e-490c-823d-6bd4235bc57 created - </pre> - <p> - See <a href="#settingSecrets">virsh secret-set-value</a> on how - to set the value of the secret. - </p> - - <p> - The volume type secret can be supplied in domain XML for a luks storage - volume <a href="formatstorageencryption.html">encryption</a> as follows: - </p> - <pre> -<encryption format='luks'> - <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/> -</encryption> - </pre> - - <h3><a id="CephUsageType">Usage type "ceph"</a></h3> - <p> - This secret is associated with a Ceph RBD (rados block device). - The <code><usage type='ceph'></code> element must contain - a single <code>name</code> element that specifies a usage name - for the secret. The Ceph secret can then be used by UUID or by - this usage name via the <code><auth></code> element of - a <a href="formatdomain.html#elementsDisks">disk device</a> or - a <a href="formatstorage.html">storage pool (rbd)</a>. - <span class="since">Since 0.9.7</span>. The following is an example - of the steps to be taken. First create a ceph-secret.xml file: - </p> - - <pre> -<secret ephemeral='no' private='yes'> - <description>CEPH passphrase example</description> - <usage type='ceph'> - <name>ceph_example</name> - </usage> -</secret> - </pre> - - <p> - Next, use <code>virsh secret-define ceph-secret.xml</code> to define - the secret and <code>virsh secret-set-value</code> using the generated - UUID value and a base64 generated secret value in order to define the - chosen secret pass phrase. - </p> - <pre> -# virsh secret-define ceph-secret.xml -Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created -# -# virsh secret-list - UUID Usage ------------------------------------------------------------ - 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example - </pre> - <p> - See <a href="#settingSecrets">virsh secret-set-value</a> on how - to set the value of the secret. - </p> - - <p> - The ceph secret can then be used by UUID or by the - usage name via the <code><auth></code> element in a domain's - <a href="formatdomain.html#elementsDisks"><code><disk></code></a> - element as follows: - </p> - <pre> -<auth username='myname'> - <secret type='ceph' usage='ceph_example'/> -</auth> - </pre> - - <p> - As well as the <code><auth></code> element in a - <a href="formatstorage.html">storage pool (rbd)</a> - <code><source></code> element as follows: - </p> - <pre> -<auth type='ceph' username='myname'> - <secret usage='ceph_example'/> -</auth> - </pre> - - <h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3> - - <p> - This secret is associated with an iSCSI target for CHAP authentication. - The <code><usage type='iscsi'></code> element must contain - a single <code>target</code> element that specifies a usage name - for the secret. The iSCSI secret can then be used by UUID or by - this usage name via the <code><auth></code> element of - a <a href="formatdomain.html#elementsDisks">disk device</a> or - a <a href="formatstorage.html">storage pool (iscsi)</a>. - <span class="since">Since 1.0.4</span>. The following is an example - of the XML that may be used to generate a secret for iSCSI CHAP - authentication. Assume the following sample entry in an iSCSI - authentication file: - </p> - <pre> -<target iqn.2013-07.com.example:iscsi-pool> -backing-store /home/tgtd/iscsi-pool/disk1 -backing-store /home/tgtd/iscsi-pool/disk2 -incominguser myname mysecret -</target> - </pre> - <p> - Define an iscsi-secret.xml file to describe the secret. Use the - <code>incominguser</code> username used in your iSCSI authentication - configuration file as the value for the <code>username</code> attribute. - The <code>description</code> attribute should contain configuration - specific data. The <code>target</code> name may be any name of your - choosing to be used as the <code>usage</code> when used in the pool - or disk XML description. - </p> - <pre> -<secret ephemeral='no' private='yes'> - <description>Passphrase for the iSCSI example.com server</description> - <usage type='iscsi'> - <target>libvirtiscsi</target> - </usage> -</secret> - </pre> - - <p> - Next, use <code>virsh secret-define iscsi-secret.xml</code> to define - the secret and - <code><a href="#settingSecrets">virsh secret-set-value</a></code> - using the generated - UUID value and a base64 generated secret value in order to define the - chosen secret pass phrase. The pass phrase must match the password - used in the iSCSI authentication configuration file. - </p> - <pre> -# virsh secret-define secret.xml -Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created - -# virsh secret-list - UUID Usage ------------------------------------------------------------ - c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi - - </pre> - - <p> - See <a href="#settingSecrets">virsh secret-set-value</a> on how - to set the value of the secret. - </p> - - <p> - The iSCSI secret can then be used by UUID or by the - usage name via the <code><auth></code> element in a domain's - <a href="formatdomain.html#elementsDisks"><code><disk></code></a> - element as follows: - </p> - <pre> -<auth username='myname'> - <secret type='iscsi' usage='libvirtiscsi'/> -</auth> - </pre> - - <p> - As well as the <code><auth></code> element in a - <a href="formatstorage.html">storage pool (iscsi)</a> - <code><source></code> element as follows: - </p> - <pre> -<auth type='chap' username='myname'> - <secret usage='libvirtiscsi'/> -</auth> - </pre> - - <h3><a id="tlsUsageType">Usage type "tls"</a></h3> - - <p> - This secret may be used in order to provide the passphrase for the - private key used to provide TLS credentials. - The <code><usage type='tls'></code> element must contain a - single <code>name</code> element that specifies a usage name - for the secret. - <span class="since">Since 2.3.0</span>. - The following is an example of the expected XML and processing to - define the secret: - </p> - - <pre> -# cat tls-secret.xml -<secret ephemeral='no' private='yes'> - <description>sample tls secret</description> - <usage type='tls'> - <name>TLS_example</name> - </usage> -</secret> - -# virsh secret-define tls-secret.xml -Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created - -# virsh secret-list - UUID Usage ------------------------------------------------------------ - 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example -# - - </pre> - - <p> - A secret may also be defined via the - <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML"> - <code>virSecretDefineXML</code></a> API. - - Once the secret is defined, a secret value will need to be set. The - secret would be the passphrase used to access the TLS credentials. - The following is a simple example of using - <code><a href="#settingSecrets">virsh secret-set-value</a></code> to set - the secret value. The - <a href="html/libvirt-libvirt-secret.html#virSecretSetValue"> - <code>virSecretSetValue</code></a> API may also be used to set - a more secure secret without using printable/readable characters. - </p> - - <h3><a id="vTPMUsageType">Usage type "vtpm"</a></h3> - - <p> - This secret is associated with a virtualized TPM (vTPM) and serves - as a passphrase for deriving a key from for encrypting the state - of the vTPM. - The <code><usage type='vtpm'></code> element must contain - a single <code>name</code> element that specifies a usage name - for the secret. The vTPM secret can then be used by UUID - via the <code><encryption></code> element of - a <a href="formatdomain.html#elementsTpm">tpm</a> when using an - emulator. - <span class="since">Since 5.6.0</span>. The following is an example - of the steps to be taken. First create a vtpm-secret.xml file: </p> - - <pre> -# cat vtpm-secret.xml -<secret ephemeral='no' private='yes'> - <description>sample vTPM secret</description> - <usage type='vtpm'> - <name>VTPM_example</name> - </usage> -</secret> - -# virsh secret-define vtpm-secret.xml -Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created - -# virsh secret-list - UUID Usage ----------------------------------------------------------------------------------------- - 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example - -# - - </pre> - - <p> - A secret may also be defined via the - <a href="html/libvirt-libvirt-secret.html#virSecretDefineXML"> - <code>virSecretDefineXML</code></a> API. - - Once the secret is defined, a secret value will need to be set. The - secret would be the passphrase used to decrypt the vTPM state. - The following is a simple example of using - <code><a href="#settingSecrets">virsh secret-set-value</a></code> - to set the secret value. The - <a href="html/libvirt-libvirt-secret.html#virSecretSetValue"> - <code>virSecretSetValue</code></a> API may also be used to set - a more secure secret without using printable/readable characters. - </p> - - <h2><a id="settingSecrets">Setting secret values in virsh</a></h2> - - <p> - To set the value of the secret you can use the following virsh commands. - If the secret is a password-like string (printable characters, no newline) - you can use: - </p> - <pre> -# virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935 -Enter new value for secret: -Secret value set - </pre> - - <p> - Another secure option is to read the secret from a file. This way the - secret can contain any bytes (even NUL and non-printable characters). The - length of the secret is the length of the input file. Alternatively the - <code>--plain</code> option can be omitted if the file contents are - base64-encoded. - </p> - - <pre> -# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile -Secret value set - </pre> - - <p> - <b>WARNING</b> The following approach is <b>insecure</b> 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. - </p> - - <pre> -# MYSECRET=`printf %s "open sesame" | base64` -# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET -Secret value set - </pre> - - </body> -</html> diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst new file mode 100644 index 0000000000..a3ffb7c4b9 --- /dev/null +++ b/docs/formatsecret.rst @@ -0,0 +1,337 @@ +.. role:: since + +================= +Secret XML format +================= + +.. contents:: + +Secret XML +---------- + +Secrets stored by libvirt may have attributes associated with them, using the +``secret`` element. The ``secret`` element has two optional attributes, each +with values '``yes``' and '``no``', and defaulting to '``no``': + +``ephemeral`` + This secret must only be kept in memory, never stored persistently. +``private`` + The value of the secret must not be revealed to any caller of libvirt, nor to + any other node. + +The top-level ``secret`` element may contain the following elements: + +``uuid`` + An unique identifier for this secret (not necessarily in the UUID format). If + omitted when defining a new secret, a random UUID is generated. +``description`` + A human-readable description of the purpose of the secret. +``usage`` + Specifies what this secret is used for. A mandatory ``type`` attribute + specifies the usage category, currently only ``volume``, ``ceph``, ``iscsi``, + ``tls``, and ``vtpm`` are defined. Specific usage categories are described + below. + +Usage type "volume" +~~~~~~~~~~~~~~~~~~~ + +This secret is associated with a volume, whether the format is either for a +"luks" encrypted volume. Each volume will have a unique secret associated with +it and it is safe to delete the secret after the volume is deleted. The +``<usage type='volume'>`` element must contain a single ``volume`` element that +specifies the path of the volume this secret is associated with. For example, +create a volume-secret.xml file as follows: + +:: + + <secret ephemeral='no' private='yes'> + <description>Super secret name of my first puppy</description> + <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/puppyname.img</volume> + </usage> + </secret> + +Define the secret and set the passphrase as follows: + +:: + + # virsh secret-define volume-secret.xml + Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created + +See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the +secret. + +The volume type secret can be supplied either in volume XML during creation of a +`storage volume <formatstorage.html#StorageVol>`__ in order to provide the +passphrase to encrypt the volume or in domain XML `disk +device <formatdomain.html#elementsDisks>`__ in order to provide the passphrase +to decrypt the volume, :since:`since 2.1.0` . An example follows: + +:: + + # cat luks-secret.xml + <secret ephemeral='no' private='yes'> + <description>LUKS Sample Secret</description> + <uuid>f52a81b2-424e-490c-823d-6bd4235bc57</uuid> + <usage type='volume'> + <volume>/var/lib/libvirt/images/luks-sample.img</volume> + </usage> + </secret> + + # virsh secret-define luks-secret.xml + Secret f52a81b2-424e-490c-823d-6bd4235bc57 created + +See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the +secret. + +The volume type secret can be supplied in domain XML for a luks storage volume +`encryption <formatstorageencryption.html>`__ as follows: + +:: + + <encryption format='luks'> + <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/> + </encryption> + +Usage type "ceph" +~~~~~~~~~~~~~~~~~ + +This secret is associated with a Ceph RBD (rados block device). The +``<usage type='ceph'>`` element must contain a single ``name`` element that +specifies a usage name for the secret. The Ceph secret can then be used by UUID +or by this usage name via the ``<auth>`` element of a `disk +device <formatdomain.html#elementsDisks>`__ or a `storage pool +(rbd) <formatstorage.html>`__. :since:`Since 0.9.7` . The following is an +example of the steps to be taken. First create a ceph-secret.xml file: + +:: + + <secret ephemeral='no' private='yes'> + <description>CEPH passphrase example</description> + <usage type='ceph'> + <name>ceph_example</name> + </usage> + </secret> + +Next, use ``virsh secret-define ceph-secret.xml`` to define the secret and +``virsh secret-set-value`` using the generated UUID value and a base64 generated +secret value in order to define the chosen secret pass phrase. + +:: + + # virsh secret-define ceph-secret.xml + Secret 1b40a534-8301-45d5-b1aa-11894ebb1735 created + # + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + 1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example + +See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the +secret. + +The ceph secret can then be used by UUID or by the usage name via the ``<auth>`` +element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ element as +follows: + +:: + + <auth username='myname'> + <secret type='ceph' usage='ceph_example'/> + </auth> + +As well as the ``<auth>`` element in a `storage pool +(rbd) <formatstorage.html>`__ ``<source>`` element as follows: + +:: + + <auth type='ceph' username='myname'> + <secret usage='ceph_example'/> + </auth> + +Usage type "iscsi" +~~~~~~~~~~~~~~~~~~ + +This secret is associated with an iSCSI target for CHAP authentication. The +``<usage type='iscsi'>`` element must contain a single ``target`` element that +specifies a usage name for the secret. The iSCSI secret can then be used by UUID +or by this usage name via the ``<auth>`` element of a `disk +device <formatdomain.html#elementsDisks>`__ or a `storage pool +(iscsi) <formatstorage.html>`__. :since:`Since 1.0.4` . The following is an +example of the XML that may be used to generate a secret for iSCSI CHAP +authentication. Assume the following sample entry in an iSCSI authentication +file: + +:: + + <target iqn.2013-07.com.example:iscsi-pool> + backing-store /home/tgtd/iscsi-pool/disk1 + backing-store /home/tgtd/iscsi-pool/disk2 + incominguser myname mysecret + </target> + +Define an iscsi-secret.xml file to describe the secret. Use the ``incominguser`` +username used in your iSCSI authentication configuration file as the value for +the ``username`` attribute. The ``description`` attribute should contain +configuration specific data. The ``target`` name may be any name of your +choosing to be used as the ``usage`` when used in the pool or disk XML +description. + +:: + + <secret ephemeral='no' private='yes'> + <description>Passphrase for the iSCSI example.com server</description> + <usage type='iscsi'> + <target>libvirtiscsi</target> + </usage> + </secret> + +Next, use ``virsh secret-define iscsi-secret.xml`` to define the secret and +``virsh secret-set-value`` using the generated UUID value and a base64 generated +secret value in order to define the chosen secret pass phrase. The pass phrase +must match the password used in the iSCSI authentication configuration file. + +:: + + # virsh secret-define secret.xml + Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created + + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi + + +See `virsh secret-set-value <#settingSecrets>`__ on how to set the value of the +secret. + +The iSCSI secret can then be used by UUID or by the usage name via the +``<auth>`` element in a domain's `<disk> <formatdomain.html#elementsDisks>`__ +element as follows: + +:: + + <auth username='myname'> + <secret type='iscsi' usage='libvirtiscsi'/> + </auth> + +As well as the ``<auth>`` element in a `storage pool +(iscsi) <formatstorage.html>`__ ``<source>`` element as follows: + +:: + + <auth type='chap' username='myname'> + <secret usage='libvirtiscsi'/> + </auth> + +Usage type "tls" +~~~~~~~~~~~~~~~~ + +This secret may be used in order to provide the passphrase for the private key +used to provide TLS credentials. The ``<usage type='tls'>`` element must contain +a single ``name`` element that specifies a usage name for the secret. +:since:`Since 2.3.0` . The following is an example of the expected XML and +processing to define the secret: + +:: + + # cat tls-secret.xml + <secret ephemeral='no' private='yes'> + <description>sample tls secret</description> + <usage type='tls'> + <name>TLS_example</name> + </usage> + </secret> + + # virsh secret-define tls-secret.xml + Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created + + # virsh secret-list + UUID Usage + ----------------------------------------------------------- + 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example + # + + +A secret may also be defined via the +`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__ +API. Once the secret is defined, a secret value will need to be set. The secret +would be the passphrase used to access the TLS credentials. The following is a +simple example of using ``virsh secret-set-value`` to set the secret value. The +`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API +may also be used to set a more secure secret without using printable/readable +characters. + +Usage type "vtpm" +~~~~~~~~~~~~~~~~~ + +This secret is associated with a virtualized TPM (vTPM) and serves as a +passphrase for deriving a key from for encrypting the state of the vTPM. The +``<usage type='vtpm'>`` element must contain a single ``name`` element that +specifies a usage name for the secret. The vTPM secret can then be used by UUID +via the ``<encryption>`` element of a `tpm <formatdomain.html#elementsTpm>`__ +when using an emulator. :since:`Since 5.6.0` . The following is an example of +the steps to be taken. First create a vtpm-secret.xml file: + +:: + + # cat vtpm-secret.xml + <secret ephemeral='no' private='yes'> + <description>sample vTPM secret</description> + <usage type='vtpm'> + <name>VTPM_example</name> + </usage> + </secret> + + # virsh secret-define vtpm-secret.xml + Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created + + # virsh secret-list + UUID Usage + ---------------------------------------------------------------------------------------- + 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example + + # + + +A secret may also be defined via the +`virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__ +API. Once the secret is defined, a secret value will need to be set. The secret +would be the passphrase used to decrypt the vTPM state. The following is a +simple example of using ``virsh secret-set-value`` to set the secret value. The +`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API +may also be used to set a more secure secret without using printable/readable +characters. + +Setting secret values in virsh +------------------------------ + +To set the value of the secret you can use the following virsh commands. If the +secret is a password-like string (printable characters, no newline) you can use: + +:: + + # virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935 + Enter new value for secret: + Secret value set + +Another secure option is to read the secret from a file. This way the secret can +contain any bytes (even NUL and non-printable characters). The length of the +secret is the length of the input file. Alternatively the ``--plain`` option can +be omitted if the file contents are base64-encoded. + +:: + + # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile + 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. + +:: + + # MYSECRET=`printf %s "open sesame" | base64` + # virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET + Secret value set diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in index c8c9f08d1e..395a7269b1 100644 --- a/docs/formatstorageencryption.html.in +++ b/docs/formatstorageencryption.html.in @@ -143,7 +143,7 @@ <h2><a id="example">Examples</a></h2> <p> - Assuming a <a href="formatsecret.html#VolumeUsageType"> + Assuming a <a href="formatsecret.html#usage-type-volume"> <code>luks volume type secret</code></a> is already defined, a simple example specifying use of the <code>luks</code> format for either volume creation without a specific cipher being defined or diff --git a/docs/meson.build b/docs/meson.build index fce6533301..f614bcadeb 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -46,7 +46,6 @@ docs_html_in_files = [ 'formatnetworkport', 'formatnode', 'formatnwfilter', - 'formatsecret', 'formatstoragecaps', 'formatstorageencryption', 'hooks', @@ -93,6 +92,7 @@ docs_rst_files = [ 'formatbackup', 'formatcheckpoint', 'formatdomain', + 'formatsecret', 'formatsnapshot', 'formatstorage', 'glib-adoption', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Also update the link from 'formatstorageencryption' to the 'usage-type-volume' anchor.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.html.in | 414 --------------------------- docs/formatsecret.rst | 337 ++++++++++++++++++++++ docs/formatstorageencryption.html.in | 2 +- docs/meson.build | 2 +- 4 files changed, 339 insertions(+), 416 deletions(-) delete mode 100644 docs/formatsecret.html.in create mode 100644 docs/formatsecret.rst
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
The examples contain some whitespace and command prompts which just waste space. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/formatsecret.rst b/docs/formatsecret.rst index a3ffb7c4b9..15b2a221d7 100644 --- a/docs/formatsecret.rst +++ b/docs/formatsecret.rst @@ -251,8 +251,6 @@ processing to define the secret: UUID Usage ----------------------------------------------------------- 718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example - # - A secret may also be defined via the `virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__ @@ -292,9 +290,6 @@ the steps to be taken. First create a vtpm-secret.xml file: ---------------------------------------------------------------------------------------- 6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example - # - - A secret may also be defined via the `virSecretDefineXML <html/libvirt-libvirt-secret.html#virSecretDefineXML>`__ API. Once the secret is defined, a secret value will need to be set. The secret -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
The examples contain some whitespace and command prompts which just waste space.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/formatsecret.rst | 5 ----- 1 file changed, 5 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index f614bcadeb..7146bd078b 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -39,9 +39,9 @@ docs_html_in_files = [ 'drvvmware', 'drvxen', 'firewall', + 'format', 'formatcaps', 'formatdomaincaps', - 'format', 'formatnetwork', 'formatnetworkport', 'formatnode', @@ -70,13 +70,13 @@ docs_html_in_files = [ docs_rst_files = [ 'aclpolkit', 'advanced-tests', - 'api_extension', 'api', + 'api_extension', 'apps', 'auditlog', 'auth', - 'bindings', 'best-practices', + 'bindings', 'bugs', 'ci', 'coding-style', @@ -86,8 +86,8 @@ docs_rst_files = [ 'daemons', 'developer-tooling', 'drivers', - 'drvqemu', 'drvch', + 'drvqemu', 'errors', 'formatbackup', 'formatcheckpoint', -- 2.35.1
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/meson.build | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (2)
-
Ján Tomko -
Peter Krempa