mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-23 22:25:25 +00:00
8f83af6823
https://bugzilla.redhat.com/show_bug.cgi?id=1526382
Since commit c4eedd793 disallowed qcow2 encrypted images to be
used for domains, it no longer makes sense to allow a qcow2
encrypted volume to be created or resized.
Add a test that will exhibit the failure of creation as well
as the xml2xml validation of the format still being correct.
Update the documentation to note the removal of the capability
to create and use qcow/default encrypted volumes.
Signed-off-by: John Ferlan <jferlan@redhat.com>
ACKed-by: Michal Privoznik <mprivozn@redhat.com>
331 lines
11 KiB
XML
331 lines
11 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html>
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<body>
|
|
<h1>Secret XML format</h1>
|
|
|
|
<ul id="toc"></ul>
|
|
|
|
<h2><a id="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>
|
|
<dt><code>usage</code></dt>
|
|
<dd>
|
|
Specifies what this secret is used for. A mandatory
|
|
<code>type</code> attribute specifies the usage category, currently
|
|
only <code>volume</code>, <code>ceph</code>, <code>iscsi</code>,
|
|
and <code>tls</code> are defined. Specific usage categories
|
|
are described below.
|
|
</dd>
|
|
</dl>
|
|
|
|
<h3><a id="VolumeUsageType">Usage type "volume"</a></h3>
|
|
|
|
<p>
|
|
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
|
|
<code><usage type='volume'></code> element must contain a
|
|
single <code>volume</code> element that specifies the path of the volume
|
|
this secret is associated with. For example, create a volume-secret.xml
|
|
file as follows:
|
|
</p>
|
|
|
|
<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>
|
|
Define the secret and set the passphrase as follows:
|
|
</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>
|
|
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>
|
|
|
|
<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>
|
|
|
|
<h3><a id="CephUsageType">Usage type "ceph"</a></h3>
|
|
<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
|
|
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>. 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
|
|
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
|
|
|
|
#
|
|
</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:
|
|
</p>
|
|
<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>
|
|
|
|
<h3><a id="iSCSIUsageType">Usage type "iscsi"</a></h3>
|
|
|
|
<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
|
|
for the secret. The iSCSI secret can then be used by UUID or by
|
|
this usage name via the <code><auth></code> element of
|
|
a <a href="formatdomain.html#elementsDisks">disk device</a> or
|
|
a <a href="formatstorage.html">storage pool (iscsi)</a>.
|
|
<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.
|
|
</p>
|
|
<pre>
|
|
<secret ephemeral='no' private='yes'>
|
|
<description>Passphrase for the iSCSI example.com server</description>
|
|
<usage type='iscsi'>
|
|
<target>libvirtiscsi</target>
|
|
</usage>
|
|
</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
|
|
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
|
|
#
|
|
</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>
|
|
|
|
<h3><a id="tlsUsageType">Usage type "tls"</a></h3>
|
|
|
|
<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>
|
|
# 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
|
|
#
|
|
|
|
</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>
|
|
# MYSECRET=`printf %s "letmein" | base64`
|
|
# virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
|
|
Secret value set
|
|
|
|
</pre>
|
|
|
|
</body>
|
|
</html>
|