[libvirt] [PATCH 5/6] docs: Update formatsecrets to include more examples of each type
Osier Yang
jyang at redhat.com
Tue Aug 20 06:09:54 UTC 2013
On 08/08/13 08:43, John Ferlan wrote:
> 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
Given the way you names the xml file for other secret types in this context,
this should be volume-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
s/volume can/volume secret/, or s/volume can/volume type secret/,
I prefer the latter one, since both of "volume" and "secret" are general
terms in libvirt.
And s/disk volume/storage 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>
> +
Given that you created example for storage pool chap auth. Here
we should have example for storage pool ceph auth too.
> + <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.
Add an example for "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
[1]
> + 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
Duplicate with [1], could be more compact I think.
> + 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>
More information about the libvir-list
mailing list