NAME¶

guestfs-python - How to use libguestfs from Python

SYNOPSIS¶

 import guestfs
 g = guestfs.GuestFS ()
 g.add_drive_opts ("disk.img", format="raw", readonly=1)
 g.launch ()

DESCRIPTION¶

This manual page documents how to call libguestfs from the Python programming language. This page just documents the differences from the C API and gives some examples. If you are not familiar with using libguestfs, you also need to read guestfs(3).

EXCEPTIONS¶

Errors from libguestfs functions are mapped into "RuntimeException" with a single string argument which is the error message.

MORE DOCUMENTATION¶

Type:

 $ python
 >>> import guestfs
 >>> help (guestfs)

EXAMPLE 1: CREATE A DISK IMAGE¶

 # Example showing how to create a disk image.
 
 import os
 import guestfs
 
 output = "disk.img"
 
 g = guestfs.GuestFS ()
 
 # Create a raw-format sparse disk image, 512 MB in size.
 f = open (output, "w")
 f.truncate (512 * 1024 * 1024)
 f.close ()
 
 # Set the trace flag so that we can see each libguestfs call.
 g.set_trace (1)
 
 # Set the autosync flag so that the disk will be synchronized
 # automatically when the libguestfs handle is closed.
 g.set_autosync (1)
 
 # Attach the disk image to libguestfs.
 g.add_drive_opts (output, format = "raw", readonly = 0)
 
 # Run the libguestfs back-end.
 g.launch ()
 
 # Get the list of devices.  Because we only added one drive
 # above, we expect that this list should contain a single
 # element.
 devices = g.list_devices ()
 assert (len (devices) == 1)
 
 # Partition the disk as one single MBR partition.
 g.part_disk (devices[0], "mbr")
 
 # Get the list of partitions.  We expect a single element, which
 # is the partition we have just created.
 partitions = g.list_partitions ()
 assert (len (partitions) == 1)
 
 # Create a filesystem on the partition.
 g.mkfs ("ext4", partitions[0])
 
 # Now mount the filesystem so that we can add files.
 g.mount_options ("", partitions[0], "/")
 
 # Create some files and directories.
 g.touch ("/empty")
 message = "Hello, world\n"
 g.write ("/hello", message)
 g.mkdir ("/foo")
 
 # This one uploads the local file /etc/resolv.conf into
 # the disk image.
 g.upload ("/etc/resolv.conf", "/foo/resolv.conf")
 
 # Because 'autosync' was set (above) we can just close the handle
 # and the disk contents will be synchronized.  You can also do
 # this manually by calling g.umount_all and g.sync.
 g.close ()

EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE¶

 # Example showing how to inspect a virtual machine disk.
 
 import sys
 import guestfs
 
 assert (len (sys.argv) == 2)
 disk = sys.argv[1]
 
 g = guestfs.GuestFS ()
 
 # Attach the disk image read-only to libguestfs.
 g.add_drive_opts (disk, readonly=1)
 
 # Run the libguestfs back-end.
 g.launch ()
 
 # Ask libguestfs to inspect for operating systems.
 roots = g.inspect_os ()
 if len (roots) == 0:
     raise (Error ("inspect_vm: no operating systems found"))
 
 for root in roots:
     print "Root device: %s" % root
 
     # Print basic information about the operating system.
     print "  Product name: %s" % (g.inspect_get_product_name (root))
     print "  Version:      %d.%d" % \
         (g.inspect_get_major_version (root),
          g.inspect_get_minor_version (root))
     print "  Type:         %s" % (g.inspect_get_type (root))
     print "  Distro:       %s" % (g.inspect_get_distro (root))
 
     # Mount up the disks, like guestfish -i.
     #
     # Sort keys by length, shortest first, so that we end up
     # mounting the filesystems in the correct order.
     mps = g.inspect_get_mountpoints (root)
     def compare (a, b):
         if len(a[0]) > len(b[0]):
             return 1
         elif len(a[0]) == len(b[0]):
             return 0
         else:
             return -1
     mps.sort (compare)
     for mp_dev in mps:
         try:
             g.mount_ro (mp_dev[1], mp_dev[0])
         except RuntimeError as msg:
             print "%s (ignored)" % msg
 
     # If /etc/issue.net file exists, print up to 3 lines.
     filename = "/etc/issue.net"
     if g.is_file (filename):
         print "--- %s ---" % filename
         lines = g.head_n (3, filename)
         for line in lines: print line
 
     # Unmount everything.
     g.umount_all ()

SEE ALSO¶

guestfs(3), guestfs-examples(3), guestfs-erlang(3), guestfs-java(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-recipes(1), guestfs-ruby(3), <http://libguestfs.org/>.

AUTHORS¶

Richard W.M. Jones ("rjones at redhat dot com")

COPYRIGHT¶

Copyright (C) 2010 Red Hat Inc. <http://libguestfs.org/> The examples in this manual page may be freely copied, modified and distributed without any restrictions. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA