contrib/intro/libguestfs-intro.html

   1 <html>
   2   <head>
   3     <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
   4     <title>Short introduction to libguestfs</title>
   5     <style>
   6       body {
   7         counter-reset: chapter;
   8       }
   9
  10       body > p, body > img, body > pre, body > table {
  11         margin-left: 2em;
  12       }
  13
  14       h1 {
  15         color: rgb(204,0,0);
  16         font-size: 130%;
  17         border-bottom: 1px solid rgb(204,0,0);
  18       }
  19       author {
  20         display: block;
  21         position: absolute;
  22         right: 2em;
  23         top: 1em;
  24         font-size: 80%;
  25         text-align: right;
  26       }
  27
  28       h2 {
  29         margin-top: 4em;
  30         color: rgb(204,0,0);
  31         counter-increment: chapter;
  32         counter-reset: section;
  33       }
  34       h2:before {
  35         font-size: 80%;
  36         color: #666;
  37         content: counter(chapter) " ... ";
  38       }
  39
  40       pre {
  41         background-color: #fcfcfc;
  42         border-top: 1px dotted #eee;
  43         border-bottom: 1px dotted #eee;
  44         border-left: 2px solid rgb(204,0,0);
  45         padding: 5px;
  46         margin-left: 1em;
  47       }
  48
  49       p.sourcelnk {
  50         text-align: left;
  51         font-size: 70%;
  52       }
  53     </style>
  54   </head>
  55   <body>
  56     <h1>Short introduction to libguestfs</h1>
  57     <author>by Richard W.M. Jones &lt;rjones@redhat.com&gt;</author>
  58
  59     <h2>The Idea</h2>
  60
  61     <p><b>Reuse qemu, Linux kernel and userspace tools</b> to read and
  62     write disk images.</p>
  63
  64     <img src="overview.svg"/>
  65
  66     <h2>The Stable API</h2>
  67
  68 <pre>
  69   /* get the Linux VFS type corresponding to a mounted device */
  70 extern char *<b>guestfs_vfs_type</b> (guestfs_h *g, const char *device);
  71 </pre>
  72
  73 <table style="margin-bottom: 4em;" width="100%">
  74   <tr><td valign="top">Example using this API:</td><td>
  75 <pre>
  76 #include &lt;guestfs.h&gt;
  77
  78 char *fstype = <b>guestfs_vfs_type (g, "/dev/vda1")</b>;
  79 printf ("%s\n", fstype);
  80 free (fstype);
  81 &rarr; <b>ntfs</b>
  82 </pre>
  83 <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>
  84     </td>
  85   </tr>
  86 </table>
  87
  88     <table width="100%">
  89       <tr><td valign="top">
  90
  91 <pre>
  92   ("<b>vfs_type</b>",
  93    (RString "fstype",
  94         [Device "device"], []),
  95    198, [],
  96    [ (* tests *) ],
  97    "get the Linux VFS type corresponding to a mounted device",
  98    "\
  99 This command gets the filesystem type corresponding to
 100 the filesystem on C&lt;device&gt;.
 101
 102 For most filesystems, the result is the name of the Linux
 103 VFS module which would be used to mount this filesystem
 104 if you mounted it without specifying the filesystem type.
 105 For example a string such as C&lt;ext3&gt; or C&lt;ntfs&gt;.");
 106 </pre>
 107 <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>
 108
 109         </td>
 110         <td valign="top">
 111
 112 <pre>
 113 char *
 114 <b>do_vfs_type</b> (const char *device)
 115 {
 116   return get_blkid_tag (device, "TYPE");
 117 }
 118
 119 static char *
 120 get_blkid_tag (const char *device, const char *tag)
 121 {
 122   char *out, *err;
 123   int r;
 124
 125   r = commandr (&amp;out, &amp;err,
 126                 "blkid",
 127                 "-c", "/dev/null",
 128                 "-o", "value", "-s", tag, device, NULL);
 129   if (r != 0 &amp;&amp; r != 2) {
 130     if (r &gt;= 0)
 131       reply_with_error ("%s: %s (blkid returned %d)",
 132                         device, err, r);
 133     else
 134       reply_with_error ("%s: %s", device, err);
 135     free (out);
 136     free (err);
 137     return NULL;
 138   }
 139
 140   /* ... */
 141
 142   return out;             /* caller frees */
 143 }
 144 </pre>
 145 <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>
 146
 147         </td>
 148       </tr>
 149     </table>
 150
 151     <p>
 152       Just these two fragments generate:
 153     </p>
 154
 155     <ul>
 156       <li> bindings in <a href="http://libguestfs.org/guestfs.3.html#api_overview">C</a>,
 157         <a href="http://libguestfs.org/guestfs-perl.3.html">Perl</a>,
 158         <a href="http://libguestfs.org/guestfs-python.3.html">Python</a>,
 159         <a href="http://libguestfs.org/guestfs-ruby.3.html">Ruby</a>,
 160         <a href="http://libguestfs.org/guestfs-java.3.html">Java</a>,
 161         <a href="http://libguestfs.org/guestfs-ocaml.3.html">OCaml</a>,
 162         PHP,
 163         Haskell,
 164         <a href="http://libguestfs.org/guestfs-erlang.3.html">Erlang</a>
 165         and C# </li>
 166       <li> <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>
 167         (shell script) </li>
 168       <li> documentation in man pages and HTML </li>
 169       <li> internal RPC code </li>
 170     </ul>
 171
 172     <h2>Tools written around the API</h2>
 173
 174     <img src="tools.svg" />
 175
 176     <table>
 177       <tr><td valign="top" style="padding-bottom: 1.5em;">
 178 <pre>
 179 <b>guestfish -N fs -m /dev/sda1 &lt;&lt;EOF</b>
 180   <font style="color: green;">mkdir /etc
 181   upload /etc/resolv.conf /etc/resolv.conf
 182   write /etc/hostname "test01.redhat.com"</font>
 183 <b>EOF</b>
 184 </pre>
 185 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual&nbsp;...</a></p>
 186         </td><td valign="top">
 187 <pre>
 188 <b>virt-df -a /dev/vg/F15x32 -h</b>
 189 Filesystem                    Size  Used Available Use%
 190 F15x32:/dev/sda1              484M   31M      428M   7%
 191 F15x32:/dev/vg_f15x32/lv_root 5.5G  3.4G      1.8G  63%
 192 </pre>
 193 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual&nbsp;...</a></p>
 194       </td></tr>
 195       <tr><td valign="top">
 196 <pre>
 197 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
 198 <i>(launches editor)</i>
 199 </pre>
 200 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual&nbsp;...</a></p>
 201         </td><td valign="top">
 202 <pre>
 203 <b>virt-win-reg -c qemu:///system --unsafe-printable-strings \
 204   Win7x32 'HKLM\SYSTEM\ControlSet001\Services\Tcpip\Parameters' \
 205   | grep DhcpIPAddress</b>
 206 "DhcpIPAddress"=str(1):"192.168.122.178"
 207 </pre>
 208 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual&nbsp;...</a></p>
 209       </td></tr>
 210     </table>
 211
 212     <h2>Inspection</h2>
 213
 214 <pre>
 215 $ <b>virt-inspector -c qemu:///system -d Win7x32</b>
 216
 217 <font style="color: #888;">&lt;?xml version="1.0"?&gt;</font>
 218 <font style="color: #888;">&lt;operatingsystems&gt;</font>
 219   <font style="color: #888;">&lt;operatingsystem&gt;</font>
 220     <font style="color: #888;">&lt;root&gt;</font>/dev/sda2<font style="color: #888;">&lt;/root&gt;</font>
 221     <font style="color: #888;">&lt;name&gt;</font>windows<font style="color: #888;">&lt;/name&gt;</font>
 222     <font style="color: #888;">&lt;arch&gt;</font>i386<font style="color: #888;">&lt;/arch&gt;</font>
 223     <font style="color: #888;">&lt;distro&gt;</font>windows<font style="color: #888;">&lt;/distro&gt;</font>
 224     <font style="color: #888;">&lt;product_name&gt;</font>Windows 7 Enterprise<font style="color: #888;">&lt;/product_name&gt;</font>
 225     <font style="color: #888;">&lt;product_variant&gt;</font>Client<font style="color: #888;">&lt;/product_variant&gt;</font>
 226     <font style="color: #888;">&lt;major_version&gt;</font>6<font style="color: #888;">&lt;/major_version&gt;</font>
 227     <font style="color: #888;">&lt;minor_version&gt;</font>1<font style="color: #888;">&lt;/minor_version&gt;</font>
 228     <font style="color: #888;">&lt;windows_systemroot&gt;</font>/Windows<font style="color: #888;">&lt;/windows_systemroot&gt;</font>
 229     <font style="color: #888;">&lt;windows_current_control_set&gt;</font>ControlSet001<font style="color: #888;">&lt;/windows_current_control_set&gt;</font>
 230     <font style="color: #888;">&lt;hostname&gt;</font>win7x32<font style="color: #888;">&lt;/hostname&gt;</font>
 231 <i>... etc ...</i>
 232 </pre>
 233 <p class="sourcelnk"><a href="win7.xml">full&nbsp;XML&nbsp;...</a></p>
 234
 235     <table>
 236       <tr><td colspan="2" align="middle">
 237           <small><i>Click to enlarge the images</i></small>
 238       </td></tr>
 239       <tr><td width="50%">
 240           <a href="virt-manager.png"><img src="virt-manager-t.png"></a>
 241         </td><td width="50%" align="middle" valign="top">
 242           <a href="vmm-icons.png"><img src="vmm-icons-t.png"></a>
 243       </td></tr>
 244     </table>
 245
 246 <pre>
 247   char **roots;
 248   size_t i;
 249   char *type, *distro, *product_name;
 250   int major, minor;
 251
 252   roots = <b>guestfs_inspect_os</b> (g);
 253
 254   if (roots == NULL)
 255     exit (EXIT_FAILURE);
 256
 257   if (roots[0] == NULL) {
 258     fprintf (stderr, "no operating systems found\n");
 259     exit (EXIT_FAILURE);
 260   }
 261
 262   for (i = 0; roots[i] != NULL; ++i) {
 263     type = <b>guestfs_inspect_get_type</b> (g, roots[i]);
 264     distro = <b>guestfs_inspect_get_distro</b> (g, roots[i]);
 265     product_name = <b>guestfs_inspect_get_product_name</b> (g, roots[i]);
 266     major = <b>guestfs_inspect_get_major_version</b> (g, roots[i]);
 267     minor = <b>guestfs_inspect_get_minor_version</b> (g, roots[i]);
 268
 269     printf ("Root: %s\n"
 270             "  Type: %s\n"
 271             "  Distro: %s\n"
 272             "  Version: %d.%d\n"
 273             "  Product name: %s\n\n");
 274             roots[i],
 275             type ? : "unknown", distro ? : "unknown", major, minor,
 276             product_name ? : "");
 277
 278     free (type);
 279     free (distro);
 280     free (product_name);
 281     free (roots[i]);
 282   }
 283
 284   free (roots);
 285 </pre>
 286 <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>
 287
 288
 289
 290
 291     <h2>V2V &amp; P2V</h2>
 292
 293
 294
 295
 296     <h2>Read more ...</h2>
 297
 298     <p>
 299       <a href="http://libguestfs.org/">libguestfs.org</a> is the
 300       main website.
 301     </p>
 302
 303     <p>
 304       <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
 305       is the manual page documenting the C API and the internals.
 306     </p>
 307
 308     <p>
 309       There are manual pages
 310       documenting <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>, <a href="http://libguestfs.org/guestmount.1.html">guestmount</a>
 311       and each virt tool.  See
 312       the <a href="http://libguestfs.org/">main website</a> or your
 313       local man command.
 314     </p>
 315
 316     <hr/>
 317
 318     <p style="font-size: 70%;">
 319       This page &copy; 2011 Red Hat Inc. and distributed
 320       under the terms of the GNU General Public License as published by
 321       the Free Software Foundation; either version 2 of the License, or
 322       (at your option) any later version.
 323     </p>
 324
 325   </body>
 326 </html>