<li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
      

<li><a href="#description">DESCRIPTION</a></li>
        <li><a href="#object_methods">OBJECT METHODS</a></li>
        <ul>

   

    <li><a href="#initialize">initialize</a></li>
          

<li><a href="#load">load</a></li>
               

<li><a href="#capture">capture</a></li>
                

<li><a href="#node_status">node_status</a></li>
                <li><a href="#does_image_exist">does_image_exist</a></li>
         

<li><a href="#get_image_size">get_image_size</a></li>
      

<li><a href="#get_image_repository_search_paths">get_image_repository_search_paths</a></li>
                <li><a href="#power_status">power_status</a></li>
                <li><a href="#power_on">power_on</a></li>
                <li><a href="#power_off">power_off</a></li>
                <li><a href="#power_reset">power_reset</a></li>
                <li><a href="#post_maintenance_action">post_maintenance_action</a></li>
        </ul>

        <li><a href="#private_methods">PRIVATE METHODS</a></li>
        <ul>

                <li><a href="#driver">driver</a></li>
                <li><a href="#get_driver_name">get_driver_name</a></li>
                <li><a href="#get_domain_name">get_domain_name</a></li>
                <li><a href="#get_domain_file_base_name">get_domain_file_base_name</a></li>
                <li><a href="#get_domain_xml_directory_path">get_domain_xml_directory_path</a></li>
                <li><a href="#get_domain_xml_file_path">get_domain_xml_file_path</a></li>
                <li><a href="#get_master_image_directory_path">get_master_image_directory_path</a></li>
                <li><a href="#get_master_image_file_path">get_master_image_file_path</a></li>
                <li><a href="#get_copy_on_write_file_path">get_copy_on_write_file_path</a></li>
                <li><a href="#delete_existing_domains">delete_existing_domains</a></li>
                <li><a href="#delete_domain">delete_domain</a></li>
                <li><a href="#generate_domain_xml">generate_domain_xml</a></li>
                <li><a href="#get_domain_info">get_domain_info</a></li>
                <li><a href="#get_domain_xml">get_domain_xml</a></li>
                <li><a href="#domain_exists">domain_exists</a></li>
                <li><a href="#get_snapshot_info">get_snapshot_info</a></li>
                <li><a href="#create_snapshot">create_snapshot</a></li>
                <li><a href="#delete_snapshot">delete_snapshot</a></li>
                <li><a href="#get_image_size_bytes">get_image_size_bytes</a></li>
                <li><a href="#find_repository_image_file_paths">find_repository_image_file_paths</a></li>
        </ul>

        <li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>VCL::Provisioning::libvirt - VCL provisioning module to support the libvirt toolkit</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
 use VCL::Module::Provisioning::libvirt;
 my $provisioner = (VCL::Module::Provisioning::libvirt)-&gt;new({data_structure =&gt; $self-&gt;data});</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<pre>
 Provides support allowing VCL to provisioning resources supported by the
 libvirt toolkit.
 <a href="http://libvirt.org">http://libvirt.org</a></pre>
<p>
</p>
<hr />
<h1><a name="object_methods">OBJECT METHODS</a></h1>
<p>
</p>
<h2><a name="initialize">initialize</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Enumerates the libvirt driver modules directory:
               lib/VCL/Module/Provisioning/libvirt/

               Attempts to create and initialize an object for each hypervisor
               driver module found in this directory. The first driver module
               object successfully initialized is used. This object is made
               accessible within this module via $self-&gt;driver. This allows
               libvirt support driver modules to be added without having to
               alter the code in libvirt.pm.</pre>
