Provided by: libsys-virt-perl_0.9.7-2_amd64 bug

NAME

       Sys::Virt::Domain - Represent & manage a libvirt guest domain

DESCRIPTION

       The "Sys::Virt::Domain" module represents a guest domain managed by the virtual machine
       monitor.

METHODS

       my $id = $dom->get_id()
           Returns an integer with a locally unique identifier for the domain.

       my $uuid = $dom->get_uuid()
           Returns a 16 byte long string containing the raw globally unique identifier (UUID) for
           the domain.

       my $uuid = $dom->get_uuid_string()
           Returns a printable string representation of the raw UUID, in the format
           'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'.

       my $name = $dom->get_name()
           Returns a string with a locally unique name of the domain

       $dom->is_active()
           Returns a true value if the domain is currently running

       $dom->is_persistent()
           Returns a true value if the domain has a persistent configuration file defined

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

       my $xml = $dom->get_xml_description()
           Returns an XML document containing a complete description of the domain's
           configuration

       my $type = $dom->get_os_type()
           Returns a string containing the name of the OS type running within the domain.

       $dom->create($flags)
           Start a domain whose configuration was previously defined using the "define_domain"
           method in Sys::Virt. The $flags parameter accepts one of the DOMAIN CREATION constants
           documented later, and defaults to 0 if omitted.

       $dom->undefine()
           Remove the configuration associated with a domain previously defined with the
           "define_domain" method in Sys::Virt. If the domain is running, you probably want to
           use the "shutdown" or "destroy" methods instead.

       $dom->suspend()
           Temporarily stop execution of the domain, allowing later continuation by calling the
           "resume" method.

       $dom->resume()
           Resume execution of a domain previously halted with the "suspend" method.

       $dom->save($filename)
           Take a snapshot of the domain's state and save the information to the file named in
           the $filename parameter. The domain can later be restored from this file with the
           "restore_domain" method on the Sys::Virt object.

       $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 $flags parameter is unused and defaults to zero.

       $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 $flags parameter is unused and defaults to zero.

       $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 $flags parameter is unused and defaults to zero.

       $dom->core_dump($filename[, $flags])
           Trigger a core dump of the guest virtual machine, saving its memory image to $filename
           so it can be analysed by tools such as "crash".  The optional $flags flags parameter
           is currently unused and if omitted will default to 0.

       $dom->destroy()
           Immediately terminate the machine, and remove it from the virtual machine monitor. The
           $dom handle is invalid after this call completes and should not be used again.

       my $info = $dom->get_info()
           Returns a hash reference summarising the execution state of the domain. The elements
           of the hash are as follows:

           maxMem
               The maximum memory allowed for this domain, in kilobytes

           memory
               The current memory allocated to the domain in kilobytes

           cpuTime
               The amount of CPU time used by the domain

           nrVirtCpu
               The current number of virtual CPUs enabled in the domain

           state
               The execution state of the machine, which will be one of the constants
               &Sys::Virt::Domain::STATE_*.

       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 $state values are the same as for the "get_info" API,
           and the $reason values come from:

           Sys::Virt::Domain::STATE_CRASHED_UNKNOWN
               It is not known why the domain has crashed

           Sys::Virt::Domain::STATE_NOSTATE_UNKNOWN
               It is not known why the domain has no state

           Sys::Virt::Domain::STATE_PAUSED_DUMP
               The guest is paused due to a core dump operation

           Sys::Virt::Domain::STATE_PAUSED_FROM_SNAPSHOT
               The guest is paused due to a snapshot

           Sys::Virt::Domain::STATE_PAUSED_IOERROR
               The guest is paused due to an I/O error

           Sys::Virt::Domain::STATE_PAUSED_MIGRATION
               The guest is paused due to migration

           Sys::Virt::Domain::STATE_PAUSED_SAVE
               The guest is paused due to a save operation

           Sys::Virt::Domain::STATE_PAUSED_UNKNOWN
               It is not known why the domain has paused

           Sys::Virt::Domain::STATE_PAUSED_USER
               The guest is paused at admin request

           Sys::Virt::Domain::STATE_PAUSED_WATCHDOG
               The guest is paused due to the watchdog

           Sys::Virt::Domain::STATE_PAUSED_SHUTTING_DOWN
               The guest is paused while domain shutdown takes place

           Sys::Virt::Domain::STATE_RUNNING_BOOTED
               The guest is running after being booted

           Sys::Virt::Domain::STATE_RUNNING_FROM_SNAPSHOT
               The guest is running after restore from snapshot

           Sys::Virt::Domain::STATE_RUNNING_MIGRATED
               The guest is running after migration

           Sys::Virt::Domain::STATE_RUNNING_MIGRATION_CANCELED
               The guest is running after migration abort

           Sys::Virt::Domain::STATE_RUNNING_RESTORED
               The guest is running after restore from file

           Sys::Virt::Domain::STATE_RUNNING_SAVE_CANCELED
               The guest is running after save cancel

           Sys::Virt::Domain::STATE_RUNNING_UNKNOWN
               It is not known why the domain has started

           Sys::Virt::Domain::STATE_RUNNING_UNPAUSED
               The guest is running after a resume

           Sys::Virt::Domain::STATE_SHUTDOWN_UNKNOWN
               It is not known why the domain has shutdown

           Sys::Virt::Domain::STATE_SHUTDOWN_USER
               The guest is shutdown due to admin request

           Sys::Virt::Domain::STATE_SHUTOFF_CRASHED
               The guest is shutoff after a crash

           Sys::Virt::Domain::STATE_SHUTOFF_DESTROYED
               The guest is shutoff after being destroyed

           Sys::Virt::Domain::STATE_SHUTOFF_FAILED
               The guest is shutoff due to a virtualization failure

           Sys::Virt::Domain::STATE_SHUTOFF_FROM_SNAPSHOT
               The guest is shutoff after a snapshot

           Sys::Virt::Domain::STATE_SHUTOFF_MIGRATED
               The guest is shutoff after migration

           Sys::Virt::Domain::STATE_SHUTOFF_SAVED
               The guest is shutoff after a save

           Sys::Virt::Domain::STATE_SHUTOFF_SHUTDOWN
               The guest is shutoff due to controlled shutdown

           Sys::Virt::Domain::STATE_SHUTOFF_UNKNOWN
               It is not known why the domain has shutoff

       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

           "state"
               One of the CONTROL INFO constants listed later

           "details"
               Currently unsed, always 0.

           "stateTime"
               The elapsed time since the control channel entered the current state.

       $dom->send_key($keycodeset, $holdtime, \@keycodes, $flags=0)
           Sends a sequence of keycodes to the guest domain. The $keycodeset should be one of the
           constants listed later in the KEYCODE SET section. $holdtiem is the duration, in
           milliseconds, to keep the key pressed before releasing it and sending the next
           keycode.  @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. $flags is currently unused.

       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 $dev parameter should be the path to the backing store on the
           host. $flags is currently unused and defaults to 0 if omitted. The returned hash
           contains the following elements

           capacity
               Logical size in bytes of the block device backing image *

           allocation
               Highest allocated extent in bytes of the block device backing image

           physical
               Physical size in bytes of the container of the backing image

       $dom->set_max_memory($mem)
           Set the maximum memory for the domain to the value $mem. The value of the $mem
           parameter is specified in kilobytes.

       $mem = $dom->get_max_memory()
           Returns the current maximum memory allowed for this domain in kilobytes.

       $dom->set_memory($mem, $flags)
           Set the current memory for the domain to the value $mem. The value of the $mem
           parameter is specified in kilobytes. This must be less than, or equal to the domain's
           max memory limit.  The $flags parameter can control whether the update affects the
           live guest, or inactive config, defaulting to modifying the current state.

       $dom->shutdown()
           Request that the guest OS perform a graceful shutdown and poweroff.

       $dom->reboot([$flags])
           Request that the guest OS perform a graceful shutdown and optionally restart. The
           optional $flags parameter is currently unused and if omitted defaults to zero.

       $dom->reset([$flags])
           Perform a hardware reset of the virtual machine. The guest OS is given no opportunity
           to shutdown gracefully. The optional $flags parameter is currently unused and if
           omitted defaults to zero.

       $dom->get_max_vcpus()
           Return the maximum number of vcpus that are configured for the domain

       $dom->attach_device($xml[, $flags])
           Hotplug a new device whose configuration is given by $xml, to the running guest. The
           optional <$flags> parameter defaults to 0, but can accept one of the device hotplug
           flags described later.

       $dom->detach_device($xml[, $flags])
           Hotunplug a existing device whose configuration is given by $xml, from the running
           guest. The optional <$flags> parameter defaults to 0, but can accept one of the device
           hotplug flags described later.

       $dom->update_device($xml[, $flags])
           Update the configuration of an existing device. The new configuration is given by
           $xml. The optional <$flags> parameter defaults to 0 but can accept one of the device
           hotplug flags described later.

       $data = $dom->block_peek($path, $offset, $size[, $flags)
           Peek into the guest disk $path, at byte $offset capturing $size bytes of data. The
           returned scalar may contain embedded NULLs. The optional $flags parameter is currently
           unused and if omitted defaults to zero.

       $data = $dom->memory_peek($offset, $size[, $flags])
           Peek into the guest memory at byte $offset virtual address, capturing $size bytes of
           memory. The return scalar may contain embedded NULLs. The optional $flags parameter is
           currently unused and if omitted defaults to zero.

       $flag = $dom->get_autostart();
           Return a true value if the guest domain is configured to automatically start upon
           boot. Return false, otherwise

       $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

       $dom->set_vcpus($count, [$flags])
           Set the number of virtual CPUs in the guest VM to $count.  The optional $flags
           parameter can be used to control whether the setting changes the live config or
           inactive config.

       $count = $dom->get_vcpus([$flags])
           Get the number of virtual CPUs in the guest VM.  The optional $flags parameter can be
           used to control whether to query the setting of the live config or inactive config.

       $type = $dom->get_scheduler_type()
           Return the scheduler type for the guest domain

       %stats = $dom->block_stats($path)
           Fetch the current I/O statistics for the block device given by $path.  The returned
           hash containins keys for

       my %params = $dom->get_scheduler_parameters()
           Return the set of scheduler tunable parameters for the guest.

       $dom->set_scheduler_parameters($params)
           Update the set of scheduler tunable parameters. The value names for tunables vary, and
           can be discovered using the "get_scheduler_params" call

       my $params = $dom->get_memory_parameters()
           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.

       $dom->set_memory_parameters($params)
           Update the memory tunable parameters for the guest. The $params should be a hash
           reference whose keys are one of the MEMORY PARAMETERS constants.

           "rd_req"
               Number of read requests

           "rd_bytes"
               Number of bytes read

           "wr_req"
               Number of write requests

           "wr_bytes"
               Number of bytes written

           "errs"
               Some kind of error count

       my $params = $dom->get_blkio_parameters()
           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.

       $dom->set_blkio_parameters($params)
           Update the blkio tunable parameters for the guest. The $params should be a hash
           reference whose keys are one of the BLKIO PARAMETERS constants.

           "weight"
               Relative I/O weighting

       $dom->interface_stats($path)
           Fetch the current I/O statistics for the block device given by $path.  The returned
           hash containins keys for

           "rx_bytes"
               Total bytes received

           "rx_packets"
               Total packets received

           "rx_errs"
               Total packets received with errors

           "rx_drop"
               Total packets drop at reception

           "tx_bytes"
               Total bytes transmitted

           "tx_packets"
               Total packets transmitted

           "tx_errs"
               Total packets transmitted with errors

           "tx_drop"
               Total packets dropped at transmission.

       $dom->memory_stats($flags=0)
           Fetch the current memory statistics for the guest domain. The $flags parameter is
           currently unused and can be omitted.  The returned hash containins keys for

           "swap_in"
               Data read from swap space

           "swap_out"
               Data written to swap space

           "major_fault"
               Page fault involving disk I/O

           "minor_fault"
               Page fault not involving disk I/O

           "unused"
               Memory not used by the system

           "available"
               Total memory seen by guest

       %info = $dom->get_security_label()
           Fetch information about the security label assigned to the guest domain. The returned
           hash has two keys, "model" gives the name of the security model in effect (eg
           "selinux"), while "label" provides the name of the security label applied to the
           domain.

       $ddom = $dom->migrate(destcon, flags, dname, uri, bandwidth)
           Migrate a domain to an alternative host. The "destcon" parameter should be a
           "Sys::Virt" connection to the remote target host.  If the "flags" parameter is zero
           offline migration will be performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant
           can be used to request live migration. The "dname" parameter allows the guest to be
           renamed on the target host, if set to "undef", the domains' current name will be
           maintained. In normal circumstances, the source host determines the target hostname
           from the URI associated with the "destcon" connection. If the destination host is
           multi-homed it may be necessary to supply an alternate destination hostame via the
           "uri" parameter. The "bandwidth" parameter allows network usage to be throttled during
           migration. If set to zero, no throttling will be performed. The "flags", "dname",
           "uri" and "bandwidth" parameters are all optional, and if omitted default to zero,
           "undef", "undef", and zero respectively.

       $ddom = $dom->migrate2(destcon, dxml, flags, dname, uri, bandwidth)
           Migrate a domain to an alternative host. This function works in the same way as
           "migrate", except is also allows "dxml" to specify a changed XML configuration for the
           guest on the target host.

       $dom->migrate_to_uri(desturi, flags, dname, bandwidth)
           Migrate a domain to an alternative host. The "destri" parameter should be a valid
           libvirt connection URI for the remote target host.  If the "flags" parameter is zero
           offline migration will be performed. The "Sys::Virt::Domain::MIGRATE_LIVE" constant
           can be used to request live migration. The "dname" parameter allows the guest to be
           renamed on the target host, if set to "undef", the domains' current name will be
           maintained. In normal circumstances, the source host determines the target hostname
           from the URI associated with the "destcon" connection. If the destination host is
           multi-homed it may be necessary to supply an alternate destination hostame via the
           "uri" parameter. The "bandwidth" parameter allows network usage to be throttled during
           migration. If set to zero, no throttling will be performed. The "flags", "dname" and
           "bandwidth" parameters are all optional, and if omitted default to zero, "undef",
           "undef", and zero respectively.

       $dom->migrate_to_uri2(dconnuri, miguri, dxml, flags, dname, bandwidth)
           Migrate a domain to an alternative host. This function works in almost the same way as
           "migrate_to_uri", except is also allows "dxml" to specify a changed XML configuration
           for the guest on the target host.  The "dconnuri" must always specify the URI of the
           remote libvirtd daemon, or be "undef". The "miguri" parameter can be used to specify
           the URI for initiating the migration operation, or be "undef".

       $dom->migrate_set_max_downtime($downtime, $flags)
           Set the maximum allowed downtime during migration of the guest. A longer downtime
           makes it more likely that migration will complete, at the cost of longer time blackout
           for the guest OS at the switch over point. The "downtime" parameter is measured in
           milliseconds.  The $flags parameter is currently unused and defaults to zero.

       $dom->migrate_set_max_speed($bandwidth, $flags)
           Set the maximum allowed bandwidth during migration of the guest.  The "bandwidth"
           parameter is measured in kilobytes/second.  The $flags parameter is currently unused
           and defaults to zero.

       $bandwidth = $dom->migrate_get_max_speed($flag)
           Get the maximum allowed bandwidth during migration fo the guest.  The returned
           <bandwidth> value is measured in kilobytes/second.  The $flags parameter is currently
           unused and defaults to zero.

       $dom->inject_nmi($flags)
           Trigger an NMI in the guest virtual machine. The $flags parameter is currently unused
           and defaults to 0.

       $dom->open_console($st, $devname, $flags)
           Open the text console for a serial, parallel or paravirt console device identified by
           $devname, connecting it to the stream $st. If $devname is undefined, the default
           console will be opened. $st must be a "Sys::Virt::Stream" object used for bi-
           directional communication with the console. $flags is currently unused, defaulting to
           0.

       $dom->open_graphics($idx, $fd, $flags)
           Open the graphics console for a guest, identified by $idx, counting from 0. The $fd
           should be a file descriptor for an anoymous socket pair. The $flags argument should be
           one of the constants listed at the end of this document, and defaults to 0.

       $dom->screenshot($st, $screen, $flags)
           Capture a screenshot of the virtual machine's monitor. The $screen parameter controls
           which monitor is captured when using a multi-head or multi-card configuration. $st
           must be a "Sys::Virt::Stream" object from which the data can be read. $flags is
           currently unused and defaults to 0.

       @vcpuinfo = $dom->get_vcpu_info()
           Obtain information about the state of all virtual CPUs in a running guest domain. The
           returned list will have one element for each vCPU, where each elements contains a hash
           reference. The keys in the hash are, "number" the vCPU number, "cpu" the physical CPU
           on which the vCPU is currently scheduled, "cpuTime" the cummulative execution time of
           the vCPU, "state" the running state and "affinity" giving the allowed shedular
           placement. The value for "affinity" is a string representing a bitmask against
           physical CPUs, 8 cpus per character.

       $dom->pin_vcpu($vcpu, $mask)
           Ping the virtual CPU given by index $vcpu to physical CPUs given by $mask. The $mask
           is a string representing a bitmask against physical CPUs, 8 cpus per character.

       my $info = $dom->get_job_info()
           Returns a hash reference summarising the execution state of the background job. The
           elements of the hash are as follows:

       $dom->abort_job()
           Aborts the currently executing job

       my $info = $dom->get_block_job_info($path, $flags=0)
           Returns a hash reference summarising the execution state of the block job. The $path
           parameter should be the fully qualified path of the block device being changed.

       $dom->set_block_job_speed($path, $bandwidth, $flags=0)
           Change the maximum I/O bandwidth used by the block job that is currently executing for
           $path. The $bandwidth argument is specified in KB/s

       $dom->abort_block_job($path, $flags=0)
           Abort the current job that is executing for the block device associated with $path

       $dom->block_pull($path, $bandwith, $flags=0)
           Merge the backing files associated with $path into the top level file. The $bandwidth
           parameter specifies the maximum I/O rate to allow in KB/s.

       $count = $dom->num_of_snapshots()
           Return the number of saved snapshots of the domain

       @names = $dom->list_snapshot_names()
           List the names of all saved snapshots. The names can be used with the
           "lookup_snapshot_by_name"

       @snapshots = $dom->list_snapshots()
           Return a list of all snapshots currently known to the domain. The elements in the
           returned list are instances of the Sys::Virt::DomainSnapshot class.

       my $snapshot = $dom->get_snapshot_by_name($name)
           Return the domain snapshot with a name of $name. The returned object is an instance of
           the Sys::Virt::DomainSnapshot class.

       $dom->has_current_snapshot()
           Returns a true value if the domain has a currently active snapshot

       $snapshot = $dom->current_snapshot()
           Returns the currently active snapshot for the domain.

       $snapshot = $dom->create_snapshot($xml[, $flags])
           Create a new snapshot from the $xml.

           type
               The type of job, one of the JOB TYPE constants listed later in this document.

           timeElapsed
               The elapsed time in milliseconds

           timeRemaining
               The expected remaining time in milliseconds. Only set if the "type" is
               JOB_UNBOUNDED.

           dataTotal
               The total amount of data expected to be processed by the job, in bytes.

           dataProcessed
               The current amount of data processed by the job, in bytes.

           dataRemaining
               The expected amount of data remaining to be processed by the job, in bytes.

           memTotal
               The total amount of mem expected to be processed by the job, in bytes.

           memProcessed
               The current amount of mem processed by the job, in bytes.

           memRemaining
               The expected amount of mem remaining to be processed by the job, in bytes.

           fileTotal
               The total amount of file expected to be processed by the job, in bytes.

           fileProcessed
               The current amount of file processed by the job, in bytes.

           fileRemaining
               The expected amount of file remaining to be processed by the job, in bytes.

CONSTANTS

       A number of the APIs take a "flags" parameter. In most cases passing a value of zero will
       be satisfactory. Some APIs, however, accept named constants to alter their behaviour. This
       section documents the current known constants.

   DOMAIN STATE
       The domain state constants are useful in interpreting the "state" key in the hash returned
       by the "get_info" method.

       Sys::Virt::Domain::STATE_NOSTATE
           The domain is active, but is not running / blocked (eg idle)

       Sys::Virt::Domain::STATE_RUNNING
           The domain is active and running

       Sys::Virt::Domain::STATE_BLOCKED
           The domain is active, but execution is blocked

       Sys::Virt::Domain::STATE_PAUSED
           The domain is active, but execution has been paused

       Sys::Virt::Domain::STATE_SHUTDOWN
           The domain is active, but in the shutdown phase

       Sys::Virt::Domain::STATE_SHUTOFF
           The domain is inactive, and shut down.

       Sys::Virt::Domain::STATE_CRASHED
           The domain is inactive, and crashed.

   CONTROL INFO
       The following constants can be used to determine what the guest domain control channel
       status is

       Sys::Virt::Domain::CONTROL_ERROR
           The control channel has a fatal error

       Sys::Virt::Domain::CONTROL_OK
           The control channel is ready for jobs

       Sys::Virt::Domain::CONTROL_OCCUPIED
           The control channel is busy

       Sys::Virt::Domain::CONTROL_JOB
           The control channel is busy with a job

   DOMAIN CREATION
       The following constants can be used to control the behaviour of domain creation

       Sys::Virt::Domain::START_PAUSED
           Keep the guest vCPUs paused after starting the guest

       Sys::Virt::Domain::START_AUTODESTROY
           Automatically destroy the guest when the connection is closed (or fails)

       Sys::Virt::Domain::START_BYPASS_CACHE
           Do not use OS I/O cache if starting a domain with a saved state image

       Sys::Virt::Domain::START_FORCE_BOOT
           Boot the guest, even if there was a saved snapshot

   KEYCODE SETS
       The following constants define the set of supported keycode sets

       Sys::Virt::Domain::KEYCODE_SET_LINUX
           The Linux event subsystem keycodes

       Sys::Virt::Domain::KEYCODE_SET_XT
           The original XT keycodes

       Sys::Virt::Domain::KEYCODE_SET_ATSET1
           The AT Set1 keycodes (aka XT)

       Sys::Virt::Domain::KEYCODE_SET_ATSET2
           The AT Set2 keycodes (aka AT)

       Sys::Virt::Domain::KEYCODE_SET_ATSET3
           The AT Set3 keycodes (aka PS2)

       Sys::Virt::Domain::KEYCODE_SET_OSX
           The OS-X keycodes

       Sys::Virt::Domain::KEYCODE_SET_XT_KBD
           The XT keycodes from the Linux Keyboard driver

       Sys::Virt::Domain::KEYCODE_SET_USB
           The USB HID keycode set

       Sys::Virt::Domain::KEYCODE_SET_WIN32
           The Windows keycode set

       Sys::Virt::Domain::KEYCODE_SET_RFB
           The XT keycode set, with the extended scancodes using the high bit of the first byte,
           instead of the low bit of the second byte.

   MEMORY PEEK
       The following constants can be used with the "memory_peek" method's flags parameter

       Sys::Virt::Domain::MEMORY_VIRTUAL
           Indicates that the offset is using virtual memory addressing.

   VCPU STATE
       The following constants are useful when interpreting the virtual CPU run state

       Sys::Virt::Domain::VCPU_OFFLINE
           The virtual CPU is not online

       Sys::Virt::Domain::VCPU_RUNNING
           The virtual CPU is executing code

       Sys::Virt::Domain::VCPU_BLOCKED
           The virtual CPU is waiting to be scheduled

   OPEN GRAPHICS CONSTANTS
       The following constants are used when opening a connection to the guest graphics server

       Sys::Virt::Domain::OPEN_GRAPHICS_SKIPAUTH
           Skip authentication of the client

   XML DUMP OPTIONS
       The following constants are used to control the information included in the XML
       configuration dump

       Sys::Virt::Domain::XML_INACTIVE
           Report the persistent inactive configuration for the guest, even if it is currently
           running.

       Sys::Virt::Domain::XML_SECURE
           Include security sensitive information in the XML dump, such as passwords.

   DEVICE HOTPLUG OPTIONS
       The following constants are used to control device hotplug operations

       Sys::Virt::Domain::DEVICE_MODIFY_CURRENT
           Modify the domain in its current state

       Sys::Virt::Domain::DEVICE_MODIFY_LIVE
           Modify only the live state of the domain

       Sys::Virt::Domain::DEVICE_MODIFY_CONFIG
           Modify only the persistent config of the domain

   MEMORY OPTIONS
       The following constants are used to control memory change operations

       Sys::Virt::Domain::MEM_CURRENT
           Modify the current state

       Sys::Virt::Domain::MEM_LIVE
           Modify only the live state of the domain

       Sys::Virt::Domain::MEM_CONFIG
           Modify only the persistent config of the domain

       Sys::Virt::Domain::MEM_MAXIMUM
           Modify the maximum memory value

   CONFIG OPTIONS
       The following constants are used to control what configuration a domain update changes

       Sys::Virt::Domain::AFFECT_CURRENT
           Modify the current state

       Sys::Virt::Domain::AFFECT_LIVE
           Modify only the live state of the domain

       Sys::Virt::Domain::AFFECT_CONFIG
           Modify only the persistent config of the domain

   MIGRATE OPTIONS
       The following constants are used to control how migration is performed

       Sys::Virt::Domain::MIGRATE_LIVE
           Migrate the guest without interrupting its execution on the source host.

       Sys::Virt::Domain::MIGRATE_PEER2PEER
           Manage the migration process over a direct peer-2-peer connection between the source
           and destination host libvirtd daemons.

       Sys::Virt::Domain::MIGRATE_TUNNELLED
           Tunnel the migration data over the libvirt daemon connection, rather than the native
           hypervisor data transport. Requires PEER2PEER flag to be set.

       Sys::Virt::Domain::MIGRATE_PERSIST_DEST
           Make the domain persistent on the destination host, defining its configuration file
           upon completion of migration.

       Sys::Virt::Domain::MIGRATE_UNDEFINE_SOURCE
           Remove the domain's persistent configuration after migration completes successfully.

       Sys::Virt::Domain::MIGRATE_PAUSED
           Do not re-start execution of the guest CPUs on the destination host after migration
           completes.

       Sys::Virt::Domain::MIGRATE_NON_SHARED_DISK
           Copy the complete contents of the disk images during migration

       Sys::Virt::Domain::MIGRATE_NON_SHARED_INC
           Copy the incrementally changed contents of the disk images during migration

       Sys::Virt::Domain::MIGRATE_CHANGE_PROTECTION
           Do not allow changes to the virtual domain configuration while migration is taking
           place. This option is automatically implied if doing a peer-2-peer migration.

   UNDEFINE CONSTANTS
       The following constants can be used when undefining virtual domain configurations

       Sys::Virt::Domain::UNDEFINE_MANAGED_SAVE
           Also remove any managed save image when undefining the virtual domain

       Sys::Virt::Domain::UNDEFINE_SNAPSHOTS_METADATA
           Also remove any snapshot metadata when undefining the virtual domain.

   JOB TYPES
       The following constants describe the different background job types.

       Sys::Virt::Domain::JOB_NONE
           No job is active

       Sys::Virt::Domain::JOB_BOUNDED
           A job with a finite completion time is active

       Sys::Virt::Domain::JOB_UNBOUNDED
           A job with an unbounded completion time is active

       Sys::Virt::Domain::JOB_COMPLETED
           The job has finished, but isn't cleaned up

       Sys::Virt::Domain::JOB_FAILED
           The job has hit an error, but isn't cleaned up

       Sys::Virt::Domain::JOB_CANCELLED
           The job was aborted at user request, but isn't cleaned up

   MEMORY PARAMETERS
       The following constants are useful when getting/setting memory parameters for guests

       Sys::Virt::Domain::MEMORY_HARD_LIMIT
           The maximum memory the guest can use.

       Sys::Virt::Domain::MEMORY_SOFT_LIMIT
           The memory upper limit enforced during memory contention.

       Sys::Virt::Domain::MEMORY_MIN_GUARANTEE
           The minimum memory guaranteed to be reserved for the guest.

       Sys::Virt::Domain::MEMORY_SWAP_HARD_LIMIT
           The maximum swap the guest can use.

       Sys::Virt::Domain::MEMORY_PARAM_UNLIMITED
           The value of an unlimited memory parameter

   BLKIO PARAMETERS
       Sys::Virt::Domain::BLKIO_WEIGHT
           The I/O weight parameter

   SCHEDULER CONSTANTS
       Sys::Virt::Domain::SCHEDULER_CAP
           The VM cap tunable

       Sys::Virt::Domain::SCHEDULER_CPU_SHARES
           The CPU shares tunable

       Sys::Virt::Domain::SCHEDULER_LIMIT
           The VM limit tunable

       Sys::Virt::Domain::SCHEDULER_RESERVATION
           The VM reservation tunable

       Sys::Virt::Domain::SCHEDULER_SHARES
           The VM shares tunable

       Sys::Virt::Domain::SCHEDULER_VCPU_PERIOD
           The VCPU period tunable

       Sys::Virt::Domain::SCHEDULER_VCPU_QUOTA
           The VCPU quota tunable

       Sys::Virt::Domain::SCHEDULER_WEIGHT
           The VM weight tunable

   VCPU FLAGS
       The following constants are useful when getting/setting the VCPU count for a guest

       Sys::Virt::Domain::VCPU_LIVE
           Flag to request the live value

       Sys::Virt::Domain::VCPU_CONFIG
           Flag to request the persistent config value

       Sys::Virt::Domain::VCPU_CURRENT
           Flag to request the current config value

   STATE CHANGE EVENTS
       The following constants allow domain state change events to be interpreted. The events
       contain both a state change, and a reason.

       Sys::Virt::Domain::EVENT_DEFINED
           Indicates that a persistent configuration has been defined for the domain.

           Sys::Virt::Domain::EVENT_DEFINED_ADDED
               The defined configuration is newly added

           Sys::Virt::Domain::EVENT_DEFINED_UPDATED
               The defined configuration is an update to an existing configuration

       Sys::Virt::Domain::EVENT_RESUMED
           The domain has resumed execution

           Sys::Virt::Domain::EVENT_RESUMED_MIGRATED
               The domain resumed because migration has completed. This is emitted on the
               destination host.

           Sys::Virt::Domain::EVENT_RESUMED_UNPAUSED
               The domain resumed because the admin unpaused it.

           Sys::Virt::Domain::EVENT_RESUMED_FROM_SNAPSHOT
               The domain resumed because it was restored from a snapshot

       Sys::Virt::Domain::EVENT_STARTED
           The domain has started running

           Sys::Virt::Domain::EVENT_STARTED_BOOTED
               The domain was booted from shutoff state

           Sys::Virt::Domain::EVENT_STARTED_MIGRATED
               The domain started due to an incoming migration

           Sys::Virt::Domain::EVENT_STARTED_RESTORED
               The domain was restored from saved state file

       Sys::Virt::Domain::EVENT_STOPPED
           The domain has stopped running

           Sys::Virt::Domain::EVENT_STOPPED_CRASHED
               The domain stopped because guest operating system has crashed

           Sys::Virt::Domain::EVENT_STOPPED_DESTROYED
               The domain stopped because administrator issued a destroy command.

           Sys::Virt::Domain::EVENT_STOPPED_FAILED
               The domain stopped because of a fault in the host virtualization environment.

           Sys::Virt::Domain::EVENT_STOPPED_MIGRATED
               The domain stopped because it was migrated to another machine.

           Sys::Virt::Domain::EVENT_STOPPED_SAVED
               The domain was saved to a state file

           Sys::Virt::Domain::EVENT_STOPPED_SHUTDOWN
               The domain stopped due to graceful shutdown of the guest.

       Sys::Virt::Domain::EVENT_SUSPENDED
           The domain has stopped executing, but still exists

           Sys::Virt::Domain::EVENT_SUSPENDED_MIGRATED
               The domain has been suspended due to offline migration

           Sys::Virt::Domain::EVENT_SUSPENDED_PAUSED
               The domain has been suspended due to administrator pause request.

           Sys::Virt::Domain::EVENT_SUSPENDED_IOERROR
               The domain has been suspended due to a block device I/O error.

           Sys::Virt::Domain::EVENT_SUSPENDED_FROM_SNAPSHOT
               The domain has been suspended due to resume from snapshot

           Sys::Virt::Domain::EVENT_SUSPENDED_WATCHDOG
               The domain has been suspended due to the watchdog triggering

           Sys::Virt::Domain::EVENT_SUSPENDED_RESTORED
               The domain has been suspended due to restore from saved state

       Sys::Virt::Domain::EVENT_UNDEFINED
           The persistent configuration has gone away

           Sys::Virt::Domain::EVENT_UNDEFINED_REMOVED
               The domain configuration has gone away due to it being removed by administrator.

   EVENT ID CONSTANTS
       Sys::Virt::Domain::EVENT_ID_LIFECYCLE
           Domain lifecycle events

       Sys::Virt::Domain::EVENT_ID_REBOOT
           Soft / warm reboot events

       Sys::Virt::Domain::EVENT_ID_RTC_CHANGE
           RTC clock adjustments

       Sys::Virt::Domain::EVENT_ID_IO_ERROR
           File IO errors, typically from disks

       Sys::Virt::Domain::EVENT_ID_WATCHDOG
           Watchdog device triggering

       Sys::Virt::Domain::EVENT_ID_GRAPHICS
           Graphics client connections.

       Sys::Virt::Domain::EVENT_ID_IO_ERROR_REASON
           File IO errors, typically from disks, with a root cause

       Sys::Virt::Domain::EVENT_ID_CONTROL_ERROR
           Errors from the virtualization control channel

       Sys::Virt::Domain::EVENT_ID_BLOCK_JOB
           Completion status of asynchronous block jobs

       Sys::Virt::Domain::EVENT_ID_DISK_CHANGE
           Changes in disk media

   IO ERROR EVENT CONSTANTS
       These constants describe what action was taken due to the IO error.

       Sys::Virt::Domain::EVENT_IO_ERROR_NONE
           No action was taken, the error was ignored & reported as success to guest

       Sys::Virt::Domain::EVENT_IO_ERROR_PAUSE
           The guest is paused since the error occurred

       Sys::Virt::Domain::EVENT_IO_ERROR_REPORT
           The error has been reported to the guest OS

   WATCHDOG EVENT CONSTANTS
       These constants describe what action was taken due to the watchdog firing

       Sys::Virt::Domain::EVENT_WATCHDOG_NONE
           No action was taken, the watchdog was ignored

       Sys::Virt::Domain::EVENT_WATCHDOG_PAUSE
           The guest is paused since the watchdog fired

       Sys::Virt::Domain::EVENT_WATCHDOG_POWEROFF
           The guest is powered off after the watchdog fired

       Sys::Virt::Domain::EVENT_WATCHDOG_RESET
           The guest is reset after the watchdog fired

       Sys::Virt::Domain::EVENT_WATCHDOG_SHUTDOWN
           The guest attempted to gracefully shutdown after the watchdog fired

       Sys::Virt::Domain::EVENT_WATCHDOG_DEBUG
           No action was taken, the watchdog was logged

   GRAPHICS EVENT PHASE CONSTANTS
       These constants describe the phase of the graphics connection

       Sys::Virt::Domain::EVENT_GRAPHICS_CONNECT
           The initial client connection

       Sys::Virt::Domain::EVENT_GRAPHICS_INITIALIZE
           The client has been authenticated & the connection is running

       Sys::Virt::Domain::EVENT_GRAPHICS_DISCONNECT
           The client has disconnected

   GRAPHICS EVENT ADDRESS CONSTANTS
       These constants describe the format of the address

       Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV4
           An IPv4 address

       Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_IPV6
           An IPv6 address

       Sys::Virt::Domain::EVENT_GRAPHICS_ADDRESS_UNIX
           An UNIX socket path address

   DISK CHANGE EVENT CONSTANTS
       These constants describe the reason for a disk change event

       Sys::Virt::Domain::EVENT_DISK_CHANGE_MISSING_ON_START
           The disk media was missing when attempting to start the guest

   DOMAIN BLOCK JOB TYPE CONSTANTS
       The following constants identify the different types of domain block jobs

       Sys::Virt::Domain::BLOCK_JOB_TYPE_UNKNOWN
           An unknown block job type

       Sys::Virt::Domain::BLOCK_JOB_TYPE_PULL
           The block pull job type

   DOMAIN BLOCK JOB COMPLETION CONSTANTS
       The following constants can be used to determine the completion status of a block job

       Sys::Virt::Domain::BLOCK_JOB_COMPLETED
           A successfully completed block job

       Sys::Virt::Domain::BLOCK_JOB_FAILED
           An unsuccessful block job

   DOMAIN SAVE / RESTORE CONSTANTS
       The following constants can be used when saving or restoring virtual machines

       Sys::Virt::Domain::SAVE_BYPASS_CACHE
           Do not use OS I/O cache when saving state.

       Sys::Virt::Domain::SAVE_PAUSED
           Mark the saved state as paused to prevent the guest CPUs starting upon restore.

       Sys::Virt::Domain::SAVE_RUNNING
           Mark the saved state as running to allow the guest CPUs to start upon restore.

   DOMAIN CORE DUMP CONSTANTS
       The following constants can be used when triggering domain core dumps

       Sys::Virt::Domain::DUMP_LIVE
           Do not pause execution while dumping the guest

       Sys::Virt::Domain::DUMP_CRASH
           Crash the guest after completing the core dump

       Sys::Virt::Domain::DUMP_BYPASS_CACHE
           Do not use OS I/O cache when writing core dump

       Sys::Virt::Domain::DUMP_RESET
           Reset the virtual machine after finishing the dump

AUTHORS

       Daniel P. Berrange <berrange@redhat.com>

COPYRIGHT

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

LICENSE

       This program is free software; you can redistribute it and/or modify it under the terms of
       either the GNU General Public License as published by the Free Software Foundation (either
       version 2 of the License, or at your option any later version), or, the Artistic License,
       as specified in the Perl README file.

SEE ALSO

       Sys::Virt, Sys::Virt::Error, "http://libvirt.org"