2013-05-03 18:25:37 +04:00
<?xml version="1.0" encoding="UTF-8"?>
2017-07-26 20:01:25 +03:00
<!DOCTYPE html>
2013-05-03 18:25:37 +04:00
< 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 >
2017-07-26 17:52:42 +03:00
< h2 > < a id = "SecretAttributes" > Secret XML< / a > < / h2 >
2009-07-28 04:39:48 +04:00
< 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-14 22:09:08 +03:00
only < code > volume< / code > , < code > ceph< / code > , < code > iscsi< / code > ,
and < code > tls< / 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 >
2017-07-26 17:52:42 +03:00
< h3 > < a id = "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
2018-06-20 23:21:50 +03:00
for a "luks" encrypted volume. Each volume will have a
2016-07-11 13:59:03 +03:00
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 >
2016-11-12 01:40:27 +03:00
< 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>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
# 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
#
2013-08-07 17:07:28 +04:00
< / pre >
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 >
2016-11-12 01:40:27 +03:00
# 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
#
2016-07-11 13:59:03 +03:00
< / pre >
2018-06-20 23:21:50 +03:00
< p >
The volume type secret can be supplied in domain XML for a luks storage
volume < a href = "formatstorageencryption.html" > encryption< / a > as follows:
< / p >
< pre >
< encryption format='luks'>
< secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/>
< /encryption>
< / pre >
2017-07-26 17:52:42 +03:00
< h3 > < a id = "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 >
2016-11-12 01:40:27 +03:00
< secret ephemeral='no' private='yes'>
< description> CEPH passphrase example< /description>
< usage type='ceph'>
< name> ceph_example< /name>
< /usage>
< /secret>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
# 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
#
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
< auth username='myname'>
< secret type='ceph' usage='ceph_example'/>
< /auth>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
< auth type='ceph' username='myname'>
< secret usage='ceph_example'/>
< /auth>
2013-08-07 17:07:28 +04:00
< / pre >
2011-10-28 21:30:45 +04:00
2017-07-26 17:52:42 +03:00
< h3 > < a id = "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 >
2016-11-12 01:40:27 +03:00
< 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>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
< secret ephemeral='no' private='yes'>
< description> Passphrase for the iSCSI example.com server< /description>
< usage type='iscsi'>
< target> libvirtiscsi< /target>
< /usage>
< /secret>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
# 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 "mysecret" | base64`
# virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
Secret value set
#
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
< auth username='myname'>
< secret type='iscsi' usage='libvirtiscsi'/>
< /auth>
2013-08-07 17:07:28 +04:00
< / 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 >
2016-11-12 01:40:27 +03:00
< auth type='chap' username='myname'>
< secret usage='libvirtiscsi'/>
< /auth>
2013-08-07 17:07:28 +04:00
< / pre >
2016-06-01 22:00:57 +03:00
2017-07-26 17:52:42 +03:00
< h3 > < a id = "tlsUsageType" > Usage type "tls"< / a > < / h3 >
2016-07-14 22:09:08 +03:00
< p >
This secret may be used in order to provide the passphrase for the
private key used to provide TLS credentials.
The < code > < usage type='tls'> < / code > element must contain a
single < code > name< / code > element that specifies a usage name
for the secret.
< span class = "since" > Since 2.3.0< / span > .
The following is an example of the expected XML and processing to
define the secret:
< / p >
< pre >
2016-11-12 01:40:27 +03:00
# cat tls-secret.xml
< secret ephemeral='no' private='yes'>
< description> sample tls secret< /description>
< usage type='tls'>
< name> TLS_example< /name>
< /usage>
< /secret>
# virsh secret-define tls-secret.xml
Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created
# virsh secret-list
UUID Usage
-----------------------------------------------------------
718c71bd-67b5-4a2b-87ec-a24e8ca200dc tls TLS_example
#
2016-07-14 22:09:08 +03:00
< / pre >
< p >
A secret may also be defined via the
< a href = "html/libvirt-libvirt-secret.html#virSecretDefineXML" >
< code > virSecretDefineXML< / code > < / a > API.
Once the secret is defined, a secret value will need to be set. The
secret would be the passphrase used to access the TLS credentials.
The following is a simple example of using
< code > virsh secret-set-value< / code > to set the secret value. The
< a href = "html/libvirt-libvirt-secret.html#virSecretSetValue" >
< code > virSecretSetValue< / code > < / a > API may also be used to set
a more secure secret without using printable/readable characters.
< / p >
< pre >
2016-11-12 01:40:27 +03:00
# MYSECRET=`printf %s "letmein" | base64`
# virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
Secret value set
2016-07-14 22:09:08 +03:00
< / pre >
2009-07-28 04:39:48 +04:00
< / body >
< / html >
