Sys::Virt(3pm)

📦
version 12.4.0 · 12 versions
, in epel 10

💖 Sys::Virt(3pm) 💖

okay so this is the Sys::Virt page from the User Contributed Perl Documentation (section 3pm), and bestie, it's a whole vibe — it's how you talk to libvirt from Perl. buckle up 🎀

✨ NAME ✨

Sys::Virt — literally the module that lets you represent and manage a libvirt hypervisor connection. that's the whole thing. slay.

🦋 SYNOPSIS 🦋

like, the entire energy of this module in four lines:

  my $conn = Sys::Virt->new(uri => $uri);

  my @domains = $conn->list_domains();

  foreach my $dom (@domains) {
    print "Domain ", $dom->get_id, " ", $dom->get_name, "\n";
  }

look at her go 💅

🌸 DESCRIPTION 🌸

so Sys::Virt gives you a Perl XS binding to the libvirt virtual machine management APIs. the whole point? machines running inside arbitrary virtualization containers can be managed through one consistent API. no cap, that's the flex. ✨

🎀 CALLBACK HANDLING 🎀

every single callback registration routine hands you back a $callbackID — except for "domain_event_register" and "register_close_callback", those two are the exceptions, don't come for me.

⚠️ IMPORTANT: you must deregister all callbacks — and yes that includes the ones you registered with "domain_event_register" and "register_close_callback". if you don't, the Sys::Virt object will not get garbage collected and the connection to "libvirtd" will not be closed. like it just sits there. forever. haunting you. 😭

so keep that return value, bestie. hold onto it. it's your deregistration ticket 🎟️

🫶 ERROR HANDLING 🫶

any operation in the Sys::Virt API that has a failure scenario will throw an instance of the Sys::Virt::Error module. to catch it, you just wrap the method in an eval block:

  eval { my $conn = Sys::Virt->new(uri => $uri); };
  if ($@) {
    print STDERR "Unable to open connection to $addr" . $@->message . "\n";
  }

that's it, that's the trap 🪤

for all the deets on what's actually inside those error objects, go read the Sys::Virt::Error manual page. iykyk.

👑 METHODS 👑

my $conn = Sys::Virt->new(uri => $uri, readonly => $ro, flags => $flags);

attaches you to the virtualization host identified by "uri". you can leave the "uri" parameter out entirely — but then you get the default connection, which is to the local Xen hypervisor. iconic of it, honestly.

some example URIs, since everyone always asks:

  • xen:/// — Xen on the local machine
  • test:///default — a dummy "in memory" driver, made for test suites
  • qemu:///system — the system-wide driver for QEMU / KVM virtualization
  • qemu:///session — the per-user driver for QEMU virtualization
  • qemu+tls://somehost/system — system-wide QEMU driver on "somehost", using TLS security
  • xen+tcp://somehost/ — Xen driver on "somehost", using TCP / SASL security
for even more detail, consult "http://libvirt.org/uri.html" 🔗

now the optional params, listen up:

if you supply the optional "readonly" parameter, an unprivileged connection to the hypervisor gets attempted. if you don't supply it, it defaults to making a fully privileged connection to the hypervisor. and if the calling application isn't running as root, you may need to provide authentication callbacks. like, may. it's giving "depends" 😌

then there's the optional "auth" parameter. set it to a non-zero value and authentication gets enabled during connection, using the default set of credential gathering callbacks. ⚠️ heads up though: those default callbacks prompt for credentials on the console, so they are not suitable for graphical applications. for those, you need to supply a custom implementation.

  • the "credlist" parameter should be an array reference listing the set of credential types that will be supported — the credential constants in this module can be used as values in this list.
  • the "callback" parameter should be a subroutine reference containing the code necessary to gather the credentials.

when that subroutine gets invoked, it's supplied with a single parameter: an array reference of requested credentials. the elements of that array are hash references, with these keys:

  • "type" — the type of credential
  • "prompt" — a user descriptive user prompt
  • "challenge" — the name of the credential required

you collect the answer from the user, and return it by setting the "result" key. ✨ fun fact: that key may already be set with a default result, if applicable.

as a simple example returning hardcoded credentials:

  my $uri  = "qemu+tcp://192.168.122.1/system";
  my $username = "test";
  my $password = "123456";

  my $con = Sys::Virt->new(uri => $uri,
                           auth => 1,
                           credlist => [
                             Sys::Virt::CRED_AUTHNAME,
                             Sys::Virt::CRED_PASSPHRASE,
                           ],
                           callback =>
       sub {
             my $creds = shift;

             foreach my $cred (@{$creds}) {
                if ($cred->{type} == Sys::Virt::CRED_AUTHNAME) {
                    $cred->{result} = $username;
                }
                if ($cred->{type} == Sys::Virt::CRED_PASSPHRASE) {
                    $cred->{result} = $password;
                }
             }
             return 0;
       });

and for backwards compatibility with earlier releases, the "address" parameter is accepted as a synonym for the "uri" parameter. but the use of "uri" is recommended for all newly written code — so like, new code, new you 💅

$conn->set_identity($identity, $flags=0)

changes the identity used for access control over the connection. normally the remote daemon just uses the identity associated with the UNIX domain socket that the app opens — and only a privileged client is usually able to override this. main character energy only 🔥

the $identity should be a hash reference whose keys are one of the IDENTITY constants. the $flags parameter is currently unused, and defaults to 0 if omitted.

my $st = $conn->new_stream($flags)

creates a new stream, with the given flags. short and sweet 🦋

my $dom = $conn->create_domain($xml, $flags=0);

creates a brand new domain based on the XML description you pass into the $xml parameter. what comes back is an instance of the Sys::Virt::Domain class. 💀 real talk: this method is not available with unprivileged connections to the hypervisor. the $flags parameter accepts one of the DOMAIN CREATION constants documented in Sys::Virt::Domain, and defaults to 0 if omitted.

my $dom = $conn->create_domain_with_files($xml, $fds, $flags=0);

same deal, creates a new domain from the XML description in the $xml parameter, and returns an instance of the Sys::Virt::Domain class. again, ⚠️ not available with unprivileged connections to the hypervisor.

the $fds parameter is an array of UNIX file descriptors which will be passed to the init process of the container — and heads up, this is only supported with container based virtualization, so don't try it elsewhere fr fr. the $flags parameter accepts one of the DOMAIN CREATION constants documented in Sys::Virt::Domain, and defaults to 0 if omitted.

my $dom = $conn->define_domain($xml, $flags=0);

defines a new domain based on the XML in $xml — but does not start it. she's registered, she's not awake yet 😴. returns an instance of the Sys::Virt::Domain class.

