2 <html xmlns="http://www.w3.org/1999/xhtml">
4 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
5 <title>Short introduction to libguestfs</title>
8 counter-reset: chapter;
11 body > p, body > img, body > pre, body > table {
18 border-bottom: 1px solid rgb(204,0,0);
32 counter-increment: chapter;
33 counter-reset: section;
38 content: counter(chapter) " ... ";
42 background-color: #fcfcfc;
43 border-top: 1px dotted #eee;
44 border-bottom: 1px dotted #eee;
45 border-left: 2px solid rgb(204,0,0);
57 <h1>Short introduction to libguestfs</h1>
58 <author>by Richard W.M. Jones <rjones@redhat.com></author>
62 <p><b>Reuse qemu, Linux kernel and userspace tools</b> to read and
63 write disk images.</p>
65 <object type="image/svg+xml" data="overview.svg">
66 <img src="overview.png"/> <!-- fallback for lame IE -->
69 <h2>The Stable API</h2>
72 /* get the Linux VFS type corresponding to a mounted device */
73 extern char *<b>guestfs_vfs_type</b> (guestfs_h *g, const char *device);
76 <table style="margin-bottom: 4em;" width="100%">
77 <tr><td valign="top">Example using this API:</td><td>
79 #include <guestfs.h>
81 char *fstype = <b>guestfs_vfs_type (g, "/dev/vda1")</b>;
82 printf ("%s\n", fstype);
86 <p class="sourcelnk"><a href="http://git.annexia.org/?p=libguestfs.git;a=blob;f=fish/inspect.c;h=2ca54d2296fce5370504c1085cbcd7ac1b51ad3a;hb=HEAD#l208">click to see a real example ...</a></p>
97 [Device "device"], []),
100 "get the Linux VFS type corresponding to a mounted device",
102 This command gets the filesystem type corresponding to
103 the filesystem on C<device>.
105 For most filesystems, the result is the name of the Linux
106 VFS module which would be used to mount this filesystem
107 if you mounted it without specifying the filesystem type.
108 For example a string such as C<ext3> or C<ntfs>.");
110 <p class="sourcelnk"><a href="http://git.annexia.org/?p=libguestfs.git;a=blob;f=generator/generator_actions.ml;h=d3fa3e0b939eb047a5ff103a68f09c6898807748;hb=HEAD#l4775">full source ...</a></p>
117 <b>do_vfs_type</b> (const char *device)
119 return get_blkid_tag (device, "TYPE");
123 get_blkid_tag (const char *device, const char *tag)
128 r = commandr (&out, &err,
131 "-o", "value", "-s", tag, device, NULL);
132 if (r != 0 && r != 2) {
134 reply_with_error ("%s: %s (blkid returned %d)",
137 reply_with_error ("%s: %s", device, err);
145 return out; /* caller frees */
148 <p class="sourcelnk"><a href="http://git.annexia.org/?p=libguestfs.git;a=blob;f=daemon/blkid.c;hb=HEAD">full source ...</a></p>
155 Just these two fragments generate:
159 <li> bindings in <a href="http://libguestfs.org/guestfs.3.html#api_overview">C</a>,
160 <a href="http://libguestfs.org/guestfs-perl.3.html">Perl</a>,
161 <a href="http://libguestfs.org/guestfs-python.3.html">Python</a>,
162 <a href="http://libguestfs.org/guestfs-ruby.3.html">Ruby</a>,
163 <a href="http://libguestfs.org/guestfs-java.3.html">Java</a>,
164 <a href="http://libguestfs.org/guestfs-ocaml.3.html">OCaml</a>,
167 <a href="http://libguestfs.org/guestfs-erlang.3.html">Erlang</a>
169 <li> <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>
171 <li> documentation in man pages and HTML </li>
172 <li> internal RPC code </li>
175 <h2>Tools written around the API</h2>
177 <object type="image/svg+xml" data="tools.svg">
178 <img src="tools.png"/> <!-- fallback for lame IE -->
182 <tr><td valign="top" style="padding-bottom: 1.5em;" colspan="2">
184 <b>guestfish -N bootrootlv:/dev/VG/LV:ext4:ext4:10G:256M <<EOF</b>
185 <font style="color: green;">mount-options "" /dev/VG/LV /
187 mount-options "" /dev/sda1 /boot
188 txz-in filesystem.tar.xz /
189 write /etc/HOSTNAME "test01.example.com\n"
190 upload /etc/resolv.conf /etc/resolv.conf</font>
192 <b>guestmount -a test1.img -i mnt/</b>
194 bin dev home lib mnt proc sbin tmp var
195 boot etc initrd.img lost+found old-root root sys usr vmlinuz
196 <b>cat mnt/etc/HOSTNAME</b>
198 <b>fusermount -u mnt</b>
200 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual for guestfish ...</a> <br/>
201 <a href="http://libguestfs.org/guestmount.1.html">manual for guestmount ...</a></p>
203 <tr><td valign="top" style="padding-bottom: 1.5em;">
205 <b>virt-df -a /dev/vg/F15x32 -h</b>
206 Filesystem Size Used Available Use%
207 F15x32:/dev/sda1 484M 31M 428M 7%
208 F15x32:/dev/vg_f15x32/lv_root 5.5G 3.4G 1.8G 63%
210 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual ...</a></p>
212 <td valign="top" style="padding-bottom: 1.5em;">
214 <b>virt-cat -c qemu:///system -d WinXP 'c:\boot.ini'</b>
217 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
219 multi(0)disk(0)rdisk(0)partition(1)\WINDOWS=
220 "Microsoft Windows XP Professional" /noexecute=optin
223 <p class="sourcelnk"><a href="http://libguestfs.org/virt-cat.1.html">manual ...</a></p>
225 <tr><td valign="top" style="padding-bottom: 1.5em;">
227 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
228 <i>(launches text editor to edit guest /etc/passwd)</i>
230 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd \
231 -e 's/^root:.*?:/root::/'</b>
233 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual ...</a></p>
234 </td><td valign="top" style="padding-bottom: 1.5em;">
236 <b>virt-win-reg -c qemu:///system --unsafe-printable-strings \
237 Win7x32 'HKLM\SYSTEM\ControlSet001\Services\Tcpip\Parameters' \
238 | grep DhcpIPAddress</b>
239 "DhcpIPAddress"=str(1):"192.168.122.178"
241 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual ...</a></p>
248 $ <b>virt-filesystems -c qemu:///system -d Win7x32 --all --long -h --uuid</b>
249 Name Type VFS Label MBR Size Parent UUID
250 /dev/sda1 filesystem ntfs System Reserved - 100M - F81C92571C92112C
251 /dev/sda2 filesystem ntfs - - 20G - F2E8996AE8992E3B
252 /dev/sda1 partition - - 07 100M /dev/sda -
253 /dev/sda2 partition - - 07 20G /dev/sda -
254 /dev/sda device - - - 20G - -
256 <p class="sourcelnk">
257 <a href="http://libguestfs.org/virt-filesystems.1.html">manual ...</a>
261 $ <b>virt-inspector -c qemu:///system -d Win7x32</b>
262 <font style="color: #888;"><?xml version="1.0"?></font>
263 <font style="color: #888;"><operatingsystems></font>
264 <font style="color: #888;"><operatingsystem></font>
265 <font style="color: #888;"><root></font>/dev/sda2<font style="color: #888;"></root></font>
266 <font style="color: #888;"><name></font>windows<font style="color: #888;"></name></font>
267 <font style="color: #888;"><arch></font>i386<font style="color: #888;"></arch></font>
268 <font style="color: #888;"><distro></font>windows<font style="color: #888;"></distro></font>
269 <font style="color: #888;"><product_name></font>Windows 7 Enterprise<font style="color: #888;"></product_name></font>
270 <font style="color: #888;"><product_variant></font>Client<font style="color: #888;"></product_variant></font>
271 <font style="color: #888;"><major_version></font>6<font style="color: #888;"></major_version></font>
272 <font style="color: #888;"><minor_version></font>1<font style="color: #888;"></minor_version></font>
273 <font style="color: #888;"><windows_systemroot></font>/Windows<font style="color: #888;"></windows_systemroot></font>
274 <font style="color: #888;"><windows_current_control_set></font>ControlSet001<font style="color: #888;"></windows_current_control_set></font>
275 <font style="color: #888;"><hostname></font>win7x32<font style="color: #888;"></hostname></font>
278 <p class="sourcelnk">
279 <a href="win7.xml">full XML ...</a> <br/>
280 <a href="http://libguestfs.org/virt-inspector.1.html">manual ...</a>
286 char *type, *distro, *product_name;
289 roots = <b>guestfs_inspect_os</b> (g);
294 if (roots[0] == NULL) {
295 fprintf (stderr, "no operating systems found\n");
299 for (i = 0; roots[i] != NULL; ++i) {
300 type = <b>guestfs_inspect_get_type</b> (g, roots[i]);
301 distro = <b>guestfs_inspect_get_distro</b> (g, roots[i]);
302 product_name = <b>guestfs_inspect_get_product_name</b> (g, roots[i]);
303 major = <b>guestfs_inspect_get_major_version</b> (g, roots[i]);
304 minor = <b>guestfs_inspect_get_minor_version</b> (g, roots[i]);
310 " Product name: %s\n\n");
312 type ? : "unknown", distro ? : "unknown", major, minor,
313 product_name ? : "");
323 <p class="sourcelnk"><a href="http://git.annexia.org/?p=libguestfs.git;a=blob;f=rescue/virt-rescue.c;h=0c0036460434f1365d9591d6b2b805d999b07056;hb=HEAD#l351">full source ...</a></p>
326 <tr><td colspan="2" align="middle">
327 <small><i>Click to enlarge the images</i></small>
330 <a href="virt-manager.png"><img src="virt-manager-t.png"></a>
331 </td><td width="50%" align="middle" valign="top">
332 <a href="vmm-icons.png"><img src="vmm-icons-t.png"></a>
339 <h2>Graphical browsers</h2>
342 <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser1.png?w=438&h=450"/>
346 <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser2.png?w=438&h=450"/>
350 <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser3.png?w=366&h=450"/>
354 <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser4.png?w=366&h=450"/>
356 <p class="sourcelnk"><a href="https://rwmj.wordpress.com/2011/07/29/some-screenshots-from-the-new-guest-filesystem-browser/">source ...</a></p>
359 <img src="https://rwmj.files.wordpress.com/2009/11/file-browser.png?w=500"/>
361 <p class="sourcelnk"><a href="https://rwmj.wordpress.com/2009/11/03/browsing-guests-using-fuse/">source ...</a></p>
365 <h2>Find out more ...</h2>
368 <a href="http://libguestfs.org/">libguestfs.org</a> is the
373 <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
374 is the manual page documenting the C API and the internals.
378 There are manual pages
379 documenting <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>, <a href="http://libguestfs.org/guestmount.1.html">guestmount</a>
380 and each virt tool. See
381 the <a href="http://libguestfs.org/">main website</a> or your
386 For information about virt-v2v and virt-p2v, see
387 <a href="http://libguestfs.org/virt-v2v/">http://libguestfs.org/virt-v2v/</a>
392 <p style="font-size: 70%;">
393 This page © 2011 Red Hat Inc. and distributed
394 under the terms of the GNU General Public License as published by
395 the Free Software Foundation; either version 2 of the License, or
396 (at your option) any later version.