From 6548a876f367427404a0f9ce9a634b01e0ccac78 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Thu, 28 Oct 2010 22:32:50 +0100 Subject: [PATCH] inspector: Introductory documentation for XML format. --- inspector/virt-inspector | 130 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) diff --git a/inspector/virt-inspector b/inspector/virt-inspector index 03b01b3..71a8884 100755 --- a/inspector/virt-inspector +++ b/inspector/virt-inspector @@ -146,6 +146,42 @@ if (@roots == 0) { prog => basename ($0)); } +=head1 XML FORMAT + +The virt-inspector XML is described precisely in a RELAX NG schema +which is supplied with libguestfs. This section is just an overview. + +The top-level element is EoperatingsystemsE, and it contains +one or more EoperatingsystemE elements. You would only see +more than one EoperatingsystemE element if the virtual machine +is multi-boot, which is vanishingly rare in real world VMs. + +=head2 EoperatingsystemE + +In the EoperatingsystemE tag are various optional fields that +describe the operating system, its architecture, the descriptive +"product name" string, the type of OS and so on, as in this example: + + + + /dev/sda2 + windows + i386 + windows + Windows 7 Enterprise + 6 + 1 + /Windows + +These fields are derived from the libguestfs inspection API, and +you can find more details in L. + +The ErootE element is the root filesystem device, but from the +point of view of libguestfs (block devices may have completely +different names inside the VM itself). + +=cut + # Start the XML output. my $xml = new XML::Writer (DATA_MODE => 1, DATA_INDENT => 2); @@ -201,6 +237,27 @@ foreach $root (@roots) { $xml->endTag ("operatingsystems"); $xml->end (); +=head2 EmountpointsE + +Un*x-like guests typically have multiple filesystems which are mounted +at various mountpoints, and these are described in the +EmountpointsE element which looks like this: + + + + ... + + / + /boot + + +As with ErootE, devices are from the point of view of +libguestfs, and may have completely different names inside the guest. +Only mountable filesystems appear in this list, not things like swap +devices. + +=cut + sub output_mountpoints { local $_; @@ -216,6 +273,30 @@ sub output_mountpoints $xml->endTag ("mountpoints"); } +=head2 EfilesystemsE + +EfilesystemsE is like EmountpointsE but covers I +filesystems belonging to the guest, including swap and empty +partitions. (In the rare case of a multi-boot guest, it covers +filesystems belonging to this OS or shared by this OS and other OSes). + +You might see something like this: + + + + ... + + + ext4 + + e6a4db1e-15c2-477b-ac2a-699181c396aa + + +The optional elements within EfilesystemE are the filesystem +type, the label, and the UUID. + +=cut + sub output_filesystems { local $_; @@ -252,6 +333,35 @@ sub output_filesystems $xml->endTag ("filesystems"); } +=head2 EapplicationsE + +The related elements Epackage_formatE, +Epackage_managementE and EapplicationsE describe +applications installed in the virtual machine. At the moment we are +only able to list RPMs installed, but in future we will support other +Linux distros and Windows. + +Epackage_formatE, if present, describes the packaging +system used. Typical values would be C and C. + +Epackage_managementE, if present, describes the package +manager. Typical values include C, C and C + +EapplicationsE lists the packages or applications +installed. At present this simply lists them by name: + + + + ... + + + coreutils + + +In future we will also include the version here. + +=cut + sub output_applications { local $_; @@ -361,6 +471,25 @@ sub canonicalize $_; } +=head1 USING XPATH + +You can use the XPath query language, and/or the xpath tool, in order +to select parts of the XML. + +For example: + + $ virt-inspector Guest | xpath //filesystems + Found 1 nodes: + -- NODE -- + + + ext4 + [etc] + + $ virt-inspector Guest | \ + xpath "string(//filesystem[@dev='/dev/sda1']/type)" + Query didn't return a nodeset. Value: ext4 + =head1 SHELL QUOTING Libvirt guest names can contain arbitrary characters, some of which @@ -375,6 +504,7 @@ L, L, L, L, +L, L. =head1 AUTHORS -- 1.8.3.1