X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=blobdiff_plain;f=README;h=252e595b47d76dd937141266b65a589f9d5167e4;hp=c8b42424152620ec189a74a8184d2d6af28c6474;hb=41b959fd9b057354f642d84398b875d02b88b864;hpb=91df7a164befc0c9a24f85733837874da5a057ac diff --git a/README b/README index c8b4242..252e595 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -libguestfs is a library for accessing and modifying guest disk images. +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: @@ -6,22 +6,20 @@ virt-p2v), performing partial backups, performing partial guest clones, cloning guests and changing registry/UUID/hostname info, and much else besides. -libguestfs uses Linux kernel and qemu code, and can access any type of +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. -libguestfs provides ways to enumerate guest storage (eg. partitions, +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 mount guest filesystems on -the host (requires root privs and NFS). +in the context of the guest. Also you can access filesystems over FTP. -libguestfs is a library that can be linked with C and C++ management -programs (or management programs written in other languages, if people -contribute the language bindings). You can also use it from shell -scripts or the command line. +Libguestfs is a library that can be linked with C and C++ management +programs (or management programs written in OCaml, Perl, Python, Ruby or Java). +You can also use it from shell scripts or the command line. -libguestfs was written by Richard W.M. Jones (rjones@redhat.com). +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 @@ -30,13 +28,33 @@ For discussion please use the fedora-virt mailing list: Requirements ---------------------------------------------------------------------- -- Recent QEMU with vmchannel support +- recent QEMU >= 0.10 with vmchannel support + http://lists.gnu.org/archive/html/qemu-devel/2009-02/msg01042.html -- febootstrap >= 1.2 +- febootstrap >= 1.5 - XDR, rpcgen -- (Optional) Local Fedora mirror +- Augeas (http://augeas.net/) + +- perldoc (pod2man, pod2text) to generate the manual pages and +other documentation. + +- (Optional) Readline to have nicer command-line editing in guestfish. + +- (Optional) OCaml if you want to rebuild the generated files, and +also to build the OCaml bindings + +- (Optional) local Fedora mirror + +- (Optional) 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 Running ./configure will check you have all the requirements installed on your machine. @@ -47,10 +65,10 @@ Building Then make the daemon, library and root filesystem: - ./configure [--mirror=URI] + ./configure [--with-mirror=URI] make -Use the optional --mirror parameter to specify the URI of a local +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. @@ -63,21 +81,64 @@ these commands as root: make install + +Note on using KVM +---------------------------------------------------------------------- + +If you are using x86-64, then by default the configure script will +look for qemu-kvm (KVM support). You will need a reasonably recent +processor for this to work. KVM is much faster than using plain QEMU. + +You may also need to enable KVM support for non-root users, by following +these instructions: + + http://www.linux-kvm.org/page/FAQ#How_can_I_use_kvm_with_a_non-privileged_user.3F + +On some systems, this will work too: + + chmod o+rw /dev/kvm + +On some systems, the chmod will not survive a reboot, and you will +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 NFS export will work fine, but running commands in +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. +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 +---------------------------------------------------------------------- + +Having a local Fedora mirror makes a massive difference to the time it +takes to build and rebuild initramfs images. + +Failing that, use squid to cache yum downloads, but read this first: +https://lists.dulug.duke.edu/pipermail/yum/2006-August/009041.html +(In brief, because yum chooses random mirrors each time, squid doesn't +work very well with default yum configuration. To get around this, +choose a Fedora mirror which is close to you, set this with +'./configure --with-mirror=[...]', and then proxy the whole lot +through squid by setting http_proxy environment variable). + +You will also need to substantially increase the squid configuration +limits: +http://fedoraproject.org/wiki/Using_Mock_to_test_package_builds#Using_Squid_to_Speed_Up_Mock_package_downloads + +IntelligentMirror is another possibility, although I couldn't get it +to work for me. + + Copyright and license information ----------------------------------------------------------------------