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

NAME

6       guestfs-perl - How to use libguestfs from Perl
7

SYNOPSIS

9        use Sys::Guestfs;
10
11        my $g = Sys::Guestfs->new ();
12        $g->add_drive_opts ('guest.img', format => 'raw');
13        $g->launch ();
14        $g->mount ('/dev/sda1', '/');
15        $g->touch ('/hello');
16        $g->shutdown ();
17        $g->close ();
18

DESCRIPTION

20       This manual page documents how to call libguestfs from the Perl
21       programming language.  This page just documents the differences from
22       the C API and gives some examples.  If you are not familiar with using
23       libguestfs, you also need to read guestfs(3).  To read the full Perl
24       API, see Sys::Guestfs(3).
25
26   ERRORS
27       Errors from libguestfs functions turn into calls to "croak" (see
28       Carp(3)).
29

EXAMPLE 1: CREATE A DISK IMAGE

31        #!/usr/bin/perl -w
32
33        # Example showing how to create a disk image.
34
35        use strict;
36        use Sys::Guestfs;
37
38        my $output = "disk.img";
39
40        my $g = new Sys::Guestfs ();
41
42        # Create a raw-format sparse disk image, 512 MB in size.
43        open FILE, ">$output" or die "$output: $!";
44        truncate FILE, 512 * 1024 * 1024 or die "$output: truncate: $!";
45        close FILE or die "$output: $!";
46
47        # Set the trace flag so that we can see each libguestfs call.
48        $g->set_trace (1);
49
50        # Attach the disk image to libguestfs.
51        $g->add_drive_opts ($output, format => "raw", readonly => 0);
52
53        # Run the libguestfs back-end.
54        $g->launch ();
55
56        # Get the list of devices.  Because we only added one drive
57        # above, we expect that this list should contain a single
58        # element.
59        my @devices = $g->list_devices ();
60        if (@devices != 1) {
61            die "error: expected a single device from list-devices";
62        }
63
64        # Partition the disk as one single MBR partition.
65        $g->part_disk ($devices[0], "mbr");
66
67        # Get the list of partitions.  We expect a single element, which
68        # is the partition we have just created.
69        my @partitions = $g->list_partitions ();
70        if (@partitions != 1) {
71            die "error: expected a single partition from list-partitions";
72        }
73
74        # Create a filesystem on the partition.
75        $g->mkfs ("ext4", $partitions[0]);
76
77        # Now mount the filesystem so that we can add files.
78        $g->mount ($partitions[0], "/");
79
80        # Create some files and directories.
81        $g->touch ("/empty");
82        my $message = "Hello, world\n";
83        $g->write ("/hello", $message);
84        $g->mkdir ("/foo");
85
86        # This one uploads the local file /etc/resolv.conf into
87        # the disk image.
88        $g->upload ("/etc/resolv.conf", "/foo/resolv.conf");
89
90        # Because we wrote to the disk and we want to detect write
91        # errors, call $g->shutdown.  You don't need to do this:
92        # $g->close will do it implicitly.
93        $g->shutdown ();
94
95        # Note also that handles are automatically closed if they are
96        # reaped by reference counting.  You only need to call close
97        # if you want to close the handle right away.
98        $g->close ();
99

EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

101        #!/usr/bin/perl -w
102
103        # Example showing how to inspect a virtual machine disk.
104
105        use strict;
106        use Sys::Guestfs;
107
108        if (@ARGV < 1) {
109            die "usage: inspect_vm disk.img"
110        }
111
112        my $disk = $ARGV[0];
113
114        my $g = new Sys::Guestfs ();
115
116        # Attach the disk image read-only to libguestfs.
117        # You could also add an optional format => ... argument here.  This is
118        # advisable since automatic format detection is insecure.
119        $g->add_drive_opts ($disk, readonly => 1);
120
121        # Run the libguestfs back-end.
122        $g->launch ();
123
124        # Ask libguestfs to inspect for operating systems.
125        my @roots = $g->inspect_os ();
126        if (@roots == 0) {
127            die "inspect_vm: no operating systems found";
128        }
129
130        for my $root (@roots) {
131            printf "Root device: %s\n", $root;
132
133            # Print basic information about the operating system.
134            printf "  Product name: %s\n", $g->inspect_get_product_name ($root);
135            printf "  Version:      %d.%d\n",
136                $g->inspect_get_major_version ($root),
137                $g->inspect_get_minor_version ($root);
138            printf "  Type:         %s\n", $g->inspect_get_type ($root);
139            printf "  Distro:       %s\n", $g->inspect_get_distro ($root);
140
141            # Mount up the disks, like guestfish -i.
142            #
143            # Sort keys by length, shortest first, so that we end up
144            # mounting the filesystems in the correct order.
145            my %mps = $g->inspect_get_mountpoints ($root);
146            my @mps = sort { length $a <=> length $b } (keys %mps);
147            for my $mp (@mps) {
148                eval { $g->mount_ro ($mps{$mp}, $mp) };
149                if ($@) {
150                    print "$@ (ignored)\n"
151                }
152            }
153
154            # If /etc/issue.net file exists, print up to 3 lines.
155            my $filename = "/etc/issue.net";
156            if ($g->is_file ($filename)) {
157                printf "--- %s ---\n", $filename;
158                my @lines = $g->head_n (3, $filename);
159                print "$_\n" foreach @lines;
160            }
161
162            # Unmount everything.
163            $g->umount_all ()
164        }
165

SEE ALSO

167       Sys::Guestfs(3), guestfs(3), guestfs-examples(3), guestfs-erlang(3),
168       guestfs-java(3), guestfs-lua(3), guestfs-ocaml(3), guestfs-python(3),
169       guestfs-recipes(1), guestfs-ruby(3), http://libguestfs.org/.
170

AUTHORS

172       Richard W.M. Jones ("rjones at redhat dot com")
173
175       Copyright (C) 2011-2012 Red Hat Inc.
176

LICENSE

178       This manual page contains examples which we hope you will use in your
179       programs.  The examples may be freely copied, modified and distributed
180       for any purpose without any restrictions.
181

BUGS

183       To get a list of bugs against libguestfs, use this link:
184       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
185
186       To report a new bug against libguestfs, use this link:
187       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
188
189       When reporting a bug, please supply:
190
191       ·   The version of libguestfs.
192
193       ·   Where you got libguestfs (eg. which Linux distro, compiled from
194           source, etc)
195
196       ·   Describe the bug accurately and give a way to reproduce it.
197
198       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
199           into the bug report.
200
201
202
203libguestfs-1.20.11                2013-08-27                   guestfs-perl(3)
Impressum