libguestfs gotchas

I just added this section to the libguestfs man page. Always good to be upfront about your mistakes.

   LIBGUESTFS GOTCHAS
   Gotcha (programming): "A feature of a
   system [...] that works in the way it is documented but is
   counterintuitive and almost invites mistakes."

   Since we developed libguestfs and the associated tools, there are
   several things we would have designed differently, but are now stuck
   with for backwards compatibility or other reasons.  If there is ever a
   libguestfs 2.0 release, you can expect these to change.  Beware of
   them.

   Autosync / forgetting to sync.
       When modifying a filesystem from C or another language, you must
       unmount all filesystems and call "guestfs_sync" explicitly before
       you close the libguestfs handle.  You can also call:

        guestfs_set_autosync (handle, 1);

       to have the unmount/sync done automatically for you when the handle
       is closed.  (This feature is called "autosync",
       guestfs_set_autosync q.v.)

       If you forget to do this, then it is entirely possible that your
       changes won’t be written out, or will be partially written, or
       (very rarely) that you’ll get disk corruption.

       Note that in guestfish(3) autosync is the default.  So quick and
       dirty guestfish scripts that forget to sync will work just fine,
       which can make this extra-puzzling if you are trying to debug a
       problem.

   Read-only should be the default.
       In guestfish(3), --ro should be the default, and you should have to
       specify --rw if you want to make changes to the image.

       This would reduce the potential to corrupt live VM images.

       Note that many filesystems change the disk when you just mount and
       unmount, even if you didn’t perform any writes.  You need to use
       "guestfs_add_drive_ro" to guarantee that the disk is not changed.

   guestfish command line is hard to use.
       "guestfish disk.img" doesn’t do what people expect (open "disk.img"
       for examination).  It tries to run a guestfish command "disk.img"
       which doesn’t exist, so it fails, and it fails with a strange and
       unintuitive error message.  Like the Bourne shell, we should have
       used "guestfish -c command" to run commands.

Leave a comment

Filed under Uncategorized

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s