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

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

> + 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/,

> + <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.

> + <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"?

> + </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>&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.

> + 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>