<p>
</p>
<h2><a name="load">load</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Loads the requested image on the domain:</pre>
<ul>
<li>
<p>Destroy and delete any domains have already been defined for the computer
assigned to this reservation.</p>
</li>
<li>
<p>Construct the default libvirt XML definition for the domain.</p>
</li>
<li>
<p>Call the libvirt driver module's 'extend_domain_xml' subroutine if it is
implemented. Pass the default domain XML definition hash reference as an
argument. The 'extend_domain_xml' subroutine may add or modify XML values. This
allows the driver module to customize the XML specific to that driver.</p>
</li>
<li>
<p>Call the driver module's 'pre_define' subroutine if it is implemented. This
subroutine completes any necessary tasks which are specific to the driver being
used prior to defining the domain.</p>
</li>
<li>
<p>Create a text file on the node containing the domain XML definition.</p>
</li>
<li>
<p>Define the domain on the node by calling 'virsh define &lt;XML file&gt;'.</p>
</li>
<li>
<p>Power on the domain.</p>
</li>
<li>
<p>Call the domain guest OS module's 'post_load' subroutine if implemented.</p>
</li>
</ul>
<p>
</p>
<h2><a name="capture">capture</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Captures the image currently loaded on the computer.</pre>
<p>
</p>
<h2><a name="node_status">node_status</a></h2>
<pre>
 Parameters  : $computer_id (optional)
 Returns     : string
 Description : Checks the status of the computer in order to determine if the
               computer is ready to be reserved or needs to be reloaded. A
               string is returned depending on the status of the computer:
               'READY':
                  * Computer is ready to be reserved
                  * It is accessible
                  * It is loaded with the correct image
                  * OS module's post-load tasks have run
               'POST_LOAD':
                  * Computer is loaded with the correct image
                  * OS module's post-load tasks have not run
               'RELOAD':
                  * Computer is not accessible or not loaded with the correct
                    image</pre>
<p>
</p>
<h2><a name="does_image_exist">does_image_exist</a></h2>
<pre>
 Parameters  : $image_name (optional)
 Returns     : array (boolean)
 Description : Checks if the requested image exists on the node or in the
               repository. If the image exists, an array containing the image
               file paths is returned. A boolean evaluation can be done on the
               return value to simply determine if an image exists.</pre>
<p>
</p>
<h2><a name="get_image_size">get_image_size</a></h2>
<pre>
 Parameters  : $image_name (optional)
 Returns     : integer
 Description : Returns the size of the image in megabytes.</pre>
<p>
</p>
<h2><a name="get_image_repository_search_paths">get_image_repository_search_paths</a></h2>
<pre>
 Parameters  : $management_node_identifier (optional)
 Returns     : array
 Description : Returns an array containing paths on the management node where an
               image may reside. The paths may contain wildcards. This is used
               to attempt to locate an image on another managment node in order
               to retrieve it.</pre>
<p>
</p>
<h2><a name="power_status">power_status</a></h2>
<pre>
 Parameters  : $domain_name (optional)
 Returns     : string
 Description : Determines the power state of the domain. A string is returned
               containing one of the following values:
                  * 'on'
                  * 'off'
                  * 'suspended'</pre>
<p>
</p>
<h2><a name="power_on">power_on</a></h2>
<pre>
 Parameters  : $domain_name (optional)
 Returns     : boolean
 Description : Powers on the domain. Returns true if the domain was successfully
               powered on or was already powered on.</pre>
<p>
</p>
<h2><a name="power_off">power_off</a></h2>
<pre>
 Parameters  : $domain_name
 Returns     : boolean
 Description : Powers off the domain. Returns true if the domain was
               successfully powered off or was already powered off.</pre>
<p>
</p>
<h2><a name="power_reset">power_reset</a></h2>
<pre>
 Parameters  : $domain_name (optional)
 Returns     : boolean
 Description : Resets the power of the domain by powering it off and then back
               on.</pre>
<p>
</p>
<h2><a name="post_maintenance_action">post_maintenance_action</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Performs tasks to the computer after it has been put into
               maintenance mode.</pre>
<p>
</p>
<hr />
<h1><a name="private_methods">PRIVATE METHODS</a></h1>
<p>
</p>
<h2><a name="driver">driver</a></h2>
<pre>
 Parameters  : none
 Returns     : Libvirt driver object
 Description : Returns a reference to the libvirt driver object which is created
               when this libvirt.pm module is initialized.</pre>
<p>
</p>
<h2><a name="get_driver_name">get_driver_name</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the name of the libvirt driver being used to control the
               node. Example: 'KVM'</pre>
<p>
</p>
<h2><a name="get_domain_name">get_domain_name</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the name of the domain. This name is passed to various
               virsh commands. It is also the name displayed in virt-manager.
               Example: 'vclv99-197:vmwarewin7-Windows764bit1846-v3'</pre>
<p>
</p>
<h2><a name="get_domain_file_base_name">get_domain_file_base_name</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the base name for files created for the current
               reservation. A file extension is not included. This file name is
               used for the domain's XML definition file and it's copy on write
               image file. Example: 'vclv99-37_234-v23'</pre>
