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   and virtio-serial support are not required but 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 - Augeas (http://augeas.net/) (optional)
  36
  37 - gperf
  38
  39 - squashfs-tools (mksquashfs only)
  40
  41 - genisoimage / mkisofs
  42
  43 - hivex >= 1.2.1 (http://libguestfs.org/download)
  44
  45 - (Optional) Berkeley DB 'db_dump' and 'db_load' utilities
  46   (db4-utils or db4.X-util or similar)
  47
  48 - (Optional) FUSE to build the FUSE module
  49
  50 - perldoc (pod2man, pod2text, pod2html) to generate the manual pages
  51   and other documentation.
  52
  53 - (Optional) Readline to have nicer command-line editing in guestfish.
  54
  55 - (Optional) xmllint to validate virt-inspector RELAX NG schema
  56
  57 - (Optional) OCaml if you want to rebuild the generated files, and
  58   also to build the OCaml bindings
  59
  60 - (Optional) Perl if you want to build the perl bindings
  61
  62 - (Optional) Python if you want to build the python bindings
  63
  64 - (Optional) Ruby, rake if you want to build the ruby bindings
  65
  66 - (Optional) Java, JNI, jpackage-utils if you want to build the java
  67 bindings
  68
  69 - (Optional) GHC if you want to build the Haskell bindings
  70
  71 - (Optional) Perl Sys::Virt module.
  72
  73 - (Optional) Perl Win::Hivex module.
  74
  75 - (Optional) Perl Pod::Usage module.
  76
  77 - (Optional) Perl Test::More module (from perl Test::Simple).
  78
  79 - (Optional) Perl String::ShellQuote module.
  80
  81 - (Optional, but highly recommended) perl-libintl for translating perl code.
  82
  83 - po4a for translating manpages and POD files.
  84   This is optional when compiling from the tarball, but mandatory
  85   if you compile from git.
  86
  87 - (Optional) PHP, phpize if you want to build the PHP bindings
  88
  89 Running ./configure will check you have all the requirements installed
  90 on your machine.
  91
  92
  93 Building
  94 ----------------------------------------------------------------------
  95
  96 Then make the daemon, library and root filesystem:
  97
  98   ./configure
  99   make
 100
 101 Finally run the tests:
 102
 103   make check
 104
 105 If everything works, you can install the library and tools by running
 106 this command as root:
 107
 108   make install
 109
 110
 111 qemu
 112 ----------------------------------------------------------------------
 113
 114 By far the most common problem is with broken or incompatible
 115 qemu releases.
 116
 117 Different versions of qemu have problems booting the appliance for
 118 different reasons.  This varies between versions of qemu, and Linux
 119 distributions which add their own patches.
 120
 121 If you find a problem, you could try using your own qemu built from
 122 source (qemu is very easy to build from source), with a 'qemu
 123 wrapper'.  Qemu wrappers are described in the guestfs(3) manpage.
 124
 125
 126 Note on using KVM
 127 ----------------------------------------------------------------------
 128
 129 By default the configure script will look for qemu-kvm (KVM support).
 130 You will need a reasonably recent processor for this to work.  KVM is
 131 much faster than using plain Qemu.
 132
 133 You may also need to enable KVM support for non-root users, by following
 134 these instructions:
 135
 136   http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F
 137
 138 On some systems, this will work too:
 139
 140   chmod o+rw /dev/kvm
 141
 142 On some systems, the chmod will not survive a reboot, and you will
 143 need to make edits to the udev configuration.
 144
 145
 146 vmchannel
 147 ----------------------------------------------------------------------
 148
 149 Previous versions of libguestfs required something called "vmchannel".
 150 Vmchannel is a special device given to virtual machines which allows
 151 them to communicate in some way with the host, often (but not always)
 152 without using a traditional network device.  In reality, there is no
 153 one thing called "vmchannel".  This idea has been reimplemented
 154 several times under the name vmchannel, and other hypervisors have
 155 their own incompatible implementation(s) too.
 156
 157 In libguestfs <= 1.0.71, we required a specific vmchannel which is
 158 properly known as "guestfwd" and has been upstream in qemu since here:
 159
 160   http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
 161
 162 In libguestfs >= 1.0.71 we don't require any vmchannel implementation,
 163 as long as qemu has been compiled with support for SLIRP (user mode
 164 networking, or "-net user"), which is almost always the case.
 165
 166 In libguestfs >= 1.5.4 we switched again to using qemu's virtio-serial
 167 and removed all the other vmchannels and the SLIRP channel.
 168
 169
 170 Supermin appliance
 171 ----------------------------------------------------------------------
 172
 173 In libguestfs >= 1.7.19 the supermin appliance is the default and only
 174 supported form of appliance.  For more information see febootstrap
 175 (http://people.redhat.com/~rjones/febootstrap/).
 176
 177
 178 Mirroring tip
 179 ----------------------------------------------------------------------
 180
 181 On my machines I can usually rebuild the appliance in around 3
 182 minutes.  If it takes much longer for you, use a local distro mirror
 183 or squid.
 184
 185 To use squid to cache yum downloads, read this first:
 186 https://lists.dulug.duke.edu/pipermail/yum/2006-August/009041.html
 187 (In brief, because yum chooses random mirrors each time, squid doesn't
 188 work very well with default yum configuration.  To get around this,
 189 choose a Fedora mirror which is close to you, set this with
 190 './configure --with-mirror=[...]', and then proxy the whole lot
 191 through squid by setting http_proxy environment variable).
 192
 193 You will also need to substantially increase the squid configuration
 194 limits:
 195 http://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#Using_Squid_to_Speed_Up_Mock_package_downloads
 196
 197
 198 Porting to other Linux distros / non-Linux
 199 ----------------------------------------------------------------------
 200
 201 libguestfs itself should be fairly portable to other Linux
 202 distributions.  Non-Linux ports are trickier, but we will accept
 203 patches if they aren't too invasive.
 204
 205 The main porting issues are with the dependencies needed to build the
 206 appliance.  You will need to port the febootstrap first
 207 (http://people.redhat.com/~rjones/febootstrap/).
 208
 209
 210 Copyright and license information
 211 ----------------------------------------------------------------------
 212
 213 Copyright (C) 2009-2010 Red Hat Inc.
 214
 215 The library is distributed under the LGPLv2+.  The programs are
 216 distributed under the GPLv2+.  Please see the files COPYING and
 217 COPYING.LIB for full license information.