libvirt/docs/formatsecret.html.in

<html>
  <body>
    <h1>Secret XML format</h1>

    <ul id="toc"></ul>

    <h2><a name="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> and <code>ceph</code> are defined.
        Specific usage categories are described below.
      </dd>
    </dl>

    <h3>Usage type "volume"</h3>

    <p>
      This secret is associated with a volume, and it is safe to delete the
      secret after the volume is deleted.  The <code>&lt;usage
      type='volume'&gt;</code> element must contain a
      single <code>volume</code> element that specifies the key of the volume
      this secret is associated with.
    </p>

    <h3>Usage type "ceph"</h3>

    <p>
      This secret is associated with a Ceph RBD (rados block device).
      The <code>&lt;usage type='ceph'&gt;</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>&lt;auth&gt;</code> element of
      a <a href="domain.html#elementsDisks">disk
      device</a>. <span class="since">Since 0.9.7</span>.
    </p>

    <h2><a name="example">Example</a></h2>

    <pre>
      &lt;secret ephemeral='no' private='yes'&gt;
         &lt;description&gt;LUKS passphrase for the main hard drive of our mail server&lt;/description&gt;
         &lt;usage type='volume'&gt;
            &lt;volume&gt;/var/lib/libvirt/images/mail.img&lt;/volume&gt;
         &lt;/usage&gt;
      &lt;/secret&gt;</pre>
  </body>
</html>
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/html: Re-generated docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list 2009-07-28 02:39:48 +02:00			`<html>`
			`<body>`
			`<h1>Secret XML format</h1>`

			`<ul id="toc"></ul>`

			`<h2><a name="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>`
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'> 2009-09-01 19:25:11 +02:00			`<dt><code>usage</code></dt>`
			`<dd>`
Cleanup whitespace in docs This patch is the result of running the following command in the docs directory: sed -i 's/\t/ /g; s/\s$//' .html.in * docs/*.html.in:convert tabs into 8 spaces and remove trailing whitespace 2009-11-06 16:04:19 +01:00			`Specifies what this secret is used for. A mandatory`
			`<code>type</code> attribute specifies the usage category, currently`
secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net> 2011-10-28 11:30:45 -06:00			`only <code>volume</code> and <code>ceph</code> are defined.`
			`Specific usage categories are described below.`
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'> 2009-09-01 19:25:11 +02:00			`</dd>`
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/html: Re-generated docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list 2009-07-28 02:39:48 +02:00			`</dl>`

Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'> 2009-09-01 19:25:11 +02:00			`<h3>Usage type "volume"</h3>`

			`<p>`
			`This secret is associated with a volume, 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 key of the volume`
			`this secret is associated with.`
			`</p>`

secret: add Ceph secret type Add a new secret type to store a Ceph authentication key. The name is simply an identifier for easy human reference. The xml looks like this: <secret ephemeral='no' private='no'> <uuid>0a81f5b2-8403-7b23-c8d6-21ccc2f80d6f</uuid> <usage type='ceph'> <name>mycluster_admin</name> </usage> </secret> Signed-off-by: Sage Weil <sage@newdream.net> Signed-off-by: Josh Durgin <josh.durgin@dreamhost.net> 2011-10-28 11:30:45 -06:00			`<h3>Usage type "ceph"</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="domain.html#elementsDisks">disk`
			`device</a>. <span class="since">Since 0.9.7</span>.`
			`</p>`

Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/html: Re-generated docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list 2009-07-28 02:39:48 +02:00			`<h2><a name="example">Example</a></h2>`

			`<pre>`
			`<secret ephemeral='no' private='yes'>`
			`<description>LUKS passphrase for the main hard drive of our mail server</description>`
Add <usage> to <secret> docs * docs/formatsecret.html.in, docs/formatsecret.html: Document <usage type='volume'>, replacing stand-alone <volume>. * docs/schemas/secret.rng: Update schema to require <usage type='volume'> 2009-09-01 19:25:11 +02:00			`<usage type='volume'>`
			`<volume>/var/lib/libvirt/images/mail.img</volume>`
			`</usage>`
Secret manipulation public API This patch adds a "secret" as a separately managed object, using a special-purpose API to transfer the secret values between nodes and libvirt users. * docs/schemas/secret.rng, docs/schemas/Makefilem.am: Add new schema for virSecret objects * docs/html: Re-generated docs/formatsecret.html.in, docs/sitemap.html.in: Add page describing the virSecret XML schema * include/libvirt/libvirt.h.in: Define the new virSecret public API * src/libvirt_public.syms: Export symbols for new public APIs * mingw32-libvirt.spec.in, libvirt.spec.in: Add secret.rng to files list 2009-07-28 02:39:48 +02:00			`</secret></pre>`
			`</body>`
			`</html>`