1 # libguestfs generated file
2 # WARNING: THIS FILE IS GENERATED BY 'src/generator.ml'.
3 # ANY CHANGES YOU MAKE TO THIS FILE WILL BE LOST.
5 # Copyright (C) 2009 Red Hat Inc.
7 # This library is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation; either
10 # version 2 of the License, or (at your option) any later version.
12 # This library is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with this library; if not, write to the Free Software
19 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 Sys::Guestfs - Perl bindings for libguestfs
31 my $h = Sys::Guestfs->new ();
32 $h->add_drive ('guest.img');
35 $h->mount ('/dev/sda1', '/');
41 The C<Sys::Guestfs> module provides a Perl XS binding to the
42 libguestfs API for examining and modifying virtual machine
45 Amongst the things this is good for: making batch configuration
46 changes to guests, getting disk used/free statistics (see also:
47 virt-df), migrating between virtualization systems (see also:
48 virt-p2v), performing partial backups, performing partial guest
49 clones, cloning guests and changing registry/UUID/hostname info, and
52 Libguestfs uses Linux kernel and qemu code, and can access any type of
53 guest filesystem that Linux and qemu can, including but not limited
54 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
55 schemes, qcow, qcow2, vmdk.
57 Libguestfs provides ways to enumerate guest storage (eg. partitions,
58 LVs, what filesystem is in each LV, etc.). It can also run commands
59 in the context of the guest. Also you can access filesystems over FTP.
63 All errors turn into calls to C<croak> (see L<Carp(3)>).
77 XSLoader::load ('Sys::Guestfs');
79 =item $h = Sys::Guestfs->new ();
81 Create a new guestfs handle.
87 my $class = ref ($proto) || $proto;
89 my $self = Sys::Guestfs::_create ();
94 =item $h->add_cdrom (filename);
96 This function adds a virtual CD-ROM disk image to the guest.
98 This is equivalent to the qemu parameter C<-cdrom filename>.
100 =item $h->add_drive (filename);
102 This function adds a virtual machine disk image C<filename> to the
103 guest. The first time you call this function, the disk appears as IDE
104 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
107 You don't necessarily need to be root when using libguestfs. However
108 you obviously do need sufficient permissions to access the filename
109 for whatever operations you want to perform (ie. read access if you
110 just want to read the image or write access if you want to modify the
113 This is equivalent to the qemu parameter C<-drive file=filename>.
115 =item $content = $h->cat (path);
117 Return the contents of the file named C<path>.
119 Note that this function cannot correctly handle binary files
120 (specifically, files containing C<\0> character which is treated
121 as end of string). For those you need to use the C<$h-E<gt>read_file>
122 function which has a more complex interface.
124 Because of the message protocol, there is a transfer limit
125 of somewhere between 2MB and 4MB. To transfer large files you should use
128 =item $h->config (qemuparam, qemuvalue);
130 This can be used to add arbitrary qemu command line parameters
131 of the form C<-param value>. Actually it's not quite arbitrary - we
132 prevent you from setting some parameters which would interfere with
133 parameters that we use.
135 The first character of C<param> string must be a C<-> (dash).
137 C<value> can be NULL.
139 =item $autosync = $h->get_autosync ();
141 Get the autosync flag.
143 =item $path = $h->get_path ();
145 Return the current search path.
147 This is always non-NULL. If it wasn't set already, then this will
148 return the default path.
150 =item $verbose = $h->get_verbose ();
152 This returns the verbose messages flag.
154 =item $h->kill_subprocess ();
156 This kills the qemu subprocess. You should never need to call this.
160 Internally libguestfs is implemented by running a virtual machine
163 You should call this after configuring the handle
164 (eg. adding drives) but before performing any actions.
166 =item @devices = $h->list_devices ();
168 List all the block devices.
170 The full block device names are returned, eg. C</dev/sda>
172 =item @partitions = $h->list_partitions ();
174 List all the partitions detected on all block devices.
176 The full partition device names are returned, eg. C</dev/sda1>
178 This does not return logical volumes. For that you will need to
181 =item $listing = $h->ll (directory);
183 List the files in C<directory> (relative to the root directory,
184 there is no cwd) in the format of 'ls -la'.
186 This command is mostly useful for interactive sessions. It
187 is I<not> intended that you try to parse the output string.
189 =item @listing = $h->ls (directory);
191 List the files in C<directory> (relative to the root directory,
192 there is no cwd). The '.' and '..' entries are not returned, but
193 hidden files are shown.
195 This command is mostly useful for interactive sessions. Programs
196 should probably use C<$h-E<gt>readdir> instead.
198 =item @logvols = $h->lvs ();
200 List all the logical volumes detected. This is the equivalent
201 of the L<lvs(8)> command.
203 This returns a list of the logical volume device names
204 (eg. C</dev/VolGroup00/LogVol00>).
206 See also C<$h-E<gt>lvs_full>.
208 =item @logvols = $h->lvs_full ();
210 List all the logical volumes detected. This is the equivalent
211 of the L<lvs(8)> command. The "full" version includes all fields.
213 =item $h->mount (device, mountpoint);
215 Mount a guest disk at a position in the filesystem. Block devices
216 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
217 the guest. If those block devices contain partitions, they will have
218 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
221 The rules are the same as for L<mount(2)>: A filesystem must
222 first be mounted on C</> before others can be mounted. Other
223 filesystems can only be mounted on directories which already
226 The mounted filesystem is writable, if we have sufficient permissions
227 on the underlying device.
229 The filesystem options C<sync> and C<noatime> are set with this
230 call, in order to improve reliability.
232 =item @physvols = $h->pvs ();
234 List all the physical volumes detected. This is the equivalent
235 of the L<pvs(8)> command.
237 This returns a list of just the device names that contain
238 PVs (eg. C</dev/sda2>).
240 See also C<$h-E<gt>pvs_full>.
242 =item @physvols = $h->pvs_full ();
244 List all the physical volumes detected. This is the equivalent
245 of the L<pvs(8)> command. The "full" version includes all fields.
247 =item $h->set_autosync (autosync);
249 If C<autosync> is true, this enables autosync. Libguestfs will make a
250 best effort attempt to run C<$h-E<gt>sync> when the handle is closed
251 (also if the program exits without closing handles).
253 =item $h->set_path (path);
255 Set the path that libguestfs searches for kernel and initrd.img.
257 The default is C<$libdir/guestfs> unless overridden by setting
258 C<LIBGUESTFS_PATH> environment variable.
260 The string C<path> is stashed in the libguestfs handle, so the caller
261 must make sure it remains valid for the lifetime of the handle.
263 Setting C<path> to C<NULL> restores the default path.
265 =item $h->set_verbose (verbose);
267 If C<verbose> is true, this turns on verbose messages (to C<stderr>).
269 Verbose messages are disabled unless the environment variable
270 C<LIBGUESTFS_DEBUG> is defined and set to C<1>.
274 This syncs the disk, so that any writes are flushed through to the
275 underlying disk image.
277 You should always call this if you have modified a disk image, before
280 =item $h->touch (path);
282 Touch acts like the L<touch(1)> command. It can be used to
283 update the timestamps on a file, or, if the file does not exist,
284 to create a new zero-length file.
286 =item @volgroups = $h->vgs ();
288 List all the volumes groups detected. This is the equivalent
289 of the L<vgs(8)> command.
291 This returns a list of just the volume group names that were
292 detected (eg. C<VolGroup00>).
294 See also C<$h-E<gt>vgs_full>.
296 =item @volgroups = $h->vgs_full ();
298 List all the volumes groups detected. This is the equivalent
299 of the L<vgs(8)> command. The "full" version includes all fields.
301 =item $h->wait_ready ();
303 Internally libguestfs is implemented by running a virtual machine
306 You should call this after C<$h-E<gt>launch> to wait for the launch
317 Copyright (C) 2009 Red Hat Inc.
321 Please see the file COPYING.LIB for the full license.
325 L<guestfs(3)>, L<guestfish(1)>.