Secret XML format

Secret XML

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':

ephemeral: This secret must only be kept in memory, never stored persistently.
private: The value of the secret must not be revealed to any caller of libvirt, nor to any other node.

The top-level secret element may contain the following elements:

uuid: An unique identifier for this secret (not necessarily in the UUID format). If omitted when defining a new secret, a random UUID is generated.
description: A human-readable description of the purpose of the secret.
usage: Specifies what this secret is used for. A mandatory type attribute specifies the usage category, currently only volume, ceph, iscsi, and passphrase are defined. Specific usage categories are described below.

Usage type "volume"

This secret is associated with a volume, 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 key 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 pass phrase as follows:

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

The volume type secret can then be used in the XML for a storage volume encryption as follows:

      <encryption format='qcow'>
        <secret type='passphrase' uuid='0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f'/>
      </encryption>

Usage type "ceph"

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
      #
      # CEPHPHRASE=`printf %s "pass phrase" | base64`
      # virsh secret-set-value 1b40a534-8301-45d5-b1aa-11894ebb1735 $CEPHPHRASE
      Secret value set

      #

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>

Usage type "iscsi"

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

      # MYSECRET=`printf %s "mysecret" | base64`
      # virsh secret-set-value c4dbe20b-b1a3-4ac1-b6e6-2ac97852ebb6 $MYSECRET
      Secret value set
      #

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>

Usage type "passphrase"

This secret is a general purpose secret to be used by various libvirt objects to provide a single passphrase as required by the object in order to perform its authentication. For example, this secret will be used either by the storage volume in order to provide the passphrase to encrypt a luks volume or by the disk device in order to provide the passphrase to decrypt the luks volume for usage. Since 2.1.0. The following is an example of a secret.xml file:

      # cat secret.xml
      <secret ephemeral='no' private='yes'>
         <description>sample passphrase secret</description>
         <usage type='passphrase'>
            <name>name_example</name>
         </usage>
      </secret>

      # virsh secret-define secret.xml
      Secret 718c71bd-67b5-4a2b-87ec-a24e8ca200dc created

      # virsh secret-list
       UUID                                 Usage
      -----------------------------------------------------------
       718c71bd-67b5-4a2b-87ec-a24e8ca200dc  passphrase  name_example
      #

A secret may also be defined via the virSecretDefineXML API. Once the secret is defined, a secret value will need to be set. This value would be the same used to create and use the volume. 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.

      # MYSECRET=`printf %s "letmein" | base64`
      # virsh secret-set-value 718c71bd-67b5-4a2b-87ec-a24e8ca200dc $MYSECRET
      Secret value set