libguestfs on Debian

libguestfs now compiles and passes most of the tests on Debian.

debian5x64:~/d/libguestfs$ LIBGUESTFS_QEMU=~/d/qemu/qemu.wrapper ./fish/guestfish 

Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.

Type: 'help' for help with commands
      'quit' to quit the shell

><fs> alloc /tmp/test 100M
><fs> run
><fs> sfdisk /dev/sda 0 0 0 ,
><fs> mkfs ext3 /dev/sda1
><fs> 
debian5x64:~/d/libguestfs$ file /tmp/test 
/tmp/test: x86 boot sector; partition 1: ID=0x83, starthead 0, startsector 1, 192779 sectors

You need the latest febootstrap and libguestfs from git, and read my previous posting about getting febootstrap to work on Debian.

Someone want to file an RTP or ITP …? I filed ITPs for febootstrap (530425) and libguestfs (530427). I’d really like someone to run with these packages as although I filed ITPs I’m not sure I’m best qualified to maintain them in Debian. Preliminary Debian packages can be found here.

Update: Debian unstable qemu 0.10.4 can’t boot the appliance – it hangs very early in the boot sequence (BIOS, before kernel). Solution is to compile qemu from git and use a qemu wrapper. qemu 0.10.5 added to Debian unstable today works.

Update #2: All tests now pass on Debian:

  1/140 test_find_0
  2/140 test_find_1
  3/140 test_find_2
  4/140 test_lvresize_0
  5/140 test_zerofree_0
test_zerofree_0 skipped (reason: SKIP_TEST_* variable set)
  6/140 test_hexdump_0
  7/140 test_strings_e_0
  8/140 test_strings_e_1
test_strings_e_1 skipped (reason: test disabled in generator)
  9/140 test_strings_0
 10/140 test_strings_1
 11/140 test_equal_0
 12/140 test_equal_1
 13/140 test_equal_2
 14/140 test_ping_daemon_0
 15/140 test_dmesg_0
 16/140 test_drop_caches_0
 17/140 test_mv_0
 18/140 test_mv_1
 19/140 test_cp_a_0
 20/140 test_cp_0
 21/140 test_cp_1
 22/140 test_cp_2
 23/140 test_grub_install_0
 24/140 test_zero_0
 25/140 test_fsck_0
 26/140 test_fsck_1
 27/140 test_set_e2uuid_0
 28/140 test_set_e2uuid_1
 29/140 test_set_e2uuid_2
 30/140 test_set_e2uuid_3
 31/140 test_set_e2label_0
 32/140 test_pvremove_0
 33/140 test_pvremove_1
 34/140 test_pvremove_2
 35/140 test_vgremove_0
 36/140 test_vgremove_1
 37/140 test_lvremove_0
 38/140 test_lvremove_1
 39/140 test_lvremove_2
 40/140 test_mount_ro_0
 41/140 test_mount_ro_1
 42/140 test_tgz_in_0
 43/140 test_tar_in_0
 44/140 test_checksum_0
 45/140 test_checksum_1
 46/140 test_checksum_2
 47/140 test_checksum_3
 48/140 test_checksum_4
 49/140 test_checksum_5
 50/140 test_checksum_6
 51/140 test_checksum_7
 52/140 test_download_0
 53/140 test_upload_0
 54/140 test_blockdev_rereadpt_0
 55/140 test_blockdev_flushbufs_0
 56/140 test_blockdev_getsize64_0
 57/140 test_blockdev_getsz_0
 58/140 test_blockdev_getbsz_0
 59/140 test_blockdev_getss_0
 60/140 test_blockdev_getro_0
 61/140 test_blockdev_setrw_0
 62/140 test_blockdev_setro_0
 63/140 test_statvfs_0
 64/140 test_lstat_0
 65/140 test_stat_0
 66/140 test_command_lines_0
 67/140 test_command_lines_1
 68/140 test_command_lines_2
 69/140 test_command_lines_3
 70/140 test_command_lines_4
 71/140 test_command_lines_5
 72/140 test_command_lines_6
 73/140 test_command_lines_7
 74/140 test_command_lines_8
 75/140 test_command_lines_9
 76/140 test_command_lines_10
 77/140 test_command_0
 78/140 test_command_1
 79/140 test_command_2
 80/140 test_command_3
 81/140 test_command_4
 82/140 test_command_5
 83/140 test_command_6
 84/140 test_command_7
 85/140 test_command_8
 86/140 test_command_9
 87/140 test_command_10
 88/140 test_command_11
 89/140 test_file_0
 90/140 test_file_1
 91/140 test_file_2
 92/140 test_umount_all_0
 93/140 test_umount_all_1
 94/140 test_mounts_0
 95/140 test_umount_0
 96/140 test_umount_1
 97/140 test_write_file_0
 98/140 test_write_file_1
 99/140 test_write_file_2
100/140 test_write_file_3
101/140 test_write_file_4
102/140 test_write_file_5
103/140 test_mkfs_0
104/140 test_lvcreate_0
105/140 test_vgcreate_0
106/140 test_pvcreate_0
107/140 test_is_dir_0
108/140 test_is_dir_1
109/140 test_is_file_0
110/140 test_is_file_1
111/140 test_exists_0
112/140 test_exists_1
113/140 test_mkdir_p_0
114/140 test_mkdir_p_1
115/140 test_mkdir_p_2
116/140 test_mkdir_0
117/140 test_mkdir_1
118/140 test_rm_rf_0
119/140 test_rmdir_0
120/140 test_rmdir_1
121/140 test_rmdir_2
122/140 test_rm_0
123/140 test_rm_1
124/140 test_rm_2
125/140 test_read_lines_0
126/140 test_read_lines_1
127/140 test_lvs_0
128/140 test_lvs_1
129/140 test_vgs_0
130/140 test_vgs_1
131/140 test_pvs_0
132/140 test_pvs_1
133/140 test_list_partitions_0
134/140 test_list_partitions_1
135/140 test_list_devices_0
136/140 test_ls_0
137/140 test_cat_0
138/140 test_touch_0
139/140 test_sync_0
140/140 test_mount_0

except zerofree. They need to package zerofree.

febootstrap now runs on Debian

With a minor patch I got febootstrap running on Debian. What can you do with it? Install and boot mini Fedora appliances from a Debian host.

If you want to try it, note you will need to install the following Debian packages before compiling from source:

autoconf automake make fakechroot >= 2.9 fakeroot yum >= 3.2.21

Note: fakechroot 2.9 and yum 3.2.21 (or above) must be installed from Debian unstable. fakechroot 2.8 will definitely not work.

New tool: virt-inspector

Today we released the first proper version of virt-inspector, which is a command line tool that tells you what’s in a virtual machine. You just point it at a disk image or a libvirt domain and it can tell you things like:

• What operating system(s) are installed, and what distros and versions.
• How disk partitions are expected to be mounted (eg. /dev/sda1 -> /boot)
• What applications are installed.
• What kernel(s) are installed.
• What kernel modules are installed.

The report that comes out can be in plain text or in XML so you can feed it to another program. You can also use it as a wrapper around guestfish, to pre-mount the filesystems as they would be mounted on the virtual machine:

  $ eval `virt-inspector --fish /dev/Guests/CentOS5.img`
  
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  
  Type: 'help' for help with commands
        'quit' to quit the shell
  
  ><fs> mounts
  /dev/mapper/VolGroup00-LogVol00
  /dev/sda1
  ><fs> ll /boot/
  total 12151
  drwxr-xr-x  4 root root    1024 May 11 18:16 .
  drwxr-xr-x 22 root root    4096 May 19 05:06 ..
  -rw-r--r--  1 root root  931546 May  7 11:05 System.map-2.6.18-128.1.10.el5
  -rw-r--r--  1 root root  931457 Jan 21 11:10 System.map-2.6.18-128.el5
  -rw-r--r--  1 root root   67942 May  7 11:05 config-2.6.18-128.1.10.el5
  -rw-r--r--  1 root root   67937 Jan 21 11:10 config-2.6.18-128.el5
  [etc]

libguestfs – fun with tar

I’ve added tar support to libguestfs. Two examples:

Extract a directory subtree

This pulls out /usr/share/doc from the guest and saves it as a local file called /tmp/doc.tar.gz:

$ guestfish -a guest.img -m /dev/VolGroup00/LogVol00 

Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.

Type: 'help' for help with commands
      'quit' to quit the shell

><fs> tgz-out /usr/share/doc /tmp/doc.tar.gz

Convert a tarball to an ext3 filesystem

$ cat /tmp/tar2ext3.sh
#!/bin/sh -
if [ $# -ne 2 ]; then
    echo "tar2ext3 input.tgz output.img"; exit 1
fi
guestfish <<EOF
alloc $2 100M
run
sfdisk /dev/sda 0 0 0 ,
mkfs ext3 /dev/sda1
mount /dev/sda1 /
tgz-in $1 /
sync
EOF
$ /tmp/tar2ext3.sh libguestfs-1.0.2.tar.gz test.img
$ ll test.img
-rw-rw-r--. 1 rjones rjones 104857600 2009-04-20 15:49 test.img

Now test.img contains all those files, inside an ext3 filesystem.

libguestfs 1.0.0 released, and Ruby bindings

libguestfs 1.0.0 is out, sources and binary RPMs here.

I also added Ruby bindings:

$ irb 
irb(main):002:0> require 'guestfs'
=> true
irb(main):003:0> g = Guestfs::create()
=> #<Guestfs::Guestfs:0x7feab981b630>
irb(main):004:0> g.add_drive("RHEL52PV32.img")
=> nil
irb(main):005:0> g.launch()
=> nil
irb(main):006:0> g.wait_ready()
=> nil
irb(main):007:0> g.lvs()
=> ["/dev/VolGroup00/LogVol00", "/dev/VolGroup00/LogVol01"]
irb(main):008:0> g.pvs()
=> ["/dev/sda2"]
irb(main):009:0> g.vgs()
=> ["VolGroup00"]
irb(main):010:0> g.list_partitions()
=> ["/dev/sda1", "/dev/sda2"]

libguestfs 0.8, now with fewer bugs :-)

I released libguestfs 0.8 yesterday, the library for accessing virtual machines. This version fixes a large number of bugs, because I wrote a test suite which sends several hundred commands through the library and verifies the results. Took a couple of days to fix all the bugs this found …

Here are some interesting things you can do with guestfish.

1: Just find out what’s in a virtual machine:

$ guestfish -a RHEL52PV32.img run : list-devices
/dev/sda

$ guestfish -a RHEL52PV32.img run : list-partitions
/dev/sda1
/dev/sda2

$ guestfish -a RHEL52PV32.img run : lvs
/dev/VolGroup00/LogVol00
/dev/VolGroup00/LogVol01

2: Make virtual machine filesystems containing partitions, LVM, filesystems and whatever else you want:

$ guestfish
Welcome to guestfish, the libguestfs filesystem interactive shell for
editing virtual machine filesystems.

Type: 'help' for help with commands
      'quit' to quit the shell

><fs> alloc /tmp/test 500M
><fs> run
><fs> pvcreate /dev/sda
><fs> vgcreate VG /dev/sda
><fs> vgs
VG
><fs> lvcreate LV VG 250
><fs> lvs
/dev/VG/LV
><fs> mkfs ext3 /dev/VG/LV
><fs> mount /dev/VG/LV /
><fs> touch /myfile
><fs> ll /
total 13
drwxr-xr-x  3 root root  1024 Apr 12 17:19 .
drwxr-xr-x 18 root root     0 Apr 12 17:15 ..
drwx------  2 root root 12288 Apr 12 17:19 lost+found
-rw-r--r--  1 root root     0 Apr 12 17:19 myfile
><fs> sync
><fs> quit
$ ll /tmp/test
-rw-rw-r--. 1 rjones rjones 524288000 2009-04-12 22:19 /tmp/test
$ file /tmp/test
/tmp/test: LVM2 (Linux Logical Volume Manager) , UUID: bhL0DP0rySspzviDKHN7TZABBcfTWuo

3: Use Augeas to edit configuration files:

$ guestfish -a RHEL52PV32.img -m /dev/VolGroup00/LogVol00
  
  Welcome to guestfish, the libguestfs filesystem interactive shell for
  editing virtual machine filesystems.
  
  Type: 'help' for help with commands
        'quit' to quit the shell
  
