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 {
  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         background-color: #f3f3f3;
  30         margin-top: 2em;
  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 #888;
  44         border-bottom: 1px dotted #888;
  45         border-left: 6px solid rgb(204,0,0);
  46         padding: 5px;
  47         margin-left: 1em;
  48       }
  49
  50       p.sourcelnk {
  51         text-align: right;
  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     <img src="overview.svg"/>
  66
  67     <h2>The Stable API</h2>
  68
  69 <pre>
  70   /* get the Linux VFS type corresponding to a mounted device */
  71 extern char *<b>guestfs_vfs_type</b> (guestfs_h *g, const char *device);
  72 </pre>
  73
  74 <table style="margin-bottom: 4em;" width="100%">
  75   <tr><td valign="top">Example using this API:</td><td>
  76 <pre>
  77 #include &lt;guestfs.h&gt;
  78
  79 char *fstype = <b>guestfs_vfs_type (g, "/dev/vda1")</b>;
  80 printf ("%s\n", fstype);
  81 free (fstype);
  82 &rarr; <b>ntfs</b>
  83 </pre>
  84 <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>
  85     </td>
  86   </tr>
  87 </table>
  88
  89     <table width="100%">
  90       <tr><td valign="top">
  91
  92 <pre style="font-size: 80%;">
  93   ("<b>vfs_type</b>",
  94    (RString "fstype",
  95         [Device "device"], []),
  96    198, [],
  97    [ (* tests *) ],
  98    "get the Linux VFS type corresponding to a mounted device",
  99    "\
 100 This command gets the filesystem type corresponding to
 101 the filesystem on C&lt;device&gt;.
 102
 103 For most filesystems, the result is the name of the Linux
 104 VFS module which would be used to mount this filesystem
 105 if you mounted it without specifying the filesystem type.
 106 For example a string such as C&lt;ext3&gt; or C&lt;ntfs&gt;.");
 107 </pre>
 108 <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>
 109
 110         </td>
 111         <td valign="top">
 112
 113 <pre style="font-size: 80%;">
 114 char *
 115 <b>do_vfs_type</b> (const char *device)
 116 {
 117   return get_blkid_tag (device, "TYPE");
 118 }
 119
 120 static char *
 121 get_blkid_tag (const char *device, const char *tag)
 122 {
 123   char *out, *err;
 124   int r;
 125
 126   r = commandr (&amp;out, &amp;err,
 127                 "blkid",
 128                 "-c", "/dev/null",
 129                 "-o", "value", "-s", tag, device, NULL);
 130   if (r != 0 &amp;&amp; r != 2) {
 131     if (r &gt;= 0)
 132       reply_with_error ("%s: %s (blkid returned %d)",
 133                         device, err, r);
 134     else
 135       reply_with_error ("%s: %s", device, err);
 136     free (out);
 137     free (err);
 138     return NULL;
 139   }
 140
 141   /* ... */
 142
 143   return out;             /* caller frees */
 144 }
 145 </pre>
 146 <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>
 147
 148         </td>
 149       </tr>
 150     </table>
 151
 152     <p>
 153       Just these two fragments generate:
 154     </p>
 155
 156     <ul>
 157       <li> bindings in <a href="http://libguestfs.org/guestfs.3.html#api_overview">C</a>,
 158         <a href="http://libguestfs.org/guestfs-perl.3.html">Perl</a>,
 159         <a href="http://libguestfs.org/guestfs-python.3.html">Python</a>,
 160         <a href="http://libguestfs.org/guestfs-ruby.3.html">Ruby</a>,
 161         <a href="http://libguestfs.org/guestfs-java.3.html">Java</a>,
 162         <a href="http://libguestfs.org/guestfs-ocaml.3.html">OCaml</a>,
 163         PHP,
 164         Haskell,
 165         <a href="http://libguestfs.org/guestfs-erlang.3.html">Erlang</a>
 166         and C# </li>
 167       <li> <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>
 168         (shell script) </li>
 169       <li> documentation in man pages and HTML </li>
 170       <li> internal RPC code </li>
 171     </ul>
 172
 173     <h2>Tools written around the API</h2>
 174
 175     <img src="tools.svg" />
 176
 177     <table>
 178       <tr><td valign="top">
 179 <pre>
 180 <b>guestfish -N fs -m /dev/sda1 &lt;&lt;EOF</b>
 181   <font style="color: green;">mkdir /etc
 182   upload /etc/resolv.conf /etc/resolv.conf
 183   write /etc/hostname "test01.redhat.com"</font>
 184 <b>EOF</b>
 185 </pre>
 186 <p class="sourcelnk"><a href="http://libguestfs.org/guestfish.1.html">manual&nbsp;...</a></p>
 187         </td><td valign="top">
 188 <pre>
 189 <b>virt-df -a /dev/vg/F15x32 -h</b>
 190 Filesystem                    Size  Used Available Use%
 191 F15x32:/dev/sda1              484M   31M      428M   7%
 192 F15x32:/dev/vg_f15x32/lv_root 5.5G  3.4G      1.8G  63%
 193 </pre>
 194 <p class="sourcelnk"><a href="http://libguestfs.org/virt-df.1.html">manual&nbsp;...</a></p>
 195       </td></tr>
 196       <tr><td valign="top">
 197 <pre>
 198 <b>virt-edit -c qemu:///system -d F15x32 /etc/passwd</b>
 199 <i>(launches editor)</i>
 200 </pre>
 201 <p class="sourcelnk"><a href="http://libguestfs.org/virt-edit.1.html">manual&nbsp;...</a></p>
 202         </td><td valign="top">
 203 <pre>
 204 <b>virt-win-reg -c qemu:///system --unsafe-printable-strings \
 205   Win7x32 'HKLM\SYSTEM\ControlSet001\Services\Tcpip\Parameters' \
 206   | grep DhcpIPAddress</b>
 207 "DhcpIPAddress"=str(1):"192.168.122.178"
 208 </pre>
 209 <p class="sourcelnk"><a href="http://libguestfs.org/virt-win-reg.1.html">manual&nbsp;...</a></p>
 210       </td></tr>
 211     </table>
 212
 213     <h2>Inspection</h2>
 214
 215
 216
 217
 218     <h2>V2V &amp; P2V</h2>
 219
 220
 221
 222
 223     <h2>Read more ...</h2>
 224
 225     <p>
 226       <a href="http://libguestfs.org/">libguestfs.org</a> is the
 227       main website.
 228     </p>
 229
 230     <p>
 231       <a href="http://libguestfs.org/guestfs.3.html">guestfs(3)</a>
 232       is the manual page documenting the C API and the internals.
 233     </p>
 234
 235     <p>
 236       There are manual pages
 237       documenting <a href="http://libguestfs.org/guestfish.1.html">guestfish</a>, <a href="http://libguestfs.org/guestmount.1.html">guestmount</a>
 238       and each virt tool.  See
 239       the <a href="http://libguestfs.org/">main website</a> or your
 240       local man command.
 241     </p>
 242
 243     <hr/>
 244
 245     <p style="font-size: 70%;">
 246       This page &copy; 2011 Red Hat Inc. and distributed
 247       under the terms of the GNU General Public License as published by
 248       the Free Software Foundation; either version 2 of the License, or
 249       (at your option) any later version.
 250     </p>
 251
 252   </body>
 253 </html>