[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [libvirt] [PATCH 5/6] docs: Update formatsecrets to include more examples of each type



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>&lt;usage
>>         type='volume'&gt;</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>
>> +      &lt;secret ephemeral='no' private='yes'&gt;
>> +         &lt;description&gt;LUKS passphrase for the main hard drive
>> of our mail server&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/mail.img&lt;/volume&gt;
>> +         &lt;/usage&gt;
>> +      &lt;/secret&gt;
>> +    </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>
>> +      &lt;encryption format='qcow'&gt;
>> +        &lt;secret type='passphrase'
>> uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/&gt;
>> +      &lt;/encryption&gt;
>> +    </pre>
>>   +    <h3><a name="CephUsageType">Usage type "ceph"</a></h3>
>>       <p>
>>         This secret is associated with a Ceph RBD (rados block device).
>>         The <code>&lt;usage type='ceph'&gt;</code> element must contain
>> @@ -66,10 +99,57 @@
>>         this usage name via the <code>&lt;auth&gt;</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>
>> +      &lt;secret ephemeral='no' private='yes'&gt;
>> +         &lt;description&gt;CEPH passphrase example&lt;/description&gt;
>> +         &lt;auth type='ceph' username='myname'/&gt;
>> +         &lt;usage type='ceph'&gt;
>> +            &lt;name&gt;ceph_example&lt;/name&gt;
>> +         &lt;/usage&gt;
>> +      &lt;/secret&gt;
>> +    </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>&lt;auth&gt;</code> element in a
>> +      domain's <code>&lt;disk&gt;</code> element as follows:
>> +    </p>
>> +    <pre>
>> +      &lt;source protocol='rbd' name='pool/image'&gt;
>> +        &lt;host name='mon1.example.org' port='6321'/&gt;
>> +      &lt;/source&gt;
>> +      &lt;auth username='myname'&gt;
>> +        &lt;secret type='ceph' usage='ceph_example'/&gt;
>> +      &lt;/auth&gt;
>> +    </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>&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>
      &lt;auth type='ceph' username='myname'&gt;
        &lt;secret usage='ceph_example'/&gt;
      &lt;/auth&gt;
    </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>
>>         &lt;secret ephemeral='no' private='yes'&gt;
>> -         &lt;description&gt;LUKS passphrase for the main hard drive
>> of our mail server&lt;/description&gt;
>> -         &lt;usage type='volume'&gt;
>> -           
>> &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
>> +         &lt;description&gt;iSCSI passphrase for the iSCSI
>> example.com server&lt;/description&gt;
>> +         &lt;auth type='chap' username='myuser'/&gt;
>> +         &lt;usage type='iscsi'&gt;
>> +            &lt;target&gt;libvirtiscsi&lt;/target&gt;
>>            &lt;/usage&gt;
>> -      &lt;/secret&gt;</pre>
>> +      &lt;/secret&gt;
>> +    </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>
    &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;
    </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>
    &lt;secret ephemeral='no' private='yes'&gt;
       &lt;description&gt;Passphrase for the iSCSI example.com server&lt;/description&gt;
       &lt;auth type='chap' username='myname'/&gt;
       &lt;usage type='iscsi'&gt;
          &lt;target&gt;libvirtiscsi&lt;/target&gt;
       &lt;/usage&gt;
    &lt;/secret&gt;
  </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>&lt;auth&gt;</code> element in a
>> +      domain's <code>&lt;disk&gt;</code> element as follows:
>> +    </p>
>> +    <pre>
>> +      &lt;auth username='libvirt'&gt;
>> +        &lt;secret type='iscsi' usage='libvirtiscsi'/&gt;
>> +      &lt;/auth&gt;
>> +    </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>&lt;auth&gt;</code> element in a
>> +      storage pool <code>&lt;source&gt;</code> element as follows:
>> +    </p>
>> +    <pre>
>> +      &lt;auth type='chap' username='libvirt'&gt;
>> +        &lt;secret usage='libvirtiscsi'/&gt;
>> +      &lt;/auth&gt;
>> +    </pre>
>>     </body>
>>   </html>
> 


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]