9:59 a.m.
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
9:59 a.m.
New subject: [PATCH 01/17] docs: Remove 'virshcmdref' page
The page isn't linked from anywhere and the project was archived.
Signed-off-by: Peter Krempa <pkrempa(a)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/">... 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_Referenc...>)
- (<a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...>)
- (<a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...>)
- </li>
- <li>
- HTML format, one long page
- (<a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...>)
- (<a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...>)
- (<a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...>)
- </li>
- <li>
- <a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...
format</a>
- </li>
- <li>
- <a
href="https://libvirt.org/sources/virshcmdref/Virsh_Command_Referenc...
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...;.
- </p>
-
- </body>
-</html>
--
2.35.1
11:54 a.m.
New subject: [PATCH 01/17] docs: Remove 'virshcmdref' page
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(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 02/17] docs: Drop 'devguide' page
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(a)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/"...
Development Guide (C language) HTML</a></li>
- <li><a
href="https://libvirt.org/docs/libvirt-appdev-guide/en-US/pdf/"...
Development Guide (C language) PDF</a></li>
- <li><a
href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/htm...
Development Guide (Python language) HTML</a></li>
- <li><a
href="https://libvirt.org/docs/libvirt-appdev-guide-python/en-US/pdf...
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">h...
-
-# Python language
-$ git clone <a
href="https://libvirt.org/git/?p=libvirt-appdev-guide-python.git&quo...
-
-# Publican Style/Theme
-$ git clone <a
href="https://libvirt.org/git/?p=libvirt-publican.git">https...
- </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
11:54 a.m.
New subject: [PATCH 02/17] docs: Drop 'devguide' page
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(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 03/17] docs: formatsnapshot: Convert to 'rst'
Signed-off-by: Peter Krempa <pkrempa(a)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
11:56 a.m.
New subject: [PATCH 03/17] docs: formatsnapshot: Convert to 'rst'
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
10:39 a.m.
New subject: [PATCH 03/17] docs: formatsnapshot: Convert to 'rst'
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(a)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.
9:59 a.m.
New subject: [PATCH 04/17] docs: Convert 'goals' to rST
Signed-off-by: Peter Krempa <pkrempa(a)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
11:58 a.m.
New subject: [PATCH 04/17] docs: Convert 'goals' to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 05/17] docs: Convert 'strategy' to rST
Signed-off-by: Peter Krempa <pkrempa(a)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
noon
New subject: [PATCH 05/17] docs: Convert 'strategy' to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 06/17] docs: Convert 'contribute' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)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&q...
- 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">st...
- 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"...
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
12:02 p.m.
New subject: [PATCH 06/17] docs: Convert 'contribute' page to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 07/17] docs: Convert 'bugs' page to rST
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(a)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&...
Fedora libvirt tickets</a></li>
- <li><a
href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fed...
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=Fed...
+ - `New Fedora libvirt
+ ticket
<https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&com...
+
+- 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
12:04 p.m.
New subject: [PATCH 07/17] docs: Convert 'bugs' page to rST
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(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 08/17] docs: Convert 'errors' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)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
12:04 p.m.
New subject: [PATCH 08/17] docs: Convert 'errors' page to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 09/17] docs: Convert 'support' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)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
12:06 p.m.
New subject: [PATCH 09/17] docs: Convert 'support' page to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 10/17] docs: Convert 'securityprocess' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)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">li...
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">...
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(a)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
12:08 p.m.
New subject: [PATCH 10/17] docs: Convert 'securityprocess' page to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 11/17] docs: securityprocess: Don't claim that we have maint branches
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(a)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
12:11 p.m.
New subject: [PATCH 11/17] docs: securityprocess: Don't claim that we have maint branches
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(a)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(a)redhat.com>
Jano
+The distro maintainers will be responsible for backporting the
officially
+published fixes to other release branches where applicable.
--
2.35.1
9:59 a.m.
New subject: [PATCH 12/17] docs: Convert 'governance' page to rST
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(a)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
12:15 p.m.
New subject: [PATCH 12/17] docs: Convert 'governance' page to rST
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(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 13/17] docs: page.xsl: Update anchor to the 'Code of conduct' paragraph
Use the anchor name as generated by rst2html.
Signed-off-by: Peter Krempa <pkrempa(a)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
12:16 p.m.
New subject: [PATCH 13/17] docs: page.xsl: Update anchor to the 'Code of conduct' paragraph
On a Monday in 2022, Peter Krempa wrote:
Use the anchor name as generated by rst2html.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/page.xsl | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 14/17] docs: Convert 'drivers' page to rST
Signed-off-by: Peter Krempa <pkrempa(a)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
12:35 p.m.
New subject: [PATCH 14/17] docs: Convert 'drivers' page to rST
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 15/17] docs: Convert 'formatsecret' page to rST
Also update the link from 'formatstorageencryption' to the
'usage-type-volume' anchor.
Signed-off-by: Peter Krempa <pkrempa(a)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
12:37 p.m.
New subject: [PATCH 15/17] docs: Convert 'formatsecret' page to rST
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(a)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(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 16/17] docs: formatsecret: Drop few unneeded empty lines
The examples contain some whitespace and command prompts which just
waste space.
Signed-off-by: Peter Krempa <pkrempa(a)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
12:37 p.m.
New subject: [PATCH 16/17] docs: formatsecret: Drop few unneeded empty lines
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(a)redhat.com>
---
docs/formatsecret.rst | 5 -----
1 file changed, 5 deletions(-)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
9:59 a.m.
New subject: [PATCH 17/17] docs: meson: Restore alphabetical order
Signed-off-by: Peter Krempa <pkrempa(a)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
12:37 p.m.
New subject: [PATCH 17/17] docs: meson: Restore alphabetical order
On a Monday in 2022, Peter Krempa wrote:
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/meson.build | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
Reviewed-by: Ján Tomko <jtomko(a)redhat.com>
Jano
990
days inactive
991
days old
35 comments
2 participants
participants (2)
-
Ján Tomko -
Peter Krempa