guestfs-python(3)					      Virtualization Support						 guestfs-python(3)

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
"
	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

libguestfs-1.18.1						    2013-12-07							 guestfs-python(3)