<p>
</p>
<h2><a name="get_domain_xml_directory_path">get_domain_xml_directory_path</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the directory path on the node where domain definition
               XML files reside. The directory used is: '/tmp/vcl'</pre>
<p>
</p>
<h2><a name="get_domain_xml_file_path">get_domain_xml_file_path</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the domain XML definition file path on the node.
               Example: '/tmp/vcl/vclv99-37_234-v23.xml'</pre>
<p>
</p>
<h2><a name="get_master_image_directory_path">get_master_image_directory_path</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the directory path on the node where the master image
               files reside. Example: '/var/lib/libvirt/images'</pre>
<p>
</p>
<h2><a name="get_master_image_file_path">get_master_image_file_path</a></h2>
<pre>
 Parameters  : $image_name (optional)
 Returns     : string
 Description : Returns the path on the node where the master image file resides.
               Example:
               '/var/lib/libvirt/images/vmwarelinux-RHEL54Small2251-v1.qcow2'</pre>
<p>
</p>
<h2><a name="get_copy_on_write_file_path">get_copy_on_write_file_path</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns the path on the node where the copy on write file for the
               domain resides. Example:
               '/var/lib/libvirt/images/vclv99-197_2251-v1.qcow2'</pre>
<p>
</p>
<h2><a name="delete_existing_domains">delete_existing_domains</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Deletes existing domains which were previously created for the
               computer assigned to the current reservation.</pre>
<p>
</p>
<h2><a name="delete_domain">delete_domain</a></h2>
<pre>
 Parameters  : $domain_name
 Returns     : boolean
 Description : Deletes a domain from the node.</pre>
<p>
</p>
<h2><a name="generate_domain_xml">generate_domain_xml</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Generates a string containing the XML definition for the domain.

</pre>
<p>
</p>
<h2><a name="get_domain_info">get_domain_info</a></h2>
<pre>
 Parameters  : none
 Returns     : hash reference
 Description : Retrieves information about all of the domains defined on the
               node and constructs a hash containing the information. Example:
                  &quot;vclv99-197:vmwarewin7-Windows764bit1846-v3&quot; =&gt; {
                     &quot;id&quot; =&gt; 135,
                     &quot;state&quot; =&gt; &quot;paused&quot;
                  },
                  &quot;vclv99-37:vmwarewinxp-base234-v23&quot; =&gt; {
                     &quot;state&quot; =&gt; &quot;shut off&quot;
                  }

</pre>
<p>
</p>
<h2><a name="get_domain_xml">get_domain_xml</a></h2>
<pre>
 Parameters  : $domain_name
 Returns     : hash reference
 Description : Retrieves the XML definition of a domain already defined on the
               node. Generates a hash using XML::Simple::XMLin.

</pre>
<p>
</p>
<h2><a name="domain_exists">domain_exists</a></h2>
<pre>
 Parameters  : $domain_name
 Returns     : boolean
 Description : Determines if the domain is defined on the node.

</pre>
<p>
</p>
<h2><a name="get_snapshot_info">get_snapshot_info</a></h2>
<pre>
 Parameters  : $domain_name
 Returns     : hash reference
 Description : Retrieves snapshot information for the domain specified by the
               argument and constructs a hash. The hash keys are the snapshot
               names. Example:
                  &quot;VCL snapshot&quot; =&gt; {
                     &quot;creation_time&quot; =&gt; &quot;2011-12-07 16:05:50 -0500&quot;,
                     &quot;state&quot; =&gt; &quot;shutoff&quot;
                  }

</pre>
<p>
</p>
<h2><a name="create_snapshot">create_snapshot</a></h2>
<pre>
 Parameters  : $domain_name, $description
 Returns     : boolean
 Description : Creates a snapshot of the domain specified by the argument.

</pre>
<p>
</p>
<h2><a name="delete_snapshot">delete_snapshot</a></h2>
<pre>
 Parameters  : $domain_name, $snapshot
 Returns     : boolean
 Description : Deletes a snapshot created of the domain specified by the
               argument.

</pre>
<p>
</p>
<h2><a name="get_image_size_bytes">get_image_size_bytes</a></h2>
<pre>
 Parameters  : $image_name (optional)
 Returns     : integer
 Description : Returns the size of the image in bytes.

</pre>
<p>
</p>
<h2><a name="find_repository_image_file_paths">find_repository_image_file_paths</a></h2>
<pre>
 Parameters  : $image_name (optional)
 Returns     : 

