NuKVM/libvirt
3
0
Fork 0
mirror of https://github.com/libvirt/libvirt.git synced 2025-02-25 18:55:26 -06:00
Code Issues Packages Projects Releases Wiki Activity
9bbf0d7e64
libvirt/docs/formatstorageencryption.html.in

96 lines
4.3 KiB
HTML
Raw Normal View History

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 09:25:37 -05: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 14:50:10 -05: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>
util: Add 'usage' for encryption In order to use more common code and set up for a future type, modify the encryption secret to allow the "usage" attribute or the "uuid" attribute to define the secret. The "usage" in the case of a volume secret would be the path to the volume as dictated by the backwards compatibility brought on by virStorageGenerateQcowEncryption where it set up the usage field as the vol->target.path and didn't allow someone to provide it. This carries into virSecretObjListFindByUsageLocked which takes the secret usage attribute value from from the domain disk definition and compares it against the usage type from the secret definition. Since none of the code dealing with qcow/qcow2 encryption secrets uses usage for lookup, it's a mostly cosmetic change. The real usage comes in a future path where the encryption is expanded to be a luks volume and the secret will allow definition of the usage field. This code will make use of the virSecretLookup{Parse|Format}Secret common code. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-05-30 06:47:46 -05:00
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>passphrase</code>. The
<code>uuid</code> is "uuid" of the <code>secret</code> while
<code>usage</code> is the value "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
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 14:50:10 -05:00
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-01 17:02:10 -05: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 14:50:10 -05:00
<h3><a name="StorageEncryptionDefault">"default" format</a></h3>
<p>
docs: fix encryption format attribute in example The correct attribute name is 'format', not 'type'. https://bugzilla.redhat.com/show_bug.cgi?id=1139910
2014-09-10 02:25:40 -05:00
<code>&lt;encryption format="default"/&gt;</code> can be specified only
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 14:50:10 -05:00
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>
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 14:01:31 -05:00
<h3><a name="StorageEncryptionLuks">"luks" format</a></h3>
<p>
The <code>luks</code> format is specific to a luks encrypted volume
and the secret used in order to either encrypt or decrypt the volume.
A single <code>&lt;secret type='passphrase'...&gt;</code> element is
expected. The secret may be referenced via either a <code>uuid</code> or
<code>usage</code> attribute. One of the two must be present. When
present for volume creation, the secret will be used in order for
volume encryption. When present for domain usage, the secret will
be used as the passphrase to decrypt the volume.
<span class="since">Since 2.1.0</span>.
</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 14:50:10 -05:00
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 14:01:31 -05:00
<h2><a name="example">Examples</a></h2>
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 14:50:10 -05:00
<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>
encryption: Add luks parsing for storageencryption Add parse and format of the luks/passphrase secret including tests for volume XML parsing. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-01 14:01:31 -05:00
<p>
Here is a simple example, specifying use of the <code>luks</code> format
where it's assumed that a <code>secret</code> has been defined using a
<code>usage</code> element with a <code>id</code> of "luks_example":
</p>
<pre>
&lt;encryption format='luks'&gt;
&lt;secret type='passphrase' usage='luks_example'/&gt;
&lt;/encryption&gt;
</pre>
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 14:50:10 -05:00
</body>
</html>
Reference in New Issue Copy Permalink