not available with unprivileged connections to the hypervisor. you can start the defined domain later by calling the "create" method on the returned "Sys::Virt::Domain" object. the $flags parameter accepts one of the DOMAIN DEFINE constants documented in Sys::Virt::Domain, and defaults to 0 if omitted.

my $net = $conn->create_network($xml, $flags=0);

creates a new network based on the XML description passed into $xml, returning an instance of the Sys::Virt::Network class. ⚠️ not available with unprivileged connections to the hypervisor. the $flags parameter accepts one of the NETWORK CREATION constants documented in Sys::Virt::Network, and defaults to 0 if omitted.

my $net = $conn->define_network($xml, $flags=0);

defines — but does not start — a new network from the XML description in $xml. returns an instance of the Sys::Virt::Network class. not available with unprivileged connections to the hypervisor. you can start the defined network later by calling the "create" method on the returned "Sys::Virt::Network" object. the $flags parameter accepts one of the NETWORK DEFINE constants documented in Sys::Virt::Network, and defaults to 0 if omitted. ✨

my $nwfilter = $conn->define_nwfilter($xml, $flags=0);

defines a new network filter based on the XML description passed into $xml, and returns an instance of the Sys::Virt::NWFilter class. ⚠️ not available with unprivileged connections to the hypervisor. the $flags parameter accepts one of the NWFILTER DEFINE constants documented in Sys::Virt::NWFilter, and defaults to 0 if omitted.

my $binding = $conn->create_nwfilter_binding($xml, $flags=0);