array
 Description : 

Locates 

valid image 

files stored in the image repository.
      

Searches 

for 

all 

files 

beginning 

with the

 image name and then
          

checks 

the 

results to 

remove 

any 

files which should not be
           

included. 

File 

extensions 

which 

are 

excluded:

 vmx, txt, xml
        

       If multiple vmdk files are found it is assumed that the 

image is
 

           one of the split vmdk formats and 

the <image name>.vmdk contains
               the descriptor information. 

This 

file is 

excluded because it
               causes qemu-img to fail.

</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE 

ALSO</a></h1>
<p><a href="http://cwiki.apache.org/VCL/">http://cwiki.apache.org/VCL/</a>

</p>

</body>

</html>

<li><a href="#name">NAME</a></li>
     

 <li><a href="#description">DESCRIPTION</a></li>
        <li><a 

href="#object_methods">OBJECT METHODS</a></li>
        <ul>

          

<li><a href="#initialize">initialize</a></li>
                

<li><a href="#get_domain_type">get_domain_type</a></li>
                <li><a href="#get_disk_driver_name">get_disk_driver_name</a></li>
                

<li><a href="#get_disk_format">get_disk_format</a></li>
                <li><a href="#get_disk_file_extension">get_disk_file_extension</a></li>
       

<li><a href="#pre_define">pre_define</a></li>
        </ul>

       

<li><a href="#private_methods">PRIVATE METHODS</a></li>
        <ul>

      

<li><a href="#get_virtual_disk_file_info">get_virtual_disk_file_info</a></li>
            

<li><a href="#get_virtual_disk_size_bytes">get_virtual_disk_size_bytes</a></li>
                <li><a href="#copy_virtual_disk">copy_virtual_disk</a></li>
       

<li><a href="#create_copy_on_write_image">create_copy_on_write_image</a></li>
               

<li><a href="#update_windows_image">update_windows_image</a></li>
        </ul>

        <li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END 

-->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>VCL::Provisioning::libvirt::KVM - Libvirt hypervisor driver module to allow
support for the KVM hypervisor</p>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<pre>
 This is a driver module to allow the main libvirt.pm provisioning module to
 support KVM hosts. It performs the KVM-specific tasks not handled by libvirt
 itself.</pre>
<p>
</p>
<hr />
<h1><a name="object_methods">OBJECT METHODS</a></h1>
<p>
</p>
<h2><a name="initialize">initialize</a></h2>
<pre>
 Parameters  : none
 Returns     : boolean
 Description : Checks if the node has KVM installed by checking if /usr/bin/qemu
               exists. Returns true if the file exists, 

false otherwise.</pre>
<p>
</p>
<h2><a name="get_domain_type">get_domain_type</a></h2>
<pre>
 Parameters  : 

none
 Returns     : 

string
 Description : 

Returns 'kvm'. This is specified in the domain 

XML 

definition:
               

&lt;domain type='kvm'&gt;</pre>
<pre>

=cut</pre>
<p><table cellspacing="0" cellpadding="0"><tr><td>sub get_domain_type {
<tr><td><td>my $self = shift;
<tr><td><td>unless (ref($self) &amp;&amp; $self-&gt;<code>isa('VCL::Module'))</code> {
<tr><td><td>notify($ERRORS{'CRITICAL'}, 0, ``subroutine was called as a function, it must be called as a class method'');
<tr><td><td>return;
<tr><td><td>}
</table></p>
<pre>

        return 'kvm';
}</pre>
<p>#/////////////////////////////////////////////////////////////////////////////</p>
<p>
</p>
<h2><a name="get_disk_driver_name">get_disk_driver_name</a></h2>
<pre>
 Parameters  : none
 Returns     : 

string
 Description : 

Returns 'qemu'. The disk driver name is specified in the domain
             

XML 

definition:
 

     <domain ...>
         

  <devices>
   

      <disk ...>
        

&lt;driver name='qemu' ...&gt;</pre>
<p>
</p>
<h2><a name="get_disk_format">get_disk_format</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns 'qcow2'. The 

disk format is 

specified in the domain XML
               definition:
      

<domain ...>
                    

 <devices>
                        

<disk ...>
                         

 &lt;driver type='qcow2' ...&gt;</pre>