><fs> aug-init / 0
><fs> aug-match /augeas/*
/augeas/root
/augeas/save
/augeas/files
><fs> aug-match /files//error
><fs> aug-match /augeas//error
><fs> aug-match /augeas/root/*
><fs> aug-match /files/etc/*
/files/etc/ldap.conf
/files/etc/aliases
/files/etc/yum.repos.d
/files/etc/yum.conf
/files/etc/sysconfig
[etc]
><fs> aug-match /files/etc/hosts/*
/files/etc/hosts/comment[1]
/files/etc/hosts/comment[2]
/files/etc/hosts/1
/files/etc/hosts/2
><fs> cat /etc/hosts               
# Do not remove the following line, or various programs
# that require network functionality will fail.
127.0.0.1      	       localhost.localdomain localhost
::1		               localhost6.localdomain6 localhost6
><fs> aug-get /files/etc/hosts/comment[1]
Do not remove the following line, or various programs
><fs> help aug-insert
aug-insert - insert a sibling Augeas node
       aug-insert   
  
      Create a new sibling "label" for "path", inserting it into the tree
      before or after "path" (depending on the boolean flag "before").
  
      "path" must match exactly one existing node in the tree, and "label"
      must be a label, ie. not contain "/", "*" or end with a bracketed index
      "[N]".
  
><fs> aug-insert /files/etc/hosts/comment[2] comment false
><fs> aug-match /files/etc/hosts/*
/files/etc/hosts/comment[1]
/files/etc/hosts/comment[2]
/files/etc/hosts/comment[3]
/files/etc/hosts/1
/files/etc/hosts/2
><fs> aug-set /files/etc/hosts/comment[3] HELLO
><fs> aug-save
><fs> cat /etc/hosts
# Do not remove the following line, or various programs
# that require network functionality will fail.
# HELLO
127.0.0.1		localhost.localdomain localhost
::1			localhost6.localdomain6 localhost6

There are C, C++, shell, Perl and OCaml bindings for all of these calls, and you don’t need to be root to do any of it.

libguestfs ocaml bindings

In addition to perl bindings, libguestfs now has OCaml bindings:

open Printf

let () =
  if Array.length Sys.argv <= 1 ||
    not (Sys.file_exists Sys.argv.(1)) then (
    eprintf "Usage: lvs guest.img\n";
    exit 1
  );

  let h = Guestfs.create () in
  Guestfs.add_drive h Sys.argv.(1);
  Guestfs.launch h;
  Guestfs.wait_ready h;

  let pvs = Guestfs.pvs h in
  printf "PVs found: [ %s ]\n"
    (String.concat "; " (Array.to_list pvs));

  let vgs = Guestfs.vgs h in
  printf "VGs found: [ %s ]\n"
    (String.concat "; " (Array.to_list vgs));

  let lvs = Guestfs.lvs h in
  printf "LVs found: [ %s ]\n"
    (String.concat "; " (Array.to_list lvs));

which produces the following output:

$ ./lvs RHEL52PV32.img
PVs found: [ /dev/sda2 ]
VGs found: [ VolGroup00 ]
LVs found: [ /dev/VolGroup00/LogVol00; /dev/VolGroup00/LogVol01 ]

libguestfs perl bindings

You can now use Perl to examine and modify virtual machine disk images through libguestfs, as in this example:

#!/usr/bin/perl -w
use strict;
use Sys::Guestfs;

# Look for LVM LVs, VGs and PVs in a guest image.

die "Usage: lvs.pl guest.img\n" if @ARGV != 1 || ! -f $ARGV[0];

my $h = Sys::Guestfs->new ();
$h->add_drive ($ARGV[0]);

print "Launching, this can take a few seconds\n";
$h->launch ();
$h->wait_ready ();

print "Looking for PVs on the disk image\n";
my @pvs = $h->pvs ();
print "PVs found: (", join (", ", @pvs), ")\n";

print "Looking for VGs on the disk image\n";
my @vgs = $h->vgs ();
print "VGs found: (", join (", ", @vgs), ")\n";

print "Looking for LVs on the disk image\n";
my @lvs = $h->lvs ();
print "LVs found: (", join (", ", @lvs), ")\n";

Which produces this output:

$ ./lvs.pl RHEL52PV32.img
Creating the libguestfs handle
Launching, this can take a few seconds
Looking for PVs on the disk image
PVs found: (/dev/sda2)
Looking for VGs on the disk image
VGs found: (VolGroup00)
Looking for LVs on the disk image
LVs found: (/dev/VolGroup00/LogVol00, /dev/VolGroup00/LogVol01)

libguestfs: LVM support

libguestfs is the library I’m writing that lets you examine and modify any virtual machine disk image, offline or online.

I spent about 18 hours finding a bug in the LVM parsing code, but that bug has now been squashed and as of version 0.4 on the website you can examine PVs, VGs and LVs, as well as listing devices and partitions.

Next up: language bindings for Perl, OCaml and Python.
(C and C++ and shell scripting access already exist).

$ guestfish 

Welcome to guestfish, the libguestfs
filesystem interactive shell for
editing virtual machine filesystems.

Type: 'help' for help with commands
      'quit' to quit the shell

><fs> add /mnt/share/tmp/RHEL52PV32.img
><fs> run
><fs> pvs
/dev/sda2
><fs> lvs
/dev/VolGroup00/LogVol00
/dev/VolGroup00/LogVol01
><fs> mount /dev/VolGroup00/LogVol00 /
><fs> ls /
bin
boot
dev
etc
home
[...]

More libguestfs progress

Now with added ls!

><fs> mount /dev/sda1 /
><fs> ll /
total 13
drwxr-xr-x  3 root root  1024 Apr  4 04:40 .
drwxr-xr-x 18 root root     0 Apr  4 11:36 ..
-rw-r--r--  1 root root     0 Apr  4 04:40 goodbye
-rw-r--r--  1 root root     0 Apr  3 17:23 hello
drwx------  2 root root 12288 Apr  3 15:27 lost+found
><fs> touch /testing-1-2-3
><fs> ll /
total 13
drwxr-xr-x  3 root root  1024 Apr  4 11:37 .
drwxr-xr-x 18 root root     0 Apr  4 11:36 ..
-rw-r--r--  1 root root     0 Apr  4 04:40 goodbye
-rw-r--r--  1 root root     0 Apr  3 17:23 hello
drwx------  2 root root 12288 Apr  3 15:27 lost+found
-rw-r--r--  1 root root     0 Apr  4 11:37 testing-1-2-3

The more serious point to that was to make sure that the RPC protocol we’re using (based on XDR) can transfer strings and lists of strings in both directions, which will be necessary for the device / LV enumeration APIs.