README

   1 Libguestfs is a library for accessing and modifying guest disk images.
   2 Amongst the things this is good for: making batch configuration
   3 changes to guests, getting disk used/free statistics (see also:
   4 virt-df), migrating between virtualization systems (see also:
   5 virt-p2v), performing partial backups, performing partial guest
   6 clones, cloning guests and changing registry/UUID/hostname info, and
   7 much else besides.
   8
   9 Libguestfs uses Linux kernel and qemu code, and can access any type of
  10 guest filesystem that Linux and qemu can, including but not limited
  11 to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
  12 schemes, qcow, qcow2, vmdk.
  13
  14 Libguestfs provides ways to enumerate guest storage (eg. partitions,
  15 LVs, what filesystem is in each LV, etc.).  It can also run commands
  16 in the context of the guest.  Also you can access filesystems over
  17 FUSE.
  18
  19 Libguestfs is a library that can be linked with C and C++ management
  20 programs (or management programs written in OCaml, Perl, Python, Ruby,
  21 Java, PHP, Haskell or C#).  You can also use it from shell scripts or the
  22 command line.
  23
  24 Libguestfs was written by Richard W.M. Jones (rjones@redhat.com) and
  25 hacked on by lots of other people.  For discussion, development,
  26 patches, etc. please use the mailing list:
  27
  28   http://www.redhat.com/mailman/listinfo/libguestfs
  29
  30
  31 Home page
  32 ----------------------------------------------------------------------
  33
  34   http://libguestfs.org/
  35
  36
  37 Requirements
  38 ----------------------------------------------------------------------
  39
  40 - recent QEMU >= 0.12 with virtio-serial support
  41
  42 - febootstrap >= 3.0
  43      *NB*: febootstrap 2.x WILL NOT WORK
  44            febootstrap 3.x is distro-independent, and is required on
  45              Debian and other distros too
  46
  47 - XDR, rpcgen (on Linux these are provided by glibc)
  48
  49 - pcre (Perl Compatible Regular Expressions C library) (optional)
  50
  51 - libmagic (the library that corresponds to the 'file' command) (optional)
  52
  53 - libvirt (optional)
  54
  55 - libxml2 (optional)
  56
  57 - Augeas (http://augeas.net/) (optional)
  58
  59 - gperf
  60
  61 - squashfs-tools (mksquashfs only)
  62
  63 - genisoimage / mkisofs
  64
  65 - hivex >= 1.2.1 (http://libguestfs.org/download)
  66
  67 - (Optional) Berkeley DB 'db_dump' and 'db_load' utilities
  68   (db4-utils or db4.X-util or similar)
  69
  70 - (Optional) FUSE to build the FUSE module
  71
  72 - perldoc (pod2man, pod2text, pod2html) to generate the manual pages
  73   and other documentation.
  74
  75 - (Optional) Readline to have nicer command-line editing in guestfish.
  76
  77 - (Optional) xmllint to validate virt-inspector RELAX NG schema
  78
  79 - (Optional) OCaml if you want to rebuild the generated files, and
  80   also to build the OCaml bindings
  81
  82 - (Optional) local Fedora mirror
  83
  84 - (Optional) Perl if you want to build the perl bindings
  85
  86 - (Optional) Python if you want to build the python bindings
  87
  88 - (Optional) Ruby, rake if you want to build the ruby bindings
  89
  90 - (Optional) Java, JNI, jpackage-utils if you want to build the java
  91 bindings
  92
  93 - (Optional) GHC if you want to build the Haskell bindings
  94
  95 - (Optional) Perl Sys::Virt module.
  96
  97 - (Optional) Perl Win::Hivex module.
  98
  99 - (Optional) Perl Pod::Usage module.
 100
 101 - (Optional) Perl Test::More module (from perl Test::Simple).
 102
 103 - (Optional) Perl String::ShellQuote module.
 104
 105 - (Optional, but highly recommended) perl-libintl for translating perl code.
 106
 107 - (Optional) po4a for translating manpages and POD files.
 108
 109 - (Optional) PHP, phpize if you want to build the PHP bindings
 110
 111 Running ./configure will check you have all the requirements installed
 112 on your machine.
 113
 114
 115 Building
 116 ----------------------------------------------------------------------
 117
 118 Then make the daemon, library and root filesystem:
 119
 120   ./configure [--with-mirror=URI]
 121   make
 122
 123 Use the optional --with-mirror parameter to specify the URI of a local
 124 Fedora mirror.  See the discussion of the MIRROR parameter in the
 125 febootstrap(8) manpage.
 126
 127 Finally run the tests:
 128
 129   make check
 130
 131 If everything works, you can install the library and tools by running
 132 this command as root:
 133
 134   make install
 135
 136
 137 qemu
 138 ----------------------------------------------------------------------
 139
 140 By far the most common problem is with broken or incompatible
 141 qemu releases.
 142
 143 Different versions of qemu have problems booting the appliance for
 144 different reasons.  This varies between versions of qemu, and Linux
 145 distributions which add their own patches.
 146
 147 If you find a problem, you could try using your own qemu built from
 148 source (qemu is very easy to build from source), with a 'qemu
 149 wrapper'.  Qemu wrappers are described in the guestfs(3) manpage.
 150
 151
 152 Note on using KVM
 153 ----------------------------------------------------------------------
 154
 155 By default the configure script will look for qemu-kvm (KVM support).
 156 You will need a reasonably recent processor for this to work.  KVM is
 157 much faster than using plain Qemu.
 158
 159 You may also need to enable KVM support for non-root users, by following
 160 these instructions:
 161
 162   http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
 163
 164 On some systems, this will work too:
 165
 166   chmod o+rw /dev/kvm
 167
 168 On some systems, the chmod will not survive a reboot, and you will
 169 need to make edits to the udev configuration.
 170
 171
 172 vmchannel
 173 ----------------------------------------------------------------------
 174
 175 Previous versions of libguestfs required something called "vmchannel".
 176 Vmchannel is a special device given to virtual machines which allows
 177 them to communicate in some way with the host, often (but not always)
 178 without using a traditional network device.  In reality, there is no
 179 one thing called "vmchannel".  This idea has been reimplemented
 180 several times under the name vmchannel, and other hypervisors have
 181 their own incompatible implementation(s) too.
 182
 183 In libguestfs <= 1.0.71, we required a specific vmchannel which is
 184 properly known as "guestfwd" and has been upstream in qemu since here:
 185
 186   http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
 187
 188 In libguestfs >= 1.0.71 we don't require any vmchannel implementation,
 189 as long as qemu has been compiled with support for SLIRP (user mode
 190 networking, or "-net user"), which is almost always the case.
 191
 192 In libguestfs >= 1.5.4 we switched again to using qemu's virtio-serial
 193 and removed all the other vmchannels and the SLIRP channel.
 194
 195
 196 Supermin appliance
 197 ----------------------------------------------------------------------
 198
 199 In libguestfs >= 1.7.19 the supermin appliance is the default and only
 200 supported form of appliance.  For more information see febootstrap
 201 (http://people.redhat.com/~rjones/febootstrap/).
 202
 203
 204 Mirroring tip
 205 ----------------------------------------------------------------------
 206
 207 On my machines I can usually rebuild the appliance in around 3
 208 minutes.  If it takes much longer for you, use a local Fedora mirror
 209 or squid.
 210
 211 To use squid to cache yum downloads, read this first:
 212 https://lists.dulug.duke.edu/pipermail/yum/2006-August/009041.html
 213 (In brief, because yum chooses random mirrors each time, squid doesn't
 214 work very well with default yum configuration.  To get around this,
 215 choose a Fedora mirror which is close to you, set this with
 216 './configure --with-mirror=[...]', and then proxy the whole lot
 217 through squid by setting http_proxy environment variable).
 218
 219 You will also need to substantially increase the squid configuration
 220 limits:
 221 http://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#Using_Squid_to_Speed_Up_Mock_package_downloads
 222
 223
 224 Porting to other Linux distros / non-Linux
 225 ----------------------------------------------------------------------
 226
 227 libguestfs itself should be fairly portable to other Linux
 228 distributions.  Non-Linux ports are trickier, but we will accept
 229 patches if they aren't too invasive.
 230
 231 The main porting issues are with the dependencies needed to build the
 232 appliance.  You will need to port the febootstrap first
 233 (http://people.redhat.com/~rjones/febootstrap/).
 234
 235
 236 Copyright and license information
 237 ----------------------------------------------------------------------
 238
 239 Copyright (C) 2009-2010 Red Hat Inc.
 240
 241 The library is distributed under the LGPLv2+.  The programs are
 242 distributed under the GPLv2+.  Please see the files COPYING and
 243 COPYING.LIB for full license information.