Secrets stored by libvirt may have attributes associated with them, using
the secret element. The secret element has two
optional attributes, each with values 'yes' and
'no', and defaulting to 'no':
ephemeralprivate
The top-level secret element may contain the following
elements:
uuiddescriptionusagetype attribute specifies the usage category, currently
only volume, ceph, iscsi,
tls, and vtpm are defined. Specific usage
categories are described below.
This secret is associated with a volume, whether the format is either
for 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
<usage type='volume'> element must contain a
single volume element that specifies the path of the volume
this secret is associated with. For example, create a volume-secret.xml
file as follows:
<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>
Define the secret and set the passphrase as follows:
# virsh secret-define volume-secret.xml
Secret 0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f created
See virsh secret-set-value on how to set the value of the secret.
The volume type secret can be supplied either in volume XML during creation of a storage volume in order to provide the passphrase to encrypt the volume or in domain XML disk device in order to provide the passphrase to decrypt the volume, since 2.1.0. An example follows:
# 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
See virsh secret-set-value on how to set the value of the secret.
The volume type secret can be supplied in domain XML for a luks storage volume encryption as follows:
<encryption format='luks'>
<secret type='passphrase' uuid='f52a81b2-424e-490c-823d-6bd4235bc57'/>
</encryption>
This secret is associated with a Ceph RBD (rados block device).
The <usage type='ceph'> element must contain
a single name 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 <auth> element of
a disk device or
a storage pool (rbd).
Since 0.9.7. The following is an example
of the steps to be taken. First create a ceph-secret.xml file:
<secret ephemeral='no' private='yes'>
<description>CEPH passphrase example</description>
<usage type='ceph'>
<name>ceph_example</name>
</usage>
</secret>
Next, use virsh secret-define ceph-secret.xml to define
the secret and virsh secret-set-value using the generated
UUID value and a base64 generated secret value in order to define the
chosen secret pass phrase.
# 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
See virsh secret-set-value on how to set the value of the secret.
The ceph secret can then be used by UUID or by the
usage name via the <auth> element in a domain's
<disk>
element as follows:
<auth username='myname'>
<secret type='ceph' usage='ceph_example'/>
</auth>
As well as the <auth> element in a
storage pool (rbd)
<source> element as follows:
<auth type='ceph' username='myname'>
<secret usage='ceph_example'/>
</auth>
This secret is associated with an iSCSI target for CHAP authentication.
The <usage type='iscsi'> element must contain
a single target element that specifies a usage name
for the secret. The iSCSI secret can then be used by UUID or by
this usage name via the <auth> element of
a disk device or
a storage pool (iscsi).
Since 1.0.4. 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:
<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>
Define an iscsi-secret.xml file to describe the secret. Use the
incominguser username used in your iSCSI authentication
configuration file as the value for the username attribute.
The description attribute should contain configuration
specific data. The target name may be any name of your
choosing to be used as the usage when used in the pool
or disk XML description.
<secret ephemeral='no' private='yes'>
<description>Passphrase for the iSCSI example.com server</description>
<usage type='iscsi'>
<target>libvirtiscsi</target>
</usage>
</secret>
Next, use virsh secret-define iscsi-secret.xml to define
the secret and
virsh secret-set-value
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.
# virsh secret-define secret.xml
Secret c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 created
# virsh secret-list
UUID Usage
-----------------------------------------------------------
c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 iscsi libvirtiscsi
See virsh secret-set-value on how to set the value of the secret.
The iSCSI secret can then be used by UUID or by the
usage name via the <auth> element in a domain's
<disk>
element as follows:
<auth username='myname'>
<secret type='iscsi' usage='libvirtiscsi'/>
</auth>
As well as the <auth> element in a
storage pool (iscsi)
<source> element as follows:
<auth type='chap' username='myname'>
<secret usage='libvirtiscsi'/>
</auth>
This secret may be used in order to provide the passphrase for the
private key used to provide TLS credentials.
The <usage type='tls'> element must contain a
single name element that specifies a usage name
for the secret.
Since 2.3.0.
The following is an example of the expected XML and processing to
define the secret:
# 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
#
A secret may also be defined via the
virSecretDefineXML 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
virsh secret-set-value to set
the secret value. The
virSecretSetValue API may also be used to set
a more secure secret without using printable/readable characters.
This secret is associated with a virtualized TPM (vTPM) and serves
as a passphrase for deriving a key from for encrypting the state
of the vTPM.
The <usage type='vtpm'> element must contain
a single name element that specifies a usage name
for the secret. The vTPM secret can then be used by UUID
via the <encryption> element of
a tpm when using an
emulator.
Since 5.6.0. The following is an example
of the steps to be taken. First create a vtpm-secret.xml file:
# cat vtpm-secret.xml
<secret ephemeral='no' private='yes'>
<description>sample vTPM secret</description>
<usage type='vtpm'>
<name>VTPM_example</name>
</usage>
</secret>
# virsh secret-define vtpm-secret.xml
Secret 6dd3e4a5-1d76-44ce-961f-f119f5aad935 created
# virsh secret-list
UUID Usage
----------------------------------------------------------------------------------------
6dd3e4a5-1d76-44ce-961f-f119f5aad935 vtpm VTPM_example
#
A secret may also be defined via the
virSecretDefineXML API.
Once the secret is defined, a secret value will need to be set. The
secret would be the passphrase used to decrypt the vTPM state.
The following is a simple example of using
virsh secret-set-value
to set the secret value. The
virSecretSetValue API may also be used to set
a more secure secret without using printable/readable characters.
To set the value of the secret you can use the following virsh commands. If the secret is a password-like string (printable characters, no newline) you can use:
# virsh secret-set-value --interactive 6dd3e4a5-1d76-44ce-961f-f119f5aad935
Enter new value for secret:
Secret value set
Another secure option is to read the secret from a file. This way the
secret can contain any bytes (even NUL and non-printable characters). The
length of the secret is the length of the input file. Alternatively the
--plain option can be omitted if the file contents are
base64-encoded.
# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 --file --plain secretinfile
Secret value set
WARNING The following approach is insecure and deprecated. The secret can also be set via an argument. Note that other users may see the actual secret in the process listing! The secret must be base64 encoded.
# MYSECRET=`printf %s "open sesame" | base64`
# virsh secret-set-value 6dd3e4a5-1d76-44ce-961f-f119f5aad935 $MYSECRET
Secret value set