# Secret XML format

- Secret XML
- Example

## 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` and `ceph` 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.

### 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. Since 0.9.7.

### 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. Since 1.0.4.

## Example

          <secret ephemeral='no' private='yes'>
             <description>LUKS passphrase for the main hard drive of our mail server</description>
             <usage type='volume'>
                <volume>/var/lib/libvirt/images/mail.img</volume>
             </usage>
          </secret>