Linux Certif

Toute la documentation sur la certification Linux LPI

Sys::Guestfs::Lib.3pm

NAME

Sys::Guestfs::Lib - Useful functions for using libguestfs from Perl

SYNOPSIS

  use Sys::Guestfs::Lib qw(open_guest inspect_all_partitions ...);
 
  $g = open_guest ($name);
 
  %fses = inspect_all_partitions ($g, \@partitions);
 
 

(and many more calls - see the rest of this manpage)

DESCRIPTION

"Sys::Guestfs::Lib" is an extra library of useful functions for using the libguestfs API from Perl. It also provides tighter integration with libvirt.

The basic libguestfs API is not covered by this manpage. Please refer instead to Sys::Guestfs(3) and guestfs(3). The libvirt API is also not covered. For that, see Sys::Virt(3).

BASIC FUNCTIONS

open_guest

  $g = open_guest ($name);
 
  $g = open_guest ($name, rw => 1, ...);
 
  $g = open_guest ($name, address => $uri, ...);
 
  $g = open_guest ([$img1, $img2, ...], address => $uri, ...);
 
  ($g, $conn, $dom, @images) = open_guest ($name);
 
 

This function opens a libguestfs handle for either the libvirt domain called $name, or the disk image called $name. Any disk images found through libvirt or specified explicitly are attached to the libguestfs handle.

The "Sys::Guestfs" handle $g is returned, or if there was an error it throws an exception. To catch errors, wrap the call in an eval block.

The first parameter is either a string referring to a libvirt domain or a disk image, or (if a guest has several disk images) an arrayref "[$img1, $img2, ...]".

The handle is read-only by default. Use the optional parameter "rw => 1" to open a read-write handle. However if you open a read-write handle, this function will refuse to use active libvirt domains.

The handle is still in the config state when it is returned, so you have to call "$g->launch ()".

The optional "address" parameter can be added to specify the libvirt URI.

The implicit libvirt handle is closed after this function, unless you call the function in "wantarray" context, in which case the function returns a tuple of: the open libguestfs handle, the open libvirt handle, and the open libvirt domain handle, and a list of images. (This is useful if you want to do other things like pulling the XML description of the guest). Note that if this is a straight disk image, then $conn and $dom will be "undef".

If the "Sys::Virt" module is not available, then libvirt is bypassed, and this function can only open disk images.

The optional "interface" parameter can be used to open devices with "add_drive{,_ro}_with_if". See ``guestfs_add_drive_with_if'' in Sys::Guestfs for more details.

feature_available

  $bool = feature_available ($g, $feature [, $feature ...]);
 
 

This function is a useful wrapper around the basic "$g->available" call.

"$g->available" tests for availability of a list of features and dies with an error if any is not available.

This call tests for the list of features and returns true if all are available, or false otherwise.

For a list of features you can test for, see ``AVAILABILITY'' in guestfs(3).

get_partitions

  @partitions = get_partitions ($g);
 
 

This function takes an open libguestfs handle $g and returns all partitions and logical volumes found on it.

What is returned is everything that could contain a filesystem (or swap). Physical volumes are not normally included from the list except if they contain a filesystem directly. Nor are devices which are partitioned (eg. "/dev/sda" would not be returned if "/dev/sda1" exists).

resolve_windows_path

  $path = resolve_windows_path ($g, $path);
 
  $path = resolve_windows_path ($g, "/windows/system");
    ==> "/WINDOWS/System"
        or undef if no path exists
 
 

This function, which is specific to FAT/NTFS filesystems (ie. Windows guests), lets you look up a case insensitive $path in the filesystem and returns the true, case sensitive path as required by the underlying kernel or NTFS-3g driver.

If $path does not exist then this function returns "undef".

The $path parameter must begin with "/" character and be separated by "/" characters. Do not use "\", drive names, etc.

file_architecture

Deprecated function. Replace any calls to this function with:

  $g->file_architecture ($path);
 
 

OPERATING SYSTEM INSPECTION FUNCTIONS

