perl-libguestfs/Sys::Guestfs::Lib(3pm)

1Sys::Guestfs::Lib(3)  User Contributed Perl Documentation Sys::Guestfs::Lib(3)
2
3
4

NAME

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

SYNOPSIS

9        use Sys::Guestfs::Lib qw(open_guest inspect_all_partitions ...);
10
11        $g = open_guest ($name);
12
13        %fses = inspect_all_partitions ($g, \@partitions);
14
15       (and many more calls - see the rest of this manpage)
16

DESCRIPTION

18       "Sys::Guestfs::Lib" is an extra library of useful functions for using
19       the libguestfs API from Perl.  It also provides tighter integration
20       with libvirt.
21
22       The basic libguestfs API is not covered by this manpage.  Please refer
23       instead to Sys::Guestfs(3) and guestfs(3).  The libvirt API is also not
24       covered.  For that, see Sys::Virt(3).
25

BASIC FUNCTIONS

27   open_guest
28        $g = open_guest ($name);
29
30        $g = open_guest ($name, rw => 1, ...);
31
32        $g = open_guest ($name, address => $uri, ...);
33
34        $g = open_guest ([$img1, $img2, ...], address => $uri, ...);
35
36        ($g, $conn, $dom, @images) = open_guest ($name);
37
38       This function opens a libguestfs handle for either the libvirt domain
39       called $name, or the disk image called $name.  Any disk images found
40       through libvirt or specified explicitly are attached to the libguestfs
41       handle.
42
43       The "Sys::Guestfs" handle $g is returned, or if there was an error it
44       throws an exception.  To catch errors, wrap the call in an eval block.
45
46       The first parameter is either a string referring to a libvirt domain or
47       a disk image, or (if a guest has several disk images) an arrayref
48       "[$img1, $img2, ...]".
49
50       The handle is read-only by default.  Use the optional parameter "rw =>
51       1" to open a read-write handle.  However if you open a read-write
52       handle, this function will refuse to use active libvirt domains.
53
54       The handle is still in the config state when it is returned, so you
55       have to call "$g->launch ()".
56
57       The optional "address" parameter can be added to specify the libvirt
58       URI.
59
60       The implicit libvirt handle is closed after this function, unless you
61       call the function in "wantarray" context, in which case the function
62       returns a tuple of: the open libguestfs handle, the open libvirt
63       handle, and the open libvirt domain handle, and a list of images.
64       (This is useful if you want to do other things like pulling the XML
65       description of the guest).  Note that if this is a straight disk image,
66       then $conn and $dom will be "undef".
67
68       If the "Sys::Virt" module is not available, then libvirt is bypassed,
69       and this function can only open disk images.
70
71       The optional "interface" parameter can be used to open devices with
72       "add_drive{,_ro}_with_if".  See "guestfs_add_drive_with_if" in
73       Sys::Guestfs for more details.
74
75   feature_available
76        $bool = feature_available ($g, $feature [, $feature ...]);
77
78       This function is a useful wrapper around the basic "$g->available"
79       call.
80
81       "$g->available" tests for availability of a list of features and dies
82       with an error if any is not available.
83
84       This call tests for the list of features and returns true if all are
85       available, or false otherwise.
86
87       For a list of features you can test for, see "AVAILABILITY" in
88       guestfs(3).
89
90   get_partitions
91        @partitions = get_partitions ($g);
92
93       This function takes an open libguestfs handle $g and returns all
94       partitions and logical volumes found on it.
95
96       What is returned is everything that could contain a filesystem (or
97       swap).  Physical volumes are not normally included from the list except
98       if they contain a filesystem directly.  Nor are devices which are
99       partitioned (eg. "/dev/sda" would not be returned if "/dev/sda1"
100       exists).
101
102   resolve_windows_path
103        $path = resolve_windows_path ($g, $path);
104
105        $path = resolve_windows_path ($g, "/windows/system");
106          ==> "/WINDOWS/System"
107              or undef if no path exists
108
109       This function, which is specific to FAT/NTFS filesystems (ie.  Windows
110       guests), lets you look up a case insensitive $path in the filesystem
111       and returns the true, case sensitive path as required by the underlying
112       kernel or NTFS-3g driver.
113
114       If $path does not exist then this function returns "undef".
115
116       The $path parameter must begin with "/" character and be separated by
117       "/" characters.  Do not use "\", drive names, etc.
118
119   file_architecture
120       Deprecated function.  Replace any calls to this function with:
121
122        $g->file_architecture ($path);
123

OPERATING SYSTEM INSPECTION FUNCTIONS

