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;">
184 <b>guestfish -N fs -m /dev/sda1 <<EOF</b>
185 <font style="color: green;">mkdir /etc
186 upload /etc/resolv.conf /etc/resolv.conf
187 write /etc/hostname "test01.redhat.com"</font>
190 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual ...</a></p>
191 </td><td valign="top">
193 <b>virt-df -a /dev/vg/F15x32 -h</b>
194 Filesystem Size Used Available Use%
195 F15x32:/dev/sda1 484M 31M 428M 7%
196 F15x32:/dev/vg_f15x32/lv_root 5.5G 3.4G 1.8G 63%
198 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual ...</a></p>
200 <tr><td valign="top">
202 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
203 <i>(launches editor)</i>
205 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual ...</a></p>
206 </td><td valign="top">
208 <b>virt-win-reg -c qemu:///system --unsafe-printable-strings \
209 Win7x32 'HKLM\SYSTEM\ControlSet001\Services\Tcpip\Parameters' \
210 | grep DhcpIPAddress</b>
211 "DhcpIPAddress"=str(1):"192.168.122.178"
213 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual ...</a></p>
220 $ <b>virt-inspector -c qemu:///system -d Win7x32</b>
222 <font style="color: #888;"><?xml version="1.0"?></font>
223 <font style="color: #888;"><operatingsystems></font>
224 <font style="color: #888;"><operatingsystem></font>
225 <font style="color: #888;"><root></font>/dev/sda2<font style="color: #888;"></root></font>
226 <font style="color: #888;"><name></font>windows<font style="color: #888;"></name></font>
227 <font style="color: #888;"><arch></font>i386<font style="color: #888;"></arch></font>
228 <font style="color: #888;"><distro></font>windows<font style="color: #888;"></distro></font>
229 <font style="color: #888;"><product_name></font>Windows 7 Enterprise<font style="color: #888;"></product_name></font>
230 <font style="color: #888;"><product_variant></font>Client<font style="color: #888;"></product_variant></font>
231 <font style="color: #888;"><major_version></font>6<font style="color: #888;"></major_version></font>
232 <font style="color: #888;"><minor_version></font>1<font style="color: #888;"></minor_version></font>
233 <font style="color: #888;"><windows_systemroot></font>/Windows<font style="color: #888;"></windows_systemroot></font>
234 <font style="color: #888;"><windows_current_control_set></font>ControlSet001<font style="color: #888;"></windows_current_control_set></font>
235 <font style="color: #888;"><hostname></font>win7x32<font style="color: #888;"></hostname></font>
238 <p class="sourcelnk"><a href="win7.xml">full XML ...</a></p>
241 <tr><td colspan="2" align="middle">
242 <small><i>Click to enlarge the images</i></small>
245 <a href="virt-manager.png"><img src="virt-manager-t.png"></a>
246 </td><td width="50%" align="middle" valign="top">
247 <a href="vmm-icons.png"><img src="vmm-icons-t.png"></a>
254 char *type, *distro, *product_name;
257 roots = <b>guestfs_inspect_os</b> (g);
262 if (roots[0] == NULL) {
263 fprintf (stderr, "no operating systems found\n");
267 for (i = 0; roots[i] != NULL; ++i) {
268 type = <b>guestfs_inspect_get_type</b> (g, roots[i]);
269 distro = <b>guestfs_inspect_get_distro</b> (g, roots[i]);
270 product_name = <b>guestfs_inspect_get_product_name</b> (g, roots[i]);
271 major = <b>guestfs_inspect_get_major_version</b> (g, roots[i]);
272 minor = <b>guestfs_inspect_get_minor_version</b> (g, roots[i]);
278 " Product name: %s\n\n");
280 type ? : "unknown", distro ? : "unknown", major, minor,
281 product_name ? : "");
291 <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>
296 <h2>V2V & P2V</h2>
301 <h2>Read more ...</h2>
304 <a href="http://libguestfs.org/">libguestfs.org</a> is the
309 <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
310 is the manual page documenting the C API and the internals.
314 There are manual pages
315 documenting <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>, <a href="http://libguestfs.org/guestmount.1.html">guestmount</a>
316 and each virt tool. See
317 the <a href="http://libguestfs.org/">main website</a> or your
323 <p style="font-size: 70%;">
324 This page © 2011 Red Hat Inc. and distributed
325 under the terms of the GNU General Public License as published by
326 the Free Software Foundation; either version 2 of the License, or
327 (at your option) any later version.