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;">
 183 <pre>
 184 <b>guestfish -N fs -m /dev/sda1 &lt;&lt;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>
 188 <b>EOF</b>
 189 </pre>
 190 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual&nbsp;...</a></p>
 191         </td><td valign="top">
 192 <pre>
 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%
 197 </pre>
 198 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual&nbsp;...</a></p>
 199       </td></tr>
 200       <tr><td valign="top">
 201 <pre>
 202 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
 203 <i>(launches editor)</i>
 204 </pre>
 205 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual&nbsp;...</a></p>
 206         </td><td valign="top">
 207 <pre>
 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"
 212 </pre>
 213 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual&nbsp;...</a></p>
 214       </td></tr>
 215     </table>
 216
 217     <h2>Inspection</h2>
 218
 219 <pre>
 220 $ <b>virt-inspector -c qemu:///system -d Win7x32</b>
 221
 222 <font style="color: #888;">&lt;?xml version="1.0"?&gt;</font>
 223 <font style="color: #888;">&lt;operatingsystems&gt;</font>
 224   <font style="color: #888;">&lt;operatingsystem&gt;</font>
 225     <font style="color: #888;">&lt;root&gt;</font>/dev/sda2<font style="color: #888;">&lt;/root&gt;</font>
 226     <font style="color: #888;">&lt;name&gt;</font>windows<font style="color: #888;">&lt;/name&gt;</font>
 227     <font style="color: #888;">&lt;arch&gt;</font>i386<font style="color: #888;">&lt;/arch&gt;</font>
 228     <font style="color: #888;">&lt;distro&gt;</font>windows<font style="color: #888;">&lt;/distro&gt;</font>
 229     <font style="color: #888;">&lt;product_name&gt;</font>Windows 7 Enterprise<font style="color: #888;">&lt;/product_name&gt;</font>
 230     <font style="color: #888;">&lt;product_variant&gt;</font>Client<font style="color: #888;">&lt;/product_variant&gt;</font>
 231     <font style="color: #888;">&lt;major_version&gt;</font>6<font style="color: #888;">&lt;/major_version&gt;</font>
 232     <font style="color: #888;">&lt;minor_version&gt;</font>1<font style="color: #888;">&lt;/minor_version&gt;</font>
 233     <font style="color: #888;">&lt;windows_systemroot&gt;</font>/Windows<font style="color: #888;">&lt;/windows_systemroot&gt;</font>
 234     <font style="color: #888;">&lt;windows_current_control_set&gt;</font>ControlSet001<font style="color: #888;">&lt;/windows_current_control_set&gt;</font>
 235     <font style="color: #888;">&lt;hostname&gt;</font>win7x32<font style="color: #888;">&lt;/hostname&gt;</font>
 236 <i>... etc ...</i>
 237 </pre>
 238 <p class="sourcelnk"><a href="win7.xml">full&nbsp;XML&nbsp;...</a></p>
 239
 240     <table>
 241       <tr><td colspan="2" align="middle">
 242           <small><i>Click to enlarge the images</i></small>
 243       </td></tr>
 244       <tr><td width="50%">
 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>
 248       </td></tr>
 249     </table>
 250
 251 <pre>
 252   char **roots;
 253   size_t i;
 254   char *type, *distro, *product_name;
 255   int major, minor;
 256
 257   roots = <b>guestfs_inspect_os</b> (g);
 258
 259   if (roots == NULL)
 260     exit (EXIT_FAILURE);
 261
 262   if (roots[0] == NULL) {
 263     fprintf (stderr, "no operating systems found\n");
 264     exit (EXIT_FAILURE);
 265   }
 266
 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]);
 273
 274     printf ("Root: %s\n"
 275             "  Type: %s\n"
 276             "  Distro: %s\n"
 277             "  Version: %d.%d\n"
 278             "  Product name: %s\n\n");
 279             roots[i],
 280             type ? : "unknown", distro ? : "unknown", major, minor,
 281             product_name ? : "");
 282
 283     free (type);
 284     free (distro);
 285     free (product_name);
 286     free (roots[i]);
 287   }
 288
 289   free (roots);
 290 </pre>
 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&nbsp;source&nbsp;...</a></p>
 292
 293
 294
 295
 296     <h2>V2V &amp; P2V</h2>
 297
 298
 299
 300
 301     <h2>Read more ...</h2>
 302
 303     <p>
 304       <a href="http://libguestfs.org/">libguestfs.org</a> is the
 305       main website.
 306     </p>
 307
 308     <p>
 309       <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
 310       is the manual page documenting the C API and the internals.
 311     </p>
 312
 313     <p>
 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
 318       local man command.
 319     </p>
 320
 321     <hr/>
 322
 323     <p style="font-size: 70%;">
 324       This page &copy; 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.
 328     </p>
 329
 330   </body>
 331 </html>