Sys-Virt-4.0.0/0000755000076500007650000000000013231646075013370 5ustar berrangeberrangeSys-Virt-4.0.0/MANIFEST.SKIP0000644000076500007650000000023013004103366015246 0ustar berrangeberrangepm_to_blib Virt\.o Virt\.c Virt\.bs Virt\.xsc .*.old Sys-Virt- blib .*\.bak CVS .cvsignore .*~ .#.* #.* ^Makefile$ ^cover_db/ .hg .*\.orig .*\.sh \.git Sys-Virt-4.0.0/AUTHORS0000644000076500007650000000073713004103366014434 0ustar berrangeberrange Sys::Virt Authors ================= Sys::Virt is written and maintained by Daniel P. Berrange Patches contributed by: Anthony Hinsinger Stepan Kasal Ludwig Nussel Zhe Peng Osier Yang Michal Privoznik -- End Sys-Virt-4.0.0/MANIFEST0000644000076500007650000000263713231646073014527 0ustar berrangeberrangeAUTHORS Changes examples/auth.pl examples/devices.pl examples/dhcp-leases.pl examples/dom-fsinfo.pl examples/dom-ifinfo.pl examples/dom-migrate.pl examples/dom-stats.pl examples/dump-info.pl examples/dump-xml.pl examples/emulator-pin.pl examples/events.pl examples/fs-freeze.pl examples/hv-stat.pl examples/iothreadinfo.pl examples/node-alloc.pl examples/node-cpu.pl examples/node-devlist.pl examples/node-info.pl examples/node-ksm.pl examples/open-console.pl examples/save-restore.pl examples/send-key.pl examples/vcpuinfo.pl examples/vol-download-all.pl examples/vol-download-nonblock.pl examples/vol-download.pl examples/vol-sparse.pl examples/vol-upload-all.pl examples/vol-upload-nonblock.pl examples/vol-upload.pl HACKING INSTALL lib/Sys/Virt.pm lib/Sys/Virt/Domain.pm lib/Sys/Virt/DomainSnapshot.pm lib/Sys/Virt/Error.pm lib/Sys/Virt/Event.pm lib/Sys/Virt/Interface.pm lib/Sys/Virt/Network.pm lib/Sys/Virt/NodeDevice.pm lib/Sys/Virt/NWFilter.pm lib/Sys/Virt/Secret.pm lib/Sys/Virt/StoragePool.pm lib/Sys/Virt/StorageVol.pm lib/Sys/Virt/Stream.pm LICENSE Makefile.PL MANIFEST This list of files MANIFEST.SKIP META.yml META.yml.PL MYMETA.json MYMETA.yml perl-Sys-Virt.spec perl-Sys-Virt.spec.PL README t/005-pod.t t/010-pod-coverage.t t/015-changes.t t/020-constants.t t/030-api-coverage.t t/100-connect.t t/200-domains.t t/300-networks.t t/400-storage-pools.t t/500-storage-vols.t t/600-interfaces.t t/800-events.t typemap Virt.xs Sys-Virt-4.0.0/lib/0000755000076500007650000000000013231646075014136 5ustar berrangeberrangeSys-Virt-4.0.0/lib/Sys/0000755000076500007650000000000013231646075014714 5ustar berrangeberrangeSys-Virt-4.0.0/lib/Sys/Virt/0000755000076500007650000000000013231646075015640 5ustar berrangeberrangeSys-Virt-4.0.0/lib/Sys/Virt/NWFilter.pm0000644000076500007650000000601213227163412017661 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::NWFilter - Represent & manage a libvirt virtual network =head1 DESCRIPTION The C module represents a virtual network managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::NWFilter; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::NWFilter::_lookup_by_name($con, $params{name}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::NWFilter::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::NWFilter::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{xml}) { $self = Sys::Virt::NWFilter::_define_xml($con, $params{xml}); } else { die "address, id or uuid parameters are required"; } bless $self, $class; return $self; } =item my $uuid = $filter->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the network. =item my $uuid = $filter->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =item my $name = $filter->get_name() Returns a string with a locally unique name of the network =item my $xml = $filter->get_xml_description() Returns an XML document containing a complete description of the network's configuration =item $filter->undefine() Remove the configuration associated with a network previously defined with the C method in L. If the network is running, you probably want to use the C or C methods instead. =cut 1; =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Event.pm0000644000076500007650000001304413004103366017246 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Event - An event loop contract =head1 DESCRIPTION The C module represents the contract for integrating libvirt with an event loop. This package is abstract and intended to be subclassed to provide an actual implementation. =head1 METHODS =over 4 =cut package Sys::Virt::Event; use strict; use warnings; our $eventimpl = undef; =item register_default() Register the default libvirt event loop implementation =item run_default() Run a single iteration of the default event loop implementation =item register($impl) Register an event loop implementation. The implementation should be a instance of a sub-class of the C package. =cut sub register { my $impl = shift; if (!(ref($impl) && $impl->isa("Sys::Virt::Event"))) { die "event implementation must be a subclass of Sys::Virt::Event"; } $eventimpl = $impl; Sys::Virt::Event::_register_impl(); } sub _add_handle { $eventimpl->add_handle(@_); } sub _update_handle { $eventimpl->update_handle(@_); } sub _remove_handle { $eventimpl->remove_handle(@_); } sub _add_timeout { $eventimpl->add_timeout(@_); } sub _update_timeout { $eventimpl->update_timeout(@_); } sub _remove_timeout { $eventimpl->remove_timeout(@_); } =item $self->_run_handle_callback($watch, $fd, $events, $cb, $opaque) A helper method for executing a callback in response to one of more C<$events> on the file handle C<$fd>. The C<$watch> number is the unique idenifier associated with the file descriptor. The C<$cb> and C<$opaque> parameters are the callback and data registered for the handle. =cut sub _run_handle_callback { my $self = shift; my $watch = shift; my $fd = shift; my $events = shift; my $cb = shift; my $opaque = shift; Sys::Virt::Event::_run_handle_callback_helper($watch, $fd, $events, $cb, $opaque); } =item $self->_run_timeout_callback($timer, $cb, $opaque) A helper method for executing a callback in response to the expiry of a timeout identified by C<$timer>. The C<$cb> and C<$opaque> parameters are the callback and data registered for the timeout. =cut sub _run_timeout_callback { my $self = shift; my $timer = shift; my $cb = shift; my $opaque = shift; Sys::Virt::Event::_run_timeout_callback_helper($timer, $cb, $opaque); } =item $self->_free_callback_opaque($ff, $opaque) A helper method for freeing the data associated with a callback. The C<$ff> and C<$opaque> parameters are the callback and data registered for the handle/timeout. =cut sub _free_callback_opaque { my $self = shift; my $ff = shift; my $opaque = shift; Sys::Virt::Event::_free_callback_opaque_helper($ff, $opaque); } 1; =item my $watch = Sys::Virt::Event::add_handle($fd, $events, $coderef) Adds a watch on the file descriptor C<$fd> for the events C<$events> which is a mask of the FILE HANDLE EVENTS constants listed later. The C<$coderef> parameter is a subroutine to invoke when an event is triggered. The subroutine will be passed three parameters, the watch identifier, the file descriptor and the event mask. This method returns the watch identifier which can be used to update or remove the watch =item Sys::Virt::Event::update_handle($watch, $events) Update the event mask for the file descriptor watch C<$watch> to use the events C<$events>. =item Sys::Virt::Event::remove_handle($watch) Remove the event mask for the file descriptor watch C<$watch>. =item my $watch = Sys::Virt::Event::add_timeout($frequency, $coderef) Adds a timeout to trigger with C<$frequency> milliseconds interval. The C<$coderef> parameter is a subroutine to invoke when an event is triggered. The subroutine will be passed one parameter, the timer identifier. This method returns the watch identifier which can be used to update or remove the watch =item Sys::Virt::Event::update_timeout($timer, $frequency) Update the timeout C<$timer> to have the frequency C<$frequency> milliseconds. =item Sys::Virt::Event::remove_timeout($timer) Remove the timeout C<$timer> =back =head1 CONSTANTS =head2 FILE HANDLE EVENTS When integrating with an event loop the following constants define the file descriptor events =over 4 =item Sys::Virt::Event::HANDLE_READABLE The file descriptor has data available for read without blocking =item Sys::Virt::Event::HANDLE_WRITABLE The file descriptor has ability to write data without blocking =item Sys::Virt::Event::HANDLE_ERROR An error occurred on the file descriptor =item Sys::Virt::Event::HANDLE_HANGUP The remote end of the file descriptor closed =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Error.pm0000644000076500007650000003666713144275472017313 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Error - error object for libvirt APIs =head1 DESCRIPTION The C class provides an encoding of the libvirt errors. Instances of this object can be thrown by pretty much any of the Sys::Virt APIs. =head1 METHODS =over 4 =cut package Sys::Virt::Error; use strict; use warnings; use overload ('""' => 'stringify'); =item $err->stringify Convert the object into string format suitable for printing on a console to inform a user of the error. =cut sub stringify { my $self = shift; return "libvirt error code: " . $self->{code} . ", message: " . $self->{message} . ($self->{message} =~ /\n$/ ? "" : "\n"); } =item my $code = $err->level Return the raw error level represented by this error. One of the ERROR LEVEL CONSTANTS =cut sub level { my $self = shift; return $self->{code} } =item my $code = $err->code Return the raw error code represented by this error. One of the ERROR CODE CONSTANTS =cut sub code { my $self = shift; return $self->{code} } =item my $from = $err->domain Return the error domain raising this error. One of the ERROR DOMAIN CONSTANTS =cut sub domain { my $self = shift; return $self->{domain} } =item my $msg = $err->message Return an informative message describing the error condition. =cut sub message { my $self = shift; return $self->{message} } 1; =back =head1 CONSTANTS =head2 ERROR LEVEL CONSTANTS =over 4 =item Sys::Virt::Error::LEVEL_NONE Undefined error level =item Sys::Virt::Error::LEVEL_WARNING Warning error level =item Sys::Virt::Error::LEVEL_ERROR Fatal error level =back =head2 ERROR DOMAIN CONSTANTS The error domain indicates which internal part of libvirt the error report was raised from. =over 4 =item Sys::Virt::Error::FROM_CONF Configuration file handling =item Sys::Virt::Error::FROM_DOM Error while operating on a domain =item Sys::Virt::Error::FROM_DOMAIN Domain configuration handling =item Sys::Virt::Error::FROM_LXC LXC virtualization driver =item Sys::Virt::Error::FROM_NET Error while operating on a network =item Sys::Virt::Error::FROM_NETWORK Network configuration handling =item Sys::Virt::Error::FROM_NODEDEV Node device configuration handling =item Sys::Virt::Error::FROM_NONE No specific error domain. =item Sys::Virt::Error::FROM_OPENVZ OpenVZ virtualization driver =item Sys::Virt::Error::FROM_PROXY Xen proxy virtualization driver =item Sys::Virt::Error::FROM_QEMU QEMU virtualization driver =item Sys::Virt::Error::FROM_REMOTE Remote client virtualization driver =item Sys::Virt::Error::FROM_RPC XML-RPC handling code =item Sys::Virt::Error::FROM_SECURITY Security services driver =item Sys::Virt::Error::FROM_SEXPR SEXPR parsing code =item Sys::Virt::Error::FROM_STATS_LINUX Device statistics code =item Sys::Virt::Error::FROM_STORAGE Storage configuration handling =item Sys::Virt::Error::FROM_TEST Test virtualization driver =item Sys::Virt::Error::FROM_UML UML virtualization driver =item Sys::Virt::Error::FROM_XEN Xen hypervisor driver =item Sys::Virt::Error::FROM_XEND XenD daemon driver =item Sys::Virt::Error::FROM_XENSTORE XenStore driver =item Sys::Virt::Error::FROM_XENXM Xen XM configuration file driver =item Sys::Virt::Error::FROM_XEN_INOTIFY Xen Inotify events driver =item Sys::Virt::Error::FROM_XML Low level XML parser =item Sys::Virt::Error::FROM_ESX The VMWare ESX driver =item Sys::Virt::Error::FROM_INTERFACE The host network interface driver =item Sys::Virt::Error::FROM_ONE The Open Nebula driver. This constant is no longer used and retained only for backwards compatibility =item Sys::Virt::Error::FROM_PHYP The IBM Power Hypervisor driver =item Sys::Virt::Error::FROM_SECRET The secret management driver =item Sys::Virt::Error::FROM_VBOX The VirtualBox driver =item Sys::Virt::Error::FROM_AUDIT The audit driver =item Sys::Virt::Error::FROM_CPU The CPU information driver =item Sys::Virt::Error::FROM_DOMAIN_SNAPSHOT The domain snapshot driver =item Sys::Virt::Error::FROM_HOOK The daemon hook driver =item Sys::Virt::Error::FROM_NWFILTER The network filter driver =item Sys::Virt::Error::FROM_STREAMS The data streams driver =item Sys::Virt::Error::FROM_SYSINFO The system information driver =item Sys::Virt::Error::FROM_VMWARE The VMWare driver =item Sys::Virt::Error::FROM_XENAPI The XenAPI driver =item Sys::Virt::Error::FROM_EVENT The event driver =item Sys::Virt::Error::FROM_LIBXL The libxl Xen driver =item Sys::Virt::Error::FROM_LOCKING The lock manager drivers =item Sys::Virt::Error::FROM_HYPERV The Hyper-V driver =item Sys::Virt::Error::FROM_CAPABILITIES The capabilities driver =item Sys::Virt::Error::FROM_AUTH The authentication handling code =item Sys::Virt::Error::FROM_URI The URI handling code =item Sys::Virt::Error::FROM_DBUS The DBus handling code =item Sys::Virt::Error::FROM_DEVICE The device handling code =item Sys::Virt::Error::FROM_SSH The libSSH2 socket client =item Sys::Virt::Error::FROM_PARALLELS The Parallels virtualization driver =item Sys::Virt::Error::FROM_LOCKSPACE The lockspace handling code =item Sys::Virt::Error::FROM_INITCTL The initctl client code =item Sys::Virt::Error::FROM_CGROUP The cgroups code =item Sys::Virt::Error::FROM_IDENTITY The identity management code =item Sys::Virt::Error::FROM_ACCESS The access control code =item Sys::Virt::Error::FROM_SYSTEMD The systemd init service =item Sys::Virt::Error::FROM_BHYVE The FreeBSD BHyve driver =item Sys::Virt::Error::FROM_CRYPTO The cryptographic helper APIs. =item Sys::Virt::Error::FROM_FIREWALL The firewall helper APIs. =item Sys::Virt::Error::FROM_POLKIT The polkit authentication / authorization APIs =item Sys::Virt::Error::FROM_THREAD The thread helper utils =item Sys::Virt::Error::FROM_ADMIN The administrative service =item Sys::Virt::Error::FROM_LOGGING The logging service =item Sys::Virt::Error::FROM_XENXL The Xen XL driver =item Sys::Virt::Error::FROM_PERF The performance events subsystem =item Sys::Virt::Error::FROM_LIBSSH The libSSH socket client =item Sys::Virt::Error::FROM_RESCTRL The resource control subsystem =back =head2 ERROR CODE CONSTANTS The error codes allow for specific problems to be identified and handled separately from generic error handling. =over 4 =item Sys::Virt::Error::ERR_AUTH_FAILED Authentication falure when connecting to a driver =item Sys::Virt::Error::ERR_CALL_FAILED Operation not supported by driver (DEPRECATED & unused) =item Sys::Virt::Error::ERR_CONF_SYNTAX Configuration file syntax error =item Sys::Virt::Error::ERR_DOM_EXIST The domain already exists =item Sys::Virt::Error::ERR_DRIVER_FULL Too many hypervisor drivers have been registered =item Sys::Virt::Error::ERR_GET_FAILED HTTP GET command failed talking to XenD =item Sys::Virt::Error::ERR_GNUTLS_ERROR GNUTLS encryption error in RPC driver =item Sys::Virt::Error::ERR_HTTP_ERROR Unexpected HTTP error code from XenD =item Sys::Virt::Error::ERR_INTERNAL_ERROR Generic internal error =item Sys::Virt::Error::ERR_INVALID_ARG Invalid argument supplied to function =item Sys::Virt::Error::ERR_INVALID_CONN Invalid connection object =item Sys::Virt::Error::ERR_INVALID_DOMAIN Invalid domain object =item Sys::Virt::Error::ERR_INVALID_MAC Invalid MAC address string =item Sys::Virt::Error::ERR_INVALID_NETWORK Invalid network object =item Sys::Virt::Error::ERR_INVALID_NODE_DEVICE Invalid node device object =item Sys::Virt::Error::ERR_INVALID_STORAGE_POOL Invalid storage pool object =item Sys::Virt::Error::ERR_INVALID_STORAGE_VOL Invalid storage vol object =item Sys::Virt::Error::ERR_NETWORK_EXIST Network with this name/uuid already exists =item Sys::Virt::Error::ERR_NO_CONNECT Unable to connect to requested hypervisor driver =item Sys::Virt::Error::ERR_NO_DEVICE Missing device information =item Sys::Virt::Error::ERR_NO_DOMAIN No such domain with that name/uuid/id =item Sys::Virt::Error::ERR_NO_KERNEL Missing kernel information in domain configuration =item Sys::Virt::Error::ERR_NO_MEMORY Missing memory information in domain configuration =item Sys::Virt::Error::ERR_NO_NAME Missing name in object configuration =item Sys::Virt::Error::ERR_NO_NETWORK No such network with that name/uuid =item Sys::Virt::Error::ERR_NO_NODE_DEVICE No such node device with that name =item Sys::Virt::Error::ERR_NO_OS Missing OS information in domain configuration =item Sys::Virt::Error::ERR_NO_ROOT Missing root device information in domain configuration =item Sys::Virt::Error::ERR_NO_SECURITY_MODEL Missing security model information in domain configuratio =item Sys::Virt::Error::ERR_NO_SOURCE Missing source device information in domain configuration =item Sys::Virt::Error::ERR_NO_STORAGE_POOL No such storage pool with that name/uuid =item Sys::Virt::Error::ERR_NO_STORAGE_VOL No such storage volume with that name/path/key =item Sys::Virt::Error::ERR_NO_SUPPORT This operation is not supported by the active driver =item Sys::Virt::Error::ERR_NO_TARGET Missing target device information in domain configuration =item Sys::Virt::Error::ERR_NO_XEN Unable to connect to Xen hypervisor =item Sys::Virt::Error::ERR_NO_XENSTORE Unable to connect to XenStorage daemon =item Sys::Virt::Error::ERR_OK No error code. This should never be see =item Sys::Virt::Error::ERR_OPEN_FAILED Unable to open a configuration file =item Sys::Virt::Error::ERR_OPERATIONED_DENIED The operation is forbidden for the current connection =item Sys::Virt::Error::ERR_OPERATION_FAILED The operation failed to complete =item Sys::Virt::Error::ERR_OS_TYPE Missing/incorrect OS type in domain configuration =item Sys::Virt::Error::ERR_PARSE_FAILED Failed to parse configuration file =item Sys::Virt::Error::ERR_POST_FAILED HTTP POST failure talking to XenD =item Sys::Virt::Error::ERR_READ_FAILED Unable to read from configuration file =item Sys::Virt::Error::ERR_RPC Generic RPC error talking to XenD =item Sys::Virt::Error::ERR_SEXPR_SERIAL Failed to generic SEXPR for XenD =item Sys::Virt::Error::ERR_SYSTEM_ERROR Generic operating system error =item Sys::Virt::Error::ERR_UNKNOWN_HOST Unknown hostname =item Sys::Virt::Error::ERR_WRITE_FAILED Failed to write to configuration file =item Sys::Virt::Error::ERR_XEN_CALL Failure while talking to Xen hypervisor =item Sys::Virt::Error::ERR_XML_DETAIL Detailed XML parsing error =item Sys::Virt::Error::ERR_XML_ERROR Generic XML parsing error =item Sys::Virt::Error::WAR_NO_NETWORK Warning that no network driver is activated =item Sys::Virt::Error::WAR_NO_NODE Warning that no node device driver is activated =item Sys::Virt::Error::WAR_NO_STORAGE Warning that no storage driver is activated =item Sys::Virt::Error::ERR_INVALID_INTERFACE Invalid network interface object =item Sys::Virt::Error::ERR_NO_INTERFACE No interface with the matching name / mac address =item Sys::Virt::Error::ERR_OPERATION_INVALID The requested operation is not valid for the current object state =item Sys::Virt::Error::WAR_NO_INTERFACE The network interface driver is not available =item Sys::Virt::Error::ERR_MULTIPLE_INTERFACES There are multiple interfaces with the requested MAC address =item Sys::Virt::Error::ERR_BUILD_FIREWALL The firwall could not be constructed =item Sys::Virt::Error::WAR_NO_NWFILTER The network filter driver could not be activated =item Sys::Virt::Error::ERR_NO_NWFILTER There is no network filter driver available =item Sys::Virt::Error::ERR_INVALID_NWFILTER The network filter object was invalid =item Sys::Virt::Error::WAR_NO_SECRET There secret management driver is not available =item Sys::Virt::Error::ERR_NO_SECRET No secret with the matching uuid / usage ID =item Sys::Virt::Error::ERR_INVALID_SECRET Invalid secret object =item Sys::Virt::Error::ERR_CONFIG_UNSUPPORTED The requested XML configuration is not supported by the hypervisor =item Sys::Virt::Error::ERR_OPERATION_TIMEOUT The operation could not be completed in a satisfactory time =item Sys::Virt::Error::ERR_MIGRATE_PERSIST_FAILED Unable to persistent the domain configuration after migration successfully completed =item Sys::Virt::Error::ERR_HOOK_SCRIPT_FAILED Execution of a daemon hook script failed =item Sys::Virt::Error::ERR_INVALID_DOMAIN_SNAPSHOT The domain snapshot object pointer was invalid =item Sys::Virt::Error::ERR_NO_DOMAIN_SNAPSHOT No matching domain snapshot was found =item Sys::Virt::Error::ERR_INVALID_STREAM The stream object pointer was invalid =item Sys::Virt::Error::ERR_ARGUMENT_UNSUPPORTED The argument value was not supported by the driver =item Sys::Virt::Error::ERR_STORAGE_POOL_BUILT The storage pool has already been built =item Sys::Virt::Error::ERR_STORAGE_PROBE_FAILED Probing the storage pool failed =item Sys::Virt::Error::ERR_SNAPSHOT_REVERT_RISKY Reverting the snapshot could cause data loss =item Sys::Virt::Error::ERR_OPERATION_ABORTED The asynchronous operation was aborted at admin request =item Sys::Virt::Error::ERR_AUTH_CANCELLED The user cancelled the authentication process =item Sys::Virt::Error::ERR_NO_DOMAIN_METADATA The requested metadata does not exist =item Sys::Virt::Error::ERR_MIGRATE_UNSAFE The migration operation would be unsafe to perform =item Sys::Virt::Error::ERR_OVERFLOW The calculation would overflow =item Sys::Virt::Error::ERR_BLOCK_COPY_ACTIVE Action prevented by block copy job =item Sys::Virt::Error::ERR_AGENT_UNRESPONSIVE The guest agent is not responding =item Sys::Virt::Error::ERR_OPERATION_UNSUPPORTED The operation is not supported on this host =item Sys::Virt::Error::ERR_SSH The SSH operation failed =item Sys::Virt::Error::ERR_RESOURCE_BUSY The resource requested is already in use =item Sys::Virt::Error::ERR_ACCESS_DENIED Not authorized to perform the operation =item Sys::Virt::Error::ERR_DBUS_SERVICE An error from a DBus service API =item Sys::Virt::Error::ERR_STORAGE_VOL_EXIST The storage volume already exists =item Sys::Virt::Error::ERR_CPU_INCOMPATIBLE The CPUs are not compatible =item Sys::Virt::Error::ERR_INVALID_SCHEMA The XML document does not comply with the XML schema =item Sys::Virt::Error::ERR_MIGRATE_FINISH_OK Migration finished but expected to return NULL domain. =item Sys::Virt::Error::ERR_AUTH_UNAVAILABLE Authentication services were not available =item Sys::Virt::Error::ERR_NO_SERVER Libvirt server was not found =item Sys::Virt::Error::ERR_NO_CLIENT Libvirt client was not found =item Sys::Virt::Error::ERR_AGENT_UNSYNCED Libvirt guest agent replies with wrong id to guest-sync command =item Sys::Virt::Error::ERR_LIBSSH The libSSH operation failed =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/StoragePool.pm0000644000076500007650000003145713227163412020440 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006-2009 Red Hat # Copyright (C) 2006-2009 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::StoragePool - Represent & manage a libvirt storage pool =head1 DESCRIPTION The C module represents a storage pool managed by libvirt. There are a variety of storage pool implementations for LVM, Local directories/filesystems, network filesystems, disk partitioning, iSCSI, and SCSI. =head1 METHODS =over 4 =cut package Sys::Virt::StoragePool; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::StoragePool::_lookup_by_name($con, $params{name}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::StoragePool::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::StoragePool::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{volume}) { $self = Sys::Virt::StoragePool::_lookup_by_volume($params{volume}); } elsif (exists $params{xml}) { if ($params{nocreate}) { $self = Sys::Virt::StoragePool::_define_xml($con, $params{xml}); } else { $self = Sys::Virt::StoragePool::_create_xml($con, $params{xml}); } } else { die "address, id or uuid parameters are required"; } bless $self, $class; return $self; } =item my $uuid = $pool->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the storage pool. =item my $uuid = $pool->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =item my $name = $pool->get_name() Returns a string with a locally unique name of the storage pool =item $pool->is_active() Returns a true value if the storage pool is currently running =item $pool->is_persistent() Returns a true value if the storage pool has a persistent configuration file defined =item my $xml = $pool->get_xml_description() Returns an XML document containing a complete description of the storage pool's configuration =item $pool->create() Start a storage pool whose configuration was previously defined using the C method in L. =item $pool->undefine() Remove the configuration associated with a storage pool previously defined with the C method in L. If the storage pool is running, you probably want to use the C method instead. =item $pool->destroy() Immediately stop the storage pool. =item $flag = $pool->get_autostart(); Return a true value if the storage pool is configured to automatically start upon boot. Return false, otherwise =item $pool->set_autostart($flag) Set the state of the autostart flag, which determines whether the storage pool will automatically start upon boot of the host OS =item $pool->refresh([$flags]); Refresh the storage pool state. Typically this will rescan the list of storage volumes. The C<$flags> parameter is currently unused and if omitted defaults to zero. =item $pool->build([$flags]); Construct the storage pool if it does not exist. As an example, for a disk based storage pool this would ensure a partition table exists. The C<$flags> parameter allows control over the build operation and if omitted defaults to zero. =item $pool->delete([$flags]); Delete the storage pool. The C<$flags> parameter allows the data to be optionally wiped during delete and if omitted defaults to zero. =item $info = $pool->get_info() Retrieve information about the current storage pool state. The returned hash reference has the following keys =over 4 =item state The current status of the storage pool. See constants later. =item capacity The total logical size of the storage pool =item allocation The current physical allocation of the storage pool =item available The available space for creation of new volumes. This may be less than the difference between capacity & allocation if there are sizing / metadata constraints for volumes =back =item my $nnames = $pool->num_of_storage_volumes() Return the number of running volumes in this storage pool. The value can be used as the C parameter to C. =item my @volNames = $pool->list_storage_vol_names($maxnames) Return a list of all volume names in this storage pool. The names can be used with the C method. =item my @vols = $pool->list_volumes() Return a list of all volumes in the storage pool. The elements in the returned list are instances of the L class. This method requires O(n) RPC calls, so the C method is recommended as a more efficient alternative. =cut sub list_volumes { my $self = shift; my $nnames = $self->num_of_storage_volumes(); my @names = $self->list_storage_vol_names($nnames); my @volumes; foreach my $name (@names) { eval { push @volumes, Sys::Virt::StorageVol->_new(pool => $self, name => $name); }; if ($@) { # nada - volume went away before we could look it up }; } return @volumes; } =item my @volumes = $pool->list_all_volumes($flags) Return a list of all storage volumes associated with this pool. The elements in the returned list are instances of the L class. The C<$flags> parameter can be used to filter the list of return storage volumes. =item my $vol = $pool->get_volume_by_name($name) Return the volume with a name of C<$name>. The returned object is an instance of the L class. =cut sub get_volume_by_name { my $self = shift; my $name = shift; return Sys::Virt::StorageVol->_new(pool => $self, name => $name); } =item my $vol = $pool->create_volume($xml) Create a new volume based on the XML description passed into the C<$xml> parameter. The returned object is an instance of the L class. If the optional C is provided, data will be copied from that source volume =cut sub create_volume { my $self = shift; my $xml = shift; return Sys::Virt::StorageVol->_new(pool => $self, xml => $xml); } =item my $vol = $pool->clone_volume($xml, $clonevol); Create a new volume based on the XML description passed into the C<$xml> parameter. The returned object is an instance of the L class. The new volume will be populated with data from the specified clone source volume. =cut sub clone_volume { my $self = shift; my $xml = shift; my $clone = shift; return Sys::Virt::StorageVol->_new(pool => $self, xml => $xml, clone => $clone); } 1; =back =head1 CONSTANTS The following sets of constants may be useful in dealing with some of the methods in this package =head2 POOL STATES The following constants are useful for interpreting the C key value in the hash returned by C =over 4 =item Sys::Virt::StoragePool::STATE_INACTIVE The storage pool is not currently active =item Sys::Virt::StoragePool::STATE_BUILDING The storage pool is still being constructed and is not ready for use yet. =item Sys::Virt::StoragePool::STATE_RUNNING The storage pool is running and can be queried for volumes =item Sys::Virt::StoragePool::STATE_DEGRADED The storage pool is running, but its operation is degraded due to a failure. =item Sys::Virt::StoragePool::STATE_INACCESSIBLE The storage pool is not currently accessible =back =head2 DELETION MODES =over 4 =item Sys::Virt::StoragePool::DELETE_NORMAL Delete the pool without any attempt to scrub data =item Sys::Virt::StoragePool::DELETE_ZEROED Fill the allocated storage with zeros when deleting =back =head2 BUILD MODES =over 4 =item Sys::Virt::StoragePool::BUILD_NEW Construct a new storage pool from constituent bits =item Sys::Virt::StoragePool::BUILD_RESIZE Resize an existing built storage pool preserving data where appropriate =item Sys::Virt::StoragePool::BUILD_REPAIR Repair an existing storage pool operating in degraded mode =item Sys::Virt::StoragePool::BUILD_NO_OVERWRITE Do not overwrite existing storage pool data =item Sys::Virt::StoragePool::BUILD_OVERWRITE Overwrite existing storage pool data =back =head2 CREATE MODES When creating a storage pool it can be built at the same time. The following values are therefore close to their BUILD counterparts. =over 4 =item Sys::Virt::StoragePool::CREATE_NORMAL Just create the storage pool without building it. =item Sys::Virt::StoragePool::CREATE_WITH_BUILD When creating new storage pool also perform pool build without any flags. =item Sys::Virt::StoragePool::CREATE_WITH_BUILD_OVERWRITE Create the pool and perform pool build using the BUILD_OVERWRITE flag. This is mutually exclusive to CREATE_WITH_BUILD_NO_OVERWRITE. =item Sys::Virt::StoragePool::CREATE_WITH_BUILD_NO_OVERWRITE Create the pool and perform pool build using the BUILD_NO_OVERWRITE flag. This is mutually exclusive to CREATE_WITH_BUILD_OVERWRITE. =back =head2 XML DOCUMENTS The following constants are useful when requesting XML for storage pools =over 4 =item Sys::Virt::StoragePool::XML_INACTIVE Return XML describing the inactive state of the storage pool. =back =head1 LIST FILTERING The following constants are used to filter object lists =over 4 =item Sys::Virt::StoragePool::LIST_ACTIVE Include storage pools which are active =item Sys::Virt::StoragePool::LIST_INACTIVE Include storage pools which are inactive =item Sys::Virt::StoragePool::LIST_AUTOSTART Include storage pools which are marked for autostart =item Sys::Virt::StoragePool::LIST_NO_AUTOSTART Include storage pools which are not marked for autostart =item Sys::Virt::StoragePool::LIST_PERSISTENT Include storage pools which are persistent =item Sys::Virt::StoragePool::LIST_TRANSIENT Include storage pools which are transient =item Sys::Virt::StoragePool::LIST_DIR Include directory storage pools =item Sys::Virt::StoragePool::LIST_DISK Include disk storage pools =item Sys::Virt::StoragePool::LIST_FS Include filesytem storage pools =item Sys::Virt::StoragePool::LIST_ISCSI Include iSCSI storage pools =item Sys::Virt::StoragePool::LIST_LOGICAL Include LVM storage pools =item Sys::Virt::StoragePool::LIST_MPATH Include multipath storage pools =item Sys::Virt::StoragePool::LIST_NETFS Include network filesystem storage pools =item Sys::Virt::StoragePool::LIST_RBD Include RBD storage pools =item Sys::Virt::StoragePool::LIST_SCSI Include SCSI storage pools =item Sys::Virt::StoragePool::LIST_SHEEPDOG Include sheepdog storage pools =item Sys::Virt::StoragePool::LIST_GLUSTER Include gluster storage pools =item Sys::Virt::StoragePool::LIST_ZFS Include ZFS storage pools =item Sys::Virt::StoragePool::LIST_VSTORAGE Include VStorage storage pools =back =head2 EVENT ID CONSTANTS =over 4 =item Sys::Virt::StoragePool::EVENT_ID_LIFECYCLE Storage pool lifecycle events =item Sys::Virt::StoragePool::EVENT_ID_REFRESH Storage pool volume refresh events =back =head2 LIFECYCLE CHANGE EVENTS The following constants allow storage pool lifecycle change events to be interpreted. The events contain both a state change, and a reason though the reason is currently unused. =over 4 =item Sys::Virt::StoragePool::EVENT_DEFINED Indicates that a persistent configuration has been defined for the storage pool =item Sys::Virt::StoragePool::EVENT_STARTED The storage pool has started running =item Sys::Virt::StoragePool::EVENT_STOPPED The storage pool has stopped running =item Sys::Virt::StoragePool::EVENT_UNDEFINED The persistent configuration has gone away =item Sys::Virt::StoragePool::EVENT_CREATED The underlying storage has been built =item Sys::Virt::StoragePool::EVENT_DELETED The underlying storage has been released =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Secret.pm0000644000076500007650000001334213227163412017420 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Secret - Represent & manage a libvirt secret =head1 DESCRIPTION The C module represents a secret managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::Secret; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{usageID} || exists $params{usageType}) { die "usageID parameter must be provided with usageType" unless exists $params{usageID}; die "usageType parameter must be provided with usageID" unless exists $params{usageType}; $self = Sys::Virt::Secret::_lookup_by_usage($con, $params{usageType}, $params{usageID}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::Secret::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::Secret::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{xml}) { $self = Sys::Virt::Secret::_define_xml($con, $params{xml}); } else { die "usageID, xml or uuid parameters are required"; } bless $self, $class; return $self; } =item my $uuid = $sec->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the secret. =item my $uuid = $sec->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =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. =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 qualfied path. =item my $xml = $sec->get_xml_description() Returns an XML document containing a complete description of the secret's configuration =item $sec->undefine() Remove the configuration associated with a secret previously defined with the C method in L. =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. =item $sec->set_value($bytes) Sets the value for the secret to be C<$bytes>. =back =head1 CONSTANTS This section documents constants that are used with various APIs described above =head2 SECRET USAGE TYPE The following constants refer to the different usage types =over 4 =item Sys::Virt::Secret::USAGE_TYPE_NONE The constant for secrets which are not assigned for use with a particular object =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. =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. =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. =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. =back =head2 LIST FILTERING The following constants are used to filter object lists =over 4 =item Sys::Virt::Secret::LIST_EPHEMERAL Include any secrets marked as ephemeral =item Sys::Virt::Secret::LIST_NO_EPHEMERAL Include any secrets not marked as ephemeral =item Sys::Virt::Secret::LIST_PRIVATE Include any secrets marked as private =item Sys::Virt::Secret::LIST_NO_PRIVATE Include any secrets not marked as private =back =head2 EVENT ID CONSTANTS =over 4 =item Sys::Virt::Secret::EVENT_ID_LIFECYCLE Secret lifecycle events =item Sys::Virt::Secret::EVENT_ID_VALUE_CHANGED Secret value change events =back =head2 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. =over 4 =item Sys::Virt::Secret::EVENT_DEFINED Indicates that a persistent configuration has been defined for the secret. =item Sys::Virt::Secret::EVENT_UNDEFINED The persistent configuration has gone away =back =cut 1; =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/StorageVol.pm0000644000076500007650000002111213227163412020252 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006-2009 Red Hat # Copyright (C) 2006-2009 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::StorageVol - Represent & manage a libvirt storage volume =head1 DESCRIPTION The C module represents a storage volume managed by libvirt. A storage volume is always associated with a containing storage pool (C). =head1 METHODS =over 4 =cut package Sys::Virt::StorageVol; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $self; if (exists $params{name}) { my $pool = exists $params{pool} ? $params{pool} : die "pool parameter is required"; $self = Sys::Virt::StorageVol::_lookup_by_name($pool, $params{name}); } elsif (exists $params{key}) { my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; $self = Sys::Virt::StorageVol::_lookup_by_key($con, $params{key}); } elsif (exists $params{path}) { my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; $self = Sys::Virt::StorageVol::_lookup_by_path($con, $params{path}); } elsif (exists $params{xml}) { my $pool = exists $params{pool} ? $params{pool} : die "pool parameter is required"; if ($params{clone}) { $self = Sys::Virt::StorageVol::_create_xml_from($pool, $params{xml}, $params{clone}, 0); } else { $self = Sys::Virt::StorageVol::_create_xml($pool, $params{xml}, 0); } } else { die "name, key, path or xml parameters are required"; } bless $self, $class; return $self; } =item my $name = $vol->get_name() Returns a string with a locally unique name of the storage vol =item my $name = $vol->get_key() Returns a string with a globally unique key for the storage vol =item my $name = $vol->get_path() Returns a string with a locally unique file path of the storage vol =item my $xml = $vol->get_xml_description() Returns an XML document containing a complete description of the storage vol's configuration =item $vol->delete($flags) Immediately delete the storage volume freeing its storage resources. The C parameter indicates any special action to be taken when deleting the volume. =item $vol->resize($newcapacity, $flags=0) Adjust the size of the storage volume. The C<$newcapacity> value semantics depend on the C<$flags> parameter. If C<$flags> specifies C then the C<$newcapacity> is relative to the current size. If C<$flags> specifies C then the C<$newcapacity> value is the amount of space to remove =item $vol->wipe($flags = 0) Clear the data in the storage volume to avoid future information leak. The C parameter is currently unused and defaults to zero. =item $vol->wipe_pattern($algorithm, $flags = 0) Clear the data in the storage volume to avoid future information leak. The C<$algorithm> parameter specifies the data pattern used to erase data, and should be one of the WIPE ALGORITHM CONSTANTS listed later. The C parameter is currently unused and defaults to zero. =item my $info = $vol->get_info($flags = 0) Retrieve live information about the storage volume. The returned C<$info> hash reference contains three keys. C indicates whether the volume is a file or block device. C provides the maximum logical size of the volume. C provides the current physical usage of the volume. The allocation may be less than the capacity for sparse, or grow-on-demand volumes. The allocation may also be larger than the capacity, if there is a metadata overhead for the volume format. C<$flags> may take one of the values =over 4 =item Sys::Virt::StorageVol::USE_ALLOCATION Return the current allocation in allocation =item Sys::Virt::StorageVol::GET_PHYSICAL Return the physical size in allocation =back =item $vol->download($st, $offset, $length, $flags=0); Download data from C<$vol> using the stream C<$st>. If C<$offset> and C<$length> are non-zero, then restrict data to the specified volume byte range. The C<$flags> accept the following values: =over 4 =item Sys::Virt::StorageVol::VOL_DOWNLOAD_SPARSE_STREAM If this flag is is set in @flags effective transmission of holes is enabled. This assumes using the stream C<$st> with combination of C or C for honouring holes sent by server. =back =item $vol->upload($st, $offset, $length, $flags=0); Upload data to C<$vol> using the stream C<$st>. If C<$offset> and C<$length> are non-zero, then restrict data to the specified volume byte range. The C<$flags> accept the following values: =over 4 =item Sys::Virt::StorageVol::VOL_UPLOAD_SPARSE_STREAM If this is set in C<$flags> effective transmission of holes is enabled. This assumes using the stream C<$st> with combination of C or C to preserve source file sparseness. =back =back =head1 CONSTANTS The following sets of constants are useful when dealing with storage volumes =head2 VOLUME TYPES The following constants are useful for interpreting the C field in the hash returned by the C method =over 4 =item Sys::Virt::StorageVol::TYPE_FILE The volume is a plain file =item Sys::Virt::StorageVol::TYPE_BLOCK The volume is a block device =item Sys::Virt::StorageVol::TYPE_DIR The volume is a directory =item Sys::Virt::StorageVol::TYPE_NETWORK The volume is a network source =item Sys::Virt::StorageVol::TYPE_NETDIR The volume is a network directory =item Sys::Virt::StorageVol::TYPE_PLOOP The volume is a ploop directory =back =head2 CREATE MODES The following constants are useful for the C parameter of the C method =over 4 =item Sys::Virt::StorageVol::CREATE_PREALLOC_METADATA Preallocate header metadata when creating the volume. =item Sys::Virt::StorageVol::CREATE_REFLINK Perform lightweight reference copy =back =head2 DELETE MODES The following constants are useful for the C parameter of the C method =over 4 =item Sys::Virt::StorageVol::DELETE_NORMAL Do a plain delete without any attempt to scrub data. =item Sys::Virt::StorageVol::DELETE_ZEROED Zero out current allocated blocks when deleteing the volume =item Sys::Virt::StorageVol::DELETE_WITH_SNAPSHOTS Delete snapshots associated with the volume =back =head2 WIPE ALGORITHM CONSTANTS The following constants specify the algorithm for erasing data =over 4 =item Sys::Virt::StorageVol::WIPE_ALG_BSI 9-pass method recommended by the German Center of Security in Information Technologies =item Sys::Virt::StorageVol::WIPE_ALG_DOD 4-pass Dod 5220.22-M section, 8-306 procedure =item Sys::Virt::StorageVol::WIPE_ALG_GUTMANN The canonical 35-pass sequence =item Sys::Virt::StorageVol::WIPE_ALG_NNSA 4-pass NNSA Policy Letter NAP-14.1-C (XVI-8) =item Sys::Virt::StorageVol::WIPE_ALG_PFITZNER7 7-pass random =item Sys::Virt::StorageVol::WIPE_ALG_PFITZNER33 33-pass random =item Sys::Virt::StorageVol::WIPE_ALG_RANDOM 1-pass random =item Sys::Virt::StorageVol::WIPE_ALG_SCHNEIER 7-pass method described by Bruce Schneier in "Applied Cryptography" (1996) =item Sys::Virt::StorageVol::WIPE_ALG_ZERO 1-pass, all zeroes =item Sys::Virt::StorageVol::WIPE_ALG_TRIM 1-pass, trim all data on the volume by using TRIM or DISCARD =back VOLUME RESIZE CONSTANTS The following constants control how storage volumes can be resized =over 4 =item Sys::Virt::StorageVol::RESIZE_ALLOCATE Fully allocate the extra space required during resize =item Sys::Virt::StorageVol::RESIZE_DELTA Treat the new capacity as a delta to the current capacity =item Sys::Virt::StorageVol::RESIZE_SHRINK Treat the new capacity as an amount to remove from the capacity =back =cut 1; =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Interface.pm0000644000076500007650000000707313227163412020077 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006-2009 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Interface - Represent & manage a libvirt host network interface =head1 DESCRIPTION The C module represents a host network interface allowing configuration of IP addresses, bonding, vlans and bridges. =head1 METHODS =over 4 =cut package Sys::Virt::Interface; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::Interface::_lookup_by_name($con, $params{name}); } elsif (exists $params{mac}) { $self = Sys::Virt::Interface::_lookup_by_mac($con, $params{mac}); } elsif (exists $params{xml}) { $self = Sys::Virt::Interface::_define_xml($con, $params{xml}); } else { die "name, mac or xml parameters are required"; } bless $self, $class; return $self; } =item my $name = $iface->get_name() Returns a string with a locally unique name of the network =item $iface->is_active() Returns a true value if the interface is currently running =item my $name = $iface->get_mac() Returns a string with the hardware MAC address of the interface =item my $xml = $iface->get_xml_description() Returns an XML document containing a complete description of the network's configuration =item $iface->create() Start a network whose configuration was previously defined using the C method in L. =item $iface->undefine() Remove the configuration associated with a network previously defined with the C method in L. If the network is running, you probably want to use the C or C methods instead. =item $iface->destroy() Immediately terminate the machine, and remove it from the virtual machine monitor. The C<$iface> handle is invalid after this call completes and should not be used again. =back =head1 CONSTANTS =head1 CONSTANTS This section documents constants that are used with various APIs described above =head2 LIST FILTERING The following constants are used to filter object lists =over 4 =item Sys::Virt::Interface::LIST_ACTIVE Include interfaces that are active =item Sys::Virt::Interface::LIST_INACTIVE Include interfaces that are not active =back =head2 XML CONSTANTS The following constants are used when querying XML =over 4 =item Sys::Virt::Interface::XML_INACTIVE Request the inactive XML, instead of the current possibly live config. =back =cut 1; =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Network.pm0000644000076500007650000002104413227163412017622 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Network - Represent & manage a libvirt virtual network =head1 DESCRIPTION The C module represents a virtual network managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::Network; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::Network::_lookup_by_name($con, $params{name}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::Network::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::Network::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{xml}) { if ($params{nocreate}) { $self = Sys::Virt::Network::_define_xml($con, $params{xml}); } else { $self = Sys::Virt::Network::_create_xml($con, $params{xml}); } } else { die "address, id or uuid parameters are required"; } bless $self, $class; return $self; } =item my $uuid = $net->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the network. =item my $uuid = $net->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =item my $name = $net->get_name() Returns a string with a locally unique name of the network =item $net->is_active() Returns a true value if the network is currently running =item $net->is_persistent() Returns a true value if the network has a persistent configuration file defined =item my $xml = $net->get_xml_description() Returns an XML document containing a complete description of the network's configuration =item $net->create() Start a network whose configuration was previously defined using the C method in L. =item $net->undefine() Remove the configuration associated with a network previously defined with the C method in L. If the network is running, you probably want to use the C or C methods instead. =item $net->destroy() Immediately terminate the machine, and remove it from the virtual machine monitor. The C<$net> handle is invalid after this call completes and should not be used again. =item $net->update($command, $section, $parentIndex, $xml, $flags=0) Update the network configuration with C<$xml>. The C<$section> parameter, which must be one of the XML SECTION CONSTANTS listed later, indicates what schema is used in C<$xml>. The C<$command> parameter determines what action is taken. Finally, the C<$flags> parameter can be use to control which config is affected. =item $net->get_bridge_name() Return the name of the bridge device associated with the virtual network =item $flag = $net->get_autostart(); Return a true value if the virtual network is configured to automatically start upon boot. Return false, otherwise =item $net->set_autostart($flag) Set the state of the autostart flag, which determines whether the virtual network will automatically start upon boot of the host OS. =item @leases = $net->get_dhcp_leases($mac=undef, $flags=0) Get a list of all active DHCP leases. If C<$mac> is undefined than leases for all VMs are returned, otherwise only leases for the matching MAC address are returned. The C<$flags> parameter is currently unused and defaults to zero. The elements in the returned array are hash references with the following fields =over 4 =item C Network interface name =item C Seconds since the epoch until the lease expires =item C One of the Sys::Virt IP address type constants =item C The MAC address of the lease =item C The IAID of the client =item C The IP address of the lease =item C The IP address prefix =item C The optional hostname associated with the lease =item C The client ID or DUID =back =back =head1 CONSTANTS This section documents constants that are used with various APIs described above =head2 LIST FILTERING The following constants are used to filter object lists =over 4 =item Sys::Virt::Network::LIST_ACTIVE Include networks which are active =item Sys::Virt::Network::LIST_INACTIVE Include networks which are not active =item Sys::Virt::Network::LIST_AUTOSTART Include networks which are set to autostart =item Sys::Virt::Network::LIST_NO_AUTOSTART Include networks which are not set to autostart =item Sys::Virt::Network::LIST_PERSISTENT Include networks which are persistent =item Sys::Virt::Network::LIST_TRANSIENT Include networks which are transient =back =head2 XML CONSTANTS The following constants are used when querying XML =over 4 =item Sys::Virt::Network::XML_INACTIVE Request the inactive XML, instead of the current possibly live config. =back =head1 XML SECTION CONSTANTS The following constants are used to refer to sections of the XML document =over 4 =item Sys::Virt::Network::SECTION_BRIDGE The bridge device element =item Sys::Virt::Network::SECTION_DNS_HOST The DNS host record section =item Sys::Virt::Network::SECTION_DNS_SRV The DNS SRV record section =item Sys::Virt::Network::SECTION_DNS_TXT The DNS TXT record section =item Sys::Virt::Network::SECTION_DOMAIN The domain name section =item Sys::Virt::Network::SECTION_FORWARD The forward device section =item Sys::Virt::Network::SECTION_FORWARD_INTERFACE The forward interface section =item Sys::Virt::Network::SECTION_FORWARD_PF The forward physical function section =item Sys::Virt::Network::SECTION_IP The IP address section =item Sys::Virt::Network::SECTION_IP_DHCP_HOST The IP address DHCP host section =item Sys::Virt::Network::SECTION_IP_DHCP_RANGE The IP address DHCP range section =item Sys::Virt::Network::SECTION_PORTGROUP The port group section =item Sys::Virt::Network::SECTION_NONE The top level domain element =back =head2 XML UPDATE FLAGS =over 4 =item Sys::Virt::Network::UPDATE_AFFECT_CURRENT Affect whatever the current object state is =item Sys::Virt::Network::UPDATE_AFFECT_CONFIG Always update the config file =item Sys::Virt::Network::UPDATE_AFFECT_LIVE Always update the live config =back =head2 XML UPDATE COMMANDS =over 4 =item Sys::Virt::Network::UPDATE_COMMAND_NONE No update =item Sys::Virt::Network::UPDATE_COMMAND_DELETE Remove the matching entry =item Sys::Virt::Network::UPDATE_COMMAND_MODIFY Modify the matching entry =item Sys::Virt::Network::UPDATE_COMMAND_ADD_FIRST Insert the matching entry at the start =item Sys::Virt::Network::UPDATE_COMMAND_ADD_LAST Insert the matching entry at the end =back =head2 EVENT ID CONSTANTS =over 4 =item Sys::Virt::Network::EVENT_ID_LIFECYCLE Network lifecycle events =back =head2 LIFECYCLE CHANGE EVENTS The following constants allow network lifecycle change events to be interpreted. The events contain both a state change, and a reason though the reason is currently unused. =over 4 =item Sys::Virt::Network::EVENT_DEFINED Indicates that a persistent configuration has been defined for the network. =item Sys::Virt::Network::EVENT_STARTED The network has started running =item Sys::Virt::Network::EVENT_STOPPED The network has stopped running =item Sys::Virt::Network::EVENT_UNDEFINED The persistent configuration has gone away =back =cut 1; =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/NodeDevice.pm0000644000076500007650000001230413227163412020175 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006-2009 Red Hat # Copyright (C) 2006-2009 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::NodeDevice - Represent & manage a libvirt storage pool =head1 DESCRIPTION The C module represents a storage pool managed by libvirt. There are a variety of storage pool implementations for LVM, Local directories/filesystems, network filesystems, disk partitioning, iSCSI, and SCSI. =head1 METHODS =over 4 =cut package Sys::Virt::NodeDevice; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::NodeDevice::_lookup_by_name($con, $params{name}); } elsif (exists $params{wwnn}) { $self = Sys::Virt::NodeDevice::_lookup_scsihost_by_wwn($con, $params{wwnn}, $params{wwpn}, $params{flags}); } elsif (exists $params{xml}) { $self = Sys::Virt::NodeDevice::_create_xml($con, $params{xml}); } else { die "name parameter is required"; } bless $self, $class; return $self; } =item my $name = $dev->get_name() Returns a string with a locally unique name of the device =item my $parentname = $dev->get_parent() Returns a string with a locally unique name of the parent of the device, or undef if there is no parent =item my $xml = $dev->get_xml_description() Returns an XML document containing a complete description of the storage dev's configuration =item $dev->reattach() Rebind the node device to the host OS device drivers. =item $dev->dettach() Unbind the node device from the host OS device driver =item $dev->reset() Reset the node device. The device must be unbound from the host OS drivers for this to work =item $dev->destroy() Destroy the virtual device releasing any OS resources associated with it. =item my @caps = $dev->list_capabilities() Return a list of all capabilities in the device. =back =head1 CONSTANTS This section documents constants that are used with various APIs described above =head2 LIST FILTERING The following constants are used to filter object lists =over 4 =item Sys::Virt::NodeDevice::LIST_CAP_NET Include devices with the network capability =item Sys::Virt::NodeDevice::LIST_CAP_PCI_DEV Include devices with the PCI device capability =item Sys::Virt::NodeDevice::LIST_CAP_SCSI Include devices with the SCSI capability =item Sys::Virt::NodeDevice::LIST_CAP_SCSI_HOST Include devices with the SCSI host capability =item Sys::Virt::NodeDevice::LIST_CAP_SCSI_TARGET Include devices with the SCSI target capability =item Sys::Virt::NodeDevice::LIST_CAP_STORAGE Include devices with the storage capability =item Sys::Virt::NodeDevice::LIST_CAP_SYSTEM Include devices with the system capability =item Sys::Virt::NodeDevice::LIST_CAP_USB_DEV Include devices with the USB device capability =item Sys::Virt::NodeDevice::LIST_CAP_USB_INTERFACE Include devices with the USB interface capability =item Sys::Virt::NodeDevice::LIST_CAP_FC_HOST Include devices with the fibre channel host capability =item Sys::Virt::NodeDevice::LIST_CAP_VPORTS Include devices with the NPIV vport capability =item Sys::Virt::NodeDevice::LIST_CAP_SCSI_GENERIC Include devices with the SCSI generic capability =item Sys::Virt::NodeDevice::LIST_CAP_DRM Include devices with the DRM capability =item Sys::Virt::NodeDevice::LIST_CAP_MDEV Include mediated devices =item Sys::Virt::NodeDevice::LIST_CAP_MDEV_TYPES Include devices capable of mediated devices =item Sys::Virt::NodeDevice::LIST_CAP_CCW_DEV Include CCW devices =back =head2 EVENT ID CONSTANTS =over 4 =item Sys::Virt::NodeDevice::EVENT_ID_LIFECYCLE Node device lifecycle events =item Sys::Virt::NodeDevice::EVENT_ID_UPDATE Node device config update events =back =head2 LIFECYCLE CHANGE EVENTS The following constants allow node device lifecycle change events to be interpreted. The events contain both a state change, and a reason though the reason is currently unused. =over 4 =item Sys::Virt::NodeDevice::EVENT_CREATED Indicates that a device was created =item Sys::Virt::NodeDevice::EVENT_DELETED Indicates that a device has been deleted =back =cut 1; =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2009 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/DomainSnapshot.pm0000644000076500007650000001614213004103366021116 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::DomainSnapshot - Represent & manage a libvirt guest domain =head1 DESCRIPTION The C module represents a guest domain managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::DomainSnapshot; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $dom = exists $params{domain} ? $params{domain} : die "domain parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::DomainSnapshot::_lookup_by_name($dom, $params{name}); } elsif (exists $params{xml}) { $self = Sys::Virt::DomainSnapshot::_create_xml($dom, $params{xml}, $params{flags} ? $params{flags} : 0); } else { die "name or xml parameters are required"; } bless $self, $class; return $self; } =item my $str = $domss->get_name() Return the name of the snapshot =item my $xml = $domss->get_xml_description($flags) Returns an XML document containing a complete description of the domain's configuration. =item $domss->delete($flags) Deletes this snapshot object & its data. The optional C<$flags> parameter controls what should be deleted via the C constants. =item $domss->revert_to($flags) Revert the domain to the state associated with this snapshot. The optional C<$flags> control the state of the vm after the revert via the C constants. =item $parentss = $domss->get_parent(); Return the parent of the snapshot, if any =item $res = $domss->is_current() Returns a true value if this is the current snapshot. False otherwise. =item $res = $domss->has_metadata() Returns a true value if this snapshot has metadata associated with it. =item $count = $domss->num_of_child_snapshots() Return the number of saved snapshots which are children of this snapshot =item @names = $domss->list_child_snapshot_names() List the names of all saved snapshots which are children of this snapshot . The names can be used with the C =item @snapshots = $domss->list_child_snapshots() Return a list of all snapshots that are children of this snapshot. The elements in the returned list are instances of the L class. This method requires O(n) RPC calls, so the C method is recommended as a more efficient alternative. =cut sub list_child_snapshots { my $self = shift; my $nnames = $self->num_of_child_snapshots(); my @names = $self->list_child_snapshot_names($nnames); my @snapshots; foreach my $name (@names) { eval { push @snapshots, Sys::Virt::DomainSnapshot->_new(domain => $self, name => $name); }; if ($@) { # nada - snapshot went away before we could look it up }; } return @snapshots; } =item my @snapshots = $domss->list_all_children($flags) Return a list of all domain snapshots that are children of this snapshot. The elements in the returned list are instances of the L class. The C<$flags> parameter can be used to filter the list of return domain snapshots. =back =head1 CONSTANTS =head2 SNAPSHOT CREATION The following constants are useful when creating snapshots =over 4 =item Sys::Virt::DomainSnapshot::CREATE_CURRENT Set the defined snapshot to be the current snapshot =item Sys::Virt::DomainSnapshot::CREATE_DISK_ONLY Only snapshot the disk, not the memory state =item Sys::Virt::DomainSnapshot::CREATE_HALT Stop the guest after creating the snapshot =item Sys::Virt::DomainSnapshot::CREATE_NO_METADATA Do not save any metadata for the snapshot =item Sys::Virt::DomainSnapshot::CREATE_REDEFINE Replace/set the metadata with the snapshot =item Sys::Virt::DomainSnapshot::CREATE_QUIESCE Quiesce the guest disks while taking the snapshot =item Sys::Virt::DomainSnapshot::CREATE_REUSE_EXT Reuse the existing snapshot data files (if any) =item Sys::Virt::DomainSnapshot::CREATE_ATOMIC Create multiple disk snapshots atomically =item Sys::Virt::DomainSnapshot::CREATE_LIVE Create snapshot while the guest is running =back =head2 SNAPSHOT DELETION The following constants are useful when deleting snapshots =over 4 =item Sys::Virt::DomainSnapshot::DELETE_CHILDREN Recursively delete any child snapshots =item Sys::Virt::DomainSnapshot::DELETE_CHILDREN_ONLY Only delete the child snapshots =item Sys::Virt::DomainSnapshot::DELETE_METADATA_ONLY Only delete the snapshot metadata =back =head2 SNAPSHOT LIST The following constants are useful when listing snapshots =over 4 =item Sys::Virt::DomainSnapshot::LIST_METADATA Only list snapshots which have metadata =item Sys::Virt::DomainSnapshot::LIST_ROOTS Only list snapshots which are root nodes in the tree =item Sys::Virt::DomainSnapshot::LIST_DESCENDANTS Only list snapshots which are descendants of the current snapshot =item Sys::Virt::DomainSnapshot::LIST_LEAVES Only list leaf nodes in the snapshot tree =item Sys::Virt::DomainSnapshot::LIST_NO_LEAVES Only list non-leaf nodes in the snapshot tree =item Sys::Virt::DomainSnapshot::LIST_NO_METADATA Only list snapshots without metadata =item Sys::Virt::DomainSnapshot::LIST_ACTIVE Only list snapshots taken while the guest was running =item Sys::Virt::DomainSnapshot::LIST_INACTIVE Only list snapshots taken while the guest was inactive =item Sys::Virt::DomainSnapshot::LIST_EXTERNAL Only list snapshots stored in external disk images =item Sys::Virt::DomainSnapshot::LIST_INTERNAL Only list snapshots stored in internal disk images =item Sys::Virt::DomainSnapshot::LIST_DISK_ONLY Only list snapshots taken while the guest was running, which did not include memory state. =back =head2 SNAPSHOT REVERT The following constants are useful when reverting snapshots =over 4 =item Sys::Virt::DomainSnapshot::REVERT_PAUSED Leave the guest CPUs paused after reverting to the snapshot state =item Sys::Virt::DomainSnapshot::REVERT_RUNNING Start the guest CPUs after reverting to the snapshot state =item Sys::Virt::DomainSnapshot::REVERT_FORCE Force the snapshot to revert, even if it is risky to do so =back =over 4 =cut 1; =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Stream.pm0000644000076500007650000001537413227163412017435 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2011 Red Hat # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Stream - Represent & manage a libvirt stream =head1 DESCRIPTION The C module represents a stream managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::Stream; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self = Sys::Virt::Stream::_new_obj($con, $params{flags}); bless $self, $class; return $self; } =item my $st Sys::Virt::Stream->new($conn, $flags); Creates a new data stream, ready for use with a stream based API. The optional C<$flags> parameter can be used to configure the stream as non-blocking =item $st->abort() Abort I/O on the stream. Either this function or C must be called on any stream which has been activated =item $st->finish() Complete I/O on the stream. Either this function or C must be called on any stream which has been activated =item $rv = $st->recv($data, $nbytes, $flags=0) Receive up to C<$nbytes> worth of data, copying into C<$data>. Returns the number of bytes read, or -3 if hole is reached and C<$flags> contains RECV_STOP_AT_HOLE, or -2 if I/O would block, or -1 on error. The C<$flags> parameter accepts the following flags: =over 4 =item Sys::Virt::Stream::RECV_STOP_AT_HOLE If this flag is set, the C function will stop reading from stream if it has reached a hole. In that case, -3 is returned and C should be called to get the hole size. =back =item $rv = $st->send($data, $nbytes) Send upto C<$nbytes> worth of data, copying from C<$data>. Returns the number of bytes sent, or -2 if I/O would block, or -1 on error. =item $rv = $st->recv_hole($flags=0) Determine the amount of the empty space (in bytes) to be created in a stream's target file when uploading or downloading sparsely populated files. This is the counterpart to C. The optional C<$flags> parameter is currently unused and defaults to zero if omitted. =item $st->send_hole($length, $flags=0) Rather than transmitting empty file space, this method directs the stream target to create C<$length> bytes of empty space. This method would be used when uploading or downloading sparsely populated files to avoid the needless copy of empty file space. The optional C<$flags> parameter is currently unused and defaults to zero if omitted. =item $st->recv_all($handler) Receive all data available from the stream, invoking C<$handler> to process the data. The C<$handler> parameter must be a function which expects three arguments, the C<$st> stream object, a scalar containing the data received and a data byte count. The function should return the number of bytes processed, or -1 upon error. =item $st->send_all($handler) Send all data produced by C<$handler> to the stream. The C<$handler> parameter must be a function which expects three arguments, the C<$st> stream object, a scalar which must be filled with data and a maximum data byte count desired. The function should return the number of bytes filled, 0 on end of file, or -1 upon error =item $st->sparse_recv_all($handler, $hole_handler) Receive all data available from the sparse stream, invoking C<$handler> to process the data. The C<$handler> parameter must be a function which expects three arguments, the C<$st> stream object, a scalar containing the data received and a data byte count. The function should return the number of bytes processed, or -1 upon error. The second argument C<$hole_handler> is a function which expects two arguments: the C<$st> stream and a scalar, number describing the size of the hole in the stream (in bytes). The C<$hole_handler> is expected to return a non-negative number on success (usually 0) and a negative number (usually -1) otherwise. =item $st->sparse_send_all($handler, $hole_handler, $skip_handler) Send all data produced by C<$handler> to the stream. The C<$handler> parameter must be a function which expects three arguments, the C<$st> stream object, a scalar which must be filled with data and a maximum data byte count desired. The function should return the number of bytes filled, 0 on end of file, or -1 upon error. The second argument C<$hole_handler> is a function expecting just one argument C<$st> and returning an array of two elements (C<$in_data>, C<$section_len>) where C<$in_data> has zero or non-zero value if underlying file is in a hole or data section respectively. The C<$section_len> then is the number of remaining bytes in the current section in the underlying file. Finally, the third C<$skip_handler> is a function expecting two arguments C<$st> and C<$length> which moves cursor in the underlying file for C<$length> bytes. The C<$skip_handler> is expected to return a non-negative number on success (usually 0) and a negative number (usually -1) otherwise. =item $st->add_callback($events, $coderef) Register a callback to be invoked whenever the stream has one or more events from C<$events> mask set. The C<$coderef> must be a subroutine that expects 2 parameters, the original C<$st> object and the new C<$events> mask =item $st->update_callback($events) Change the event mask for a previously registered callback to C<$events> =item $st->remove_callback(); Remove a previously registered callback =back =head1 CONSTANTS =over 4 =item Sys::Virt::Stream::NONBLOCK Create a stream which will not block when performing I/O =item Sys::Virt::Stream::EVENT_READABLE The stream has data available for read without blocking =item Sys::Virt::Stream::EVENT_WRITABLE The stream has ability to write data without blocking =item Sys::Virt::Stream::EVENT_ERROR An error occurred on the stream =item Sys::Virt::Stream::EVENT_HANGUP The remote end of the stream closed =cut 1; =back =head1 AUTHORS Daniel P. Berrange =head1 COPYRIGHT Copyright (C) 2006-2009 Red Hat Copyright (C) 2006-2007 Daniel P. Berrange =head1 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. =head1 SEE ALSO L, L, C =cut Sys-Virt-4.0.0/lib/Sys/Virt/Domain.pm0000644000076500007650000033400613227163412017405 0ustar berrangeberrange# -*- perl -*- # # Copyright (C) 2006 Red Hat # Copyright (C) 2006-2007 Daniel P. Berrange # # This program is free software; You can redistribute it and/or modify # it under either: # # a) the GNU General Public License as published by the Free # Software Foundation; either version 2, or (at your option) any # later version, # # or # # b) the "Artistic License" # # The file "LICENSE" distributed along with this file provides full # details of the terms and conditions of the two licenses. =pod =head1 NAME Sys::Virt::Domain - Represent & manage a libvirt guest domain =head1 DESCRIPTION The C module represents a guest domain managed by the virtual machine monitor. =head1 METHODS =over 4 =cut package Sys::Virt::Domain; use strict; use warnings; sub _new { my $proto = shift; my $class = ref($proto) || $proto; my %params = @_; my $con = exists $params{connection} ? $params{connection} : die "connection parameter is required"; my $self; if (exists $params{name}) { $self = Sys::Virt::Domain::_lookup_by_name($con, $params{name}); } elsif (exists $params{id}) { $self = Sys::Virt::Domain::_lookup_by_id($con, $params{id}); } elsif (exists $params{uuid}) { if (length($params{uuid}) == 16) { $self = Sys::Virt::Domain::_lookup_by_uuid($con, $params{uuid}); } elsif (length($params{uuid}) == 32 || length($params{uuid}) == 36) { $self = Sys::Virt::Domain::_lookup_by_uuid_string($con, $params{uuid}); } else { die "UUID must be either 16 unsigned bytes, or 32/36 hex characters long"; } } elsif (exists $params{xml}) { if ($params{nocreate}) { $self = Sys::Virt::Domain::_define_xml($con, $params{xml}, $params{flags}); } else { if (exists $params{fds}) { $self = Sys::Virt::Domain::_create_with_files($con, $params{xml}, $params{fds}, $params{flags}); } else { $self = Sys::Virt::Domain::_create($con, $params{xml}, $params{flags}); } } } else { die "address, id or uuid parameters are required"; } bless $self, $class; return $self; } =item my $id = $dom->get_id() Returns an integer with a locally unique identifier for the domain. =item my $uuid = $dom->get_uuid() Returns a 16 byte long string containing the raw globally unique identifier (UUID) for the domain. =item my $uuid = $dom->get_uuid_string() Returns a printable string representation of the raw UUID, in the format 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'. =item my $name = $dom->get_name() Returns a string with a locally unique name of the domain =item my $hostname = $dom->get_hostname() Returns a string representing the hostname of the guest =item my $str = $dom->get_metadata($type, $uri, $flags =0) Returns the metadata element of type C<$type> associated with the domain. If C<$type> is C then the C<$uri> parameter specifies the XML namespace to retrieve, otherwise C<$uri> should be C. The optional C<$flags> parameter defaults to zero. =item $dom->set_metadata($type, $val, $key, $uri, $flags=0) Sets the metadata element of type C<$type> to hold the value C<$val>. If C<$type> is C then the C<$key> and C<$uri> elements specify an XML namespace to use, otherwise they should both be C. The optional C<$flags> parameter defaults to zero. =item $dom->is_active() Returns a true value if the domain is currently running =item $dom->is_persistent() Returns a true value if the domain has a persistent configuration file defined =item $dom->is_updated() Returns a true value if the domain is running and has a persistent configuration file defined that is out of date compared to the current live config. =item my $xml = $dom->get_xml_description($flags=0) Returns an XML document containing a complete description of the domain's configuration. The optional $flags parameter controls generation of the XML document, defaulting to 0 if omitted. It can be one or more of the XML DUMP constants listed later in this document. =item my $type = $dom->get_os_type() Returns a string containing the name of the OS type running within the domain. =item $dom->create($flags) Start a domain whose configuration was previously defined using the C method in L. The C<$flags> parameter accepts one of the DOMAIN CREATION constants documented later, and defaults to 0 if omitted. =item $dom->create_with_files($fds, $flags) Start a domain whose configuration was previously defined using the C method in L. The C<$fds> parameter is an array of UNIX file descriptors which will be passed to the init process of the container. This is only supported with container based virtualization.The C<$flags> parameter accepts one of the DOMAIN CREATION constants documented later, and defaults to 0 if omitted. =item $dom->undefine() Remove the configuration associated with a domain previously defined with the C method in L. If the domain is running, you probably want to use the C or C methods instead. =item $dom->suspend() Temporarily stop execution of the domain, allowing later continuation by calling the C method. =item $dom->resume() Resume execution of a domain previously halted with the C method. =item $dom->pm_wakeup() Wakeup the guest from power management suspend state =item $dom->pm_suspend_for_duration($target, $duration, $flags=0) Tells the guest OS to enter the power management suspend state identified by C<$target>. The C<$target> parameter should be one of the NODE SUSPEND CONTANTS listed in C. The C<$duration> specifies when the guest should automatically wakeup. The C<$flags> parameter is optional and defaults to zero. =item $dom->save($filename) Take a snapshot of the domain's state and save the information to the file named in the C<$filename> parameter. The domain can later be restored from this file with the C method on the L object. =item $dom->managed_save($flags=0) Take a snapshot of the domain's state and save the information to a managed save location. The domain will be automatically restored with this state when it is next started. The C<$flags> parameter is unused and defaults to zero. =item $bool = $dom->has_managed_save_image($flags=0) Return a non-zero value if the domain has a managed save image that will be used at next start. The C<$flags> parameter is unused and defaults to zero. =item $dom->managed_save_remove($flags=0) Remove the current managed save image, causing the guest to perform a full boot next time it is started. The C<$flags> parameter is unused and defaults to zero. =item $dom->managed_save_define_xml($xml, $flags=0) Update the XML of the managed save image to C<$xml>. The C<$flags> parameter is unused and defaults to zero. =item $xml = $dom->managed_save_get_xml_description($flags=0) Get the XML in the managed save image. The C<$flags> parameter is unused and defaults to zero. =item $dom->core_dump($filename[, $flags]) Trigger a core dump of the guest virtual machine, saving its memory image to C<$filename> so it can be analysed by tools such as C. The optional C<$flags> flags parameter is currently unused and if omitted will default to 0. =item $dom->core_dump_format($filename, $format, [, $flags]) Trigger a core dump of the guest virtual machine, saving its memory image to C<$filename> so it can be analysed by tools such as C. The C<$format> parameter is one of the core dump format constants. The optional C<$flags> flags parameter is currently unused and if omitted will default to 0. =over 4 =item Sys::Virt::Domain::CORE_DUMP_FORMAT_RAW The raw ELF format =item Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_ZLIB The zlib compressed ELF format =item Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_SNAPPY The snappy compressed ELF format =item Sys::Virt::Domain::CORE_DUMP_FORMAT_KDUMP_LZO The lzo compressed ELF format =back =item $dom->destroy() Immediately poweroff the machine. This is equivalent to removing the power plug. The guest OS is given no time to cleanup / save state. For a clean poweroff sequence, use the C method instead. =item my $info = $dom->get_info() Returns a hash reference summarising the execution state of the domain. The elements of the hash are as follows: =over 4 =item maxMem The maximum memory allowed for this domain, in kilobytes =item memory The current memory allocated to the domain in kilobytes =item cpuTime The amount of CPU time used by the domain =item nrVirtCpu The current number of virtual CPUs enabled in the domain =item state The execution state of the machine, which will be one of the constants &Sys::Virt::Domain::STATE_*. =back =item my ($state, $reason) = $dom->get_state() Returns an array whose values specify the current state of the guest, and the reason for it being in that state. The C<$state> values are the same as for the C API, and the C<$reason> values come from: =over 4 =item Sys::Virt::Domain::STATE_CRASHED_UNKNOWN It is not known why the domain has crashed =item Sys::Virt::Domain::STATE_CRASHED_PANICKED The domain has crashed due to a kernel panic =item Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN It is not known why the domain has no state =item Sys::Virt::Domain::STATE_PAUSED_DUMP The guest is paused due to a core dump operation =item Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT The guest is paused due to a snapshot =item Sys::Virt::Domain::STATE_PAUSED_IOERROR The guest is paused due to an I/O error =item Sys::Virt::Domain::STATE_PAUSED_MIGRATION The guest is paused due to migration =item Sys::Virt::Domain::STATE_PAUSED_SAVE The guest is paused due to a save operation =item Sys::Virt::Domain::STATE_PAUSED_UNKNOWN It is not known why the domain has paused =item Sys::Virt::Domain::STATE_PAUSED_USER The guest is paused at admin request =item Sys::Virt::Domain::STATE_PAUSED_WATCHDOG The guest is paused due to the watchdog =item Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN The guest is paused while domain shutdown takes place =item Sys::Virt::Domain::STATE_PAUSED_SNAPSHOT The guest is paused while a snapshot takes place =item Sys::Virt::Domain::STATE_PAUSED_CRASHED The guest is paused due to a kernel panic =item Sys::Virt::Domain::STATE_PAUSED_STARTING_UP The guest is paused as it is being started up. =item Sys::Virt::Domain::STATE_PAUSED_POSTCOPY The guest is paused as post-copy migration is taking place =item Sys::Virt::Domain::STATE_PAUSED_POSTCOPY_FAILED The guest is paused as post-copy migration failed =item Sys::Virt::Domain::STATE_RUNNING_BOOTED The guest is running after being booted =item Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT The guest is running after restore from snapshot =item Sys::Virt::Domain::STATE_RUNNING_MIGRATED The guest is running after migration =item Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED The guest is running after migration abort =item Sys::Virt::Domain::STATE_RUNNING_RESTORED The guest is running after restore from file =item Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED The guest is running after save cancel =item Sys::Virt::Domain::STATE_RUNNING_UNKNOWN It is not known why the domain has started =item Sys::Virt::Domain::STATE_RUNNING_UNPAUSED The guest is running after a resume =item Sys::Virt::Domain::STATE_RUNNING_WAKEUP The guest is running after wakeup from power management suspend =item Sys::Virt::Domain::STATE_RUNNING_CRASHED The guest was restarted after crashing =item Sys::Virt::Domain::STATE_RUNNING_POSTCOPY The guest is running but post-copy is taking place =item Sys::Virt::Domain::STATE_BLOCKED_UNKNOWN The guest is blocked for an unknown reason =item Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN It is not known why the domain has shutdown =item Sys::Virt::Domain::STATE_SHUTDOWN_USER The guest is shutdown due to admin request =item Sys::Virt::Domain::STATE_SHUTOFF_CRASHED The guest is shutoff after a crash =item Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED The guest is shutoff after being destroyed =item Sys::Virt::Domain::STATE_SHUTOFF_FAILED The guest is shutoff due to a virtualization failure =item Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT The guest is shutoff after a snapshot =item Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED The guest is shutoff after migration =item Sys::Virt::Domain::STATE_SHUTOFF_SAVED The guest is shutoff after a save =item Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN The guest is shutoff due to controlled shutdown =item Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN It is not known why the domain has shutoff =item Sys::Virt::Domain::STATE_PMSUSPENDED_UNKNOWN It is not known why the domain was suspended to RAM =item Sys::Virt::Domain::STATE_PMSUSPENDED_DISK_UNKNOWN It is not known why the domain was suspended to disk =back =item my $info = $dom->get_control_info($flags=0) Returns a hash reference providing information about the control channel. The returned keys in the hash are =over 4 =item C One of the CONTROL INFO constants listed later =item C
Currently unused, always 0. =item C The elapsed time since the control channel entered the current state. =back =item my $time = $dom->get_time($flags=0); Get the current time of the guest, in seconds and nanoseconds. The C<$flags> parameter is currently unused and defaults to zero. The return value is an array ref with two elements, the first contains the time in seconds, the second contains the remaining nanoseconds. =item $dom->set_time($secs, $nsecs, $flags=0); Set the current time of the guest, in seconds and nanoseconds. The C<$flags> parameter accepts one of =over 4 =item C Re-sync domain time from domain's RTC. =back =item $dom->set_user_password($username, $password, $flags=0); Update the password for account C<$username> to be C<$password>. C<$password> is the clear-text password string unless the PASSWORD_ENCRYPTED flag is set. =over 4 =item C The C<$password> is encrypted with the password scheme required by the guest OS. =back =item $dom->rename($newname, $flags=0) Change the name of an inactive guest to be C<$newname>. The C<$flags> parameter is currently unused and defaults to zero. =item my @errs = $dom->get_disk_errors($flags=0) Returns a list of all disk errors that have occurred on the backing store for the guest's virtual disks. The returned array elements are hash references, containing two keys =over 4 =item C The path of the disk with an error =item C The error type =back =item $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0) Sends a sequence of keycodes to the guest domain. The C<$keycodeset> should be one of the constants listed later in the KEYCODE SET section. C<$holdtiem> is the duration, in milliseconds, to keep the key pressed before releasing it and sending the next keycode. C<@keycodes> is an array reference containing the list of keycodes to send to the guest. The elements in the array should be keycode values from the specified keycode set. C<$flags> is currently unused. =item my $info = $dom->get_block_info($dev, $flags=0) Returns a hash reference summarising the disk usage of the host backing store for a guest block device. The C<$dev> parameter should be the path to the backing store on the host. C<$flags> is currently unused and defaults to 0 if omitted. The returned hash contains the following elements =over 4 =item capacity Logical size in bytes of the block device backing image * =item allocation Highest allocated extent in bytes of the block device backing image =item physical Physical size in bytes of the container of the backing image =back =item $dom->set_max_memory($mem) Set the maximum memory for the domain to the value C<$mem>. The value of the C<$mem> parameter is specified in kilobytes. =item $mem = $dom->get_max_memory() Returns the current maximum memory allowed for this domain in kilobytes. =item $dom->set_memory($mem, $flags) Set the current memory for the domain to the value C<$mem>. The value of the C<$mem> parameter is specified in kilobytes. This must be less than, or equal to the domain's max memory limit. The C<$flags> parameter can control whether the update affects the live guest, or inactive config, defaulting to modifying the current state. =item $dom->set_memory_stats_period($period, $flags) Set the period on which guests memory stats are refreshed, with C<$period> being a value in seconds. The C<$flags> parameter is currently unused. =item $dom->shutdown() Request that the guest OS perform a graceful shutdown and poweroff. This usually requires some form of cooperation from the guest operating system, such as responding to an ACPI signal, or a guest agent process. For an immediate, forceful poweroff, use the C method instead. =item $dom->reboot([$flags]) Request that the guest OS perform a graceful shutdown and optionally restart. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $dom->reset([$flags]) Perform a hardware reset of the virtual machine. The guest OS is given no opportunity to shutdown gracefully. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $dom->get_max_vcpus() Return the maximum number of vcpus that are configured for the domain =item $dom->attach_device($xml[, $flags]) Hotplug a new device whose configuration is given by C<$xml>, to the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later. =item $dom->detach_device($xml[, $flags]) Hotunplug an existing device whose configuration is given by C<$xml>, from the running guest. The optional <$flags> parameter defaults to 0, but can accept one of the device hotplug flags described later. =item $dom->update_device($xml[, $flags]) Update the configuration of an existing device. The new configuration is given by C<$xml>. The optional <$flags> parameter defaults to 0 but can accept one of the device hotplug flags described later. =item $data = $dom->block_peek($path, $offset, $size[, $flags]) Peek into the guest disk C<$path>, at byte C<$offset> capturing C<$size> bytes of data. The returned scalar may contain embedded NULLs. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $data = $dom->memory_peek($offset, $size[, $flags]) Peek into the guest memory at byte C<$offset> virtual address, capturing C<$size> bytes of memory. The return scalar may contain embedded NULLs. The optional C<$flags> parameter is currently unused and if omitted defaults to zero. =item $flag = $dom->get_autostart(); Return a true value if the guest domain is configured to automatically start upon boot. Return false, otherwise =item $dom->set_autostart($flag) Set the state of the autostart flag, which determines whether the guest will automatically start upon boot of the host OS =item $dom->set_vcpus($count, [$flags]) Set the number of virtual CPUs in the guest VM to C<$count>. The optional C<$flags> parameter can be used to control whether the setting changes the live config or inactive config. =item $dom->set_vcpu($cpumap, $state, [$flags]) Set the state of the CPUs in C<$cpumap> to C<$state>. The C<$flags> parameter defaults to zero if not present. =item $count = $dom->get_vcpus([$flags]) Get the number of virtual CPUs in the guest VM. The optional C<$flags> parameter can be used to control whether to query the setting of the live config or inactive config. =item $dom->set_guest_vcpus($cpumap, $state, [$flags=0]) Set the online status of the guest OS CPUs. The C<$cpumap> parameter describes the set of CPUs to modify (eg "0-3,^1"). C<$state> is either B<1> to set the CPUs online, or B<0> to set them offline. The C<$flags> parameter is currently unused and defaults to 0. =item $info $dom->get_guest_vcpus([$flags=0]) Query information about the guest OS CPUs. The returned data is a hash reference with the following keys. =over 4 =item B String containing bitmap representing CPU ids reported currently known to the guest. =item B String containing bitmap representing CPU ids that are currently online in the guest. =item B String containing bitmap representing CPU ids that can be offlined in the guest. =back The C<$flags> parameter is currently unused and defaults to 0. =item $type = $dom->get_scheduler_type() Return the scheduler type for the guest domain =item $stats = $dom->block_stats($path) Fetch the current I/O statistics for the block device given by C<$path>. The returned hash reference contains keys for =over 4 =item C Number of read requests =item C Number of bytes read =item C Number of write requests =item C Number of bytes written =item C Some kind of error count =back =item my $params = $dom->get_scheduler_parameters($flags=0) Return the set of scheduler tunable parameters for the guest, as a hash reference. The precise set of keys in the hash are specific to the hypervisor. =item $dom->set_scheduler_parameters($params, $flags=0) Update the set of scheduler tunable parameters. The value names for tunables vary, and can be discovered using the C call =item my $params = $dom->get_memory_parameters($flags=0) Return a hash reference containing the set of memory tunable parameters for the guest. The keys in the hash are one of the constants MEMORY PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_memory_parameters($params, $flags=0) Update the memory tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the MEMORY PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item my $params = $dom->get_blkio_parameters($flags=0) Return a hash reference containing the set of blkio tunable parameters for the guest. The keys in the hash are one of the constants BLKIO PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_blkio_parameters($params, $flags=0) Update the blkio tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the BLKIO PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $stats = $dom->get_block_iotune($disk, $flags=0) Return a hash reference containing the set of blkio tunable parameters for the guest disk C<$disk>. The keys in the hash are one of the constants BLOCK IOTUNE PARAMETERS described later. =item $dom->set_block_iotune($disk, $params, $flags=0); Update the blkio tunable parameters for the guest disk C<$disk>. The C<$params> should be a hash reference whose keys are one of the BLOCK IOTUNE PARAMETERS constants. =item my $params = $dom->get_interface_parameters($intf, $flags=0) Return a hash reference containing the set of interface tunable parameters for the guest. The keys in the hash are one of the constants INTERFACE PARAMETERS described later. =item $dom->set_interface_parameters($intf, $params, $flags=0) Update the interface tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the INTERFACE PARAMETERS constants. =item my $params = $dom->get_numa_parameters($flags=0) Return a hash reference containing the set of numa tunable parameters for the guest. The keys in the hash are one of the constants NUMA PARAMETERS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_numa_parameters($params, $flags=0) Update the numa tunable parameters for the guest. The C<$params> should be a hash reference whose keys are one of the NUMA PARAMETERS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item my $params = $dom->get_perf_events($flags=0) Return a hash reference containing the set of performance events that are available for the guest. The keys in the hash are one of the constants PERF EVENTS described later. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->set_perf_events($params, $flags=0) Update the enabled state for performance events for the guest. The C<$params> should be a hash reference whose keys are one of the PERF EVENTS constants. The C<$flags> parameter accepts one or more the CONFIG OPTION constants documented later, and defaults to 0 if omitted. =item $dom->block_resize($disk, $newsize, $flags=0) Resize the disk C<$disk> to have new size C<$newsize> KB. If the disk is backed by a special image format, the actual resize is done by the hypervisor. If the disk is backed by a raw file, or block device, the resize must be done prior to invoking this API call, and it merely updates the hypervisor's view of the disk size. The following flags may be used =over 4 =item Sys::Virt::Domain::BLOCK_RESIZE_BYTES Treat C<$newsize> as if it were in bytes, rather than KB. =back =item $dom->interface_stats($path) Fetch the current I/O statistics for the block device given by C<$path>. The returned hash containins keys for =over 4 =item C Total bytes received =item C Total packets received =item C Total packets received with errors =item C Total packets drop at reception =item C Total bytes transmitted =item C Total packets transmitted =item C Total packets transmitted with errors =item C Total packets dropped at transmission. =back =item $dom->memory_stats($flags=0) Fetch the current memory statistics for the guest domain. The C<$flags> parameter is currently unused and can be omitted. The returned hash containins keys for =over 4 =item C Data read from swap space =item C Data written to swap space =item C Page fault involving disk I/O =item C Page fault not involving disk I/O =item C Memory not used by the system =item C Total memory seen by guest =item C Resident set size. Size of memory resident in host RAM. =back =item $info = $dom->get_security_label() Fetch information about the security label assigned to the guest domain. The returned hash reference has two keys, C gives the name of the security model in effect (eg C), while C