README

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