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/env perl
32
33        # Example showing how to create a disk image.
34
35        use strict;
36        use warnings;
37        use Sys::Guestfs;
38
39        my $output = "disk.img";
40
41        my $g = new Sys::Guestfs ();
42
43        # Create a raw-format sparse disk image, 512 MB in size.
44        $g->disk_create ($output, "raw", 512 * 1024 * 1024);
45
46        # Set the trace flag so that we can see each libguestfs call.
47        $g->set_trace (1);
48
49        # Attach the disk image to libguestfs.
50        $g->add_drive_opts ($output, format => "raw", readonly => 0);
51
52        # Run the libguestfs back-end.
53        $g->launch ();
54
55        # Get the list of devices.  Because we only added one drive
56        # above, we expect that this list should contain a single
57        # element.
58        my @devices = $g->list_devices ();
59        if (@devices != 1) {
60            die "error: expected a single device from list-devices";
61        }
62
63        # Partition the disk as one single MBR partition.
64        $g->part_disk ($devices[0], "mbr");
65
66        # Get the list of partitions.  We expect a single element, which
67        # is the partition we have just created.
68        my @partitions = $g->list_partitions ();
69        if (@partitions != 1) {
70            die "error: expected a single partition from list-partitions";
71        }
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 ($partitions[0], "/");
78
79        # Create some files and directories.
80        $g->touch ("/empty");
81        my $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 we wrote to the disk and we want to detect write
90        # errors, call $g->shutdown.  You don't need to do this:
91        # $g->close will do it implicitly.
92        $g->shutdown ();
93
94        # Note also that handles are automatically closed if they are
95        # reaped by reference counting.  You only need to call close
96        # if you want to close the handle right away.
97        $g->close ();
98

EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

100        #!/usr/bin/env perl
101
102        # Example showing how to inspect a virtual machine disk.
103
104        use strict;
105        use warnings;
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-gobject(3), guestfs-golang(3), guestfs-java(3), guestfs-lua(3),
169       guestfs-ocaml(3), guestfs-python(3), guestfs-recipes(1),
170       guestfs-ruby(3), http://libguestfs.org/.
171

AUTHORS

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

LICENSE

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

BUGS

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