[PATCH 22/29] docs: Convert 'formatstorageencryption' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 docs/formatstorageencryption.html.in | 181 ---------------------------
 docs/formatstorageencryption.rst     | 142 +++++++++++++++++++++
 docs/meson.build                     |   2 +-
 3 files changed, 143 insertions(+), 182 deletions(-)
 delete mode 100644 docs/formatstorageencryption.html.in
 create mode 100644 docs/formatstorageencryption.rst

diff --git a/docs/formatstorageencryption.html.in b/docs/formatstorageencryption.html.in
deleted file mode 100644
index 395a7269b1..0000000000
--- a/docs/formatstorageencryption.html.in
+++ /dev/null
@@ -1,181 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>Storage volume encryption XML format</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="StorageEncryption">Storage volume encryption XML</a></h2>
-
-    <p>
-      Storage volumes may be encrypted, the XML snippet described below is used
-      to represent the details of the encryption.  It can be used as a part
-      of a domain or storage configuration.
-    </p>
-    <p>
-      The top-level tag of volume encryption specification
-      is <code>encryption</code>, with a mandatory
-      attribute <code>format</code>.  Currently defined values
-      of <code>format</code> are <code>default</code>, <code>qcow</code>,
-      <code>luks</code>, and <code>luks2</code>.
-      Each value of <code>format</code> implies some expectations about the
-      content of the <code>encryption</code> tag.  Other format values may be
-      defined in the future.
-    </p>
-    <p>
-      The <code>encryption</code> tag supports an optional <code>engine</code>
-      tag, which allows selecting which component actually handles
-      the encryption. Currently defined values of <code>engine</code> are
-      <code>qemu</code> and <code>librbd</code>.
-      Both <code>qemu</code> and <code>librbd</code> require using the qemu
-      driver.
-      The <code>librbd</code> engine requires qemu version >= 6.1.0, both
-      ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD
-      network disks.
-      If the engine tag is not specified, the <code>qemu</code> engine will be
-      used by default (assuming the qemu driver is used).
-      Note that <code>librbd</code> engine is currently only supported by the
-      qemu VM driver, and is not supported by the storage driver. Furthermore,
-      the storage driver currently ignores the <code>engine</code> tag.
-    </p>
-    <p>
-      The <code>encryption</code> tag can currently contain a sequence of
-      <code>secret</code> tags, each with mandatory attributes <code>type</code>
-      and either <code>uuid</code> or <code>usage</code>
-      (<span class="since">since 2.1.0</span>). The only currently defined
-      value of <code>type</code> is <code>volume</code>. The
-      <code>uuid</code> is "uuid" of the <code>secret</code> while
-      <code>usage</code> is the "usage" subelement field.
-      A secret value can be set in libvirt by the
-      <a href="html/libvirt-libvirt-secret.html#virSecretSetValue">
-      <code>virSecretSetValue</code></a> API. Alternatively, if supported
-      by the particular volume format and driver, automatically generate a
-      secret value at the time of volume creation, and store it using the
-      specified <code>uuid</code>.
-    </p>
-    <h3><a id="StorageEncryptionDefault">"default" format</a></h3>
-    <h3><a id="StorageEncryptionQcow">"qcow" format</a></h3>
-    <p>
-      <span class="since">Since 4.5.0,</span> encryption formats
-      <code>default</code> and <code>qcow</code> may no longer be used
-      to create an encrypted volume. Usage of qcow encrypted volumes
-      in QEMU began phasing out in QEMU 2.3 and by QEMU 2.9 creation
-      of a qcow encrypted volume via qemu-img required usage of secret
-      objects, but that support was not added to libvirt.
-    </p>
-    <h3><a id="StorageEncryptionLuks">"luks" format</a></h3>
-    <p>
-      The <code>luks</code> format is specific to a luks encrypted volume
-      and the secret is used in order to either encrypt during volume creation
-      or decrypt the volume for usage by the domain. A single
-      <code>&lt;secret type='passphrase'...&gt;</code> element is expected.
-      <span class="since">Since 2.1.0</span>.
-    </p>
-    <p>
-      For volume creation, it is possible to specify the encryption
-      algorithm used to encrypt the luks volume. The following two
-      optional elements may be provided for that purpose. It is hypervisor
-      dependent as to which algorithms are supported. The default algorithm
-      used by the storage driver backend when using qemu-img to create
-      the volume is 'aes-256-cbc' using 'essiv' for initialization vector
-      generation and 'sha256' hash algorithm for both the cipher and the
-      initialization vector generation.
-    </p>
-
-    <dl>
-      <dt><code>cipher</code></dt>
-      <dd>This element describes the cipher algorithm to be used to either
-          encrypt or decrypt the luks volume. This element has the following
-          attributes:
-          <dl>
-            <dt><code>name</code></dt>
-            <dd>The name of the cipher algorithm used for data encryption,
-            such as 'aes', 'des', 'cast5', 'serpent', 'twofish', etc.
-            Support of the specific algorithm is storage driver
-            implementation dependent.</dd>
-            <dt><code>size</code></dt>
-            <dd>The size of the cipher in bits, such as '256', '192', '128',
-            etc. Support of the specific size for a specific cipher is
-            hypervisor dependent.</dd>
-            <dt><code>mode</code></dt>
-            <dd>An optional cipher algorithm mode such as 'cbc', 'xts',
-            'ecb', etc. Support of the specific cipher mode is
-            hypervisor dependent.</dd>
-            <dt><code>hash</code></dt>
-            <dd>An optional master key hash algorithm such as 'md5', 'sha1',
-            'sha256', etc. Support of the specific hash algorithm is
-            hypervisor dependent.</dd>
-          </dl>
-      </dd>
-      <dt><code>ivgen</code></dt>
-      <dd>This optional element describes the initialization vector
-          generation algorithm used in conjunction with the
-          <code>cipher</code>. If the <code>cipher</code> is not provided,
-          then an error will be generated by the parser.
-          <dl>
-            <dt><code>name</code></dt>
-            <dd>The name of the algorithm, such as 'plain', 'plain64',
-            'essiv', etc. Support of the specific algorithm is hypervisor
-            dependent.</dd>
-            <dt><code>hash</code></dt>
-            <dd>An optional hash algorithm such as 'md5', 'sha1', 'sha256',
-            etc. Support of the specific ivgen hash algorithm is hypervisor
-            dependent.</dd>
-          </dl>
-      </dd>
-    </dl>
-
-    <h3><a id="StorageEncryptionLuks2">"luks2" format</a></h3>
-    <p>
-      The <code>luks2</code> format is currently supported only by the
-      <code>librbd</code> engine, and can only be applied to RBD network disks
-      (RBD images).
-      Since the <code>librbd</code> engine is currently not supported by the
-      libvirt storage driver, you cannot use it to control such disks. However,
-      pre-formatted RBD luks2 disks can be loaded to a qemu VM using the qemu
-      VM driver.
-      A single
-      <code>&lt;secret type='passphrase'...&gt;</code> element is expected.
-    </p>
-
-
-    <h2><a id="example">Examples</a></h2>
-
-    <p>
-      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
-      as part of a domain volume definition:
-    </p>
-    <pre>
-&lt;encryption format='luks'&gt;
-  &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
-&lt;/encryption&gt;
-    </pre>
-
-    <p>
-      Here is an example specifying use of the <code>luks</code> format for
-      a specific cipher algorithm for volume creation.
-      <span class="since">Since 6.10.0,</span> the <code>target</code> format
-      can also support <code>qcow2</code> type with <code>luks</code> encryption.
-    </p>
-    <pre>
-&lt;volume&gt;
-  &lt;name&gt;twofish.luks&lt;/name&gt;
-  &lt;capacity unit='G'&gt;5&lt;/capacity&gt;
-  &lt;target&gt;
-    &lt;path&gt;/var/lib/libvirt/images/demo.luks&lt;/path&gt;
-    &lt;format type='raw'/&gt;
-    &lt;encryption format='luks'&gt;
-       &lt;secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/&gt;
-       &lt;cipher name='twofish' size='256' mode='cbc' hash='sha256'/&gt;
-       &lt;ivgen name='plain64' hash='sha256'/&gt;
-    &lt;/encryption&gt;
-  &lt;/target&gt;
-&lt;/volume&gt;
-    </pre>
-
-  </body>
-</html>
diff --git a/docs/formatstorageencryption.rst b/docs/formatstorageencryption.rst
new file mode 100644
index 0000000000..7b5cccaf5e
--- /dev/null
+++ b/docs/formatstorageencryption.rst
@@ -0,0 +1,142 @@
+.. role:: since
+
+====================================
+Storage volume encryption XML format
+====================================
+
+.. contents::
+
+Storage volume encryption XML
+-----------------------------
+
+Storage volumes may be encrypted, the XML snippet described below is used to
+represent the details of the encryption. It can be used as a part of a domain or
+storage configuration.
+
+The top-level tag of volume encryption specification is ``encryption``, with a
+mandatory attribute ``format``. Currently defined values of ``format`` are
+``default``, ``qcow``, ``luks``, and ``luks2``. Each value of ``format`` implies
+some expectations about the content of the ``encryption`` tag. Other format
+values may be defined in the future.
+
+The ``encryption`` tag supports an optional ``engine`` tag, which allows
+selecting which component actually handles the encryption. Currently defined
+values of ``engine`` are ``qemu`` and ``librbd``. Both ``qemu`` and ``librbd``
+require using the qemu driver. The ``librbd`` engine requires qemu version >=
+6.1.0, both ceph cluster and librbd1 >= 16.1.0, and is only applicable for RBD
+network disks. If the engine tag is not specified, the ``qemu`` engine will be
+used by default (assuming the qemu driver is used). Note that ``librbd`` engine
+is currently only supported by the qemu VM driver, and is not supported by the
+storage driver. Furthermore, the storage driver currently ignores the ``engine``
+tag.
+
+The ``encryption`` tag can currently contain a sequence of ``secret`` tags, each
+with mandatory attributes ``type`` and either ``uuid`` or ``usage`` (
+:since:`since 2.1.0` ). The only currently defined value of ``type`` is
+``volume``. The ``uuid`` is "uuid" of the ``secret`` while ``usage`` is the
+"usage" subelement field. A secret value can be set in libvirt by the
+`virSecretSetValue <html/libvirt-libvirt-secret.html#virSecretSetValue>`__ API.
+Alternatively, if supported by the particular volume format and driver,
+automatically generate a secret value at the time of volume creation, and store
+it using the specified ``uuid``.
+
+"default" format
+~~~~~~~~~~~~~~~~
+
+"qcow" format
+~~~~~~~~~~~~~
+
+:since:`Since 4.5.0,` encryption formats ``default`` and ``qcow`` may no longer
+be used to create an encrypted volume. Usage of qcow encrypted volumes in QEMU
+began phasing out in QEMU 2.3 and by QEMU 2.9 creation of a qcow encrypted
+volume via qemu-img required usage of secret objects, but that support was not
+added to libvirt.
+
+"luks" format
+~~~~~~~~~~~~~
+
+The ``luks`` format is specific to a luks encrypted volume and the secret is
+used in order to either encrypt during volume creation or decrypt the volume for
+usage by the domain. A single ``<secret type='passphrase'...>`` element is
+expected. :since:`Since 2.1.0` .
+
+For volume creation, it is possible to specify the encryption algorithm used to
+encrypt the luks volume. The following two optional elements may be provided for
+that purpose. It is hypervisor dependent as to which algorithms are supported.
+The default algorithm used by the storage driver backend when using qemu-img to
+create the volume is 'aes-256-cbc' using 'essiv' for initialization vector
+generation and 'sha256' hash algorithm for both the cipher and the
+initialization vector generation.
+
+``cipher``
+   This element describes the cipher algorithm to be used to either encrypt or
+   decrypt the luks volume. This element has the following attributes:
+
+   ``name``
+      The name of the cipher algorithm used for data encryption, such as 'aes',
+      'des', 'cast5', 'serpent', 'twofish', etc. Support of the specific
+      algorithm is storage driver implementation dependent.
+   ``size``
+      The size of the cipher in bits, such as '256', '192', '128', etc. Support
+      of the specific size for a specific cipher is hypervisor dependent.
+   ``mode``
+      An optional cipher algorithm mode such as 'cbc', 'xts', 'ecb', etc.
+      Support of the specific cipher mode is hypervisor dependent.
+   ``hash``
+      An optional master key hash algorithm such as 'md5', 'sha1', 'sha256',
+      etc. Support of the specific hash algorithm is hypervisor dependent.
+``ivgen``
+   This optional element describes the initialization vector generation
+   algorithm used in conjunction with the ``cipher``. If the ``cipher`` is not
+   provided, then an error will be generated by the parser.
+
+   ``name``
+      The name of the algorithm, such as 'plain', 'plain64', 'essiv', etc.
+      Support of the specific algorithm is hypervisor dependent.
+   ``hash``
+      An optional hash algorithm such as 'md5', 'sha1', 'sha256', etc. Support
+      of the specific ivgen hash algorithm is hypervisor dependent.
+
+"luks2" format
+~~~~~~~~~~~~~~
+
+The ``luks2`` format is currently supported only by the ``librbd`` engine, and
+can only be applied to RBD network disks (RBD images). Since the ``librbd``
+engine is currently not supported by the libvirt storage driver, you cannot use
+it to control such disks. However, pre-formatted RBD luks2 disks can be loaded
+to a qemu VM using the qemu VM driver. A single
+``<secret type='passphrase'...>`` element is expected.
+
+Examples
+--------
+
+Assuming a `luks volume type secret <formatsecret.html#VolumeUsageType>`__ is
+already defined, a simple example specifying use of the ``luks`` format for
+either volume creation without a specific cipher being defined or as part of a
+domain volume definition:
+
+::
+
+   <encryption format='luks'>
+     <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
+   </encryption>
+
+Here is an example specifying use of the ``luks`` format for a specific cipher
+algorithm for volume creation. :since:`Since 6.10.0,` the ``target`` format can
+also support ``qcow2`` type with ``luks`` encryption.
+
+::
+
+   <volume>
+     <name>twofish.luks</name>
+     <capacity unit='G'>5</capacity>
+     <target>
+       <path>/var/lib/libvirt/images/demo.luks</path>
+       <format type='raw'/>
+       <encryption format='luks'>
+          <secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc572'/>
+          <cipher name='twofish' size='256' mode='cbc' hash='sha256'/>
+          <ivgen name='plain64' hash='sha256'/>
+       </encryption>
+     </target>
+   </volume>
diff --git a/docs/meson.build b/docs/meson.build
index b911292480..22eca7d8bd 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -25,7 +25,6 @@ docs_html_in_files = [
   'formatnetwork',
   'formatnode',
   'formatnwfilter',
-  'formatstorageencryption',
   'hooks',
   'index',
   'internals',
@@ -88,6 +87,7 @@ docs_rst_files = [
   'formatsnapshot',
   'formatstorage',
   'formatstoragecaps',
+  'formatstorageencryption',
   'glib-adoption',
   'goals',
   'governance',
-- 
2.35.1




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux