-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:
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
+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 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
Requirements
----------------------------------------------------------------------
-- nfs-utils source, unpacked
- http://download.sourceforge.net/nfs
+- recent QEMU with vmchannel support
-- Recent QEMU with vmchannel support
-
-- Compiled Linux kernels for 32 and/or 64 bit (see note below).
-
-- mkinitrd
-
-- cpio
+- febootstrap >= 1.2
- XDR, rpcgen
-- If you are running a 64 bit or non-x86 machine, see note below.
+- perldoc (pod2man, pod2text) to generate the manual pages and
+other documentation.
-We don't support initramfs at the moment. Patches gratefully
-received.
+- (Optional) OCaml if you want to modify the code or rebuild certain
+generated files.
+
+- (Optional) local Fedora mirror
Running ./configure will check you have all the requirements installed
on your machine.
Building
----------------------------------------------------------------------
-Unpack nfs-utils source into a directory somewhere, then create a
-symlink daemon/nfs-utils to where you unpacked it. For example:
-
- pushd daemon
- tar zxf /path/to/nfs-utils-1.1.4.tar.gz
- ln -s nfs-utils-1.1.4 nfs-utils
- popd
-
-For nfs-utils 1.1.4, you may find that the patch
-(nfs-utils-1.1.4-build.patch) helps.
-
-Then make the library and shell tools:
-
- ./configure
- make
-
-Make the daemon and NFS server:
- mkdir daemon/build
- pushd daemon/build
- ../configure
- make
- popd
-
-For 64 bit you'll probably want to build the 32 bit daemon and NFS
-server too:
+Then make the daemon, library and root filesystem:
- mkdir daemon/build-32
- pushd daemon/build-32
- ../configure --enable-32bit
+ ./configure [--with-mirror=URI]
make
- popd
-For complex cross-architecture environments, you may want to build
-other versions of the daemon and NFS server as well. See the note
-below.
+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 install
- pushd daemon/build
- make install
- popd
- # Repeat for each daemon/build* directory you made above.
-
-Note on 64 bit and non-x86 architectures
+Notes on cross-architecture support
----------------------------------------------------------------------
-The library runs the Linux kernel code in QEMU. It also runs a small
-control daemon inside QEMU. It might also run an NFS server. It
-might also run programs from the guest's disk/environment (if asked to).
-
-This leaves open the question of which QEMU do we run, eg. qemu (the
-i386 emulator) or qemu-system-x86_64 or qemu-system-ppc64 or ...?
-
-Several factors influence the choice:
-
-(a) The host architecture.
-
-(b) The guest architecture.
+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.
-(c) What kernel(s) we find at runtime.
+To enable this requires work for cross-architecture and 32-on-64
+support in febootstrap, fakeroot and fakechroot.
-(d) What compiler(s) we find at configure time.
+The daemon/ directory contains its own configure script. This is so
+that in future we will be able to cross-compile the daemon.
-(e) In general, we would prefer to run a 32 bit kernel over a 64 bit
-kernel, because that reduces the amount of system memory we have to
-give to qemu significantly, and makes libguestfs smaller, faster and
-use less memory.
-For example, if (a) the host is x86-64, then it might be running a
-mixture of (b) i386 and x86-64 guests. Disk formats are stable, even
-across 32 and 64 bit and endianness changes, so it doesn't really
-matter what kernel we use if we just want to access files in the
-guest. In the absence of any other factors, we would choose an i386
-kernel and run it in plain 'qemu', because that would use the least
-amount of memory.
-
-But if we wanted to enable the feature of running a guest program in
-an x86-64 guest, then we have to run an x86-64 kernel and
-qemu-system-x86_64 (an i386 kernel can't run 64 bit programs). The
-same applies if we didn't find a 32 bit kernel at runtime, or if we
-couldn't run "gcc -m32" at configure time (because we can't compile
-the daemon).
-
-SO: to enable maximum features on 64 bit architectures:
-
-(1) Ensure that "gcc -m32" can create usable binaries.
+Mirroring tip
+----------------------------------------------------------------------
-(2) Provide 32 and 64 bit kernels binaries at runtime.
+Having a local Fedora mirror makes a massive difference to the time it
+takes to build and rebuild initramfs images.
-If you have a really weird environment, eg. you want to run programs
-inside PPC64 guests on your MIPS machine, then:
+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).
-(3) Provide gcc cross-compiler and glibc for each architecture, and
-cross-compile the daemon and NFS server:
+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
- mkdir daemon/build-ppc64
- pushd daemon/build-ppc64
- ../configure --host=ppc64-gnu-linux
- make
- popd
+IntelligentMirror is another possibility, although I couldn't get it
+to work for me.
Copyright and license information
git.annexia.org / libguestfs.git / blobdiff