Update formatsecret docs to describe the various options and provide examples
in order to set up secrets for each type of secret.
---
docs/formatsecret.html.in | 156 ++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 145 insertions(+), 11 deletions(-)
diff --git a/docs/formatsecret.html.in b/docs/formatsecret.html.in
index 3e306b5..7dd0927 100644
--- a/docs/formatsecret.html.in
+++ b/docs/formatsecret.html.in
@@ -46,18 +46,51 @@
</dd>
</dl>
- <h3>Usage type "volume"</h3>
+ <h3><a name="VolumeUsageType">Usage type "volume"</a></h3>
<p>
This secret is associated with a volume, and it is safe to delete the
secret after the volume is deleted. The <code><usage
type='volume'></code> element must contain a
single <code>volume</code> element that specifies the key of the volume
- this secret is associated with.
+ this secret is associated with. For example, create a demo-secret.xml
+ file as follows:
</p>
- <h3>Usage type "ceph"</h3>
+ <pre>
+ <secret ephemeral='no' private='yes'>
+ <description>LUKS passphrase for the main hard drive of our mail server</description>
+ <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid>
+ <usage type='volume'>
+ <volume>/var/lib/libvirt/images/mail.img</volume>
+ </usage>
+ </secret>
+ </pre>
+
+ <p>
+ Define the secret and set the pass phrase as follows:
+ </p>
+ <pre>
+ # virsh secret-define demo-secret.xml
+ Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
+ #
+ # MYSECRET=`printf %s "open seseme" | base64`
+ # virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
+ Secret value set
+ #
+ </pre>
+
+ <p>
+ The volume can then be used in the XML for a disk volume
+ <a href="formatstorageencryption.html">encryption</a> as follows:
+ </p>
+ <pre>
+ <encryption format='qcow'>
+ <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/>
+ </encryption>
+ </pre>
+ <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
<p>
This secret is associated with a Ceph RBD (rados block device).
The <code><usage type='ceph'></code> element must contain
@@ -66,10 +99,57 @@
this usage name via the <code><auth></code> element of
a <a href="formatdomain.html#elementsDisks">disk device</a> or
a <a href="formatstorage.html">storage pool (rbd)</a>.
- <span class="since">Since 0.9.7</span>.
+ <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>
+ <secret ephemeral='no' private='yes'>
+ <description>CEPH passphrase example</description>
+ <auth type='ceph' username='myname'/>
+ <usage type='ceph'>
+ <name>ceph_example</name>
+ </usage>
+ </secret>
+ </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
- <h3>Usage type "iscsi"</h3>
+ #
+ </pre>
+
+ <p>
+ The ceph secret can then be used by UUID or by the
+ usage name via the <code><auth></code> element in a
+ domain's <code><disk></code> element as follows:
+ </p>
+ <pre>
+ <source protocol='rbd' name='pool/image'>
+ <host name='mon1.example.org' port='6321'/>
+ </source>
+ <auth username='myname'>
+ <secret type='ceph' usage='ceph_example'/>
+ </auth>
+ </pre>
+
+ <h3><a name="iSCSIUsageType">Usage type "iscsi"</a></h3>
<p>
This secret is associated with an iSCSI target for CHAP authentication.
@@ -82,14 +162,68 @@
<span class="since">Since 1.0.4</span>.
</p>
- <h2><a name="example">Example</a></h2>
-
+ <p>
+ The following is an example of the XML that may be used to generate
+ a secret for iSCSI CHAP authentication. First define an iscsi-secret.xml
+ file to describe the secret. Replace the <code>username</code> field
+ with the username used in your iSCSI authentication configuration file.
+ The description field 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.
+ </p>
<pre>
<secret ephemeral='no' private='yes'>
- <description>LUKS passphrase for the main hard drive of our mail server</description>
- <usage type='volume'>
- <volume>/var/lib/libvirt/images/mail.img</volume>
+ <description>iSCSI passphrase for the iSCSI example.com server</description>
+ <auth type='chap' username='myuser'/>
+ <usage type='iscsi'>
+ <target>libvirtiscsi</target>
</usage>
- </secret></pre>
+ </secret>
+ </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 "redhat" | 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><auth></code> element in a
+ domain's <code><disk></code> element as follows:
+ </p>
+ <pre>
+ <auth username='libvirt'>
+ <secret type='iscsi' usage='libvirtiscsi'/>
+ </auth>
+ </pre>
+
+ <p>
+ The iSCSI secret can then be used by UUID or by the
+ usage name via the <code><auth></code> element in a
+ storage pool <code><source></code> element as follows:
+ </p>
+ <pre>
+ <auth type='chap' username='libvirt'>
+ <secret usage='libvirtiscsi'/>
+ </auth>
+ </pre>
</body>
</html>
--
1.8.3.1
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list