Version 1.11.17.

[libguestfs.git] / README

diff --git a/README b/README
index 5d340d3..787ec32 100644 (file)
--- a/README
+++ b/README
@@ -1,80 +1,135 @@
-Libguestfs is a library for accessing and modifying guest disk images.
-Amongst the things this is good for: making batch configuration
-changes to guests, getting disk used/free statistics (see also:
-virt-df), migrating between virtualization systems (see also:
-virt-p2v), performing partial backups, performing partial guest
-clones, cloning guests and changing registry/UUID/hostname info, and
-much else besides.
+Libguestfs is tools and a library for accessing and modifying guest
+disk images.  For more information see the home page:

 
 

-Libguestfs uses Linux kernel and qemu code, and can access any type of
-guest filesystem that Linux and qemu can, including but not limited
-to: ext2/3/4, btrfs, FAT and NTFS, LVM, many different disk partition
-schemes, qcow, qcow2, vmdk.
+  http://libguestfs.org/

 
 

-Libguestfs provides ways to enumerate guest storage (eg. partitions,
-LVs, what filesystem is in each LV, etc.).  It can also run commands
-in the context of the guest.  Also you can access filesystems over FTP.
+For discussion, development, patches, etc. please use the mailing
+list:

 
 

-Libguestfs is a library that can be linked with C and C++ management
-programs (or management programs written in OCaml, Perl, Python, Ruby, Java
-or Haskell).  You can also use it from shell scripts or the command line.
+  http://www.redhat.com/mailman/listinfo/libguestfs

 
 

-Libguestfs was written by Richard W.M. Jones (rjones@redhat.com).
-For discussion please use the fedora-virt mailing list:

 
 

-  https://www.redhat.com/mailman/listinfo/fedora-virt
+Requirements
+----------------------------------------------------------------------

 
 

+Running ./configure will check you have all the requirements installed
+on your machine.

 
 

-Home page
-----------------------------------------------------------------------
+Fedora/RHEL users:

 
 

-  http://libguestfs.org/
+  A useful tip is to run:

 
 

+    yum-builddep libguestfs

 
 

-Requirements
-----------------------------------------------------------------------
+  which will install all build dependencies automatically.  If that is
+  successful, you don't need to bother with the rest of this section.
+
+Debian/Ubuntu users:
+
+  Take a look at the debian/control file and install everything listed
+  in "Build-Depends".  If that is successful, you don't need to bother
+  with the rest of this section.
+
+The full requirements are described below.
+
+For basic functionality and the C tools:
+
+- look at appliance/packagelist.in and install as many of the packages
+  that apply to your distro as possible

 
 

-- recent QEMU >= 0.10 with vmchannel support
-  http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
+- recent QEMU >= 0.13 (0.14 or later is better) with virtio-serial support

 
 

-- febootstrap >= 2.0
+- kernel >= 2.6.34 with virtio-serial support enabled.

 
 

