openkylin
/
libvirt
mirror of https://gitee.com/openkylin/libvirt.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity
libvirt/docs/formatsecret.html.in

331 lines
12 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 22:25:37 +08: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 08:39:48 +08:00
<body>
<h1>Secret XML format</h1>
<ul id="toc"></ul>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h2><a id="SecretAttributes">Secret XML</a></h2>
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 08:39:48 +08:00
<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-02 01:25:11 +08: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 23:04:19 +08:00
Specifies what this secret is used for. A mandatory
<code>type</code> attribute specifies the usage category, currently
conf: Add new secret type "tls" Add a new secret usage type known as "tls" - it will handle adding the secret objects for various TLS objects that need to provide some sort of passphrase in order to access the credentials. The format is: <secret ephemeral='no' private='no'> <description>Sample TLS secret</description> <usage type='tls'> <name>mumblyfratz</name> </usage> </secret> Once defined and a passphrase set, future patches will allow the UUID to be set in the qemu.conf file and thus used as a secret for various TLS options such as a chardev serial TCP connection, a NBD client/server connection, and migration. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-15 03:09:08 +08:00
only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
and <code>tls</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-02 01:25:11 +08: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 08:39:48 +08:00
</dl>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="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-02 01:25:11 +08:00
<p>
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 18:59:03 +08:00
This secret is associated with a volume, whether the format is either
for a "qcow" or 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>&lt;usage type='volume'&gt;</code> element must contain a
single <code>volume</code> element that specifies the path 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 21:07:28 +08: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-02 01:25:11 +08: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 21:07:28 +08:00
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&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;
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 21:07:28 +08:00
</pre>
<p>
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 18:59:03 +08:00
Define the secret and set the passphrase as follows:
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 21:07:28 +08:00
</p>
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# 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
#
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 21:07:28 +08:00
</pre>
<p>
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 18:59:03 +08:00
The volume type secret can be supplied in domain XML for a qcow storage
volume <a href="formatstorageencryption.html">encryption</a> as follows:
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 21:07:28 +08:00
</p>
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;encryption format='qcow'&gt;
&lt;secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/&gt;
&lt;/encryption&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 21:07:28 +08:00
</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-29 01:30:45 +08:00
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 18:59:03 +08:00
<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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# cat luks-secret.xml
&lt;secret ephemeral='no' private='yes'&gt;
&lt;description&gt;LUKS Sample Secret&lt;/description&gt;
&lt;uuid&gt;f52a81b2-424e-490c-823d-6bd4235bc57&lt;/uuid&gt;
&lt;usage type='volume'&gt;
&lt;volume&gt;/var/lib/libvirt/images/luks-sample.img&lt;/volume&gt;
&lt;/usage&gt;
&lt;/secret&gt;
# virsh secret-define luks-secret.xml
Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
#
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
Secret value set
#
docs: Update docs to reflect LUKS secret changes Commit id's 'c8438010', '9bbf0d7e', and '2552fec24' altered the documentation to describe adding a 'passphrase' type secret usage model in order to reference the secret for a luks volume. After commit, it was deemed that a 'volume' usage model should be used, so adjust the various documents in order rephrase descriptions in order to follow the correct usage model. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-11 18:59:03 +08:00
</pre>
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="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-29 01:30:45 +08: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-14 02:29:55 +08: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 21:07:28 +08: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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&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;
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 21:07:28 +08:00
</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# 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
#
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 21:07:28 +08:00
</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-29 01:30:45 +08: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 21:07:28 +08:00
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;auth username='myname'&gt;
&lt;secret type='ceph' usage='ceph_example'/&gt;
&lt;/auth&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 21:07:28 +08:00
</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;auth type='ceph' username='myname'&gt;
&lt;secret usage='ceph_example'/&gt;
&lt;/auth&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 21:07:28 +08:00
</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-29 01:30:45 +08:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
secret: add iscsi to possible usage types Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2013-03-21 19:53:52 +08: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 21:07:28 +08: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 19:53:52 +08: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-14 02:29:55 +08: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 21:07:28 +08: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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&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;
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 21:07:28 +08:00
</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 19:53:52 +08: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 08:39:48 +08:00
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;secret ephemeral='no' private='yes'&gt;
&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;
&lt;/usage&gt;
&lt;/secret&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 21:07:28 +08:00
</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# 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
#
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 21:07:28 +08:00
</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;auth username='myname'&gt;
&lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
&lt;/auth&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 21:07:28 +08:00
</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
&lt;auth type='chap' username='myname'&gt;
&lt;secret usage='libvirtiscsi'/&gt;
&lt;/auth&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 21:07:28 +08:00
</pre>
conf: Add new secret type "passphrase" Add a new secret type known as "passphrase" - it will handle adding the secret objects that need a passphrase without a specific username. The format is: <secret ...> <uuid>...</uuid> ... <usage type='passphrase'> <name>mumblyfratz</name> </usage> </secret> Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-06-02 03:00:57 +08:00
docs: switch to using 'id' attribute instead of 'name' for links The 'name' attribute on <a...> elements is deprecated in favour of the 'id' attribute which is allowed on any element. HTML5 drops 'name' support entirely. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2017-07-26 22:52:42 +08:00
<h3><a id="tlsUsageType">Usage type "tls"</a></h3>
conf: Add new secret type "tls" Add a new secret usage type known as "tls" - it will handle adding the secret objects for various TLS objects that need to provide some sort of passphrase in order to access the credentials. The format is: <secret ephemeral='no' private='no'> <description>Sample TLS secret</description> <usage type='tls'> <name>mumblyfratz</name> </usage> </secret> Once defined and a passphrase set, future patches will allow the UUID to be set in the qemu.conf file and thus used as a secret for various TLS options such as a chardev serial TCP connection, a NBD client/server connection, and migration. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-15 03:09:08 +08:00
<p>
This secret may be used in order to provide the passphrase for the
private key used to provide TLS credentials.
The <code>&lt;usage type='tls'&gt;</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>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# cat tls-secret.xml
&lt;secret ephemeral='no' private='yes'&gt;
&lt;description&gt;sample tls secret&lt;/description&gt;
&lt;usage type='tls'&gt;
&lt;name&gt;TLS_example&lt;/name&gt;
&lt;/usage&gt;
&lt;/secret&gt;
# 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
#
conf: Add new secret type "tls" Add a new secret usage type known as "tls" - it will handle adding the secret objects for various TLS objects that need to provide some sort of passphrase in order to access the credentials. The format is: <secret ephemeral='no' private='no'> <description>Sample TLS secret</description> <usage type='tls'> <name>mumblyfratz</name> </usage> </secret> Once defined and a passphrase set, future patches will allow the UUID to be set in the qemu.conf file and thus used as a secret for various TLS options such as a chardev serial TCP connection, a NBD client/server connection, and migration. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-15 03:09:08 +08:00
</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>virsh secret-set-value</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>
<pre>
formatsecret.html.in: Kill useless spaces in <pre/> The <pre/> section is rendered as-is on the page. That is, if all the lines are prefixed with 4 spaces the rendered page will also have them. Problem is if we put a box around such <pre/> because the content might not fix into it. Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2016-11-12 06:40:27 +08:00
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
Secret value set
conf: Add new secret type "tls" Add a new secret usage type known as "tls" - it will handle adding the secret objects for various TLS objects that need to provide some sort of passphrase in order to access the credentials. The format is: <secret ephemeral='no' private='no'> <description>Sample TLS secret</description> <usage type='tls'> <name>mumblyfratz</name> </usage> </secret> Once defined and a passphrase set, future patches will allow the UUID to be set in the qemu.conf file and thus used as a secret for various TLS options such as a chardev serial TCP connection, a NBD client/server connection, and migration. Signed-off-by: John Ferlan <jferlan@redhat.com>
2016-07-15 03:09:08 +08:00
</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 08:39:48 +08:00
</body>
</html>