The functions in this section can be used to inspect the operating system(s) available inside a virtual machine image. For example, you can find out if the VM is Linux or Windows, how the partitions are meant to be mounted, and what applications are installed.

If you just want a simple command-line interface to this functionality, use the virt-inspector(1) tool. The documentation below covers the case where you want to access this functionality from a Perl program.

Once you have the list of partitions (from "get_partitions") there are several steps involved:

1.

Look at each partition separately and find out what is on it.

The information you get back includes whether the partition contains a filesystem or swapspace, what sort of filesystem (eg. ext3, ntfs), and a first pass guess at the content of the filesystem (eg. Linux boot, Windows root).

The result of this step is a %fs hash of information, one hash for each partition.

See: "inspect_partition", "inspect_all_partitions"

2.

Work out the relationship between partitions.

In this step we work out how partitions are related to each other. In the case of a single-boot VM, we work out how the partitions are mounted in respect of each other (eg. "/dev/sda1" is mounted as "/boot"). In the case of a multi-boot VM where there are several roots, we may identify several operating system roots, and mountpoints can even be shared.

The result of this step is a single hash called %oses which is described in more detail below, but at the top level looks like:

  %oses = {
    '/dev/VG/Root1' => \%os1,
    '/dev/VG/Root2' => \%os2,
  }
 
  %os1 = {
    os => 'linux',
    mounts => {
      '/' => '/dev/VG/Root1',
      '/boot' => '/dev/sda1',
    },
    ...
  }
 
 

(example shows a multi-boot VM containing two root partitions).

See: "inspect_operating_systems"

3.

Mount up the disks.

Previous to this point we've essentially been looking at each partition in isolation. Now we construct a true guest filesystem by mounting up all of the disks. Only once everything is mounted up can we run commands in the OS context to do more detailed inspection.

See: "mount_operating_system"

4.

Check for kernels and applications.

This step now does more detailed inspection, where we can look for kernels, applications and more installed in the guest.

The result of this is an enhanced %os hash.

See: "inspect_in_detail"

5.

Generate output.

This library does not contain functions for generating output based on the analysis steps above. Use a command line tool such as virt-inspector(1) to get useful output.

inspect_all_partitions

  %fses = inspect_all_partitions ($g, \@partitions);
 
 

This calls "inspect_partition" for each partition in the list @partitions.

The result is a hash which maps partition name to "\%fs" hashref.

The contents of the %fs hash is explained below.

inspect_partition

  \%fs = inspect_partition ($g, $partition);
 
 

This function inspects the device named $partition in isolation and tries to determine what it is. It returns information such as whether the partition is formatted, and with what, whether it is mountable, and what it appears to contain (eg. a Windows root, or a Linux /usr).

If the Perl module Win::Hivex(3) is installed, then additional information is made available for Windows guests, if we can locate and read their registries.

The returned value is a hashref "\%fs" which may contain the following top-level keys (any key can be missing):

fstype

Filesystem type, eg. ``ext2'' or ``ntfs''

fsos

Apparent filesystem OS, eg. ``linux'' or ``windows''

is_swap

If set, the partition is a swap partition.

uuid

Filesystem UUID.

label

Filesystem label.

is_mountable

If set, the partition could be mounted by libguestfs.

content

Filesystem content, if we could determine it. One of: ``linux-grub'', ``linux-root'', ``linux-usrlocal'', ``linux-usr'', ``windows-root''.

osdistro

(For Linux root partitions only). Operating system distribution. One of: ``fedora'', ``rhel'', ``centos'', ``scientific'', ``debian''.

package_format

(For Linux root partitions only) The package format used by the guest distribution. One of: ``rpm'', ``deb''.

package_management

(For Linux root partitions only) The package management tool used by the guest distribution. One of: ``rhn'', ``yum'', ``apt''.

os_major_version

(For root partitions only). Operating system major version number.

os_minor_version

(For root partitions only). Operating system minor version number.

fstab

(For Linux root partitions only). The contents of the "/etc/fstab" file.

boot_ini

