External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-11-04 20:31:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
3af8186898
libvirt/docs/formatsecret.html.in

246 lines
9.0 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 14:25:37 +00: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">
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/*html: Re-generated * docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list
2009-07-28 00:39:48 +00:00
<body>
<h1>Secret XML format</h1>
<ul id="toc"></ul>
<h2><a name="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>
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'>
2009-09-01 17:25:11 +00:00
<dt><code>usage</code></dt>
<dd>
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s*$//' *.html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace
2009-11-06 15:04:19 +00:00
Specifies what this secret is used for. A mandatory
<code>type</code> attribute specifies the usage category, currently
docs: Add the missed usage type 'iscsi' Pushed under trivial rule.
2013-05-14 13:42:51 +00:00
only <code>volume</code>, <code>ceph</code> and <code>iscsi</code>
are defined. Specific usage categories are described below.
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'>
2009-09-01 17:25:11 +00:00
</dd>
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/*html: Re-generated * docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list
2009-07-28 00:39:48 +00:00
</dl>
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'>
2009-09-01 17:25:11 +00:00
<p>
This secret is associated with a volume, and it is safe to delete the
secret after the volume is deleted. The <code>&lt;usage
type='volume'&gt;</code> element must contain a
single <code>volume</code> element that specifies the key of the volume
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
this secret is associated with. For example, create a volume-secret.xml
file as follows:
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'>
2009-09-01 17:25:11 +00:00
</p>
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<pre>
&lt;secret ephemeral='no' private='yes'&gt;
&lt;description&gt;Super secret name of my first puppy&lt;/description&gt;
&lt;uuid&gt;0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f&lt;/uuid&gt;
&lt;usage type='volume'&gt;
&lt;volume&gt;/var/lib/libvirt/images/puppyname.img&lt;/volume&gt;
&lt;/usage&gt;
&lt;/secret&gt;
</pre>
<p>
Define the secret and set the pass phrase as follows:
</p>
<pre>
# virsh secret-define volume-secret.xml
Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
#
# MYSECRET=`printf %s "open sesame" | base64`
# virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
Secret value set
#
</pre>
<p>
The volume type secret can then be used in the XML for a storage volume
<a href="formatstorageencryption.html">encryption</a> as follows:
</p>
<pre>
&lt;encryption format='qcow'&gt;
&lt;secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/&gt;
&lt;/encryption&gt;
</pre>
secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net>
2011-10-28 17:30:45 +00:00
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<h3><a name="CephUsageType">Usage type "ceph"</a></h3>
secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net>
2011-10-28 17:30:45 +00:00
<p>
This secret is associated with a Ceph RBD (rados block device).
The <code>&lt;usage type='ceph'&gt;</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>&lt;auth&gt;</code> element of
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
a <a href="formatdomain.html#elementsDisks">disk device</a> or
a <a href="formatstorage.html">storage pool (rbd)</a>.
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<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>
&lt;secret ephemeral='no' private='yes'&gt;
&lt;description&gt;CEPH passphrase example&lt;/description&gt;
&lt;usage type='ceph'&gt;
&lt;name&gt;ceph_example&lt;/name&gt;
&lt;/usage&gt;
&lt;/secret&gt;
</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
#
# CEPHPHRASE=`printf %s "pass phrase" | base64`
# virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
Secret value set
#
</pre>
<p>
The ceph secret can then be used by UUID or by the
usage name via the <code>&lt;auth&gt;</code> element in a domain's
<a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
element as follows:
secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net>
2011-10-28 17:30:45 +00:00
</p>
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<pre>
&lt;auth username='myname'&gt;
&lt;secret type='ceph' usage='ceph_example'/&gt;
&lt;/auth&gt;
</pre>
<p>
As well as the <code>&lt;auth&gt;</code> element in a
<a href="formatstorage.html">storage pool (rbd)</a>
<code>&lt;source&gt;</code> element as follows:
</p>
<pre>
&lt;auth type='ceph' username='myname'&gt;
&lt;secret usage='ceph_example'/&gt;
&lt;/auth&gt;
</pre>
secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net>
2011-10-28 17:30:45 +00:00
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
secret: add iscsi to possible usage types Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2013-03-21 11:53:52 +00:00
<p>
This secret is associated with an iSCSI target for CHAP authentication.
The <code>&lt;usage type='iscsi'&gt;</code> element must contain
a single <code>target</code> element that specifies a usage name
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
for the secret. The iSCSI secret can then be used by UUID or by
secret: add iscsi to possible usage types Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2013-03-21 11:53:52 +00:00
this usage name via the <code>&lt;auth&gt;</code> element of
storage_pool: Rework chap XML to mimic ceph The existing 'chap' XML logic was never used - just defined. Rather than try to insert a square peg into a round hole, blow it up and rewrite the logic to follow the 'ceph' format. Remove the former "chap.login" and "chap.passwd" fields and replace with "chap.username" and "chap.secret" in _virStoragePoolAuthChap. Adjust the virStoragePoolDefParseAuthChap() to process. Change the rng file to describe the new layout Update the formatstorage.html to describe the usage of the secret element to mention that the secret type "iscsi" and "ceph" can be used to storage pool too. Update the formatsecret.html to include a reference to the storage pool Update tests to handle the changes from 'login' and 'passwd' to 'username' and '<secret>' format
2013-07-13 18:29:55 +00:00
a <a href="formatdomain.html#elementsDisks">disk device</a> or
a <a href="formatstorage.html">storage pool (iscsi)</a>.
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
<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>
&lt;target iqn.2013-07.com.example:iscsi-pool&gt;
backing-store /home/tgtd/iscsi-pool/disk1
backing-store /home/tgtd/iscsi-pool/disk2
incominguser myname mysecret
&lt;/target&gt;
</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.
secret: add iscsi to possible usage types Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2013-03-21 11:53:52 +00:00
</p>
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/*html: Re-generated * docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list
2009-07-28 00:39:48 +00:00
<pre>
&lt;secret ephemeral='no' private='yes'&gt;
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
&lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
&lt;usage type='iscsi'&gt;
&lt;target&gt;libvirtiscsi&lt;/target&gt;
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'>
2009-09-01 17:25:11 +00:00
&lt;/usage&gt;
docs: Update formatsecrets to include more examples of each type Update formatsecret docs to describe the various options and provide examples in order to set up secrets for each type of secret.
2013-08-07 13:07:28 +00:00
&lt;/secret&gt;
</pre>
<p>
Next, use <code>virsh secret-define iscsi-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. 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
# MYSECRET=`printf %s "mysecret" | base64`
# virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
Secret value set
#
</pre>
<p>
The iSCSI secret can then be used by UUID or by the
usage name via the <code>&lt;auth&gt;</code> element in a domain's
<a href="formatdomain.html#elementsDisks"><code>&lt;disk&gt;</code></a>
element as follows:
</p>
<pre>
&lt;auth username='myname'&gt;
&lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
</pre>
<p>
As well as the <code>&lt;auth&gt;</code> element in a
<a href="formatstorage.html">storage pool (iscsi)</a>
<code>&lt;source&gt;</code> element as follows:
</p>
<pre>
&lt;auth type='chap' username='myname'&gt;
&lt;secret usage='libvirtiscsi'/&gt;
&lt;/auth&gt;
</pre>
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/*html: Re-generated * docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list
2009-07-28 00:39:48 +00:00
</body>
</html>
Reference in New Issue Copy Permalink