guestfs-python(3)

1guestfs-python(3)           Virtualization Support           guestfs-python(3)
2
3
4

NAME

6       guestfs-python - How to use libguestfs from Python
7

SYNOPSIS

9        import guestfs
10        g = guestfs.GuestFS ()
11        g.add_drive_opts ("disk.img", format="raw", readonly=1)
12        g.launch
13

DESCRIPTION

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
20   EXCEPTIONS
21       Errors from libguestfs functions are mapped into "RuntimeException"
22       with a single string argument which is the error message.
23
24   MORE DOCUMENTATION
25       Type:
26
27        $ python
28        >>> import guestfs
29        >>> help (guestfs)
30

EXAMPLE 1: CREATE A DISK IMAGE

32        # Example showing how to create a disk image.
33
34        import os
35        import guestfs
36
37        output = "disk.img"
38
39        g = guestfs.GuestFS ()
40
41        # Create a raw-format sparse disk image, 512 MB in size.
42        f = open (output, "w")
43        f.truncate (512 * 1024 * 1024)
44        f.close ()
45
46        # Set the trace flag so that we can see each libguestfs call.
47        g.set_trace (1)
48
49        # Set the autosync flag so that the disk will be synchronized
50        # automatically when the libguestfs handle is closed.
51        g.set_autosync (1)
52
53        # Attach the disk image to libguestfs.
54        g.add_drive_opts (output, format = "raw", readonly = 0)
55
56        # Run the libguestfs back-end.
57        g.launch ()
58
59        # Get the list of devices.  Because we only added one drive
60        # above, we expect that this list should contain a single
61        # element.
62        devices = g.list_devices ()
63        assert (len (devices) == 1)
64
65        # Partition the disk as one single MBR partition.
66        g.part_disk (devices[0], "mbr")
67
68        # Get the list of partitions.  We expect a single element, which
69        # is the partition we have just created.
70        partitions = g.list_partitions ()
71        assert (len (partitions) == 1)
72
73        # Create a filesystem on the partition.
74        g.mkfs ("ext4", partitions[0])
75
76        # Now mount the filesystem so that we can add files.
77        g.mount_options ("", partitions[0], "/")
78
79        # Create some files and directories.
80        g.touch ("/empty")
81        message = "Hello, world\n"
82        g.write ("/hello", message)
83        g.mkdir ("/foo")
84
85        # This one uploads the local file /etc/resolv.conf into
86        # the disk image.
87        g.upload ("/etc/resolv.conf", "/foo/resolv.conf")
88
89        # Because 'autosync' was set (above) we can just close the handle
90        # and the disk contents will be synchronized.  You can also do
91        # this manually by calling g.umount_all and g.sync.
92        del g
93

EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

95        # Example showing how to inspect a virtual machine disk.
96
97        import sys
98        import guestfs
99
100        assert (len (sys.argv) == 2)
101        disk = sys.argv[1]
102
103        g = guestfs.GuestFS ()
104
105        # Attach the disk image read-only to libguestfs.
106        g.add_drive_opts (disk, readonly=1)
107
108        # Run the libguestfs back-end.
109        g.launch ()
110
111        # Ask libguestfs to inspect for operating systems.
112        roots = g.inspect_os ()
113        if len (roots) == 0:
114            raise (Error ("inspect_vm: no operating systems found"))
115
116        for root in roots:
117            print "Root device: %s" % root
118
119            # Print basic information about the operating system.
120            print "  Product name: %s" % (g.inspect_get_product_name (root))
121            print "  Version:      %d.%d" % \
122                (g.inspect_get_major_version (root),
123                 g.inspect_get_minor_version (root))
124            print "  Type:         %s" % (g.inspect_get_type (root))
125            print "  Distro:       %s" % (g.inspect_get_distro (root))
126
127            # Mount up the disks, like guestfish -i.
128            #
129            # Sort keys by length, shortest first, so that we end up
130            # mounting the filesystems in the correct order.
131            mps = g.inspect_get_mountpoints (root)
132            def compare (a, b):
133                if len(a[0]) > len(b[0]):
134                    return 1
135                elif len(a[0]) == len(b[0]):
136                    return 0
137                else:
138                    return -1
139            mps.sort (compare)
140            for mp_dev in mps:
141                try:
142                    g.mount_ro (mp_dev[1], mp_dev[0])
143                except RuntimeError as msg:
144                    print "%s (ignored)" % msg
145
146            # If /etc/issue.net file exists, print up to 3 lines.
147            filename = "/etc/issue.net"
148            if g.is_file (filename):
149                print "--- %s ---" % filename
150                lines = g.head_n (3, filename)
151                for line in lines: print line
152
153            # Unmount everything.
154            g.umount_all ()
155

AUTHORS

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

COPYRIGHT

164       Copyright (C) 2010 Red Hat Inc. <http://libguestfs.org/>
165
166       The examples in this manual page may be freely copied, modified and
167       distributed without any restrictions.
168
169       This library is free software; you can redistribute it and/or modify it
170       under the terms of the GNU Lesser General Public License as published
171       by the Free Software Foundation; either version 2 of the License, or
172       (at your option) any later version.
173
174       This library is distributed in the hope that it will be useful, but
175       WITHOUT ANY WARRANTY; without even the implied warranty of
176       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
177       Lesser General Public License for more details.
178
179       You should have received a copy of the GNU Lesser General Public
180       License along with this library; if not, write to the Free Software
181       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
182       02110-1301 USA
183
184
185
186libguestfs-1.8.15                 2011-11-10                 guestfs-python(3)