<p>
</p>
<h2><a name="get_disk_file_extension">get_disk_file_extension</a></h2>
<pre>
 Parameters  : none
 Returns     : string
 Description : Returns 'qcow2'. 

This 

is 

used 

by 

libvirt.pm 

as 

the 

file 

extension
               

of 

the 

virtual 

disk 

file paths.</pre>
<p>
</p>
<h2><a name="pre_define">pre_define</a></h2>
<pre>
 Parameters  : none

 Returns     : boolean
 Description : Performs the KVM-specific steps prior to defining a domain:
    

* 

Checks 

if 

the 

master 

image 

file 

exists on the 

node, If it does
                 not exist, 

attempts 

to 

copy image from repository to the node
      

* 

Creates 

a 

copy 

on 

write 

image which will be used by 

the domain
      

           being loaded</pre>
<p>
</p>
<hr />
<h1><a 

name="private_methods">PRIVATE METHODS</a></h1>
<p>
</p>
<h2><a name="get_virtual_disk_file_info">get_virtual_disk_file_info</a></h2>
<pre>
 Parameters  : $virtual_disk_file_path
 Returns     : hash 

reference
 Description : 

Calls 'qemu-img info' to retrieve the 

virtual 

disk 

information.
 

         Builds a hash based on the 

output. Example:
                  "backing_file" => "/var/lib/libvirt/images/vmwarewinxp-base234-v23.qcow2 (actual 

path: /var/lib/libvirt/images/

vmwarewinxp-

base234-

v23.qcow2

)",
           

 "backing_file_actual_path" => "/var/lib/libvirt/images/vmwarewinxp-base234-v23.qcow2",
               

 "cluster_size" => 65536,
         

 "disk_size" => "423M",
      

 "disk_size_bytes" => 443547648,
        

 "file_format" => "qcow2",
               

 "image" => "/var/lib/libvirt/images/vclv99-37_234-v23.qcow2",
                  

"snapshot" => {
         

         1 => {
          

          "date" => "2011-12-07 14:43:12",
     

"tag" => "snap1",
                      

"vm_clock" => "00:00:00.000",
                      

"vm_size" => 0
                  

}
 

  },
             

 "virtual_size" => "20G (21474836480 bytes)",
         

 &quot;virtual_size_bytes&quot; =&gt; &quot;21474836480&quot;</pre>
<p>
</p>
<h2><a name="get_virtual_disk_size_bytes">get_virtual_disk_size_bytes</a></h2>
<pre>
 Parameters  : 

$image_name (optional)
 Returns     : 

integer
 Description : 

Returns the size of the virtual disk in bytes.</pre>
<p>
</p>
<h2><a name="copy_virtual_disk">copy_virtual_disk</a></h2>
<pre>
 Parameters  : $source_file_paths, $destination_file_path, $disk_format (optional)
 Returns     : boolean
 Description : Calls qemu-img to copy a virtual disk image. The destination disk
               format can be 

specified 

as 

an argument. If omitted, qcow2 is
               

used.</pre>
<p>
</p>
<h2><a name="create_copy_on_write_image">create_copy_on_write_image</a></h2>
<pre>
 Parameters  : $master_image_file_path, $copy_on_write_file_path
 Returns     : boolean
 Description : Calls qemu-img to create a copy on write virtual disk 

image based
               on the 

master image. The resulting image is written to by the VM
               when it makes changes to its hard disk. Multiple VMs may utilize
               the master image file. Each writes to its own copy on write image
               file. The master image file is not altered.</pre>
<p>
</p>
<h2><a name="update_windows_image">update_windows_image</a></h2>
<pre>
 Parameters  : 

$virtual_disk_file_path
 Returns     : boolean
 Description : Runs virt-win-reg to update the registry of the image specified
               by the $virtual_disk_file_path argument. The virt-win-reg utility
       

is 

provided 

by libguestfs-tools. This subroutine returns true if
         

 virt-win-reg isn't installed.

             

Adds 

registry 

keys 

to 

disable 

VMware 

services. 

If the image is
               

Windows 5.x, registry keys are added to enable the builtin IDE
               drivers. This 

allows 

Windows 

images 

converted 

from 

VMware 

using 

a
 

              SCSI 

virtual 

disk to

 be loaded on KVM.</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><a href="http://cwiki.apache.org/VCL/

">http://cwiki.apache.org/VCL/</a>

</p>

</body>

</html>