contrib/intro/libguestfs-intro.html

   1 <!DOCTYPE html>
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3   <head>
   4     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
   5     <title>Short introduction to libguestfs</title>
   6     <style>
   7       body {
   8         counter-reset: chapter;
   9       }
  10
  11       body > p, body > img, body > pre, body > table {
  12         margin-left: 2em;
  13       }
  14
  15       h1 {
  16         color: rgb(204,0,0);
  17         font-size: 130%;
  18         border-bottom: 1px solid rgb(204,0,0);
  19       }
  20       author {
  21         display: block;
  22         position: absolute;
  23         right: 2em;
  24         top: 1em;
  25         font-size: 80%;
  26         text-align: right;
  27       }
  28
  29       h2 {
  30         margin-top: 4em;
  31         color: rgb(204,0,0);
  32         counter-increment: chapter;
  33         counter-reset: section;
  34       }
  35       h2:before {
  36         font-size: 80%;
  37         color: #666;
  38         content: counter(chapter) " ... ";
  39       }
  40
  41       pre {
  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);
  46         padding: 5px;
  47         margin-left: 1em;
  48       }
  49
  50       p.sourcelnk {
  51         text-align: left;
  52         font-size: 70%;
  53       }
  54     </style>
  55   </head>
  56   <body>
  57     <h1>Short introduction to libguestfs</h1>
  58     <author>by Richard W.M. Jones &lt;rjones@redhat.com&gt;</author>
  59
  60     <h2>The Idea</h2>
  61
  62     <p><b>Reuse qemu, Linux kernel and userspace tools</b> to read and
  63     write disk images.</p>
  64
  65     <object type="image/svg+xml" data="overview.svg">
  66       <img src="overview.png"/> <!-- fallback for lame IE -->
  67     </object>
  68
  69     <h2>The Stable API</h2>
  70
  71 <pre>
  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);
  74 </pre>
  75
  76 <table style="margin-bottom: 4em;" width="100%">
  77   <tr><td valign="top">Example using this API:</td><td>
  78 <pre>
  79 #include &lt;guestfs.h&gt;
  80
  81 char *fstype = <b>guestfs_vfs_type (g, "/dev/vda1")</b>;
  82 printf ("%s\n", fstype);
  83 free (fstype);
  84 &rarr; <b>ntfs</b>
  85 </pre>
  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&nbsp;to&nbsp;see&nbsp;a&nbsp;real&nbsp;example&nbsp;...</a></p>
  87     </td>
  88   </tr>
  89 </table>
  90
  91     <table width="100%">
  92       <tr><td valign="top">
  93
  94 <pre>
  95   ("<b>vfs_type</b>",
  96    (RString "fstype",
  97         [Device "device"], []),
  98    198, [],
  99    [ (* tests *) ],
 100    "get the Linux VFS type corresponding to a mounted device",
 101    "\
 102 This command gets the filesystem type corresponding to
 103 the filesystem on C&lt;device&gt;.
 104
 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&lt;ext3&gt; or C&lt;ntfs&gt;.");
 109 </pre>
 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&nbsp;source&nbsp;...</a></p>
 111
 112         </td>
 113         <td valign="top">
 114
 115 <pre>
 116 char *
 117 <b>do_vfs_type</b> (const char *device)
 118 {
 119   return get_blkid_tag (device, "TYPE");
 120 }
 121
 122 static char *
 123 get_blkid_tag (const char *device, const char *tag)
 124 {
 125   char *out, *err;
 126   int r;
 127
 128   r = commandr (&amp;out, &amp;err,
 129                 "blkid",
 130                 "-c", "/dev/null",
 131                 "-o", "value", "-s", tag, device, NULL);
 132   if (r != 0 &amp;&amp; r != 2) {
 133     if (r &gt;= 0)
 134       reply_with_error ("%s: %s (blkid returned %d)",
 135                         device, err, r);
 136     else
 137       reply_with_error ("%s: %s", device, err);
 138     free (out);
 139     free (err);
 140     return NULL;
 141   }
 142
 143   /* ... */
 144
 145   return out;             /* caller frees */
 146 }
 147 </pre>
 148 <p class="sourcelnk"><a href="http://git.annexia.org/?p=libguestfs.git;a=blob;f=daemon/blkid.c;hb=HEAD">full&nbsp;source&nbsp;...</a></p>
 149
 150         </td>
 151       </tr>
 152     </table>
 153
 154     <p>
 155       Just these two fragments generate:
 156     </p>
 157
 158     <ul>
 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>,
 165         PHP,
 166         Haskell,
 167         <a href="http://libguestfs.org/guestfs-erlang.3.html">Erlang</a>
 168         and C# </li>
 169       <li> <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>
 170         (shell script) </li>
 171       <li> documentation in man pages and HTML </li>
 172       <li> internal RPC code </li>
 173     </ul>
 174
 175     <h2>Tools written around the API</h2>
 176
 177     <object type="image/svg+xml" data="tools.svg">
 178       <img src="tools.png"/> <!-- fallback for lame IE -->
 179     </object>
 180
 181     <table>
 182       <tr><td valign="top" style="padding-bottom: 1.5em;" colspan="2">
 183 <pre>
 184 <b>guestfish -N bootrootlv:/dev/VG/LV:ext4:ext4:10G:256M &lt;&lt;EOF</b>
 185   <font style="color: green;">mount-options "" /dev/VG/LV /
 186   mkdir /boot
 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>
 191 <b>EOF</b>
 192 <b>guestmount -a test1.img -i mnt/</b>
 193 <b>ls 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>
 197 test01.example.com
 198 <b>fusermount -u mnt</b>
 199 </pre>
 200 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual&nbsp;for&nbsp;guestfish&nbsp;...</a> <br/>
 201 <a href="http://libguestfs.org/guestmount.1.html">manual&nbsp;for&nbsp;guestmount&nbsp;...</a></p>
 202       </td></tr>
 203       <tr><td valign="top" style="padding-bottom: 1.5em;">
 204 <pre>
 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%
 209 </pre>
 210 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual&nbsp;...</a></p>
 211         </td>
 212         <td valign="top" style="padding-bottom: 1.5em;">
 213 <pre>
 214 <b>virt-cat -c qemu:///system -d WinXP 'c:\boot.ini'</b>
 215 [boot loader]
 216 timeout=30
 217 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
 218 [operating systems]
 219 multi(0)disk(0)rdisk(0)partition(1)\WINDOWS=
 220 "Microsoft Windows XP Professional" /noexecute=optin
 221 /fastdetect
 222 </pre>
 223 <p class="sourcelnk"><a href="http://libguestfs.org/virt-cat.1.html">manual&nbsp;...</a></p>
 224       </td></tr>
 225       <tr><td valign="top" style="padding-bottom: 1.5em;">
 226 <pre>
 227 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
 228 <i>(launches text editor to edit guest /etc/passwd)</i>
 229
 230 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd \
 231   -e 's/^root:.*?:/root::/'</b>
 232 </pre>
 233 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual&nbsp;...</a></p>
 234         </td><td valign="top" style="padding-bottom: 1.5em;">
 235 <pre>
 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"
 240 </pre>
 241 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual&nbsp;...</a></p>
 242       </td></tr>
 243     </table>
 244
 245     <h2>Inspection</h2>
 246
 247 <pre>
 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  -        -
 255 </pre>
 256 <p class="sourcelnk">
 257 <a href="http://libguestfs.org/virt-filesystems.1.html">manual&nbsp;...</a>
 258 </p>
 259
 260 <pre>
 261 $ <b>virt-inspector -c qemu:///system -d Win7x32</b>
 262 <font style="color: #888;">&lt;?xml version="1.0"?&gt;</font>
 263 <font style="color: #888;">&lt;operatingsystems&gt;</font>
 264   <font style="color: #888;">&lt;operatingsystem&gt;</font>
 265     <font style="color: #888;">&lt;root&gt;</font>/dev/sda2<font style="color: #888;">&lt;/root&gt;</font>
 266     <font style="color: #888;">&lt;name&gt;</font>windows<font style="color: #888;">&lt;/name&gt;</font>
 267     <font style="color: #888;">&lt;arch&gt;</font>i386<font style="color: #888;">&lt;/arch&gt;</font>
 268     <font style="color: #888;">&lt;distro&gt;</font>windows<font style="color: #888;">&lt;/distro&gt;</font>
 269     <font style="color: #888;">&lt;product_name&gt;</font>Windows 7 Enterprise<font style="color: #888;">&lt;/product_name&gt;</font>
 270     <font style="color: #888;">&lt;product_variant&gt;</font>Client<font style="color: #888;">&lt;/product_variant&gt;</font>
 271     <font style="color: #888;">&lt;major_version&gt;</font>6<font style="color: #888;">&lt;/major_version&gt;</font>
 272     <font style="color: #888;">&lt;minor_version&gt;</font>1<font style="color: #888;">&lt;/minor_version&gt;</font>
 273     <font style="color: #888;">&lt;windows_systemroot&gt;</font>/Windows<font style="color: #888;">&lt;/windows_systemroot&gt;</font>
 274     <font style="color: #888;">&lt;windows_current_control_set&gt;</font>ControlSet001<font style="color: #888;">&lt;/windows_current_control_set&gt;</font>
 275     <font style="color: #888;">&lt;hostname&gt;</font>win7x32<font style="color: #888;">&lt;/hostname&gt;</font>
 276 <i>... etc ...</i>
 277 </pre>
 278 <p class="sourcelnk">
 279 <a href="win7.xml">full&nbsp;XML&nbsp;...</a> <br/>
 280 <a href="http://libguestfs.org/virt-inspector.1.html">manual&nbsp;...</a>
 281 </p>
 282
 283 <pre>
 284   char **roots;
 285   size_t i;
 286   char *type, *distro, *product_name;
 287   int major, minor;
 288
 289   roots = <b>guestfs_inspect_os</b> (g);
 290
 291   if (roots == NULL)
 292     exit (EXIT_FAILURE);
 293
 294   if (roots[0] == NULL) {
 295     fprintf (stderr, "no operating systems found\n");
 296     exit (EXIT_FAILURE);
 297   }
 298
 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]);
 305
 306     printf ("Root: %s\n"
 307             "  Type: %s\n"
 308             "  Distro: %s\n"
 309             "  Version: %d.%d\n"
 310             "  Product name: %s\n\n");
 311             roots[i],
 312             type ? : "unknown", distro ? : "unknown", major, minor,
 313             product_name ? : "");
 314
 315     free (type);
 316     free (distro);
 317     free (product_name);
 318     free (roots[i]);
 319   }
 320
 321   free (roots);
 322 </pre>
 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&nbsp;source&nbsp;...</a></p>
 324
 325     <table>
 326       <tr><td colspan="2" align="middle">
 327           <small><i>Click to enlarge the images</i></small>
 328       </td></tr>
 329       <tr><td width="50%">
 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>
 333       </td></tr>
 334     </table>
 335
 336
 337
 338
 339     <h2>Graphical browsers</h2>
 340
 341     <p>
 342     <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser1.png?w=438&h=450"/>
 343     </p>
 344
 345     <p>
 346     <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser2.png?w=438&h=450"/>
 347     </p>
 348
 349     <p>
 350     <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser3.png?w=366&h=450"/>
 351     </p>
 352
 353     <p>
 354     <img src="https://rwmj.files.wordpress.com/2011/07/guestfs-browser4.png?w=366&h=450"/>
 355     </p>
 356     <p class="sourcelnk"><a href="https://rwmj.wordpress.com/2011/07/29/some-screenshots-from-the-new-guest-filesystem-browser/">source&nbsp;...</a></p>
 357
 358     <p>
 359     <img src="https://rwmj.files.wordpress.com/2009/11/file-browser.png?w=500"/>
 360     </p>
 361     <p class="sourcelnk"><a href="https://rwmj.wordpress.com/2009/11/03/browsing-guests-using-fuse/">source&nbsp;...</a></p>
 362
 363
 364
 365     <h2>Find out more ...</h2>
 366
 367     <p>
 368       <a href="http://libguestfs.org/">libguestfs.org</a> is the
 369       main website.
 370     </p>
 371
 372     <p>
 373       <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
 374       is the manual page documenting the C API and the internals.
 375     </p>
 376
 377     <p>
 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
 382       local man command.
 383     </p>
 384
 385     <p>
 386       For information about virt-v2v and virt-p2v, see
 387       <a href="http://libguestfs.org/virt-v2v/">http://libguestfs.org/virt-v2v/</a>
 388     </p>
 389
 390     <hr/>
 391
 392     <p style="font-size: 70%;">
 393       This page &copy; 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.
 397     </p>
 398
 399   </body>
 400 </html>