2 # Copyright (C) 2009 Red Hat Inc.
4 # This library is free software; you can redistribute it and/or
5 # modify it under the terms of the GNU Lesser General Public
6 # License as published by the Free Software Foundation; either
7 # version 2 of the License, or (at your option) any later version.
9 # This library is distributed in the hope that it will be useful,
10 # but WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 # Lesser General Public License for more details.
14 # You should have received a copy of the GNU Lesser General Public
15 # License along with this library; if not, write to the Free Software
16 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
18 package Sys::Guestfs::Lib;
26 eval "use Sys::Virt;";
27 eval "use XML::XPath;";
28 eval "use XML::XPath::XMLParser;";
34 Sys::Guestfs::Lib - Useful functions for using libguestfs from Perl
38 use Sys::Guestfs::Lib qw(#any symbols you want to use);
40 $g = open_guest ($name);
44 C<Sys::Guestfs::Lib> is an extra library of useful functions for using
45 the libguestfs API from Perl. It also provides tighter integration
48 The basic libguestfs API is not covered by this manpage. Please refer
49 instead to L<Sys::Guestfs(3)> and L<guestfs(3)>. The libvirt API is
50 also not covered. For that, see L<Sys::Virt(3)>.
58 use vars qw(@EXPORT_OK @ISA);
61 @EXPORT_OK = qw(open_guest);
65 $g = open_guest ($name);
67 $g = open_guest ($name, rw => 1, ...);
69 $g = open_guest ($name, address => $uri, ...);
71 $g = open_guest ([$img1, $img2, ...], address => $uri, ...);
73 ($g, $conn, $dom) = open_guest ($name);
75 This function opens a libguestfs handle for either the libvirt domain
76 called C<$name>, or the disk image called C<$name>. Any disk images
77 found through libvirt or specified explicitly are attached to the
80 The C<Sys::Guestfs> handle C<$g> is returned, or if there was an error
81 it throws an exception. To catch errors, wrap the call in an eval
84 The first parameter is either a string referring to a libvirt domain
85 or a disk image, or (if a guest has several disk images) an arrayref
86 C<[$img1, $img2, ...]>.
88 The handle is I<read-only> by default. Use the optional parameter
89 C<rw =E<gt> 1> to open a read-write handle. However if you open a
90 read-write handle, this function will refuse to use active libvirt
93 The handle is still in the config state when it is returned, so you
94 have to call C<$g-E<gt>launch ()> and C<$g-E<gt>wait_ready>.
96 The optional C<address> parameter can be added to specify the libvirt
97 URI. In addition, L<Sys::Virt(3)> lists other parameters which are
98 passed through to C<Sys::Virt-E<gt>new> unchanged.
100 The implicit libvirt handle is closed after this function, I<unless>
101 you call the function in C<wantarray> context, in which case the
102 function returns a tuple of: the open libguestfs handle, the open
103 libvirt handle, and the open libvirt domain handle. (This is useful
104 if you want to do other things like pulling the XML description of the
105 guest). Note that if this is a straight disk image, then C<$conn> and
106 C<$dom> will be C<undef>.
108 If the C<Sys::Virt> module is not available, then libvirt is bypassed,
109 and this function can only open disk images.
118 my $readwrite = $params{rw};
121 if (ref ($first) eq "ARRAY") {
123 } elsif (ref ($first) eq "SCALAR") {
126 die "open_guest: first parameter must be a string or an arrayref"
133 die "guest image $_ does not exist or is not readable"
137 die "open_guest: no libvirt support (install Sys::Virt, XML::XPath and XML::XPath::XMLParser)"
138 unless exists $INC{"Sys/Virt.pm"} &&
139 exists $INC{"XML/XPath.pm"} &&
140 exists $INC{"XML/XPath/XMLParser.pm"};
142 die "open_guest: too many domains listed on command line"
145 $conn = Sys::Virt->new (readonly => 1, @_);
146 die "open_guest: cannot connect to libvirt" unless $conn;
148 my @doms = $conn->list_defined_domains ();
149 my $isitinactive = "an inactive libvirt domain";
150 unless ($readwrite) {
151 # In the case where we want read-only access to a domain,
152 # allow the user to specify an active domain too.
153 push @doms, $conn->list_domains ();
154 $isitinactive = "a libvirt domain";
157 if ($_->get_name () eq $images[0]) {
162 die "$images[0] is not the name of $isitinactive\n" unless $dom;
164 # Get the names of the image(s).
165 my $xml = $dom->get_xml_description ();
167 my $p = XML::XPath->new (xml => $xml);
168 my @disks = $p->findnodes ('//devices/disk/source/@dev');
169 @images = map { $_->getData } @disks;
172 # We've now got the list of @images, so feed them to libguestfs.
173 my $g = Sys::Guestfs->new ();
178 $g->add_drive_ro ($_);
182 return wantarray ? ($g, $conn, $dom) : $g
189 Copyright (C) 2009 Red Hat Inc.
193 Please see the file COPYING.LIB for the full license.
197 L<virt-inspector(1)>,
200 L<http://libguestfs.org/>,
202 L<http://libvirt.org/>,