[libvirt] [PATCH 5/6] docs: Update formatsecrets to include more examples of each type
John Ferlan
jferlan at redhat.com
Tue Aug 20 14:17:38 UTC 2013
On 08/20/2013 02:09 AM, Osier Yang wrote:
> 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
>
Done
>> + 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/,
>
I went with 'volume type secret' and '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.
>
OK, done. The following was added (see your comment [1] below
to understand my grammar usage)
<p>
As well as the <code><auth></code> element in a
<a href="formatstorage.html">storage pool (rbd)</a>
<code><source></code> element as follows:
</p>
<pre>
<auth type='ceph' username='myname'>
<secret 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.
>
> Add an example for "iSCSI authentication configuration file"?
>
This is where I wasn't "as sure" we should be documenting what an
iSCSI authentication configuration looks like, but for completeness
I suppose I can see your point. Here's what I have:
...
<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>
<target iqn.2013-07.com.example:iscsi-pool>
backing-store /home/tgtd/iscsi-pool/disk1
backing-store /home/tgtd/iscsi-pool/disk2
incominguser myname mysecret
</target>
</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.
</p>
<pre>
<secret ephemeral='no' private='yes'>
<description>Passphrase for the iSCSI example.com server</description>
<auth type='chap' username='myname'/>
<usage type='iscsi'>
<target>libvirtiscsi</target>
</usage>
</secret>
</pre>
>> + </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`
NOTE: Changed "redhat" to "mysecret" to match the iSCSI authentication example
>> + # 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]
>
NOTE: Added direct link for "<disk>" (both here and above)
>> + 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.
>
Replaced "The iSCSI secret can then be used by UUID or by the
usage name via" with "As well as"
John
>> + 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