diff options
author | Richard W.M. Jones <rjones@redhat.com> | 2012-03-14 23:06:44 +0000 |
---|---|---|
committer | Richard W.M. Jones <rjones@redhat.com> | 2012-03-14 23:13:41 +0000 |
commit | 2bc922dd8e12bcf05e0aeef8a8b60b6aab9ee915 (patch) | |
tree | 217b88765b04a26ce1506f58ecd6709d383db704 /inspector | |
parent | c23f3b8e527bde9a83dd7ae24273db6da87a7268 (diff) | |
download | libguestfs-2bc922dd8e12bcf05e0aeef8a8b60b6aab9ee915.tar.gz libguestfs-2bc922dd8e12bcf05e0aeef8a8b60b6aab9ee915.tar.xz libguestfs-2bc922dd8e12bcf05e0aeef8a8b60b6aab9ee915.zip |
inspector: Update man page to describe how to access inspection info from other languages and guestfish.
Diffstat (limited to 'inspector')
-rwxr-xr-x | inspector/virt-inspector.pod | 118 |
1 files changed, 112 insertions, 6 deletions
diff --git a/inspector/virt-inspector.pod b/inspector/virt-inspector.pod index 0e8d2939..b2dfdeec 100755 --- a/inspector/virt-inspector.pod +++ b/inspector/virt-inspector.pod @@ -49,8 +49,7 @@ All of the information available from virt-inspector is also available through the core libguestfs inspection API (see L<guestfs(3)/INSPECTION>). The same information can also be fetched using guestfish or via libguestfs bindings in many programming -languages -(see L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES>). +languages (see L</GETTING INSPECTION DATA FROM THE LIBGUESTFS API>). =head1 OPTIONS @@ -371,12 +370,119 @@ have meaning to the shell such as C<#> and space. You may need to quote or escape these characters on the command line. See the shell manual page L<sh(1)> for details. +=head1 GETTING INSPECTION DATA FROM THE LIBGUESTFS API + +In early versions of libguestfs, virt-inspector was a large Perl +script that contained many heuristics for inspecting guests. This had +several problems: in order to do inspection from other tools (like +guestfish) we had to call out to this Perl script; and it privileged +Perl over other languages that libguestfs supports. + +By libguestfs 1.8 we had rewritten the Perl code in C, and +incorporated it all into the core libguestfs API (L<guestfs(3)>). Now +virt-inspector is simply a thin C program over the core C API. All of +the inspection information is available from all programming languages +that libguestfs supports, and from guestfish. + +For a description of the C inspection API, read +L<guestfs(3)/INSPECTION>. + +For example code using the C inspection API, look for C<inspect_vm.c> +which ships with libguestfs. + +C<inspect_vm.c> has also been translated into other languages. For +example, C<inspect_vm.pl> is the Perl translation, and there are other +translations for OCaml, Python, etc. See +L<guestfs(3)/USING LIBGUESTFS WITH OTHER PROGRAMMING LANGUAGES> for a +list of man pages which contain this example code. + +=head2 GETTING INSPECTION DATA FROM GUESTFISH + +If you use the guestfish I<-i> option, then the main C inspection API +L<guestfs(3)/guestfs_inspect_os> is called. This is equivalent to the +guestfish command C<inspect-os>. You can also call this guestfish +command by hand. + +C<inspect-os> performs inspection on the current disk image, returning +the list of operating systems found. Each OS is represented by its +root filesystem device. In the majority of cases, this command prints +nothing (no OSes found), or a single root device, but beware that it +can print multiple lines if there are multiple OSes or if there is an +install CD attached to the guest. + + $ guestfish --ro -a F15x32.img + ><fs> run + ><fs> inspect-os + /dev/vg_f15x32/lv_root + +Using the root device, you can fetch further information about the +guest: + + ><fs> inspect-get-type /dev/vg_f15x32/lv_root + linux + ><fs> inspect-get-distro /dev/vg_f15x32/lv_root + fedora + ><fs> inspect-get-major-version /dev/vg_f15x32/lv_root + 15 + ><fs> inspect-get-product-name /dev/vg_f15x32/lv_root + Fedora release 15 (Lovelock) + +Limitations of guestfish make it hard to assign the root device to a +variable (since guestfish doesn't have variables), so if you want to +do this reproducibly you are better off writing a script using one of +the other languages that the libguestfs API supports. + +To list applications, you have to first mount up the disks: + + ><fs> inspect-get-mountpoints /dev/vg_f15x32/lv_root + /: /dev/vg_f15x32/lv_root + /boot: /dev/vda1 + ><fs> mount-ro /dev/vg_f15x32/lv_root / + ><fs> mount-ro /dev/vda1 /boot + +and then call the inspect-list-applications API: + + ><fs> inspect-list-applications /dev/vg_f15x32/lv_root | head -28 + [0] = { + app_name: ConsoleKit + app_display_name: + app_epoch: 0 + app_version: 0.4.5 + app_release: 1.fc15 + app_install_path: + app_trans_path: + app_publisher: + app_url: + app_source_package: + app_summary: + app_description: + } + [1] = { + app_name: ConsoleKit-libs + app_display_name: + app_epoch: 0 + app_version: 0.4.5 + app_release: 1.fc15 + app_install_path: + app_trans_path: + app_publisher: + app_url: + app_source_package: + app_summary: + app_description: + } + +To display an icon for the guest, note that filesystems must also be +mounted as above. You can then do: + + ><fs> inspect-get-icon /dev/vg_f15x32/lv_root | display - + =head1 OLD VERSIONS OF VIRT-INSPECTOR -Early versions of libguestfs shipped with a different virt-inspector -program written in Perl (the current version is written in C). The -XML output of the Perl virt-inspector was different and it could also -output in other formats like text. +As described above, early versions of libguestfs shipped with a +different virt-inspector program written in Perl (the current version +is written in C). The XML output of the Perl virt-inspector was +different and it could also output in other formats like text. The old virt-inspector is no longer supported or shipped with libguestfs. |