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)