-- fakeroot
+- virtio-block and virtio-net drivers should be compiled into your
+  host kernel (strictly speaking this is optional, but you will have
+  to make complex changes to the ./configure command line to get it
+  to work if you don't have virtio)

 
 

-- fakechroot >= 2.9
+- febootstrap >= 3.3 (it is best to use the latest version)
+
+  Notes: (1) febootstrap 2.x WILL NOT WORK
+         (2) febootstrap 3.x is distro-independent, and is required on
+             Debian and other distros as well as Fedora

 
 - XDR, rpcgen (on Linux these are provided by glibc)
 
 
 - XDR, rpcgen (on Linux these are provided by glibc)
 

-- squashfs-tools (mksquashfs only)
+- cpio

 
 

-- (Optional) Augeas (http://augeas.net/)
+- gperf

 
 

-- perldoc (pod2man, pod2text) to generate the manual pages and
-  other documentation.
+- genisoimage (NOT mkisofs any more)

 
 

-- (Optional) Readline to have nicer command-line editing in guestfish.
+- hivex >= 1.2.7 (http://libguestfs.org/download) (optional)

 
 

-- (Optional) 'reged' program from chntpw to decode Windows registry
-  entries (http://home.eunet.no/~pnordahl/ntpasswd/)
+- pcre (Perl Compatible Regular Expressions C library) (optional)

 
 

-- (Optional) OCaml if you want to rebuild the generated files, and
-  also to build the OCaml bindings
+- libmagic (the library that corresponds to the 'file' command) (optional)

 
 

-- (Optional) local Fedora mirror
+- libvirt (optional)

 
 

-- (Optional) Perl if you want to build the perl bindings
+- libxml2 (optional)

 
 

-- (Optional) Python if you want to build the python bindings
+- libconfig (optional)

 
 

-- (Optional) Ruby, rake if you want to build the ruby bindings
+- augeas >= 0.5.0 (http://augeas.net/) (optional)

 
 

-- (Optional) Java, JNI, jpackage-utils if you want to build the java
-bindings
+- Berkeley DB 'db_dump' and 'db_load' utilities
+  (db4-utils or db4.X-util or similar) (optional)

 
 

-- (Optional) GHC if you want to build the Haskell bindings
+- perldoc (pod2man, pod2text, pod2html) to generate the manual pages
+  and other documentation.

 
 

-Running ./configure will check you have all the requirements installed
-on your machine.
+- Readline to have nicer command-line editing in guestfish (optional)
+
+- xmllint (part of libxml2) to validate virt-inspector
+  RELAX NG schema (optional)
+
+- OCaml if you want to rebuild the generated files, and
+  also to build the OCaml bindings (optional)
+
+- po4a for translating manpages and POD files.
+  This is optional when compiling from the tarball, but mandatory
+  if you compile from git.
+
+- getfacl, getfattr libraries and programs (optional)
+
+To build FUSE support (guestmount):
+
+- FUSE libraries and kernel module (optional)
+
+To build virt-resize:
+
+- OCaml PCRE bindings (ocaml-pcre) (optional)
+
+To build language bindings:
+
+- Perl if you want to build the perl bindings (optional)
+
+- Python if you want to build the python bindings (optional)
+
+- Ruby, rake if you want to build the ruby bindings (optional)
+
+- Java, JNI, jpackage-utils if you want to build the java
+  bindings (optional)
+
+- GHC if you want to build the Haskell bindings (optional)
+
+- PHP, phpize if you want to build the PHP bindings (optional)
+
+To build the Perl tools:
+
+- Perl Sys::Virt module (optional)
+
+- Perl Win::Hivex module (optional)
+
+- Perl Pod::Usage module (optional)
+
+- Perl Test::More module (from perl Test::Simple) (optional)
+
+- Perl String::ShellQuote module (optional)
+
+- perl-libintl for translating perl code (optional)

 
 
 Building
 
 
 Building


@@ -82,13 +137,9 @@ Building
 
 Then make the daemon, library and root filesystem:
 
 
 Then make the daemon, library and root filesystem:
 

-  ./configure [--with-mirror=URI]
+  ./configure

   make
 
   make
 

-Use the optional --with-mirror parameter to specify the URI of a local
-Fedora mirror.  See the discussion of the MIRROR parameter in the
-febootstrap(8) manpage.
-

 Finally run the tests:
 
   make check
 Finally run the tests:
 
   make check


@@ -98,35 +149,35 @@ this command as root:
 
   make install
 
 
   make install
 

+You can run guestfish, guestmount and the virt tools without needing
+to install, using the "run" script in the top directory.  This script
+sets up some environment variables.  For example:

 
 

-Fedora
-----------------------------------------------------------------------
-
-We provide packages for Fedora >= 11 in Fedora.  Use those, or build
-from our source RPMs - it's far simpler that way.
+  ./run ./fish/guestfish [usual guestfish args ...]

 
 

-You can compile libguestfs on Fedora 10 but you cannot use it with the
-version of qemu in Fedora 10.  You need to compile your own qemu, see
-section 'qemu' below.
+  ./run ./inspector/virt-inspector [usual virt-inspector args ...]

 
 

+If you are already in the fish/ subdirectory, then the following
+command will also work:

 
 

-RHEL / EPEL / CentOS etc
-----------------------------------------------------------------------
+  ../run ./guestfish [...]

 
 

-We provide packages in EPEL which cover RHEL/CentOS >= 5.  Use those
-or build from our source RPMs.
+You can also make a symlink (note: NOT a hard link) from your $PATH to
+the run script, eg:

 
 

+  cd ~/bin
+  ln -s ~/libguestfs/run libguestfs-run
+  cd ~/libguestfs
+  libguestfs-run ./inspector/virt-inspector [...]

 
 

-Debian
-----------------------------------------------------------------------
+You can also run the C programs under valgrind like this:

 
 

-libguestfs should build and run on Debian.
+  ./run valgrind [valgrind opts...] ./cat/virt-cat [virt-cat opts...]

 
 

-febootstrap, yum, rpm, fakeroot, fakechroot are all packaged in
-Debian.
+This also works with sudo (eg. if you need root access for libvirt or
+to access a block device):

 
 

-Please see the fedora-virt mailing list for the status of libguestfs
-in Debian.
+  sudo ./run ./cat/virt-cat -d LinuxGuest /etc/passwd

 
 
 qemu
 
 
 qemu


@@ -135,16 +186,9 @@ qemu
 By far the most common problem is with broken or incompatible
 qemu releases.
 
 By far the most common problem is with broken or incompatible
 qemu releases.
 

-First of all, you need qemu >= 0.10.4, which contains a vmchannel
-implementation.  There are several, conflicting, incompatible things
-called 'vmchannel' which at one time or another have been added or
-proposed for qemu/KVM.  The _only_ one we support is this one:
-
-  http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html
-
-Secondly, different versions of qemu have problems booting the
-appliance for different reasons.  This varies between versions of
-qemu, and Linux distributions which add their own patches.
+Different versions of qemu have problems booting the appliance for
+different reasons.  This varies between versions of qemu, and Linux
+distributions which add their own patches.

 
 If you find a problem, you could try using your own qemu built from
 source (qemu is very easy to build from source), with a 'qemu
 
 If you find a problem, you could try using your own qemu built from
 source (qemu is very easy to build from source), with a 'qemu


@@ -171,26 +215,11 @@ On some systems, the chmod will not survive a reboot, and you will
 need to make edits to the udev configuration.
 
 
 need to make edits to the udev configuration.
 
 

-Notes on cross-architecture support
-----------------------------------------------------------------------
-
-At the moment we basically don't support cross-architecture or
-32-on-64.  This limits what is possible for some guests.  Filesystem
-operations and FTP export will work fine, but running commands in
-guests may not be possible.
-
-To enable this requires work for cross-architecture and 32-on-64
-support in febootstrap, fakeroot and fakechroot.
-
-The daemon/ directory contains its own configure script.  This is so
-that in future we will be able to cross-compile the daemon.
-
-

 Mirroring tip
 ----------------------------------------------------------------------
 
 On my machines I can usually rebuild the appliance in around 3
 Mirroring tip
 ----------------------------------------------------------------------
 
 On my machines I can usually rebuild the appliance in around 3

-minutes.  If it takes much longer for you, use a local Fedora mirror
+minutes.  If it takes much longer for you, use a local distro mirror

 or squid.
 
 To use squid to cache yum downloads, read this first:
 or squid.
 
 To use squid to cache yum downloads, read this first:


@@ -214,21 +243,14 @@ distributions.  Non-Linux ports are trickier, but we will accept
 patches if they aren't too invasive.
 
 The main porting issues are with the dependencies needed to build the
 patches if they aren't too invasive.
 
 The main porting issues are with the dependencies needed to build the

-appliance.  You will need to find or port the following packages
-first:
-
- - fakeroot
- - fakechroot
- - python
- - rpm-python    http://www.rpm.org/
- - yum           http://yum.baseurl.org/
- - febootstrap   http://et.redhat.com/~rjones/febootstrap/
+appliance.  You will need to port the febootstrap first
+(http://people.redhat.com/~rjones/febootstrap/).

 
 
 Copyright and license information
 ----------------------------------------------------------------------
 
 
 
 Copyright and license information
 ----------------------------------------------------------------------
 

-Copyright (C) 2009 Red Hat Inc.
+Copyright (C) 2009-2011 Red Hat Inc.

 
 The library is distributed under the LGPLv2+.  The programs are
 distributed under the GPLv2+.  Please see the files COPYING and
 
 The library is distributed under the LGPLv2+.  The programs are
 distributed under the GPLv2+.  Please see the files COPYING and