libvirt/docs/formatstorageencryption.html.in

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <body>
    <h1>Storage volume encryption XML format</h1>

    <ul id="toc"></ul>

    <h2><a name="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> and <code>qcow</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 can currently contain a sequence of
      <code>secret</code> tags, each with mandatory attributes <code>type</code>
      and <code>uuid</code>.  The only currently defined value of
      <code>type</code> is <code>passphrase</code>.  <code>uuid</code>
      refers to a secret known to libvirt.  libvirt can use a secret value
      previously set using <code>virSecretSetValue()</code>, or, 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 name="StorageEncryptionDefault">"default" format</a></h3>
    <p>
      <code>&lt;encryption type="default"/&gt;</code> can be specified only
      when creating a volume.  If the volume is successfully created, the
      encryption formats, parameters and secrets will be auto-generated by
      libvirt and the attached <code>encryption</code> tag will be updated.
      The unmodified contents of the <code>encryption</code> tag can be used
      in later operations with the volume, or when setting up a domain that
      uses the volume.
    </p>
    <h3><a name="StorageEncryptionQcow">"qcow" format</a></h3>
    <p>
      The <code>qcow</code> format specifies that the built-in encryption
      support in <code>qcow</code>- or <code>qcow2</code>-formatted volume
      images should be used.  A single
      <code>&lt;secret type='passphrase'&gt;</code> element is expected.  If
      the <code>secret</code> element is not present during volume creation,
      a secret is automatically generated and attached to the volume.
    </p>

    <h2><a name="example">Example</a></h2>

    <p>
      Here is a simple example, specifying use of the <code>qcow</code> format:
    </p>

    <pre>
      &lt;encryption format='qcow'&gt;
         &lt;secret type='passphrase' uuid='c1f11a6d-8c5d-4a3e-ac7a-4e171c5e0d4a' /&gt;
      &lt;/encryption&gt;</pre>
  </body>
</html>
Fix multiple formatting problems in HTML docs The rule generating the HTML docs passing the --html flag to xsltproc. This makes it use the legacy HTML parser, which either ignores or tries to fix all sorts of broken XML tags. There's no reason why we should be writing broken XML in the first place, so removing --html and adding the XHTML doctype to all files forces us to create good XML. This adds the XHTML doc type and fixes many, many XML tag problems it exposes. Signed-off-by: Daniel P. Berrange <berrange@redhat.com> 2013-05-03 18:25:37 +04:00			`<?xml version="1.0" encoding="UTF-8"?>`
			`<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">`
			`<html xmlns="http://www.w3.org/1999/xhtml">`
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/.html: Re-generate docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema 2009-08-19 23:50:10 +04:00			`<body>`
			`<h1>Storage volume encryption XML format</h1>`

			`<ul id="toc"></ul>`

			`<h2><a name="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> and <code>qcow</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 can currently contain a sequence of`
			`<code>secret</code> tags, each with mandatory attributes <code>type</code>`
			`and <code>uuid</code>. The only currently defined value of`
			`<code>type</code> is <code>passphrase</code>. <code>uuid</code>`
			`refers to a secret known to libvirt. libvirt can use a secret value`
			`previously set using <code>virSecretSetValue()</code>, or, 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>.`
docs: correct invalid xml * docs/internals.html.in: Fix xml errors. * docs/formatstorageencryption.html.in: Likewise. * docs/drvesx.html.in: Likewise. * docs/archnetwork.html.in: Likewise. * docs/logging.html.in: Likewise. * docs/drvvmware.html.in: Likewise. * docs/api.html.in: Likewise. * docs/formatnwfilter.html.in: Likewise. * docs/formatdomain.html.in: Likewise. * docs/windows.html.in: Likewise. 2011-04-02 02:02:10 +04:00			`</p>`
Add volume encryption information handling. Define an <encryption> tag specifying volume encryption format and format-depenedent parameters (e.g. passphrase, cipher name, key length, key). Currently the only defined parameter is a reference to a "secret" (passphrase/key) managed using the virSecret* API. Only the qcow/qcow2 encryption format, and a "default" format used to let libvirt choose the format during volume creation, is currently supported. This patch does not add any users; the <encryption> tag is added in the following patches to both volumes (to support encrypted volume creation) and domains. * docs/.html: Re-generate docs/formatstorageencryption.html.in, docs/sitemap.html.in: Add page describing storage encryption data format * docs/schemas/Makefile.am, docs/schemas/storageencryption.rng: Add RNG schema for storage encryption format * po/POTFILES.in: Add src/storage_encryption_conf.c * src/libvirt_private.syms: Export virStorageEncryption* functions * src/storage_encryption_conf.h, src/storage_encryption_conf.c: Internal helper APIs for dealing with storage encryption format * libvirt.spec.in, mingw32-libvirt.spec.in: Add storageencryption.rng RNG schema 2009-08-19 23:50:10 +04:00			`<h3><a name="StorageEncryptionDefault">"default" format</a></h3>`
			`<p>`
			`<code><encryption type="default"/></code> can be specified only`
			`when creating a volume. If the volume is successfully created, the`
			`encryption formats, parameters and secrets will be auto-generated by`
			`libvirt and the attached <code>encryption</code> tag will be updated.`
			`The unmodified contents of the <code>encryption</code> tag can be used`
			`in later operations with the volume, or when setting up a domain that`
			`uses the volume.`
			`</p>`
			`<h3><a name="StorageEncryptionQcow">"qcow" format</a></h3>`
			`<p>`
			`The <code>qcow</code> format specifies that the built-in encryption`
			`support in <code>qcow</code>- or <code>qcow2</code>-formatted volume`
			`images should be used. A single`
			`<code><secret type='passphrase'></code> element is expected. If`
			`the <code>secret</code> element is not present during volume creation,`
			`a secret is automatically generated and attached to the volume.`
			`</p>`

			`<h2><a name="example">Example</a></h2>`

			`<p>`
			`Here is a simple example, specifying use of the <code>qcow</code> format:`
			`</p>`

			`<pre>`
			`<encryption format='qcow'>`
			`<secret type='passphrase' uuid='c1f11a6d-8c5d-4a3e-ac7a-4e171c5e0d4a' />`
			`</encryption></pre>`
			`</body>`
			`</html>`