2013-05-03 18:25:37 +04:00
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
< html xmlns = "http://www.w3.org/1999/xhtml" >
2009-07-28 04:39:48 +04:00
< body >
< h1 > Secret XML format< / h1 >
< ul id = "toc" > < / ul >
< h2 > < a name = "SecretAttributes" > Secret XML< / a > < / h2 >
< p >
Secrets stored by libvirt may have attributes associated with them, using
the < code > secret< / code > element. The < code > secret< / code > element has two
optional attributes, each with values '< code > yes< / code > ' and
'< code > no< / code > ', and defaulting to '< code > no< / code > ':
< / p >
< dl >
< dt > < code > ephemeral< / code > < / dt >
< dd > This secret must only be kept in memory, never stored persistently.
< / dd >
< dt > < code > private< / code > < / dt >
< dd > The value of the secret must not be revealed to any caller of libvirt,
nor to any other node.
< / dd >
< / dl >
< p >
The top-level < code > secret< / code > element may contain the following
elements:
< / p >
< dl >
< dt > < code > uuid< / code > < / dt >
< dd >
An unique identifier for this secret (not necessarily in the UUID
format). If omitted when defining a new secret, a random UUID is
generated.
< / dd >
< dt > < code > description< / code > < / dt >
< dd > A human-readable description of the purpose of the secret.
< / dd >
2009-09-01 21:25:11 +04:00
< dt > < code > usage< / code > < / dt >
< dd >
2009-11-06 18:04:19 +03:00
Specifies what this secret is used for. A mandatory
< code > type< / code > attribute specifies the usage category, currently
2016-07-11 13:59:03 +03:00
only < code > volume< / code > , < code > ceph< / code > , and < code > iscsi< / code >
are defined. Specific usage categories are described below.
2009-09-01 21:25:11 +04:00
< / dd >
2009-07-28 04:39:48 +04:00
< / dl >
2013-08-07 17:07:28 +04:00
< h3 > < a name = "VolumeUsageType" > Usage type "volume"< / a > < / h3 >
2009-09-01 21:25:11 +04:00
< p >
2016-07-11 13:59:03 +03:00
This secret is associated with a volume, whether the format is either
for a "qcow" or a "luks" encrypted volume. Each volume will have a
unique secret associated with it 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 path of the volume
2013-08-07 17:07:28 +04:00
this secret is associated with. For example, create a volume-secret.xml
file as follows:
2009-09-01 21:25:11 +04:00
< / p >
2013-08-07 17:07:28 +04:00
< pre >
< secret ephemeral='no' private='yes'>
< description> Super secret name of my first puppy< /description>
< uuid> 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f< /uuid>
< usage type='volume'>
< volume> /var/lib/libvirt/images/puppyname.img< /volume>
< /usage>
< /secret>
< / pre >
< p >
2016-07-11 13:59:03 +03:00
Define the secret and set the passphrase as follows:
2013-08-07 17:07:28 +04:00
< / p >
< pre >
# virsh secret-define volume-secret.xml
Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
#
# MYSECRET=`printf %s "open sesame" | base64`
# virsh secret-set-value 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f $MYSECRET
Secret value set
#
< / pre >
< p >
2016-07-11 13:59:03 +03:00
The volume type secret can be supplied in domain XML for a qcow storage
volume < a href = "formatstorageencryption.html" > encryption< / a > as follows:
2013-08-07 17:07:28 +04:00
< / p >
< pre >
< encryption format='qcow'>
< secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/>
< /encryption>
< / pre >
2011-10-28 21:30:45 +04:00
2016-07-11 13:59:03 +03:00
< p >
The volume type secret can be supplied either in volume XML during
creation of a < a href = "formatstorage.html#StorageVol" > storage volume< / a >
in order to provide the passphrase to encrypt the volume or in
domain XML < a href = "formatdomain.html#elementsDisks" > disk device< / a >
in order to provide the passphrase to decrypt the volume,
< span class = "since" > since 2.1.0< / span > . An example follows:
< / p >
< pre >
# cat luks-secret.xml
< secret ephemeral='no' private='yes'>
< description> LUKS Sample Secret< /description>
< uuid> f52a81b2-424e-490c-823d-6bd4235bc57< /uuid>
< usage type='volume'>
< volume> /var/lib/libvirt/images/luks-sample.img< /volume>
< /usage>
< /secret>
# virsh secret-define luks-secret.xml
Secret f52a81b2-424e-490c-823d-6bd4235bc57 created
#
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value f52a81b2-424e-490c-823d-6bd4235bc57 $MYSECRET
Secret value set
#
< / pre >
2013-08-07 17:07:28 +04:00
< h3 > < a name = "CephUsageType" > Usage type "ceph"< / a > < / h3 >
2011-10-28 21:30:45 +04:00
< p >
This secret is associated with a Ceph RBD (rados block device).
The < code > < usage type='ceph'> < / code > element must contain
a single < code > name< / code > element that specifies a usage name
for the secret. The Ceph secret can then be used by UUID or by
this usage name via the < code > < auth> < / code > element of
2013-07-13 22:29:55 +04:00
a < a href = "formatdomain.html#elementsDisks" > disk device< / a > or
a < a href = "formatstorage.html" > storage pool (rbd)< / a > .
2013-08-07 17:07:28 +04:00
< 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>
< 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
2016-06-24 17:16:18 +03:00
UUID Usage
2013-08-07 17:07:28 +04:00
-----------------------------------------------------------
2016-06-24 17:16:18 +03:00
1b40a534-8301-45d5-b1aa-11894ebb1735 cephx ceph_example
2013-08-07 17:07:28 +04:00
#
# CEPHPHRASE=`printf %s "pass phrase" | base64`
# virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
Secret value set
#
< / 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
< a href = "formatdomain.html#elementsDisks" > < code > < disk> < / code > < / a >
element as follows:
2011-10-28 21:30:45 +04:00
< / p >
2013-08-07 17:07:28 +04:00
< pre >
< auth username='myname'>
< secret type='ceph' usage='ceph_example'/>
< /auth>
< / pre >
< 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 >
2011-10-28 21:30:45 +04:00
2013-08-07 17:07:28 +04:00
< h3 > < a name = "iSCSIUsageType" > Usage type "iscsi"< / a > < / h3 >
2013-03-21 15:53:52 +04:00
< p >
This secret is associated with an iSCSI target for CHAP authentication.
The < code > < usage type='iscsi'> < / code > element must contain
a single < code > target< / code > element that specifies a usage name
2013-08-07 17:07:28 +04:00
for the secret. The iSCSI secret can then be used by UUID or by
2013-03-21 15:53:52 +04:00
this usage name via the < code > < auth> < / code > element of
2013-07-13 22:29:55 +04:00
a < a href = "formatdomain.html#elementsDisks" > disk device< / a > or
a < a href = "formatstorage.html" > storage pool (iscsi)< / a > .
2013-08-07 17:07:28 +04:00
< 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.
2013-03-21 15:53:52 +04:00
< / p >
2009-07-28 04:39:48 +04:00
< pre >
< secret ephemeral='no' private='yes'>
2013-08-07 17:07:28 +04:00
< description> Passphrase for the iSCSI example.com server< /description>
< usage type='iscsi'>
< target> libvirtiscsi< /target>
2009-09-01 21:25:11 +04:00
< /usage>
2013-08-07 17:07:28 +04:00
< /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.
< / p >
< pre >
# virsh secret-define secret.xml
Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
# virsh secret-list
2016-06-24 17:16:18 +03:00
UUID Usage
2013-08-07 17:07:28 +04:00
-----------------------------------------------------------
2016-06-24 17:16:18 +03:00
c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
2013-08-07 17:07:28 +04:00
# MYSECRET=`printf %s "mysecret" | 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
usage name via the < code > < auth> < / code > element in a domain's
< a href = "formatdomain.html#elementsDisks" > < code > < disk> < / code > < / a >
element as follows:
< / p >
< pre >
< auth username='myname'>
< secret type='iscsi' usage='libvirtiscsi'/>
< /auth>
< / pre >
< p >
As well as the < code > < auth> < / code > element in a
< a href = "formatstorage.html" > storage pool (iscsi)< / a >
< code > < source> < / code > element as follows:
< / p >
< pre >
< auth type='chap' username='myname'>
< secret usage='libvirtiscsi'/>
< /auth>
< / pre >
2016-06-01 22:00:57 +03:00
2009-07-28 04:39:48 +04:00
< / body >
< / html >
