1guestfs-ruby(3) Virtualization Support guestfs-ruby(3)
2
6 guestfs-ruby - How to use libguestfs from Ruby
7
9 require 'guestfs'
10 g = Guestfs::Guestfs.new()
11 g.add_drive_opts("disk.img",
12 :readonly => 1, :format => "raw")
13 g.launch()
14
16 This manual page documents how to call libguestfs from the Ruby
17 programming language. This page just documents the differences from
18 the C API and gives some examples. If you are not familiar with using
19 libguestfs, you also need to read guestfs(3).
20 EXCEPTIONS
22 Errors from libguestfs functions are mapped into the "Error" exception.
23 This has a single parameter which is the error message (a string).
24
26 # Example showing how to create a disk image.
27 require 'guestfs'
29 output = "disk.img"
31 g = Guestfs::Guestfs.new()
33 # Create a raw-format sparse disk image, 512 MB in size.
35 File.open(output, "w") {
36 |f| f.truncate(512 * 1024 * 1024)
37 }
38 # Set the trace flag so that we can see each libguestfs call.
40 g.set_trace(1)
41 # Set the autosync flag so that the disk will be synchronized
43 # automatically when the libguestfs handle is closed.
44 g.set_autosync(1)
45 # Attach the disk image to libguestfs.
47 g.add_drive_opts(output, :format => "raw")
48 # Run the libguestfs back-end.
50 g.launch();
51 # Get the list of devices. Because we only added one drive
53 # above, we expect that this list should contain a single
54 # element.
55 devices = g.list_devices()
56 if devices.length != 1 then
57 raise "error: expected a single device from list-devices"
58 end
59 # Partition the disk as one single MBR partition.
61 g.part_disk(devices[0], "mbr")
62 # Get the list of partitions. We expect a single element, which
64 # is the partition we have just created.
65 partitions = g.list_partitions()
66 if partitions.length != 1 then
67 raise "error: expected a single partition from list-partitions"
68 end
69 # Create a filesystem on the partition.
71 g.mkfs("ext4", partitions[0])
72 # Now mount the filesystem so that we can add files.
74 g.mount_options("", partitions[0], "/")
75 # Create some files and directories.
77 g.touch("/empty")
78 message = "Hello, world\n"
79 g.write("/hello", message)
80 g.mkdir("/foo")
81 # This one uploads the local file /etc/resolv.conf into
83 # the disk image.
84 g.upload("/etc/resolv.conf", "/foo/resolv.conf")
85 # Because 'autosync' was set (above) we can just close the handle
87 # and the disk contents will be synchronized. You can also do
88 # this manually by calling g#umount_all and g#sync.
89 g.close()
90
92 # Example showing how to inspect a virtual machine disk.
93 require 'guestfs'
95 if ARGV.length == 0
97 puts "usage: inspect_vm disk.img"
98 exit 1
99 end
100 disk = ARGV[0]
101 g = Guestfs::Guestfs.new()
103 # Attach the disk image read-only to libguestfs.
105 g.add_drive_opts(disk, :readonly => 1)
106 # Run the libguestfs back-end.
108 g.launch()
109 # Ask libguestfs to inspect for operating systems.
111 roots = g.inspect_os()
112 if roots.length == 0
113 puts "inspect_vm: no operating systems found"
114 exit 1
115 end
116 for root in roots do
118 printf("Root device: %s\n", root)
119 # Print basic information about the operating system.
121 printf(" Product name: %s\n", g.inspect_get_product_name(root))
122 printf(" Version: %d.%d\n",
123 g.inspect_get_major_version(root),
124 g.inspect_get_minor_version(root))
125 printf(" Type: %s\n", g.inspect_get_type(root))
126 printf(" Distro: %s\n", g.inspect_get_distro(root))
127 # Mount up the disks, like guestfish -i.
129 #
130 # Sort keys by length, shortest first, so that we end up
131 # mounting the filesystems in the correct order.
132 mps = g.inspect_get_mountpoints(root)
133 mps = mps.sort {|a,b| a[0].length <=> b[0].length}
134 for mp in mps do
135 begin
136 g.mount_ro(mp[1], mp[0])
137 rescue Guestfs::Error => msg
138 printf("%s (ignored)\n", msg)
139 end
140 end
141 # If /etc/issue.net file exists, print up to 3 lines.
143 filename = "/etc/issue.net"
144 if g.is_file filename then
145 printf("--- %s ---\n", filename)
146 lines = g.head_n(3, filename)
147 for line in lines do
148 puts line
149 end
150 end
151 # Unmount everything.
153 g.umount_all()
154 end
155
157 guestfs(3), guestfs-examples(3), guestfs-ocaml(3), guestfs-python(3),
158 <http://libguestfs.org/>.
159
161 Richard W.M. Jones ("rjones at redhat dot com")
162
164 Copyright (C) 2010 Red Hat Inc. <http://libguestfs.org/>
165 The examples in this manual page may be freely copied, modified and
167 distributed without any restrictions.
168 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 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 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
183libguestfs-1.8.15 2011-11-10 guestfs-ruby(3)