1guestfs-python(3) Virtualization Support guestfs-python(3)
2
6 guestfs-python - How to use libguestfs from Python
7
9 import guestfs
10 g = guestfs.GuestFS (python_return_dict=True)
11 g.add_drive_opts ("disk.img", format="raw", readonly=1)
12 g.launch ()
13
15 This manual page documents how to call libguestfs from the Python
16 programming language. This page just documents the differences from
17 the C API and gives some examples. If you are not familiar with using
18 libguestfs, you also need to read guestfs(3).
19 python_return_dict=True
21 All new code should construct the handle using:
22 g = guestfs.GuestFS (python_return_dict=True)
24 This indicates that your program wants to receive Python dicts for
26 methods in the API that return hashtables.
27 In a future version of libguestfs, this will become the default.
29 EXCEPTIONS
31 Errors from libguestfs functions are mapped into "RuntimeException"
32 with a single string argument which is the error message.
33 MORE DOCUMENTATION
35 Type:
36 $ python
38 >>> import guestfs
39 >>> help (guestfs)
40
42 # Example showing how to create a disk image.
43 import os
45 import guestfs
46 output = "disk.img"
48 # All new Python code should pass python_return_dict=True
50 # to the constructor. It indicates that your program wants
51 # to receive Python dicts for methods in the API that return
52 # hashtables.
53 g = guestfs.GuestFS (python_return_dict=True)
54 # Create a raw-format sparse disk image, 512 MB in size.
56 f = open (output, "w")
57 f.truncate (512 * 1024 * 1024)
58 f.close ()
59 # Set the trace flag so that we can see each libguestfs call.
61 g.set_trace (1)
62 # Attach the disk image to libguestfs.
64 g.add_drive_opts (output, format = "raw", readonly = 0)
65 # Run the libguestfs back-end.
67 g.launch ()
68 # Get the list of devices. Because we only added one drive
70 # above, we expect that this list should contain a single
71 # element.
72 devices = g.list_devices ()
73 assert (len (devices) == 1)
74 # Partition the disk as one single MBR partition.
76 g.part_disk (devices[0], "mbr")
77 # Get the list of partitions. We expect a single element, which
79 # is the partition we have just created.
80 partitions = g.list_partitions ()
81 assert (len (partitions) == 1)
82 # Create a filesystem on the partition.
84 g.mkfs ("ext4", partitions[0])
85 # Now mount the filesystem so that we can add files.
87 g.mount (partitions[0], "/")
88 # Create some files and directories.
90 g.touch ("/empty")
91 message = "Hello, world\n"
92 g.write ("/hello", message)
93 g.mkdir ("/foo")
94 # This one uploads the local file /etc/resolv.conf into
96 # the disk image.
97 g.upload ("/etc/resolv.conf", "/foo/resolv.conf")
98 # Because we wrote to the disk and we want to detect write
100 # errors, call g.shutdown. You don't need to do this:
101 # g.close will do it implicitly.
102 g.shutdown ()
103 # Note also that handles are automatically closed if they are
105 # reaped by reference counting. You only need to call close
106 # if you want to close the handle right away.
107 g.close ()
108
110 # Example showing how to inspect a virtual machine disk.
111 import sys
113 import guestfs
114 assert (len (sys.argv) == 2)
116 disk = sys.argv[1]
117 # All new Python code should pass python_return_dict=True
119 # to the constructor. It indicates that your program wants
120 # to receive Python dicts for methods in the API that return
121 # hashtables.
122 g = guestfs.GuestFS (python_return_dict=True)
123 # Attach the disk image read-only to libguestfs.
125 g.add_drive_opts (disk, readonly=1)
126 # Run the libguestfs back-end.
128 g.launch ()
129 # Ask libguestfs to inspect for operating systems.
131 roots = g.inspect_os ()
132 if len (roots) == 0:
133 raise (Error ("inspect_vm: no operating systems found"))
134 for root in roots:
136 print "Root device: %s" % root
137 # Print basic information about the operating system.
139 print " Product name: %s" % (g.inspect_get_product_name (root))
140 print " Version: %d.%d" % \
141 (g.inspect_get_major_version (root),
142 g.inspect_get_minor_version (root))
143 print " Type: %s" % (g.inspect_get_type (root))
144 print " Distro: %s" % (g.inspect_get_distro (root))
145 # Mount up the disks, like guestfish -i.
147 #
148 # Sort keys by length, shortest first, so that we end up
149 # mounting the filesystems in the correct order.
150 mps = g.inspect_get_mountpoints (root)
151 def compare (a, b): return len(a) - len(b)
152 for device in sorted (mps.keys(), compare):
153 try:
154 g.mount_ro (mps[device], device)
155 except RuntimeError as msg:
156 print "%s (ignored)" % msg
157 # If /etc/issue.net file exists, print up to 3 lines.
159 filename = "/etc/issue.net"
160 if g.is_file (filename):
161 print "--- %s ---" % filename
162 lines = g.head_n (3, filename)
163 for line in lines: print line
164 # Unmount everything.
166 g.umount_all ()
167
169 guestfs(3), guestfs-examples(3), guestfs-erlang(3), guestfs-java(3),
170 guestfs-lua(3), guestfs-ocaml(3), guestfs-perl(3), guestfs-recipes(1),
171 guestfs-ruby(3), http://libguestfs.org/.
172
174 Richard W.M. Jones ("rjones at redhat dot com")
175
177 Copyright (C) 2010-2012 Red Hat Inc.
178
180 This manual page contains examples which we hope you will use in your
181 programs. The examples may be freely copied, modified and distributed
182 for any purpose without any restrictions.
183
185 To get a list of bugs against libguestfs, use this link:
186 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
187 To report a new bug against libguestfs, use this link:
189 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
190 When reporting a bug, please supply:
192 · The version of libguestfs.
194 · Where you got libguestfs (eg. which Linux distro, compiled from
196 source, etc)
197 · Describe the bug accurately and give a way to reproduce it.
199 · Run libguestfs-test-tool(1) and paste the complete, unedited output
201 into the bug report.
202libguestfs-1.20.11 2013-08-27 guestfs-python(3)