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_drive ($filename);
96 =item $h->add_cdrom ($filename);
98 This function adds a virtual machine disk image C<filename> to the
99 guest. The first time you call this function, the disk appears as IDE
100 disk 0 (C</dev/sda>) in the guest, the second time as C</dev/sdb>, and
103 You don't necessarily need to be root when using libguestfs. However
104 you obviously do need sufficient permissions to access the filename
105 for whatever operations you want to perform (ie. read access if you
106 just want to read the image or write access if you want to modify the
109 The C<add_cdrom> variation adds a CD-ROM device.
111 =item $h->config ($param, $value);
113 =item $h->config ($param);
115 Use this to add arbitrary parameters to the C<qemu> command line.
120 =item $h->wait_ready ();
122 Internally libguestfs is implemented by running a virtual machine
123 using L<qemu(1)>. These calls are necessary in order to boot the
126 You should call these two functions after configuring the handle
127 (eg. adding drives) but before performing any actions.
129 =item $h->set_path ($path);
131 =item $path = $h->get_path ();
133 See the discussion of C<PATH> in the L<guestfs(3)>
136 =item $h->set_autosync ($autosync);
138 =item $autosync = $h->get_autosync ();
140 See the discussion of I<AUTOSYNC> in the L<guestfs(3)>
143 =item $h->set_verbose ($verbose);
145 =item $verbose = $h->get_verbose ();
147 This sets or gets the verbose messages flag. Verbose
148 messages are sent to C<stderr>.
150 =item $content = $h->cat (path);
152 Return the contents of the file named C<path>.
154 Note that this function cannot correctly handle binary files
155 (specifically, files containing C<\0> character which is treated
156 as end of string). For those you need to use the C<$h-E<gt>read_file>
157 function which has a more complex interface.
159 Because of the message protocol, there is a transfer limit
160 of somewhere between 2MB and 4MB. To transfer large files you should use
163 =item @devices = $h->list_devices ();
165 List all the block devices.
167 The full block device names are returned, eg. C</dev/sda>
169 =item @partitions = $h->list_partitions ();
171 List all the partitions detected on all block devices.
173 The full partition device names are returned, eg. C</dev/sda1>
175 This does not return logical volumes. For that you will need to
178 =item $listing = $h->ll (directory);
180 List the files in C<directory> (relative to the root directory,
181 there is no cwd) in the format of 'ls -la'.
183 This command is mostly useful for interactive sessions. It
184 is I<not> intended that you try to parse the output string.
186 =item @listing = $h->ls (directory);
188 List the files in C<directory> (relative to the root directory,
189 there is no cwd). The '.' and '..' entries are not returned, but
190 hidden files are shown.
192 This command is mostly useful for interactive sessions. Programs
193 should probably use C<$h-E<gt>readdir> instead.
195 =item @logvols = $h->lvs ();
197 List all the logical volumes detected. This is the equivalent
198 of the L<lvs(8)> command.
200 This returns a list of the logical volume device names
201 (eg. C</dev/VolGroup00/LogVol00>).
203 See also C<$h-E<gt>lvs_full>.
205 =item @logvols = $h->lvs_full ();
207 List all the logical volumes detected. This is the equivalent
208 of the L<lvs(8)> command. The "full" version includes all fields.
210 =item $h->mount (device, mountpoint);
212 Mount a guest disk at a position in the filesystem. Block devices
213 are named C</dev/sda>, C</dev/sdb> and so on, as they were added to
214 the guest. If those block devices contain partitions, they will have
215 the usual names (eg. C</dev/sda1>). Also LVM C</dev/VG/LV>-style
218 The rules are the same as for L<mount(2)>: A filesystem must
219 first be mounted on C</> before others can be mounted. Other
220 filesystems can only be mounted on directories which already
223 The mounted filesystem is writable, if we have sufficient permissions
224 on the underlying device.
226 The filesystem options C<sync> and C<noatime> are set with this
227 call, in order to improve reliability.
229 =item @physvols = $h->pvs ();
231 List all the physical volumes detected. This is the equivalent
232 of the L<pvs(8)> command.
234 This returns a list of just the device names that contain
235 PVs (eg. C</dev/sda2>).
237 See also C<$h-E<gt>pvs_full>.
239 =item @physvols = $h->pvs_full ();
241 List all the physical volumes detected. This is the equivalent
242 of the L<pvs(8)> command. The "full" version includes all fields.
246 This syncs the disk, so that any writes are flushed through to the
247 underlying disk image.
249 You should always call this if you have modified a disk image, before
252 =item $h->touch (path);
254 Touch acts like the L<touch(1)> command. It can be used to
255 update the timestamps on a file, or, if the file does not exist,
256 to create a new zero-length file.
258 =item @volgroups = $h->vgs ();
260 List all the volumes groups detected. This is the equivalent
261 of the L<vgs(8)> command.
263 This returns a list of just the volume group names that were
264 detected (eg. C<VolGroup00>).
266 See also C<$h-E<gt>vgs_full>.
268 =item @volgroups = $h->vgs_full ();
270 List all the volumes groups detected. This is the equivalent
271 of the L<vgs(8)> command. The "full" version includes all fields.
281 Copyright (C) 2009 Red Hat Inc.
285 Please see the file COPYING.LIB for the full license.
289 L<guestfs(3)>, L<guestfish(1)>.