2012-kvm-forum/handout/2012-kvm-forum-rjones-libguestfs.tex

   1 \documentclass[12pt]{article}
   2 \usepackage{alltt,graphicx,url}
   3 \hyphenation{guestfish}
   4
   5 \title{libguestfs\\
   6 tools for viewing and modifying\\
   7 virtual machine disk images}
   8
   9 \author{Richard W.M. Jones\\
  10 \small Software Engineer\\[-0.8ex]
  11 \small Red Hat\\
  12 \small \texttt{rjones@redhat.com}\\
  13 }
  14
  15 \date{November 2012}
  16
  17 \begin{document}
  18 \maketitle
  19
  20 \section{Introduction}
  21
  22 The libguestfs project is nearly 4 years old, so for my rare
  23 opportunity to talk at the KVM Forum I thought I'd cover where we've
  24 got to in those 4 years, and also talk about some of the ways we are
  25 using the new features in KVM.
  26
  27 \section{Overview of libguestfs}
  28
  29 libguestfs is a C library with a simple, long-term stable API that
  30 contains about 400 different calls.  It also has bindings in many
  31 popular high-level languages, including Perl, Python, Ruby, OCaml,
  32 Java, PHP, and more.  The library lets you write simple programs to
  33 create, view and modify disk images, like the one in
  34 Appendix~\ref{perlexample}.
  35
  36 There are many tools which use libguestfs:
  37
  38 \begin{itemize}
  39 \item[{\bf guestfish}]
  40 Interactive and scriptable shell.
  41 \item[{\bf guestmount}]
  42 Mount filesystems from any guest or disk image on the host.
  43 \item[{\bf virt-alignment-scan}]
  44 Check alignment of partitions in guests.
  45 \item[{\bf virt-cat}]
  46 Display a file from a guest.
  47 \item[{\bf virt-copy-in}]
  48 Copy files and directories into a guest.
  49 \item[{\bf virt-copy-out}]
  50 Copy files and directories out of a guest.
  51 \item[{\bf virt-df}]
  52 Display disk usage of a guest.
  53 \item[{\bf virt-edit}]
  54 Edit a file in a guest.
  55 \item[{\bf virt-filesystems}]
  56 Display the partitions, filesystems, logical volumes etc. in a guest.
  57 \item[{\bf virt-inspector}]
  58 Inspect a guest and produce a report detailing the operating system,
  59 version, applications installed and more.
  60 \item[{\bf virt-ls}]
  61 List files and directories in a guest.
  62 \item[{\bf virt-make-fs}]
  63 Make a new filesystem.
  64 \item[{\bf virt-rescue}]
  65 Rescue mode for guests.
  66 \item[{\bf virt-resize}]
  67 Resize a guest.
  68 \item[{\bf virt-sparsify}]
  69 Make a disk sparse.
  70 \item[{\bf virt-sysprep}]
  71 Reset a guest to ``factory configuration''.
  72 \item[{\bf virt-tar-in}]
  73 Copy files from a tarball into a guest.
  74 \item[{\bf virt-tar-out}]
  75 Copy files out of a guest into a tarball.
  76 \item[{\bf virt-win-reg}]
  77 Display and edit the Windows Registry in a guest.
  78 \end{itemize}
  79
  80 and libguestfs is increasingly being used by major projects:
  81
  82 \begin{itemize}
  83 \item[{\bf BoxGrinder \& Oz}]
  84 Projects that can create guests from scratch.
  85 \item[{\bf OpenStack}]
  86 Uses libguestfs to inject files into guests.
  87 \item[{\bf virt-manager}]
  88 Uses libguestfs to display icons and applications in guests.
  89 \item[{\bf virt-v2v \& virt-p2v}]
  90 Migrate between physical machines and different hypervisors.
  91 \end{itemize}
  92
  93 \section{Using guestfish to view and inject files}
  94
  95 An easy way to get started with libguestfs is to use our shell
  96 scripting tool,
  97 {\em guestfish}\footnote{\url{http://libguestfs.org/guestfish.1.html}}
  98 to open up a disk image and look inside.
  99
 100 You can open up almost any type of disk image, such as a raw file,
 101 qcow2 file, or a logical volume or partition that contains a virtual
 102 machine.  You {\em don't} need to be root, unless you need root to
 103 access the device.
 104
 105 Simply do:
 106
 107 \begin{samepage}
 108 \begin{verbatim}
 109 $ guestfish -a disk.img -i
 110
 111 Welcome to guestfish, the libguestfs filesystem interactive shell for
 112 editing virtual machine filesystems.
 113
 114 Type: 'help' for help on commands
 115       'man' to read the manual
 116       'quit' to quit the shell
 117
 118 Operating system: Red Hat Enterprise Linux Server release 6.3 (Santiago)
 119 /dev/vg_rhel6x32/lv_root mounted on /
 120 /dev/sda1 mounted on /boot
 121 \end{verbatim}
 122 \end{samepage}
 123
 124 You can now use guestfish commands to list files and directories and
 125 create files:
 126
 127 \begin{samepage}
 128 \begin{verbatim}
 129 ><fs> ls /
 130 bin
 131 boot
 132 cgroup
 133 [etc]
 134
 135 ><fs> write-append /etc/rc.d/rc.local "service sshd start"
 136
 137 ><fs> cat /etc/rc.d/rc.local
 138 #!/bin/sh
 139 touch /var/lock/subsys/local
 140 service sshd start
 141 \end{verbatim}
 142 \end{samepage}
 143
 144 Some useful commands include:
 145
 146 \begin{itemize}
 147 \item[\texttt{cat}] Display small text files.
 148 \item[\texttt{edit}] Edit a file.
 149 \item[\texttt{less}] Display longer files.
 150 \item[\texttt{ll}] List (long) directory.
 151 \item[\texttt{ls}] List directory.
 152 \item[\texttt{mkdir}] Make a directory.
 153 \item[\texttt{rm}] Remove a file.
 154 \item[\texttt{touch}] Touch a file.
 155 \item[\texttt{upload}] Upload a local file to the disk.
 156 \item[\texttt{write}] Create a file with content.
 157 \end{itemize}
 158
 159 As there are hundreds of commands, it's a good idea to read the
 160 {\em guestfish(1)} and
 161 {\em guestfs(3)}\footnote{\url{http://libguestfs.org/guestfs.3.html}}
 162 man pages.  These are also available online at the
 163 website\footnote{\url{http://libguestfs.org}}.
 164
 165 \section{Introducing virt-rescue}
 166
 167 virt-rescue\footnote{\url{http://libguestfs.org/virt-rescue.1.html}}
 168 is a good way to rescue virtual machines that don't boot, or just
 169 generally make ad hoc changes to virtual machines.  It's like a rescue
 170 CD for virtual machines.
 171
 172 virt-rescue is a little different from guestfish in that you get an
 173 ordinary shell and ordinary tools.  However unlike guestfish,
 174 virt-rescue cannot be used from shell scripts, so it's not useful if
 175 you want to make repeatable changes to lots of your guests.
 176
 177 You must not use virt-rescue on running VMs.
 178
 179 If you had a libvirt guest called ``Fedora'' then:
 180
 181 \begin{samepage}
 182 \begin{verbatim}
 183 # virt-rescue -d Fedora
 184 [lots of boot messages]
 185
 186 Welcome to virt-rescue, the libguestfs rescue shell.
 187
 188 Note: The contents of / are the rescue appliance.
 189 You have to mount the guest's partitions under /sysroot
 190 before you can examine them.
 191
 192 ><rescue> lvs
 193   LV      VG        Attr   LSize Origin Snap%  Move Log Copy%  Convert
 194   lv_root vg_f13x64 -wi-a- 7.56g
 195   lv_swap vg_f13x64 -wi-a- 1.94g
 196 ><rescue> mount /dev/vg_f13x64/lv_root /sysroot/
 197 [  107.912813] EXT4-fs (dm-0): mounted filesystem with ordered data mode.
 198 Opts: (null)
 199 ><rescue> ls -l /sysroot/etc/fstab
 200 -rw-r--r--. 1 root root 781 Sep 16  2010 /sysroot/etc/fstab
 201 ><rescue> vi /sysroot/etc/fstab
 202 \end{verbatim}
 203 \end{samepage}
 204
 205 There is a lot more information about virt-rescue in the
 206 man page {\em virt-rescue(1)}.
 207
 208 \section{New features in libguestfs 1.20}
 209
 210 At the end of this year (2012) we hope to make a major new release of
 211 libguestfs.  Since the last version was released in May 2012, this
 212 represents over 6 months of development effort, and it includes and
 213 uses some major new features from KVM.
 214
 215 The new version will (optionally) use libvirt to manage the libguestfs
 216 appliance.  From the point of view of libguestfs this hides the
 217 complexity of dealing with the qemu command line.  It also lets us
 218 leverage libvirt for:
 219
 220 \begin{itemize}
 221 \item[security]
 222 The appliance will now be encapsulated with sVirt (SELinux or
 223 AppArmor) to prevent a malicious guest from being able to take over
 224 the qemu process and escape to attack the host.
 225 \item[remote access]
 226 libvirt will provide remote access to guests, using the ordinary
 227 libvirt remote URIs.
 228 \end{itemize}
 229
 230 We are also using new features from KVM:
 231
 232 \begin{itemize}
 233 \item[virtio-scsi]
 234 The primary new feature is Paolo Bonzini's virtio-scsi driver,
 235 which is far superior in both performance and features compared
 236 to virtio-blk.
 237 \item[up to 255 disks]
 238 With virtio-scsi, we can now access up to 255 disks at a time,
 239 and possibly many more in future.
 240 \item[hot-plugging of disks]
 241 With virtio-scsi and libvirt together we are able to hotplug
 242 (add and remove) disks, giving libguestfs users a lot more
 243 performance and flexibility.
 244 \item[sparsification]
 245 Coming soon, we'll be able to trim filesystems and cause
 246 the host backing file to become sparse.
 247 \item[qcow2 v3]
 248 We use the new version of qcow2 wherever possible because of
 249 its performance benefits.
 250 \end{itemize}
 251
 252 \newpage
 253 \appendix
 254 \section{Example: how to inspect a virtual machine disk}
 255 \label{perlexample}
 256
 257 \begin{verbatim}
 258 #!/usr/bin/perl -w
 259
 260 use strict;
 261 use Sys::Guestfs;
 262
 263 if (@ARGV < 1) {
 264     die "usage: inspect_vm disk.img"
 265 }
 266
 267 my $disk = $ARGV[0];
 268
 269 my $g = new Sys::Guestfs ();
 270 $g->add_drive_opts ($disk, readonly => 1);
 271 $g->launch ();
 272
 273 # Ask libguestfs to inspect for operating systems.
 274 my @roots = $g->inspect_os ();
 275 if (@roots == 0) {
 276     die "inspect_vm: no operating systems found";
 277 }
 278
 279 for my $root (@roots) {
 280     # Print basic information about the operating system.
 281     printf "  Product name: %s\n",
 282         $g->inspect_get_product_name ($root);
 283     printf "  Version:      %d.%d\n",
 284         $g->inspect_get_major_version ($root),
 285         $g->inspect_get_minor_version ($root);
 286
 287     # Mount up the disks, like guestfish -i.
 288     my %mps = $g->inspect_get_mountpoints ($root);
 289     my @mps = sort { length $a <=> length $b } (keys %mps);
 290     for my $mp (@mps) {
 291         eval { $g->mount_ro ($mps{$mp}, $mp) };
 292         if ($@) {
 293             print "$@ (ignored)\n"
 294         }
 295     }
 296
 297     # If /etc/issue.net file exists, print up to 3 lines.
 298     my $filename = "/etc/issue.net";
 299     if ($g->is_file ($filename)) {
 300         printf "--- %s ---\n", $filename;
 301         my @lines = $g->head_n (3, $filename);
 302         print "$_\n" foreach @lines;
 303     }
 304
 305     # Unmount everything.
 306     $g->umount_all ()
 307 }
 308 \end{verbatim}
 309
 310 \end{document}