[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