creates a new network filter binding based on the XML description passed into $xml. you get back an instance of the Sys::Virt::NWFilterBinding class. 🎀 the $flags parameter accepts one of the NETWORK FILTER BINDING CREATION constants documented in Sys::Virt::NWFilterBinding, and defaults to 0 if omitted. (note: no "not available with unprivileged connections" line on this one — that's just how the page do)

my $secret = $conn->define_secret($xml, $flags=0);

defines a new secret based on the XML description passed into $xml, returning an instance of the Sys::Virt::Secret class. 🤫 not available with unprivileged connections to the hypervisor. the $flags parameter accepts one of the SECRET DEFINE constants documented in Sys::Virt::Secret, and defaults to 0 if omitted.

my $pool = $conn->create_storage_pool($xml);

creates a new storage pool based on the XML description passed into $xml. what you get back is an instance of the Sys::Virt::StoragePool class. ⚠️ not available with unprivileged connections to the hypervisor. (and yeah, no $flags on this one — read it again, she's different 💅)

my $pool = $conn->define_storage_pool($xml, $flags=0);

defines — but does not start — a new storage pol based on the XML description passed into $xml. yes, "pol". that's how the page spells it. i'm just the messenger 🙈

returns an instance of the Sys::Virt::StoragePool class. not available with unprivileged connections to the hypervisor. the defined pool can be started later by calling the "create" method on the returned "Sys::Virt::StoragePool" object. the $flags parameter accepts one of the STORAGE POOL DEFINE constants documented in Sys::Virt::StoragePool, and defaults to 0 if omitted.

my $pool = $conn->create_interface($xml);

creates a new interface based on the XML description passed into $xml, and hands you back an instance of the Sys::Virt::Interface class. 🔌 not available with unprivileged connections to the hypervisor.

my $iface = $conn->define_interface($xml, $flags=0);

Bestie, this one defines a brand-new interface from the XML description you drop into $xml — but it does not start it. Like, it exists now, but it's giving "hibernating main character." 💤

The object it hands back is an instance of the Sys::Virt::Interface class. Heads up though: this method is not available with unprivileged connections to the hypervisor (sorry, no-trust-fund besties 🙈). When you actually wanna wake it up, call the "create" method on the returned Sys::Virt::Interface object. The $flags parameter takes one of the INTERFACE DEFINE constants documented in Sys::Virt::Interface, and it defaults to 0 if you omit it. ✨

my $dev = $conn->create_node_device($xml, $flags=0);

Making a whole new virtual node device from the XML in $xml. The returned object is a Sys::Virt::NodeDevice instance. 💅 Also not available with unprivileged connections — soz. The $flags parameter accepts one of the NODE DEVICE CREATION constants documented in Sys::Virt::NodeDevice, and defaults to 0 if omitted. 🎀

my $dev = $conn->define_node_device($xml, $flags=0);

Same energy but defined-not-started: this defines a new node dev from the XML in $xml and returns a Sys::Virt::NodeDevice instance. Not available with unprivileged connections. 🔒 You can start it later by calling "create" on that returned Sys::Virt::NodeDevice object. $flags takes one of the NODE DEVICE DEFINE constants from Sys::Virt::NodeDevice, defaulting to 0 when omitted.

my @doms = $conn->list_domains()

Returns a list of all running domains the hypervisor currently knows about 🏃‍♀️💨, and each element is a Sys::Virt::Domain instance.

Fair warning, bestie: this method needs O(n) RPC calls, so "list_all_domains" is recommended as the more efficient alternative. Your latency will thank you. 😭

my $nids = $conn->num_of_domains()

Returns the number of running domains the hypervisor knows about. Handy as the "maxids" parameter for "list_domain_ids". Count 'em up 🔢

my @domIDs = $conn->list_domain_ids($maxids)

Gives you a list of all domain IDs currently known to the hypervisor. Those IDs are exactly what you feed into the "get_domain_by_id" method. 🆔

my @doms = $conn->list_defined_domains()

All the domains that are defined but not currently running — the "I'm on my grind, don't perceive me" era of domains 💤. Elements are Sys::Virt::Domain instances.

Again: O(n) RPC calls, so "list_all_domains" is the recommended, more efficient alternative. No cap. 🫶

my $ndoms = $conn->num_of_defined_domains()

Returns the number of running domains known to the hypervisor (that's exactly how the docs put it, bestie — I'm just the messenger 🌸). You can slot it in as the "maxnames" parameter to "list_defined_domain_names".

my @names = $conn->list_defined_domain_names($maxnames)

A list of names for all domains defined but not currently running on the hypervisor. Use those names with the "get_domain_by_name" method. 📛

my @doms = $conn->list_all_domains($flags)

Now THIS is the icon — every domain the hypervisor knows about, whether it's running or shutoff 👑. Each element is a Sys::Virt::Domain instance, and you can use the $flags parameter to filter the list of returned domains. Slay. ✨

my @nets = $conn->list_networks()

Returns all networks the hypervisor currently knows about — each element being a Sys::Virt::Network instance. 🌐

But obvs: O(n) RPC calls, so "list_all_networks" is the recommended, more efficient alternative. 💅

my $nnets = $conn->num_of_networks()

Number of running networks the hypervisor knows about. Perfect as the "maxids" parameter for "list_network_ids". 🔢

my @netNames = $conn->list_network_names($maxnames)

Returns a list of all network names the hypervisor currently knows about. Those names work with the "get_network_by_name" method. 🏷️

my @nets = $conn->list_defined_networks()

Every network that's defined but not currently running on the hypervisor 💤. Elements are Sys::Virt::Network instances.

And yeah — O(n) RPC calls, so "list_all_networks" is the recommended, more efficient alternative. 😭

my $nnets = $conn->num_of_defined_networks()

Returns the number of running networks known to the host. Use it as the "maxnames" parameter to "list_defined_network_names". 🫶

my @names = $conn->list_defined_network_names($maxnames)

List of names of all networks defined but not currently running on the host. Feed those names to "get_network_by_name". 📛

my @nets = $conn->list_all_networks($flags)

All networks the hypervisor knows about, running or shutoff — the full collection 🦋. Elements are Sys::Virt::Network instances, and $flags can filter the returned networks.

my @pools = $conn->list_storage_pools()

Returns all storage pools currently known to the host — each element a Sys::Virt::StoragePool instance. 🗄️✨

Bestie, you guessed it: O(n) RPC calls, so "list_all_storage_pools" is the recommended, more efficient alternative. 💀

my $npools = $conn->num_of_storage_pools()

Number of running storage pools the hypervisor knows about — use it as the "maxids" parameter to "list_storage_pool_names". 🔢

my @poolNames = $conn->list_storage_pool_names($maxnames)

Returns all storage pool names currently known to the hypervisor. Per the docs, "the IDs can be used with the "get_network_by_id" method" — yup, that's literally what it says, I don't make the rules 🙈💅 (reproducing faithfully, bestie).

my @pools = $conn->list_defined_storage_pools()

Every storage pool defined but not currently running on the host 💤. Elements are Sys::Virt::StoragePool instances.

O(n) RPC calls again, so "list_all_storage_pools" is your more efficient alternative. 🌸

my $npools = $conn->num_of_defined_storage_pools()

Returns the number of running networks known to the host (yes, "networks" — docs said what they said, and I'm passing it along verbatim 🎀). Works as the "maxnames" parameter to "list_defined_storage_pool_names".

my @names = $conn->list_defined_storage_pool_names($maxnames)

Names of all storage pools defined but not currently running on the host. Those names go straight into "get_storage_pool_by_name". 📛

my @pools = $conn->list_all_storage_pools($flags)

Every storage pool the hypervisor knows about, running or shutoff 🔥. Elements are Sys::Virt::StoragePool instances, and $flags filters the returned pools.

my @devs = $conn->list_node_devices($capability)

All devices the host OS currently knows about — each element a Sys::Virt::NodeDevice instance. 🖥️🔌 The optional "capability" parameter lets you restrict the list to only devices with a particular capability type.

O(n) RPC calls, bestie, so "list_all_node_devices" is the recommended, more efficient alternative. 🫶

my $ndevs = $conn->num_of_node_devices($capability[, $flags])

Returns the number of host devices the hypervisor knows about — perfect as the "maxids" parameter to "list_node_device_names". 🧮 The "capability" parameter restricts the list to only devices with a particular capability type, and you should leave it as "undef" if you want the full list. The optional flags parameter is currently unused and defaults to 0 if omitted.

my @devNames = $conn->list_node_device_names($capability, $maxnames[, $flags])

my @devNames = $conn->list_node_device_names($capability, $maxnames[, $flags])

A list of all host device names currently known to the hypervisor, usable with the "get_node_device_by_name" method. 🏷️ Same deal on "capability": restrict to one capability type, or leave it "undef" for the full list. The optional flags parameter is currently unused and defaults to 0 if omitted.

my @devs = $conn->list_all_node_devices($flags)

All node devices the hypervisor currently knows about — elements are Sys::Virt::NodeDevice instances. $flags can be used to filter the returned devices. 🌈

my @ifaces = $conn->list_interfaces()

Returns all network interfaces currently known to the hypervisor, each element a Sys::Virt::Interface instance. 🔌💖

And O(n) RPC calls — so "list_all_interfaces" is the recommended, more efficient alternative. 😭

my $nifaces = $conn->num_of_interfaces()

Number of running interfaces known to the hypervisor. Slot it in as the "maxnames" parameter to "list_interface_names". 🔢

my @names = $conn->list_interface_names($maxnames)

All interface names currently known to the hypervisor — use them with "get_interface_by_name". 📛

my @ifaces = $conn->list_defined_interfaces()

Returns a list of all network interfaces currently known to the hypervisor, each element being a Sys::Virt::Interface instance. 🦋

Yes, same energy: O(n) RPC calls, so "list_all_interfaces" is the recommended, more efficient alternative. 💀

my $nifaces = $conn->num_of_defined_interfaces()

Number of inactive interfaces known to the hypervisor — use as the "maxnames" parameter to "list_defined_interface_names". 🧮

my @names = $conn->list_defined_interface_names($maxnames)

List of inactive interface names currently known to the hypervisor. Those names work with "get_interface_by_name". 🏷️

my @ifaces = $conn->list_all_interfaces($flags)

Every interface the hypervisor knows about, running or shutoff 👑✨. Elements are Sys::Virt::Interface instances, and $flags filters the returned interfaces.

my @ifaces = $conn->list_secrets()

okay so this one hands you a list of every secret the hypervisor currently knows about, and each element is a Sys::Virt::Secret object 💅 heads up tho — this does O(n) RPC calls (yes, one per secret, it's giving "walking to every store in the mall"), so the list_all_secrets method is the recommended, way more efficient alternative ✨

my $nuuids = $conn->num_of_secrets()

returns the count of secrets the hypervisor knows about 🔢 and you can totally feed that number straight into list_secrets as its maxuuids parameter 🫶

my @uuids = $conn->list_secret_uuids($maxuuids)

gives you a list of all the secret uuids the hypervisor currently knows about — and those uuids slot right into get_secret_by_uuid like they were made for each other 💖

my @secrets = $conn->list_all_secrets($flags)

returns every secret currently known to the hypervisor. and yes bestie, the original literally says the elements in the returned list are instances of the Sys::Virt::Network class 😭 that's what the doc says, so that's what you get — $flags lets you filter the list of returned secrets 🎀

my @nwfilters = $conn->list_nwfilters()

hands back all the nwfilters currently known to the hypervisor, each one a Sys::Virt::NWFilter object. same deal as above: O(n) RPC calls 😮‍💨 so list_all_nwfilters is the recommended, more efficient glow-up ✨

my $nnwfilters = $conn->num_of_nwfilters()

the number of running nwfilters known to the hypervisor — and this bad boy can be passed as the maxids parameter to list_nwfilter_names 🫶

my @filterNames = $conn->list_nwfilter_names($maxnames)

lists all nwfilter names currently known to the hypervisor, and those names work with get_nwfilter_by_name 💖

my @nwfilters = $conn->list_all_nwfilters($flags)

all the nwfilters currently known to the hypervisor, as Sys::Virt::NWFilter instances. $flags is currently unused and defaults to zero 💀

my @bindings = $conn->list_all_nwfilter_bindings($flags)

gives you all the nwfilter bindings currently known to the hypervisor, every element a Sys::Virt::NWFilterBinding object. $flags is currently unused and defaults to zero 🎀

$conn->define_save_image_xml($file, $dxml, $flags=0)

updates the XML tied to a virtual machine's save image 🖼️ $file is the fully qualified path to the save image XML, and $dxml is the shiny new XML document you're writing. $flags is currently unused and defaults to zero ⭐

$xml = $conn->get_save_image_xml_description($file, $flags=1)

fetches the current XML config for the VM's save image identified by $file. $flags accepts the same constants as Sys::Virt::Domain::managed_save_get_xml_description 💜

okay this next chunk is straight-up the lookup counter — every get-by-something you could ever want ✨

my $dom = $conn->get_domain_by_name($name)

the domain whose name is $name, returned as a Sys::Virt::Domain object 💅

my $dom = $conn->get_domain_by_id($id)

same vibe but by local id $id — also a Sys::Virt::Domain 🫶

my $dom = $conn->get_domain_by_uuid($uuid)

by globally unique id $uuid, still a Sys::Virt::Domain 💖

my $net = $conn->get_network_by_name($name)

the network named $name, as a Sys::Virt::Network object 🌐

my $net = $conn->get_network_by_uuid($uuid)

the network with globally unique id $uuid, also a Sys::Virt::Network 🌸

my $pool = $conn->get_storage_pool_by_name($name)

the storage pool named $name, as a Sys::Virt::StoragePool 🗄️

my $pool = $conn->get_storage_pool_by_uuid($uuid)

the storage pool with globally unique id $uuid — Sys::Virt::StoragePool, obviously 💅

my $pool = $conn->get_storage_pool_by_volume($vol)

the storage pool holding storage volume $vol — and heads up, $vol must be a Sys::Virt::StorageVol object or this is gonna be awkward 😭 returns a Sys::Virt::StoragePool 🫶

my $pool = $conn->get_storage_pool_by_target_path($path)

the storage pool whose target path is $path — Sys::Virt::StoragePool again 🎀

my $vol = $conn->get_storage_volume_by_path($path)

the storage volume located at $path, returned as a Sys::Virt::StorageVol ✨

my $vol = $conn->get_storage_volume_by_key($key)

the storage volume with globally unique id $key — Sys::Virt::StorageVol, periodt 💅

my $dev = $conn->get_node_device_by_name($name)

the node device named $name, as a Sys::Virt::NodeDevice 🔌

my $dev = $conn->get_node_device_scsihost_by_wwn($wwnn, $wwpn, $flags=0)

the node device that's a SCSI host identified by $wwnn and $wwpn. $flags is unused and defaults to zero 💀 returns a Sys::Virt::NodeDevice 🫶

my $iface = $conn->get_interface_by_name($name)

the interface named $name, as a Sys::Virt::Interface 🌈

my $iface = $conn->get_interface_by_mac($mac)

the interface with MAC address $mac — also a Sys::Virt::Interface 💖

my $sec = $conn->get_secret_by_uuid($uuid)

the secret with globally unique id $uuid, as a Sys::Virt::Secret 🔐

my $sec = $conn->get_secret_by_usage($usageType, $usageID)

the secret with usage type $usageType, identified by $usageID — Sys::Virt::Secret, no cap 💅

my $nwfilter = $conn->get_nwfilter_by_name($name)

okay so the doc here literally says "Return the domain with a name of $name" 😭💀 but the returned object is a Sys::Virt::NWFilter — that's what it says, bestie, I'm just the messenger 🎀

my $nwfilter = $conn->get_nwfilter_by_uuid($uuid)

the nwfilter with globally unique id $uuid, returned as a Sys::Virt::NWFilter 💖

my $binding = $conn->get_nwfilter_binding_by_port_dev($name)

the network filter binding for the port device $name, as a Sys::Virt::NWFilterBinding object 🦋

my $xml = $conn->find_storage_pool_sources($type, $srcspec[, $flags])

probes for available storage pool sources for the pool of type $type 🔍 $srcspec can be undef, or a parameter that refines the discovery process — for example, a server hostname for NFS discovery. $flags is optional and defaults to zero if you leave it out. you get back a scalar: an XML document describing all the storage pool sources it found ✨

my @stats = $conn->get_all_domain_stats($stats, \@doms=undef, $flags=0);

gets a list of all the statistics for domains known to the hypervisor 📊 $stats controls which data fields come back and should be a combination of the DOMAIN STATS FIELD CONSTANTS</> — stack 'em up for max info 💅

the optional @doms parameter is a list of Sys::Virt::Domain objects to return stats for. if it's undefined, then all domains get returned 🙈 and the $flags method can filter the list of returned domains 🎀

the return data is a list with one element per domain. each element is a hash with two keys: "dom" pointing at a Sys::Virt::Domain instance, and "data" pointing at another hash reference holding the actual statistics 🫶

$conn->interface_change_begin($flags)

kick off a transaction for changing the config of one or more network interfaces 🚦

$conn->interface_change_commit($flags)

wrap up that transaction — everything's locked in, slay ✅

$conn->interface_change_rollback($flags)

abort the transaction 😭 nothing happened, we pretend we were never here 🙈

$conn->restore_domain($savefile, $dxml=undef, $params=undef, $flags=0)

recreates a domain from the saved state file in $savefile 💾 the optional $dxml parameter lets you tweak portions of the domain XML. $params is a hash reference whose keys are a subset of the SAVE / RESTORE PARAMETER CONSTANTS</>. and $flags accepts one of the SAVE / RESTORE FLAG CONSTANTS</> described later, defaulting to zero ✨

$conn->get_max_vcpus($domtype)

the maximum number of vcpus that can be configured for a domain of type $domtype 🖥️

my $hostname = $conn->get_hostname()

the name of the host this connection is associated with 🏠

my $uri = $conn->get_uri()

the URI of the open connection 💫 and plot twist: this may be different from the URI you used when initially connecting to libvirt, when 'auto-probing' of drivers occurs 👀

my $xml = $conn->get_sysinfo()

an XML document representing the host system information — typically pulled from SMBIOS tables 🧬

my $type = $conn->get_type()

the type of virtualization backend this hypervisor object accesses. currently the only supported type is "Xen" 💀 yep, just the one 🎀

my $xml = $conn->domain_xml_from_native($format, $config);

converts the native hypervisor config $config, which is in format <$format>, into libvirrt domain XML ✨ (that's how it's spelled, bestie, I don't make the rules 💅) valid values of $format vary between hypervisor drivers 🌈

my $config = $conn->domain_xml_to_native($format, $xml)

the other direction — converts the libvirt domain XML config $xml into a native hypervisor config in format $format 🔄

my $ver = $conn->get_version()

the complete version number, as a string encoded with the formula (major * 1000000) + (minor * 1000) + micro 🧮

my $ver = $conn->get_major_version

the major version number of the libvirt library 👑

my $ver = $conn->get_minor_version

the minor version number of the libvirt library 🎀

my $ver = $conn->get_micro_version

the micro version number of the libvirt library 🦋

my $ver = $conn->get_library_version

the version number of the API associated with the active connection ⭐ it differs from get_version in that if you're connected to a remote libvirtd daemon, it returns the API version of the remote libvirt, not your local client 😮‍💨 iykyk

$conn->is_secure()

okay so this one's giving security guard energy 💅 it returns a true value if ur current connection is secure against network interception. and like, that means either u're on UNIX sockets, or u've got encryption on a TCP stream. no cap.

$conn->is_encrypted()

true value if the current connection's data stream is encrypted. that's it, that's the whole vibe 🎀

$conn->is_alive()

true value if the connection is alive — and how does it know? keep-alive packets or other recent RPC traffic. it's literally checking the pulse bestie 🫶

$conn->set_keep_alive($interval, $count)

changes how the keep alive protocol works: send $count packets spaced $interval seconds apart before it's like "ok they're gone, connection dead" 💀

my $info = $con->get_node_info()

returns a hash reference that summarises the capabilities of the host node. the elements of that hash are:

  • memory — the amount of physical memory in the host
  • model — the model of the CPU, eg x86_64
  • cpus — the total number of logical CPUs
  • mhz — the peak MHZ of the CPU
  • nodes — the number of NUMA cells
  • sockets — the number of CPU sockets
  • cores — the number of cores per socket
  • threads — the number of threads per core
NB, more accurate info about the total number of CPUs and which ones are online can be obtained using the "get_node_cpu_map" method. iykyk ✨

my ($totcpus, $onlinemap, $totonline) = $con->get_node_cpu_map();

returns an array with info about the CPUs available on the host 🌈 the first element, "totcpus", is the total number of CPUs available to the host regardless of their online stat. the second element, "onlinemap", gives u a bitmap detailing which CPUs are currently online. the third element, "totonline", is the total number of online CPUs. and the values in that bitmap can be extracted with the "unpack" method like this:

my @onlinemap = split(//, unpack("b*", $onlinemap));

my $info = $con->get_node_cpu_stats($cpuNum=-1, $flags=0)

returns a hash reference with info about the host CPU statistics 🔥 if <$cpuNum> is omitted it defaults to "Sys::Virt::NODE_CPU_STATS_ALL_CPUS", which makes it return cumulative info for all CPUs in the host. if $cpuNum is zero or larger, it returns info just for that specified number. the $flags parameter is currently unused and defaults to zero. the fields in the returned hash reference are:

  • kernel — the time spent in kernelspace
  • user — the time spent in userspace
  • idle — the idle time
  • iowait — the I/O wait time
  • utilization — the overall percentage utilization

my $info = $con->get_node_memory_stats($cellNum=-1, $flags=0)

returns a hash reference with info about the host memory statistics 🌸 if <$cellNum> is omitted it defaults to "Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS", which makes it return cumulative info for all NUMA cells in the host. if $cellNum is zero or larger, it returns info just for the specified number. the $flags parameter is currently unused and defaults to zero. the fields in the returned hash reference are:

  • total — the total memory
  • free — the free memory
  • buffers — the memory consumed by buffers
  • cached — the memory consumed for cache

my $params = $conn->get_node_memory_parameters($flags=0)

returns a hash reference containing the set of memory tunable parameters for the node 💜 the keys in that hash are one of the constants MEMORY PARAMETERS described later. the $flags parameter is currently unused, and defaults to 0 if omitted.

$conn->set_node_memory_parameters($params, $flags=0)

updates the memory tunable parameters for the node 🦋 $params should be a hash reference whose keys are one of the MEMORY PARAMETERS constants. the $flags parameter is currently unused, and defaults to 0 if omitted.

$info = $conn->get_node_sev_info($flags=0)

gets the AMD SEV info for the host 👑 $flags is currently unused and defaults to 0 if omitted. the returned hash contains the following keys:

  • Sys::Virt::SEV_CBITPOS — the CBit position
  • Sys::Virt::SEV_CERT_CHAIN — the certificate chain
  • Sys::Virt::SEV_PDH — platform diffie-hellman key
  • Sys::Virt::SEV_REDUCED_PHYS_BITS — the number of physical address bits used by SEV
  • Sys::Virt::SEV_MAX_GUESTS — maximum number of SEV guests that can be launched
  • Sys::Virt::SEV_MAX_ES_GUESTS — maximum number of SEV-ES guests that can be launched
  • Sys::Virt::SEV_CPU0_ID — the SEV firmware ID for CPU 0

$conn->node_suspend_for_duration($target, $duration, $flags=0)

suspends the the host 😴 using mode $target, which is one of the NODE SUSPEND constants listed later. the $duration parameter controls how long the node is suspended for before it wakes back up.

$conn->domain_event_register($callback)

registers a callback to receive notifications of domain state change events 💖 only a single callback can be registered with each connection instance — one at a time, no sharing bestie. the callback gets invoked with four parameters: an instance of "Sys::Virt" for the connection, an instance of "Sys::Virt::Domain" for the domain changing state, and an "event" and "detail" argument, corresponding to the event constants defined in the "Sys::Virt::Domain" module.

before discarding the connection object, the callback must be deregistered, otherwise the connection object memory will never be released in garbage collection 😭 that's a leak, and not the cute kind.

$conn->domain_event_deregister()

unregisters a callback, letting the connection object get garbage collected 🧚

$callbackID = $conn->domain_event_register_any($dom, $eventID, $callback)

registers a callback to receive notifications of domain events ✨ the $dom parameter can be "undef" to request events on all known domains, or a specific "Sys::Virt::Domain" object to filter events. the $eventID parameter is one of the EVENT ID constants described later in this document. $callback is a subroutine reference that will receive the events.

all callbacks receive a "Sys::Virt" connection as the first parameter and a "Sys::Virt::Domain" object indicating the domain on which the event occurred as the second parameter. subsequent parameters vary according to the event type:

  • EVENT_ID_LIFECYCLE — extra "event" and "detail" parameters defining the lifecycle transition that occurred
  • EVENT_ID_REBOOT — no extra parameters
  • EVENT_ID_RTC_CHANGE — the "utcoffset" gives the offset from UTC in seconds
  • EVENT_ID_WATCHDOG — the "action" defines the action taken as a result of the watchdog triggering. one of the WATCHDOG constants described later
  • EVENT_ID_IO_ERROR — the "srcPath" is the file on the host which had the error. the "devAlias" is the unique device alias from the guest configuration associated with "srcPath". the "action" is the action taken as a result of the error, one of the IO ERROR constants described later
  • EVENT_ID_GRAPHICS — the "phase" is the stage of the connection, one of the GRAPHICS PHASE constants described later. the "local" and "remote" parameters follow with the details of the local and remote network addresses. the "authScheme" describes how the user was authenticated (if at all). finally "identities" is an array ref containing authenticated identities for the user, if any

the return value is a unique callback ID that must be used when unregistering the event 🎀

$conn->domain_event_deregister_any($callbackID)

unregisters a callback, associated with the $callbackID u previously got from "domain_event_register_any" 💅

$callbackID = $conn->network_event_register_any($net, $eventID, $callback)

registers a callback to receive notifications of network events 🌐 the $net parameter can be "undef" to request events on all known networks, or a specific "Sys::Virt::Network" object to filter events. the $eventID parameter is one of the EVENT ID constants described later in this document. $callback is a subroutine reference that will receive the events.

all callbacks receive a "Sys::Virt" connection as the first parameter and a "Sys::Virt::Network" object indicating the network on which the event occurred as the second parameter. subsequent parameters vary according to the event type:

  • EVENT_ID_LIFECYCLE — extra "event" and "detail" parameters defining the lifecycle transition that occurred

the return value is a unique callback ID that must be used when unregistering the event ⭐

$conn->network_event_deregister_any($callbackID)

unregisters a callback, associated with the $callbackID u previously got from "network_event_register_any" 🍓

$callbackID = $conn->storage_pool_event_register_any($pool, $eventID, $callback)

registers a callback to receive notifications of storage pool events 📦 the $pool parameter can be "undef" to request events on all known storage pools, or a specific "Sys::Virt::StoragePool" object to filter events. the $eventID parameter is one of the EVENT ID constants described later in this document. $callback is a subroutine reference that will receive the events.

all callbacks receive a "Sys::Virt" connection as the first parameter and a "Sys::Virt::StoragePool" object indicating the storage pool on which the event occurred as the second parameter. subsequent parameters vary according to the event type:

  • EVENT_ID_LIFECYCLE — extra "event" and "detail" parameters defining the lifecycle transition that occurred
  • EVENT_ID_REFRESH — no extra parameters

the return value is a unique callback ID that must be used when unregistering the event 🌸

$conn->storage_pool_event_deregister_any($callbackID)

unregisters a callback, associated with the $callbackID u previously got from "storage_pool_event_register_any" 🦋

$callbackID = $conn->node_device_event_register_any($dev, $eventID, $callback)

Okay so bestie, this one signs you up for node device events — you know, the host-side hardware gossip. 💅

The $dev parameter? You got options: pass undef if you want to hear about events on all known node devices (yes, all of them, main character energy), or hand over a specific Sys::Virt::NodeDevice object to filter down to just that one device. Picky is fine, we respect it.

The $eventID parameter is one of the EVENT ID constants described later in this document (keep scrolling, they're coming 🫶). And $callback is a subroutine reference that will receive the events — that's your little event-handler bestie.

So, what does your callback actually get handed? All callbacks receive a Sys::Virt connection as the first parameter and a Sys::Virt::NodeDevice object indicating the node device on which the event occurred as the second parameter. Subsequent parameters vary according to the event type:

  • EVENT_ID_LIFECYCLE — extra event and detail parameters defining the lifecycle transition that occurred.

The return value is a unique callback ID that you must use when unregistering the event. Write it down, bestie, don't lose it. 😭

$conn->node_device_event_deregister_any($callbackID)

Unregister a callback, associated with the $callbackID previously obtained from node_device_event_register_any. That's it. Clean break, no drama. 🦋

$callbackID = $conn->secret_event_register_any($secret, $eventID, $callback)

Same vibe, different ✨subject✨ — this one registers a callback to received notifications of secret events. (Yes that's the original phrasing, and honestly "to received" is giving typo but we're not fixing it, we're just living with it. 💀)

$secret can be undef to request events on all known secrets, or a specific Sys::Virt::Secret object to filter events. $eventID is one of the EVENT ID constants described later in this document. $callback is a subroutine reference that will receive the events.

All callbacks receive a Sys::Virt connection as the first parameter and a Sys::Virt::Secret object indicating the secret on which the event occurred as the second parameter. Subsequent parameters vary according to the event type:

  • EVENT_ID_LIFECYCLE — extra event and detail parameters defining the lifecycle transition that occurred.
  • EVENT_ID_VALUE_CHANGED — no extra parameters. Nothing. Zip. Nada. 🍓

The return value is a unique callback ID that must be used when unregistering the event. Same deal as before, bestie.

$conn->secret_event_deregister_any($callbackID)

Unregister a callback, associated with the $callbackID previously obtained from secret_event_register_any. Bye bestie 👋💜

$conn->register_close_callback($coderef);

Register a callback to be invoked when the connection is closed. 😭 It's giving sad goodbye energy but like, useful sad goodbye energy.

The callback will be invoked with two parameters: the $conn it was registered against, and the reason for the close event. That reason value will be one of the CLOSE REASON CONSTANTS listed later in this document — so don't guess at it, go read them, iykyk.

$conn->unregister_close_callback();

Remove the previously registered close callback. One close callback, one removal method, zero lingering feelings. 🎀

my $xml = $con->baseline_cpu(\@xml, $flags=0)

Given an array ref whose elements are XML documents describing host CPUs, compute the baseline CPU model that is operable across all hosts — like finding the common denominator friend group activity that everyone will actually show up for. 🌈

The XML for the baseline CPU model is returned. The optional $flags parameter can take one of:

  • Sys::Virt::BASELINE_CPU_EXPAND_FEATURES — expand the CPU definition to list all feature flags, even those implied by the model name.
  • Sys::Virt::BASELINE_CPU_MIGRATABLE — only include features which can be live migrated.
  • Sys::Virt::BASELINE_CPU_IGNORE_HOST — when multiple CPU definitions are available, do not make the result dependent on the current host CPU.

my $xml = $con->baseline_hypervisor_cpu($emulator, $arch, $machine, $virttype, \@xml, $flags=0)

Given an array ref whose elements are XML documents describing host CPUs, compute the baseline CPU model that is operable across all hosts. The XML for the baseline CPU model is returned. (Yes, same core quest as baseline_cpu, just with more ✨specifics✨ stacked on top. 🔥)

Either $emulator or $arch must be a valid string referring to an emulator binary or an architecture name respectively. The $machine parameter is an optional name of a guest machine, and $virttype is an optional name of the virtualization type.

The optional $flags parameter accepts the same values as baseline_cpu — so go reread that list up there, no cap.

@names = $con->get_cpu_model_names($arch, $flags=0)

Get a list of valid CPU models names for the architecture given by $arch. (Again with the "models names" — the original said it, so we say it. 👑)

The $arch value should be one of the architectures listed in the capabilities XML document. The $flags parameter is currently unused and defaults to 0. It's just sitting there. Vibing. Unused. 🙈

my $info = $con->get_node_security_model()

Returns a hash reference summarising the security model of the host node. Two keys in the hash, bestie:

  • model — specifying the name of the security model (eg 'selinux')
  • doi — specifying the 'domain of interpretation' for security labels

Two keys, zero surprises, we stan a tidy hash. 💖

my $xml = $con->get_capabilities();

Returns an XML document describing the hypervisor capabilities. Short and iconic. ⭐

my $xml = $con->get_domain_capabilities($emulator, $arch, $machine, $virttype, flags=0);

Returns an XML document describing the capabilities of the requested guest configuration. Either $emulator or $arch must be a valid string referring to an emulator binary or an architecture name respectively.

The $machine parameter is an optional name of a guest machine, and $virttype is an optional name of the virtualization type.

$flags defaults to zero, and accepts one or more of the following constants:

  • $Sys::Virt::DOMAIN_CAPABILITIES_DISABLE_DEPRECATED_FEATURES — disable deprecated features when reporting CPU model information.
  • $Sys::Virt::DOMAIN_CAPABILITIES_EXPAND_CPU_FEATURES — expand base CPU features implied by the model name.

(Yes those constants really do start with a $, that's not a typo, that's just how it's written here. 💅)

my $xml = $con->get_storage_pool_capabilities($flags=0);

Returns an XML document describing the storage pool driver capabilities — like, which storage pool types are supported and so on. $flags is currently unused and defaults to zero. Another flag just... existing. Respectfully. 😌

my $result = $con->compare_cpu($xml, $flags=0);

Checks whether the CPU definition in $xml is compatible with the current hypervisor connection. This can be used to determine whether it is safe to migrate a guest to this host — so like, the vibe check before you move the whole party to a new venue. 🔥

The returned result is one of the constants listed later. The optional $flags parameter can take one of the following constants:

  • Sys::Virt::COMPARE_CPU_FAIL_INCOMPATIBLE — raise a fatal error if the CPUs are not compatible, instead of just returning a special error code.
  • Sys::Virt::COMPARE_CPU_VALIDATE_XML — validate input XML document against the RNG schema.

my $result = $con->compare_hypervisor_cpu($emulator, $arch, $machine, $virttype, $xml, $flags=0);

Checks whether the CPU definition in $xml is compatible with the current hypervisor connection. This can be used to determine whether it is safe to migrate a guest to this host. (Same safety check, more parameters, more to keep track of. 🫶)

Either $emulator or $arch must be a valid string referring to an emulator binary or an architecture name respectively. The $machine parameter is an optional name of a guest machine, and $virttype is an optional name of the virtualization type.

The returned result is one of the constants listed later. The optional $flags parameter can take the same values as the compare_cpu method.

$mem = $con->get_node_free_memory();

Returns the current free memory on the host. Just a number, doing its thing. 🧚

@mem = $con->get_node_cells_free_memory($start, $end);

Returns the free memory on each NUMA cell between $start and $end. Per-cell receipts, basically. 🌸

@pages = $con->get_node_free_pages(\@pagesizes, $start, $end);

Returns information about the number of pages free on each NUMA cell between $start and $end inclusive. ✨

The @pagesizes parameter should be an arrayref specifying which pages sizes information should be returned for. Information about supported page sizes is available in the capabilities XML.

The returned array has an element for each NUMA cell requested. The elements are hash references with two keys:

  • 'cell' — specifies the NUMA cell number
  • 'pages' — specifies the free page information for that cell

And the 'pages' value is another hash reference where the keys are the page sizes and the values are the free count for that size. Hash in a hash, like a little gift inside a gift 🎁 — that's nested data slay, bestie.

$con->node_alloc_pages(\@pages, $start, $end, $flags=0)

Allocate further huge pages for the reserved dev. The \@pages parameter is an array reference with one entry per page size to allocate for. Each entry is a further array reference where the first element is the page size and the second element is the page count. 👑

The same number of pages will be allocated on each NUMA node in the range $start to $end inclusive.

The $flags parameter accepts two constants:

  • Sys::Virt::NODE_ALLOC_PAGES_ADD — the requested number of pages will be added to the existing huge page reservation.
  • Sys::Virt::NODE_ALLOC_PAGES_SET — the huge page reservation will be set to exactly the requested number
Heads up bestie: ADD and SET are not the same vibe. One grows what's already reserved, one overwrites it to exactly the requested number. Pick deliberately, no cap. 🫶

✨ CONSTANTS ✨

These constant sets are literally your besties when you're out here using the APIs in this package 💅

🔌 CONNECTION

When you open a connection, these are the constants you can hand over:

  • Sys::Virt::CONNECT_RO — asks for a read-only connection 🙈
  • Sys::Virt::CONNECT_NO_ALIASES — stops URI aliases from getting resolved, no cap

🪪 CREDENTIAL TYPES

When you're hooking up authentication callbacks, these constants tell you what kind of credential the server is asking for:

  • Sys::Virt::CRED_AUTHNAME — the identity to act as
  • Sys::Virt::CRED_USERNAME — the identity to authorize as
  • Sys::Virt::CRED_CNONCE — the client supplies a nonce
  • Sys::Virt::CRED_REALM — the authentication realm
  • Sys::Virt::CRED_ECHOPROMPT — challenge response, non-secret version 👀
  • Sys::Virt::CRED_NOECHOPROMPT — challenge response, secret version 🤫
  • Sys::Virt::CRED_PASSPHRASE — passphrase secret
  • Sys::Virt::CRED_LANGUAGE — RFC 1766 language code
  • Sys::Virt::CRED_EXTERNAL — a credential provided externally

🫶 IDENTITY CONSTANTS

These ones are lowkey iconic if you wanna switch up the connection identity:

  • Sys::Virt::IDENTITY_USER_NAME — the process user name
  • Sys::Virt::IDENTITY_UNIX_USER_ID — the process UNIX user ID
  • Sys::Virt::IDENTITY_GROUP_NAME — the process group name
  • Sys::Virt::IDENTITY_UNIX_GROUP_ID — the process UNIX group ID
  • Sys::Virt::IDENTITY_PROCESS_ID — the process ID
  • Sys::Virt::IDENTITY_PROCESS_TIME — the process start time
  • Sys::Virt::IDENTITY_SASL_USER_NAME — the SASL authenticated user name
  • Sys::Virt::IDENTITY_X509_DISTINGUISHED_NAME — the X509 certificate distinguished name for the TLS connection 🎀
  • Sys::Virt::IDENTITY_SELINUX_CONTEXT — the SELinux process context

🧠 CPU COMPARISON CONSTANTS

  • Sys::Virt::CPU_COMPARE_INCOMPATIBLE — this host is missing one or more CPU features in the CPU description 💀
  • Sys::Virt::CPU_COMPARE_IDENTICAL — the host has an identical CPU description ✨
  • Sys::Virt::CPU_COMPARE_SUPERSET — the host offers a superset of the CPU description

😴 NODE SUSPEND CONSTANTS

  • Sys::Virt::NODE_SUSPEND_TARGET_MEM — suspends to memory (the equivalent of S3 on x86 architectures)
  • Sys::Virt::NODE_SUSPEND_TARGET_DISK — suspends to disk (the equivalent of S5 on x86 architectures)
  • Sys::Virt::NODE_SUSPEND_TARGET_HYBRID — suspends to memory and disk (the equivalent of S3+S5 on x86 architectures) 🦋

🖥️ NODE VCPU CONSTANTS

  • Sys::Virt::NODE_CPU_STATS_ALL_CPUS — request statistics for all CPUs

🍓 NODE MEMORY CONSTANTS

  • Sys::Virt::NODE_MEMORY_STATS_ALL_CELLS — request statistics for all memory cells

💾 MEMORY PARAMETERS

These constants name the memory parameters of the node:

  • Sys::Virt::NODE_MEMORY_SHARED_FULL_SCANS — how many times all mergeable areas have been scanned
  • Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARED — how many the shared memory pages are being used
  • Sys::Virt::NODE_MEMORY_SHARED_PAGES_SHARING — how many sites are sharing the pages
  • Sys::Virt::NODE_MEMORY_SHARED_PAGES_TO_SCAN — how many present pages to scan before the shared memory service goes to sleep 😴
  • Sys::Virt::NODE_MEMORY_SHARED_PAGES_UNSHARED — how many pages unique but repeatedly checked for merging
  • Sys::Virt::NODE_MEMORY_SHARED_PAGES_VOLATILE — how many pages changing too fast to be placed in a tree 🏃‍♀️
  • Sys::Virt::NODE_MEMORY_SHARED_SLEEP_MILLISECS — how many milliseconds the shared memory service should sleep before next scan
  • Sys::Virt::NODE_MEMORY_SHARED_MERGE_ACROSS_NODES — whether pages can be merged across NUMA nodes

🚪 CLOSE REASON CONSTANTS

These ones go with the connection close callback and describe why the connection closed:

  • Sys::Virt::CLOSE_REASON_CLIENT — the client application requested the connection be closed
  • Sys::Virt::CLOSE_REASON_EOF — end-of-file was encountered reading data from the connection
  • Sys::Virt::CLOSE_REASON_ERROR — an I/O error was encountered reading/writing data from/to the connection 😭
  • Sys::Virt::CLOSE_REASON_KEEPALIVE — the connection keepalive timer triggered due to lack of response from the server

⚡ CPU STATS CONSTANTS

These give you the names of the known CPU stats fields:

  • Sys::Virt::NODE_CPU_STATS_IDLE — time spent idle
  • Sys::Virt::NODE_CPU_STATS_IOWAIT — time spent waiting for I/O to complete
  • Sys::Virt::NODE_CPU_STATS_KERNEL — time spent executing kernel code
  • Sys::Virt::NODE_CPU_STATS_USER — time spent executing user code
  • Sys::Virt::NODE_CPU_STATS_INTR — time spent processing interrupts
  • Sys::Virt::NODE_CPU_STATS_UTILIZATION — percentage utilization of the CPU 🔥
  • Sys::Virt::NODE_CPU_STATS_GUEST — time spent running guest virtual CPUs

🧾 MEMORY STAS CONSTANTS

(yeah, "STAS" — we stan a typo, keeping it 💖) These give you the names of the known memory stats fields:

  • Sys::Virt::NODE_MEMORY_STATS_AVAILABLE — the amount of memory available. Heads up: it's only returned in case the $cellNum parameter of get_node_memory_stats equals NODE_MEMORY_STATS_ALL_CELLS.
  • Sys::Virt::NODE_MEMORY_STATS_BUFFERS — the amount of memory consumed by I/O buffers
  • Sys::Virt::NODE_MEMORY_STATS_CACHED — the amount of memory consumed by disk cache
  • Sys::Virt::NODE_MEMORY_STATS_FREE — the amount of free memory
  • Sys::Virt::NODE_MEMORY_STATS_TOTAL — the total amount of memory

🌈 IP address constants

These ones are for interpreting IP address types:

  • Sys::Virt::IP_ADDR_TYPE_IPV4 — an IPv4 address type
  • Sys::Virt::IP_ADDR_TYPE_IPV6 — an IPv6 address type

🐛 BUGS

Hopefully none 🫶 but fr fr, the XS code needs to be audited to make sure it isn't leaking memory. Like, audited audited. 👑

👑 AUTHORS

Daniel P. Berrange <berrange@redhat.com>

Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange

📜 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.

🦋 SEE ALSO

Sys::Virt::Domain, Sys::Virt::Network, Sys::Virt::StoragePool, Sys::Virt::StorageVol, Sys::Virt::Error, "http://libvirt.org"

okay that's the whole page bestie, you're officially a Sys::Virt scholar 🎓✨ this was perl v5.40.2, dated 2026-06-08, signing off — Sys::Virt(3pm), mwah 💋💅

📦 where this page comes from