1guestfs-java(3) Virtualization Support guestfs-java(3)
2
6 guestfs-java - How to use libguestfs from Java
7
9 import com.redhat.et.libguestfs.*;
10 GuestFS g = new GuestFS ();
12 g.add_drive ("disk.img",
13 new HashMap<String,Object>() {
14 {
15 put ("readonly", Boolean.TRUE);
16 put ("format", "raw");
17 }
18 });
19 g.launch ();
20
22 This manual page documents how to call libguestfs from the Java
23 programming language. This page just documents the differences from
24 the C API and gives some examples. If you are not familiar with using
25 libguestfs, you also need to read guestfs(3).
26 CLOSING THE HANDLE
28 The handle is closed when it is reaped by the garbage collector.
29 Because libguestfs handles include a lot of state, it is also possible
30 to close (and hence free) them explicitly by calling the "close"
31 method.
32 EXCEPTIONS
34 Errors from libguestfs functions are mapped into the
35 "LibGuestFSException" exception. This has a single parameter which is
36 the error message (a "String").
37 Calling any method on a closed handle raises the same exception.
39 EVENTS
41 The libguestfs event API is fully supported from Java. Create a class
42 which implements the "EventCallback" interface, create an instance of
43 this class, and then call the "GuestFS#set_event_callback" method to
44 register this instance. The "event" method of the class is called when
45 libguestfs generates an event.
46 For example, this will print all trace events:
48 GuestFS g = new GuestFS ();
50 g.set_trace (true);
51 g.set_event_callback (
52 new EventCallback () {
53 public void event (long event, int eh,
54 String buffer, long[] array) {
55 System.out.println (GuestFS.eventToString (event) +
56 ": " + buffer);
57 }
58 },
59 GuestFS.EVENT_TRACE);
60 g.add_drive_ro ("disk.img");
61 // etc.
62 The output looks similar to this:
64 EVENT_TRACE: add_drive_ro "disk.img"
66 EVENT_TRACE: add_drive_ro = 0
67 // etc.
68
70 // Example showing how to create a disk image.
71 import java.io.*;
73 import java.util.Map;
74 import java.util.HashMap;
75 import com.redhat.et.libguestfs.*;
76 public class CreateDisk
78 {
79 static String output = "disk.img";
80 public static void main (String[] argv)
82 {
83 try {
84 GuestFS g = new GuestFS ();
85 // Create a raw-format sparse disk image, 512 MB in size.
87 RandomAccessFile f = new RandomAccessFile (output, "rw");
88 f.setLength (512 * 1024 * 1024);
89 f.close ();
90 // Set the trace flag so that we can see each libguestfs call.
92 g.set_trace (true);
93 // Attach the disk image to libguestfs.
95 Map<String, Object> optargs = new HashMap<String, Object>() {
96 {
97 put ("format", "raw");
98 put ("readonly", Boolean.FALSE);
99 }
100 };
101 g.add_drive_opts (output, optargs);
102 // Run the libguestfs back-end.
104 g.launch ();
105 // Get the list of devices. Because we only added one drive
107 // above, we expect that this list should contain a single
108 // element.
109 String[] devices = g.list_devices ();
110 if (devices.length != 1)
111 throw new Error ("expected a single device from list-devices");
112 // Partition the disk as one single MBR partition.
114 g.part_disk (devices[0], "mbr");
115 // Get the list of partitions. We expect a single element, which
117 // is the partition we have just created.
118 String[] partitions = g.list_partitions ();
119 if (partitions.length != 1)
120 throw new Error ("expected a single partition from list-partitions");
121 // Create a filesystem on the partition.
123 g.mkfs ("ext4", partitions[0]);
124 // Now mount the filesystem so that we can add files.
126 g.mount (partitions[0], "/");
127 // Create some files and directories.
129 g.touch ("/empty");
130 String message = "Hello, world\n";
131 g.write ("/hello", message.getBytes());
132 g.mkdir ("/foo");
133 // This one uploads the local file /etc/resolv.conf into
135 // the disk image.
136 g.upload ("/etc/resolv.conf", "/foo/resolv.conf");
137 // Because we wrote to the disk and we want to detect write
139 // errors, call g.shutdown. You don't need to do this:
140 // g.close will do it implicitly.
141 g.shutdown ();
142 // Note also that handles are automatically closed if they are
144 // reaped by the garbage collector. You only need to call close
145 // if you want to close the handle right away.
146 g.close ();
147 }
148 catch (Exception exn) {
149 System.err.println (exn);
150 System.exit (1);
151 }
152 }
153 }
154
156 // Example showing how to inspect a virtual machine disk.
157 import java.util.ArrayList;
159 import java.util.Collections;
160 import java.util.Comparator;
161 import java.util.HashMap;
162 import java.util.List;
163 import java.util.Map;
164 import com.redhat.et.libguestfs.*;
165 public class InspectVM
167 {
168 static final Comparator<String> COMPARE_KEYS_LEN =
169 new Comparator<String>() {
170 public int compare (String k1, String k2) {
171 return k1.length() - k2.length();
172 }
173 };
174 public static void main (String[] argv)
176 {
177 try {
178 if (argv.length != 1)
179 throw new Error ("usage: InspectVM disk.img");
180 String disk = argv[0];
182 GuestFS g = new GuestFS ();
184 // Attach the disk image read-only to libguestfs.
186 Map<String, Object> optargs = new HashMap<String, Object>() {
187 {
188 //put ("format", "raw");
189 put ("readonly", Boolean.TRUE);
190 }
191 };
192 g.add_drive_opts (disk, optargs);
194 // Run the libguestfs back-end.
196 g.launch ();
197 // Ask libguestfs to inspect for operating systems.
199 String roots[] = g.inspect_os ();
200 if (roots.length == 0)
201 throw new Error ("inspect_vm: no operating systems found");
202 for (String root : roots) {
204 System.out.println ("Root device: " + root);
205 // Print basic information about the operating system.
207 System.out.println (" Product name: " +
208 g.inspect_get_product_name (root));
209 System.out.println (" Version: " +
210 g.inspect_get_major_version (root) +
211 "." +
212 g.inspect_get_minor_version (root));
213 System.out.println (" Type: " +
214 g.inspect_get_type (root));
215 System.out.println (" Distro: " +
216 g.inspect_get_distro (root));
217 // Mount up the disks, like guestfish -i.
219 //
220 // Sort keys by length, shortest first, so that we end up
221 // mounting the filesystems in the correct order.
222 Map<String,String> mps = g.inspect_get_mountpoints (root);
223 List<String> mps_keys = new ArrayList (mps.keySet ());
224 Collections.sort (mps_keys, COMPARE_KEYS_LEN);
225 for (String mp : mps_keys) {
227 String dev = mps.get (mp);
228 try {
229 g.mount_ro (dev, mp);
230 }
231 catch (Exception exn) {
232 System.err.println (exn + " (ignored)");
233 }
234 }
235 // If /etc/issue.net file exists, print up to 3 lines.
237 String filename = "/etc/issue.net";
238 if (g.is_file (filename)) {
239 System.out.println ("--- " + filename + " ---");
240 String[] lines = g.head_n (3, filename);
241 for (String line : lines)
242 System.out.println (line);
243 }
244 // Unmount everything.
246 g.umount_all ();
247 }
248 }
249 catch (Exception exn) {
250 System.err.println (exn);
251 System.exit (1);
252 }
253 }
254 }
255
257 guestfs(3), guestfs-examples(3), guestfs-erlang(3), guestfs-lua(3),
258 guestfs-ocaml(3), guestfs-perl(3), guestfs-python(3),
259 guestfs-recipes(1), guestfs-ruby(3), http://libguestfs.org/,
260 http://caml.inria.fr/.
261
263 Richard W.M. Jones ("rjones at redhat dot com")
264
266 Copyright (C) 2011-2012 Red Hat Inc.
267
269 This manual page contains examples which we hope you will use in your
270 programs. The examples may be freely copied, modified and distributed
271 for any purpose without any restrictions.
272
274 To get a list of bugs against libguestfs, use this link:
275 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
276 To report a new bug against libguestfs, use this link:
278 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
279 When reporting a bug, please supply:
281 · The version of libguestfs.
283 · Where you got libguestfs (eg. which Linux distro, compiled from
285 source, etc)
286 · Describe the bug accurately and give a way to reproduce it.
288 · Run libguestfs-test-tool(1) and paste the complete, unedited output
290 into the bug report.
291libguestfs-1.20.11 2013-08-27 guestfs-java(3)