.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Sys::Virt::Secret 3pm"
.TH Sys::Virt::Secret 3pm 2024-04-21 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Sys::Virt::Secret \- Represent & manage a libvirt secret
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::Secret\*(C'\fR module represents a secret managed
by the virtual machine monitor.
.SH METHODS
.IX Header "METHODS"
.ie n .IP "my $uuid = $sec\->\fBget_uuid()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$sec\fR\->\fBget_uuid()\fR" 4
.IX Item "my $uuid = $sec->get_uuid()"
Returns a 16 byte long string containing the raw globally unique identifier
(UUID) for the secret.
.ie n .IP "my $uuid = $sec\->\fBget_uuid_string()\fR" 4
.el .IP "my \f(CW$uuid\fR = \f(CW$sec\fR\->\fBget_uuid_string()\fR" 4
.IX Item "my $uuid = $sec->get_uuid_string()"
Returns a printable string representation of the raw UUID, in the format
\&'XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX'.
.ie n .IP "my $type = $sec\->\fBget_usage_type()\fR" 4
.el .IP "my \f(CW$type\fR = \f(CW$sec\fR\->\fBget_usage_type()\fR" 4
.IX Item "my $type = $sec->get_usage_type()"
Returns the usage type of this secret. The usage type determines the
format of the unique identifier for this secret.
.ie n .IP "my $id = $sec\->\fBget_usage_id()\fR" 4
.el .IP "my \f(CW$id\fR = \f(CW$sec\fR\->\fBget_usage_id()\fR" 4
.IX Item "my $id = $sec->get_usage_id()"
Returns the identifier of the object with which the secret is to
be used. For secrets with a usage type of volume, the identifier
is the fully qualified path.
.ie n .IP "my $xml = $sec\->\fBget_xml_description()\fR" 4
.el .IP "my \f(CW$xml\fR = \f(CW$sec\fR\->\fBget_xml_description()\fR" 4
.IX Item "my $xml = $sec->get_xml_description()"
Returns an XML document containing a complete description of
the secret's configuration
.ie n .IP $sec\->\fBundefine()\fR 4
.el .IP \f(CW$sec\fR\->\fBundefine()\fR 4
.IX Item "$sec->undefine()"
Remove the configuration associated with a secret previously defined
with the \f(CW\*(C`define_secret\*(C'\fR method in Sys::Virt.
.ie n .IP "$bytes = $sec\->\fBget_value()\fR" 4
.el .IP "\f(CW$bytes\fR = \f(CW$sec\fR\->\fBget_value()\fR" 4
.IX Item "$bytes = $sec->get_value()"
Returns the raw bytes for the value of this secret, or undef if
there is no value stored with the secret.
.ie n .IP $sec\->set_value($bytes) 4
.el .IP \f(CW$sec\fR\->set_value($bytes) 4
.IX Item "$sec->set_value($bytes)"
Sets the value for the secret to be \f(CW$bytes\fR.
.SH CONSTANTS
.IX Header "CONSTANTS"
This section documents constants that are used with various
APIs described above
.SS "SECRET USAGE TYPE"
.IX Subsection "SECRET USAGE TYPE"
The following constants refer to the different usage types
.IP Sys::Virt::Secret::USAGE_TYPE_NONE 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_NONE"
The constant for secrets which are not assigned for use with a
particular object
.IP Sys::Virt::Secret::USAGE_TYPE_VOLUME 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_VOLUME"
The constant for secrets which are to be used for storage
volume encryption. The usage ID for secrets will refer to
the fully qualified volume path.
.IP Sys::Virt::Secret::USAGE_TYPE_CEPH 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_CEPH"
The constant for secrets which are to be used for authenticating
to CEPH storage volumes. The usage ID for secrets will refer to
the server name.
.IP Sys::Virt::Secret::USAGE_TYPE_ISCSI 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_ISCSI"
The constant for secrets which are to be used for authenticating
to iSCSI storage volumes. The usage ID for secrets will refer to
the server name.
.IP Sys::Virt::Secret::USAGE_TYPE_TLS 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_TLS"
The constant for secrets which are to be used for authenticating
for the TLS environment. The usage ID for the secret can be any
name. The UUID for the secret will be used by the hypervisor to
fetch the secret value.
.IP Sys::Virt::Secret::USAGE_TYPE_VTPM 4
.IX Item "Sys::Virt::Secret::USAGE_TYPE_VTPM"
The constant for secrets which are to be used for encrypting
virtual TPM state. The usage ID for the secret will refer to
the TPM path. The UUID for the secret will be used by the
hypervisor to fetch the secret value.
.SS "LIST FILTERING"
.IX Subsection "LIST FILTERING"
The following constants are used to filter object lists
.IP Sys::Virt::Secret::LIST_EPHEMERAL 4
.IX Item "Sys::Virt::Secret::LIST_EPHEMERAL"
Include any secrets marked as ephemeral
.IP Sys::Virt::Secret::LIST_NO_EPHEMERAL 4
.IX Item "Sys::Virt::Secret::LIST_NO_EPHEMERAL"
Include any secrets not marked as ephemeral
.IP Sys::Virt::Secret::LIST_PRIVATE 4
.IX Item "Sys::Virt::Secret::LIST_PRIVATE"
Include any secrets marked as private
.IP Sys::Virt::Secret::LIST_NO_PRIVATE 4
.IX Item "Sys::Virt::Secret::LIST_NO_PRIVATE"
Include any secrets not marked as private
.SS "SECRET DEFINE"
.IX Subsection "SECRET DEFINE"
The following constants can be used to control the behaviour
of secret define operations
.IP Sys::Virt::Secret::DEFINE_VALIDATE 4
.IX Item "Sys::Virt::Secret::DEFINE_VALIDATE"
Validate the XML document against the XML schema
.SS "EVENT ID CONSTANTS"
.IX Subsection "EVENT ID CONSTANTS"
.IP Sys::Virt::Secret::EVENT_ID_LIFECYCLE 4
.IX Item "Sys::Virt::Secret::EVENT_ID_LIFECYCLE"
Secret lifecycle events
.IP Sys::Virt::Secret::EVENT_ID_VALUE_CHANGED 4
.IX Item "Sys::Virt::Secret::EVENT_ID_VALUE_CHANGED"
Secret value change events
.SS "LIFECYCLE CHANGE EVENTS"
.IX Subsection "LIFECYCLE CHANGE EVENTS"
The following constants allow secret lifecycle change events to be
interpreted. The events contain both a state change, and a
reason though the reason is currently unused.
.IP Sys::Virt::Secret::EVENT_DEFINED 4
.IX Item "Sys::Virt::Secret::EVENT_DEFINED"
Indicates that a persistent configuration has been defined for
the secret.
.IP Sys::Virt::Secret::EVENT_UNDEFINED 4
.IX Item "Sys::Virt::Secret::EVENT_UNDEFINED"
The persistent configuration has gone away
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2009 Red Hat
Copyright (C) 2006\-2007 Daniel P. Berrange
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU General Public License as published
by the Free Software Foundation (either version 2 of the License, or at
your option any later version), or, the Artistic License, as specified
in the Perl README file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt, Sys::Virt::Error, \f(CW\*(C`http://libvirt.org\*(C'\fR