perl/lib/Sys/Guestfs.pm

   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.
   4 #
   5 # Copyright (C) 2009 Red Hat Inc.
   6 #
   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.
  11 #
  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.
  16 #
  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
  20
  21 =pod
  22
  23 =head1 NAME
  24
  25 Sys::Guestfs - Perl bindings for libguestfs
  26
  27 =head1 SYNOPSIS
  28
  29  use Sys::Guestfs;
  30
  31  my $h = Sys::Guestfs->new ();
  32  $h->add_drive ('guest.img');
  33  $h->launch ();
  34  $h->wait_ready ();
  35  $h->mount ('/dev/sda1', '/');
  36  $h->touch ('/hello');
  37  $h->sync ();
  38
  39 =head1 DESCRIPTION
  40
  41 The C<Sys::Guestfs> module provides a Perl XS binding to the
  42 libguestfs API for examining and modifying virtual machine
  43 disk images.
  44
  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
  50 much else besides.
  51
  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.
  56
  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.
  60
  61 =head1 ERRORS
  62
  63 All errors turn into calls to C<croak> (see L<Carp(3)>).
  64
  65 =head1 METHODS
  66
  67 =over 4
  68
  69 =cut
  70
  71 package Sys::Guestfs;
  72
  73 use strict;
  74 use warnings;
  75
  76 require XSLoader;
  77 XSLoader::load ('Sys::Guestfs');
  78
  79 =item $h = Sys::Guestfs->new ();
  80
  81 Create a new guestfs handle.
  82
  83 =cut
  84
  85 sub new {
  86   my $proto = shift;
  87   my $class = ref ($proto) || $proto;
  88
  89   my $self = Sys::Guestfs::_create ();
  90   bless $self, $class;
  91   return $self;
  92 }
  93
  94 =item $h->add_drive ($filename);
  95
  96 =item $h->add_cdrom ($filename);
  97
  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
 101 so on.
 102
 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
 107 image).
 108
 109 The C<add_cdrom> variation adds a CD-ROM device.
 110
 111 =item $h->config ($param, $value);
 112
 113 =item $h->config ($param);
 114
 115 Use this to add arbitrary parameters to the C<qemu> command line.
 116 See L<qemu(1)>.
 117
 118 =item $h->launch ();
 119
 120 =item $h->wait_ready ();
 121
 122 Internally libguestfs is implemented by running a virtual machine
 123 using L<qemu(1)>.  These calls are necessary in order to boot the
 124 virtual machine.
 125
 126 You should call these two functions after configuring the handle
 127 (eg. adding drives) but before performing any actions.
 128
 129 =item $h->set_path ($path);
 130
 131 =item $path = $h->get_path ();
 132
 133 See the discussion of C<PATH> in the L<guestfs(3)>
 134 manpage.
 135
 136 =item $h->set_autosync ($autosync);
 137
 138 =item $autosync = $h->get_autosync ();
 139
 140 See the discussion of I<AUTOSYNC> in the L<guestfs(3)>
 141 manpage.
 142
 143 =item $h->set_verbose ($verbose);
 144
 145 =item $verbose = $h->get_verbose ();
 146
 147 This sets or gets the verbose messages flag.  Verbose
 148 messages are sent to C<stderr>.
 149
 150 =item $content = $h->cat (path);
 151
 152 Return the contents of the file named C<path>.
 153
 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.
 158
 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
 161 FTP.
 162
 163 =item @devices = $h->list_devices ();
 164
 165 List all the block devices.
 166
 167 The full block device names are returned, eg. C</dev/sda>
 168
 169 =item @partitions = $h->list_partitions ();
 170
 171 List all the partitions detected on all block devices.
 172
 173 The full partition device names are returned, eg. C</dev/sda1>
 174
 175 This does not return logical volumes.  For that you will need to
 176 call C<$h-E<gt>lvs>.
 177
 178 =item $listing = $h->ll (directory);
 179
 180 List the files in C<directory> (relative to the root directory,
 181 there is no cwd) in the format of 'ls -la'.
 182
 183 This command is mostly useful for interactive sessions.  It
 184 is I<not> intended that you try to parse the output string.
 185
 186 =item @listing = $h->ls (directory);
 187
 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.
 191
 192 This command is mostly useful for interactive sessions.  Programs
 193 should probably use C<$h-E<gt>readdir> instead.
 194
 195 =item @logvols = $h->lvs ();
 196
 197 List all the logical volumes detected.  This is the equivalent
 198 of the L<lvs(8)> command.
 199
 200 This returns a list of the logical volume device names
 201 (eg. C</dev/VolGroup00/LogVol00>).
 202
 203 See also C<$h-E<gt>lvs_full>.
 204
 205 =item @logvols = $h->lvs_full ();
 206
 207 List all the logical volumes detected.  This is the equivalent
 208 of the L<lvs(8)> command.  The "full" version includes all fields.
 209
 210 =item $h->mount (device, mountpoint);
 211
 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
 216 names can be used.
 217
 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
 221 exist.
 222
 223 The mounted filesystem is writable, if we have sufficient permissions
 224 on the underlying device.
 225
 226 The filesystem options C<sync> and C<noatime> are set with this
 227 call, in order to improve reliability.
 228
 229 =item @physvols = $h->pvs ();
 230
 231 List all the physical volumes detected.  This is the equivalent
 232 of the L<pvs(8)> command.
 233
 234 This returns a list of just the device names that contain
 235 PVs (eg. C</dev/sda2>).
 236
 237 See also C<$h-E<gt>pvs_full>.
 238
 239 =item @physvols = $h->pvs_full ();
 240
 241 List all the physical volumes detected.  This is the equivalent
 242 of the L<pvs(8)> command.  The "full" version includes all fields.
 243
 244 =item $h->sync ();
 245
 246 This syncs the disk, so that any writes are flushed through to the
 247 underlying disk image.
 248
 249 You should always call this if you have modified a disk image, before
 250 closing the handle.
 251
 252 =item $h->touch (path);
 253
 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.
 257
 258 =item @volgroups = $h->vgs ();
 259
 260 List all the volumes groups detected.  This is the equivalent
 261 of the L<vgs(8)> command.
 262
 263 This returns a list of just the volume group names that were
 264 detected (eg. C<VolGroup00>).
 265
 266 See also C<$h-E<gt>vgs_full>.
 267
 268 =item @volgroups = $h->vgs_full ();
 269
 270 List all the volumes groups detected.  This is the equivalent
 271 of the L<vgs(8)> command.  The "full" version includes all fields.
 272
 273 =cut
 274
 275 1;
 276
 277 =back
 278
 279 =head1 COPYRIGHT
 280
 281 Copyright (C) 2009 Red Hat Inc.
 282
 283 =head1 LICENSE
 284
 285 Please see the file COPYING.LIB for the full license.
 286
 287 =head1 SEE ALSO
 288
 289 L<guestfs(3)>, L<guestfish(1)>.
 290
 291 =cut