125       The functions in this section can be used to inspect the operating
126       system(s) available inside a virtual machine image.  For example, you
127       can find out if the VM is Linux or Windows, how the partitions are
128       meant to be mounted, and what applications are installed.
129
130       If you just want a simple command-line interface to this functionality,
131       use the virt-inspector(1) tool.  The documentation below covers the
132       case where you want to access this functionality from a Perl program.
133
134       Once you have the list of partitions (from "get_partitions") there are
135       several steps involved:
136
137       1.  Look at each partition separately and find out what is on it.
138
139           The information you get back includes whether the partition
140           contains a filesystem or swapspace, what sort of filesystem (eg.
141           ext3, ntfs), and a first pass guess at the content of the
142           filesystem (eg. Linux boot, Windows root).
143
144           The result of this step is a %fs hash of information, one hash for
145           each partition.
146
147           See: "inspect_partition", "inspect_all_partitions"
148
149       2.  Work out the relationship between partitions.
150
151           In this step we work out how partitions are related to each other.
152           In the case of a single-boot VM, we work out how the partitions are
153           mounted in respect of each other (eg. "/dev/sda1" is mounted as
154           "/boot").  In the case of a multi-boot VM where there are several
155           roots, we may identify several operating system roots, and
156           mountpoints can even be shared.
157
158           The result of this step is a single hash called %oses which is
159           described in more detail below, but at the top level looks like:
160
161            %oses = {
162              '/dev/VG/Root1' => \%os1,
163              '/dev/VG/Root2' => \%os2,
164            }
165
166            %os1 = {
167              os => 'linux',
168              mounts => {
169                '/' => '/dev/VG/Root1',
170                '/boot' => '/dev/sda1',
171              },
172              ...
173            }
174
175           (example shows a multi-boot VM containing two root partitions).
176
177           See: "inspect_operating_systems"
178
179       3.  Mount up the disks.
180
181           Previous to this point we've essentially been looking at each
182           partition in isolation.  Now we construct a true guest filesystem
183           by mounting up all of the disks.  Only once everything is mounted
184           up can we run commands in the OS context to do more detailed
185           inspection.
186
187           See: "mount_operating_system"
188
189       4.  Check for kernels and applications.
190
191           This step now does more detailed inspection, where we can look for
192           kernels, applications and more installed in the guest.
193
194           The result of this is an enhanced %os hash.
195
196           See: "inspect_in_detail"
197
198       5.  Generate output.
199
200           This library does not contain functions for generating output based
201           on the analysis steps above.  Use a command line tool such as
202           virt-inspector(1) to get useful output.
203
204   inspect_all_partitions
205        %fses = inspect_all_partitions ($g, \@partitions);
206
207       This calls "inspect_partition" for each partition in the list
208       @partitions.
209
210       The result is a hash which maps partition name to "\%fs" hashref.
211
212       The contents of the %fs hash is explained below.
213
214   inspect_partition
215        \%fs = inspect_partition ($g, $partition);
216
217       This function inspects the device named $partition in isolation and
218       tries to determine what it is.  It returns information such as whether
219       the partition is formatted, and with what, whether it is mountable, and
220       what it appears to contain (eg. a Windows root, or a Linux /usr).
221
222       If the Perl module Win::Hivex(3) is installed, then additional
223       information is made available for Windows guests, if we can locate and
224       read their registries.
225
226       The returned value is a hashref "\%fs" which may contain the following
227       top-level keys (any key can be missing):
228
229       fstype
230           Filesystem type, eg. "ext2" or "ntfs"
231
232       fsos
233           Apparent filesystem OS, eg. "linux" or "windows"
234
235       is_swap
236           If set, the partition is a swap partition.
237
238       uuid
239           Filesystem UUID.
240
241       label
242           Filesystem label.
243
244       is_mountable
245           If set, the partition could be mounted by libguestfs.
246
247       content
248           Filesystem content, if we could determine it.  One of: "linux-
249           grub", "linux-root", "linux-usrlocal", "linux-usr", "windows-root".
250
251       osdistro
252           (For Linux root partitions only).  Operating system distribution.
253           One of: "fedora", "rhel", "centos", "scientific", "debian".
254
255       package_format
256           (For Linux root partitions only) The package format used by the
257           guest distribution. One of: "rpm", "deb".
258
259       package_management
260           (For Linux root partitions only) The package management tool used
261           by the guest distribution. One of: "rhn", "yum", "apt".
262
263       os_major_version
264           (For root partitions only).  Operating system major version number.
265
266       os_minor_version
267           (For root partitions only).  Operating system minor version number.
268
269       fstab
270           (For Linux root partitions only).  The contents of the "/etc/fstab"
271           file.
272
273       boot_ini
274           (For Windows root partitions only).  The contents of the
275           "/boot.ini" (NTLDR) file.
276
277       registry
278           The value is an arrayref, which is a list of Windows registry file
279           contents, in Windows ".REG" format.
280
281   inspect_operating_systems
282        \%oses = inspect_operating_systems ($g, \%fses);
283
284       This function works out how partitions are related to each other.  In
285       the case of a single-boot VM, we work out how the partitions are
286       mounted in respect of each other (eg. "/dev/sda1" is mounted as
287       "/boot").  In the case of a multi-boot VM where there are several
288       roots, we may identify several operating system roots, and mountpoints
289       can even be shared.
290
291       This function returns a hashref "\%oses" which at the top level looks
292       like:
293
294        %oses = {
295          '/dev/VG/Root' => \%os,
296        }
297
298       There can be multiple roots for a multi-boot VM, but this function will
299       throw an error if no roots (ie. OSes) could be found.
300
301       The "\%os" hash contains the following keys (any can be omitted):
302
303       os  Operating system type, eg. "linux", "windows".
304
305       arch
306           Operating system userspace architecture, eg. "i386", "x86_64".
307
308       distro
309           Operating system distribution, eg. "debian".
310
311       product_name
312           Free text product name.
313
314       major_version
315           Operating system major version, eg. "4".
316
317       minor_version
318           Operating system minor version, eg "3".
319
320       root
321           The value is a reference to the root partition %fs hash.
322
323       root_device
324           The value is the name of the root partition (as a string).
325
326       mounts
327           Mountpoints.  The value is a hashref like this:
328
329            mounts => {
330              '/' => '/dev/VG/Root',
331              '/boot' => '/dev/sda1',
332            }
333
334       filesystems
335           Filesystems (including swap devices and unmounted partitions).  The
336           value is a hashref like this:
337
338            filesystems => {
339              '/dev/sda1' => \%fs,
340              '/dev/VG/Root' => \%fs,
341              '/dev/VG/Swap' => \%fs,
342            }
343
344   mount_operating_system
345        mount_operating_system ($g, \%os, [$ro]);
346
347       This function mounts the operating system described in the %os hash
348       according to the "mounts" table in that hash (see
349       "inspect_operating_systems").
350
351       The partitions are mounted read-only unless the third parameter is
352       specified as zero explicitly.
353
354       To reverse the effect of this call, use the standard libguestfs API
355       call "$g->umount_all ()".
356
357   inspect_in_detail
358        mount_operating_system ($g, \%os);
359        inspect_in_detail ($g, \%os);
360        $g->umount_all ();
361
362       The "inspect_in_detail" function inspects the mounted operating system
363       for installed applications, installed kernels, kernel modules, system
364       architecture, and more.
365
366       It adds extra keys to the existing %os hash reflecting what it finds.
367       These extra keys are:
368
369       apps
370           List of applications.
371
372       boot
373           Boot configurations. A hash containing:
374
375           configs
376               An array of boot configurations. Each array entry is a hash
377               containing:
378
379               initrd
380                   A reference to the expanded initrd structure (see below)
381                   for the initrd used by this boot configuration.
382
383               kernel
384                   A reference to the expanded kernel structure (see below)
385                   for the kernel used by this boot configuration.
386
387               title
388                   The human readable name of the configuration.
389
390               cmdline
391                   The kernel command line.
392
393           default
394               The index of the default configuration in the configs array.
395
396           grub_fs
397               The path of the filesystem containing the grub partition.
398
399       kernels
400           List of kernels.
401
402           This is a hash of kernel version => a hash with the following keys:
403
404           version
405               Kernel version.
406
407           arch
408               Kernel architecture (eg. "x86-64").
409
410           modules
411               List of modules.
412
413           path
414               The path to the kernel's vmlinuz file.
415
416           package
417               If the kernel was installed in a package, the name of that
418               package.
419
420       modprobe_aliases
421           (For Linux VMs).  The contents of the modprobe configuration.
422
423       initrd_modules
424           (For Linux VMs).  The kernel modules installed in the initrd.  The
425           value is a hashref of kernel version to list of modules.
426
427   inspect_linux_kernel
428        my $kernel_hash = inspect_linux_kernel($g, $vmlinuz_path, $package_format);
429
430       inspect_linux_kernel returns a hash describing the target linux kernel.
431       For the contents of the hash, see the kernels structure described under
432       "inspect_in_detail".
433

COPYRIGHT

435       Copyright (C) 2009 Red Hat Inc.
436

LICENSE

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