(For Windows root partitions only). The contents of the "/boot.ini" (NTLDR) file.

registry

The value is an arrayref, which is a list of Windows registry file contents, in Windows ".REG" format.

inspect_operating_systems

  \%oses = inspect_operating_systems ($g, \%fses);
 
 

This function works out how partitions are related to each other. In the case of a single-boot VM, we work out how the partitions are mounted in respect of each other (eg. "/dev/sda1" is mounted as "/boot"). In the case of a multi-boot VM where there are several roots, we may identify several operating system roots, and mountpoints can even be shared.

This function returns a hashref "\%oses" which at the top level looks like:

  %oses = {
    '/dev/VG/Root' => \%os,
  }
 
 

There can be multiple roots for a multi-boot VM, but this function will throw an error if no roots (ie. OSes) could be found.

The "\%os" hash contains the following keys (any can be omitted):

os

Operating system type, eg. ``linux'', ``windows''.

arch

Operating system userspace architecture, eg. ``i386'', ``x86_64''.

distro

Operating system distribution, eg. ``debian''.

product_name

Free text product name.

major_version

Operating system major version, eg. ``4''.

minor_version

Operating system minor version, eg ``3''.

root

The value is a reference to the root partition %fs hash.

root_device

The value is the name of the root partition (as a string).

mounts

Mountpoints. The value is a hashref like this:

  mounts => {
    '/' => '/dev/VG/Root',
    '/boot' => '/dev/sda1',
  }
 
 

filesystems

Filesystems (including swap devices and unmounted partitions). The value is a hashref like this:

  filesystems => {
    '/dev/sda1' => \%fs,
    '/dev/VG/Root' => \%fs,
    '/dev/VG/Swap' => \%fs,
  }
 
 

mount_operating_system

  mount_operating_system ($g, \%os, [$ro]);
 
 

This function mounts the operating system described in the %os hash according to the "mounts" table in that hash (see "inspect_operating_systems").

The partitions are mounted read-only unless the third parameter is specified as zero explicitly.

To reverse the effect of this call, use the standard libguestfs API call "$g->umount_all ()".

inspect_in_detail

  mount_operating_system ($g, \%os);
  inspect_in_detail ($g, \%os);
  $g->umount_all ();
 
 

The "inspect_in_detail" function inspects the mounted operating system for installed applications, installed kernels, kernel modules, system architecture, and more.

It adds extra keys to the existing %os hash reflecting what it finds. These extra keys are:

apps

List of applications.

boot

Boot configurations. A hash containing:

configs

An array of boot configurations. Each array entry is a hash containing:

initrd

A reference to the expanded initrd structure (see below) for the initrd used by this boot configuration.

kernel

A reference to the expanded kernel structure (see below) for the kernel used by this boot configuration.

title

The human readable name of the configuration.

cmdline

The kernel command line.

default

The index of the default configuration in the configs array.

grub_fs

The path of the filesystem containing the grub partition.

kernels

List of kernels.

This is a hash of kernel version => a hash with the following keys:

version

Kernel version.

arch

Kernel architecture (eg. "x86-64").

modules

List of modules.

path

The path to the kernel's vmlinuz file.

package

If the kernel was installed in a package, the name of that package.

modprobe_aliases

(For Linux VMs). The contents of the modprobe configuration.

initrd_modules

(For Linux VMs). The kernel modules installed in the initrd. The value is a hashref of kernel version to list of modules.

inspect_linux_kernel

  my $kernel_hash = inspect_linux_kernel($g, $vmlinuz_path, $package_format);
 
 

inspect_linux_kernel returns a hash describing the target linux kernel. For the contents of the hash, see the kernels structure described under ``inspect_in_detail''.

COPYRIGHT

Copyright (C) 2009 Red Hat Inc.

LICENSE

Please see the file COPYING.LIB for the full license.

SEE ALSO

virt-inspector(1), Sys::Guestfs(3), guestfs(3), <http://libguestfs.org/>, Sys::Virt(3), <http://libvirt.org/>, guestfish(1).