guestfs-java(3)

📦
version 1.60.1 · 7 versions
, in ubuntu stonking

💖 NAME 💖

guestfs-java — how to use libguestfs from Java, bestie. That's the whole thing. That's the vibe. 💅

(It lives in the Virtualization Support corner of your man pages, and yes, we're calling it guestfs-java(3) around here. 🎀)

✨ SYNOPSIS ✨

import com.redhat.et.libguestfs.*;

GuestFS g = new GuestFS ();
g.add_drive ("disk.img",
             new HashMap<String,Object>() {
               {
                   put ("readonly", Boolean.TRUE);
                   put ("format", "raw");
               }
             });
g.launch ();

Like… look at her go. 🦋

🌸 DESCRIPTION 🌸

Okay so this manual page documents how to call libguestfs from the Java programming language. It only covers the differences from the C API and throws in some examples, because that's the assignment. If libguestfs is brand new to you, bestie, you also need to read guestfs(3). No skipping. 🙈

🎀 CLOSING THE HANDLE 🎀

The handle gets closed when it's reaped by the garbage collector. Iconic, automatic, love that for us.

But — and here's the thing — because libguestfs handles carry around a lot of state, you can also close them (and therefore free them) explicitly, by calling the close method. Your handle, your rules. 💅

💀 EXCEPTIONS 💀

Errors from libguestfs functions get mapped into the LibGuestFSException exception. It takes a single parameter, and that parameter is the error message (a String). One (1) parameter. Not two. Don't try it.

Calling any method on a closed handle raises that exact same exception. Yes, even that one. Yes, even if you really wanted it to work.

And if malloc(3) or some other allocation fails inside the bindings? Boom — the LibGuestFSOutOfMemory exception gets thrown. 😭

🌈 EVENTS 🌈

The libguestfs event API is fully supported from Java. So here's the recipe, step by step:

  1. Create a class which implements the EventCallback interface.
  2. Create an instance of this class.
  3. Call the GuestFS#set_event_callback method to register this instance.

Then the event method of the class gets called whenever libguestfs generates an event. Obsessed, actually.

For example, this will print all trace events:

GuestFS g = new GuestFS ();
g.set_trace (true);
g.set_event_callback (
  new EventCallback () {
    public void event (long event, int eh,
                       String buffer, long[] array) {
      System.out.println (GuestFS.eventToString (event) +
                          ": " + buffer);
    }
  },
  GuestFS.EVENT_TRACE);
g.add_drive_ro ("disk.img");
// etc.

And the output looks similar to this:

EVENT_TRACE: add_drive_ro "disk.img"
EVENT_TRACE: add_drive_ro = 0
// etc.

💅 OPTIONAL ARGUMENTS 💅

Some methods take an optional map of optional parameters. The classic example is g.add_drive, which you can call in one of two ways.

Way one, no extras:

g.add_drive ("disk.img");

Way two, with optional arguments:

Map<String, Object> optargs =
  new HashMap<String, Object>() {
  {
    put ("readonly", Boolean.TRUE);
    put ("format", "raw");
  }
};
g.add_drive ("disk.img", optargs);

Want the full lore on this topic? See "CALLS WITH OPTIONAL ARGUMENTS" in guestfs(3). 🫶

🍓 Optional handle parameters 🍓

When you're creating the handle you can also pass a map of optional parameters:

Map<String, Object> optargs =
  new HashMap<String, Object>() {
  {
    put ("close_on_exit", Boolean.FALSE);
    put ("environment", Boolean.TRUE);
  }
};
GuestFS g = new GuestFS (optargs);

For more information, see "guestfs_create_flags" in guestfs(3). 💜

🔥 COMPILING AND RUNNING 🔥

Libguestfs for Java is a Java Native Interface (JNI) extension, and it's supplied in three parts. Let's meet the squad:

  • libguestfs.jar, libguestfs-VERSION.jar — the pure Java JAR file, which contains several classes, the primary one being com.redhat.et.libguestfs.GuestFS. Upstream, the JAR file contains a version number in the filename, but some Linux distros may rename it without the version number. (Distro behaviour. Whatever. 💀)
  • libguestfs_jni.so — the JNI code (written in C). This contains private native functions that interface between Java code and the regular libguestfs C library. You should not call these directly. Do not. We're serious. 🙈
  • libguestfs.so — the regular libguestfs C library.

To compile your Java program, you need to locate the JAR file and add it to the class path. For example:

export CLASSPATH=/usr/share/java/libguestfs.jar
javac MyProgram.java

To run your Java program, you also need to make sure the JAR file is on the class path, as well as the path of your program. For example:

export CLASSPATH=.:/usr/share/java/libguestfs.jar
java MyProgram

⭐ EXAMPLE 1: CREATE A DISK IMAGE ⭐

Okay, here's the full main-character example. Every line. Verbatim. Because we don't gatekeep. 👑

// Example showing how to create a disk image.

import java.io.*;
import java.util.Map;
import java.util.HashMap;
import com.redhat.et.libguestfs.*;

public class CreateDisk
{
    static String output = "disk.img";

    public static void main (String[] argv)
    {
        try {
            GuestFS g = new GuestFS ();

            // Create a raw-format sparse disk image, 512 MB in size.
            RandomAccessFile f = new RandomAccessFile (output, "rw");
            f.setLength (512 * 1024 * 1024);
            f.close ();

            // Set the trace flag so that we can see each libguestfs call.
            g.set_trace (true);

            // Attach the disk image to libguestfs.
            @SuppressWarnings("serial") Map<String, Object> optargs =
                new HashMap<String, Object>() {
                {
                    put ("format", "raw");
                    put ("readonly", Boolean.FALSE);
                }
            };
            g.add_drive_opts (output, optargs);

            // Run the libguestfs back-end.
            g.launch ();

            // Get the list of devices.  Because we only added one drive
            // above, we expect that this list should contain a single
            // element.
            String[] devices = g.list_devices ();
            if (devices.length != 1)
                throw new Error ("expected a single device from list-devices");

            // Partition the disk as one single MBR partition.
            g.part_disk (devices[0], "mbr");

            // Get the list of partitions.  We expect a single element, which
            // is the partition we have just created.
            String[] partitions = g.list_partitions ();
            if (partitions.length != 1)
                throw new Error ("expected a single partition from list-partitions");

            // Create a filesystem on the partition.
            g.mkfs ("ext4", partitions[0]);

            // Now mount the filesystem so that we can add files.
            g.mount (partitions[0], "/");

            // Create some files and directories.
            g.touch ("/empty");
            String message = "Hello, world\n";
            g.write ("/hello", message.getBytes());
            g.mkdir ("/foo");

            // This one uploads the local file /etc/resolv.conf into
            // the disk image.
            g.upload ("/etc/resolv.conf", "/foo/resolv.conf");

            // Because we wrote to the disk and we want to detect write
            // errors, call g.shutdown.  You don't need to do this:
            // g.close will do it implicitly.
            g.shutdown ();

            // Note also that handles are automatically closed if they are
            // reaped by the garbage collector.  You only need to call close
            // if you want to close the handle right away.
            g.close ();
        }
        catch (Exception exn) {
            System.err.println (exn);
            System.exit (1);
        }
    }
}

🔍 EXAMPLE 2: INSPECT A VIRTUAL MACHINE DISK IMAGE

okay bestie this one is the moment, the main character energy of the whole page — we're gonna peek inside a VM disk and figure out what OS is hiding in there 🕵️‍♀️💖

// Example showing how to inspect a virtual machine disk.

import java.util.ArrayList;
import java.util.Collections;
import java.util.Comparator;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.redhat.et.libguestfs.*;

public class InspectVM
{
    static final Comparator<String> COMPARE_KEYS_LEN =
        new Comparator<String>() {
        public int compare (String k1, String k2) {
            return k1.length() - k2.length();
        }
    };

    public static void main (String[] argv)
    {
        try {
            if (argv.length != 1)
                throw new Error ("usage: InspectVM disk.img");

            String disk = argv[0];

            GuestFS g = new GuestFS ();

            // Attach the disk image read-only to libguestfs.
            @SuppressWarnings("serial") Map<String, Object> optargs =
                new HashMap<String, Object>() {
                {
                    //put ("format", "raw");
                    put ("readonly", Boolean.TRUE);
                }
            };

            g.add_drive_opts (disk, optargs);

            // Run the libguestfs back-end.
            g.launch ();

            // Ask libguestfs to inspect for operating systems.
            String roots[] = g.inspect_os ();
            if (roots.length == 0)
                throw new Error ("inspect_vm: no operating systems found");

            for (String root : roots) {
                System.out.println ("Root device: " + root);

                // Print basic information about the operating system.
                System.out.println ("  Product name: " +
                                    g.inspect_get_product_name (root));
                System.out.println ("  Version:      " +
                                    g.inspect_get_major_version (root) +
                                    "." +
                                    g.inspect_get_minor_version (root));
                System.out.println ("  Type:         " +
                                    g.inspect_get_type (root));
                System.out.println ("  Distro:       " +
                                    g.inspect_get_distro (root));

                // Mount up the disks, like guestfish -i.
                //
                // Sort keys by length, shortest first, so that we end up
                // mounting the filesystems in the correct order.
                Map<String,String> mps = g.inspect_get_mountpoints (root);
                List<String> mps_keys = new ArrayList<String> (mps.keySet ());
                Collections.sort (mps_keys, COMPARE_KEYS_LEN);

                for (String mp : mps_keys) {
                    String dev = mps.get (mp);
                    try {
                        g.mount_ro (dev, mp);
                    }
                    catch (Exception exn) {
                        System.err.println (exn + " (ignored)");
                    }
                }

                // If /etc/issue.net file exists, print up to 3 lines.
                String filename = "/etc/issue.net";
                if (g.is_file (filename)) {
                    System.out.println ("--- " + filename + " ---");
                    String[] lines = g.head_n (3, filename);
                    for (String line : lines)
                        System.out.println (line);
                }

                // Unmount everything.
                g.umount_all ();
            }
        }
        catch (Exception exn) {
            System.err.println (exn);
            System.exit (1);
        }
    }
}

like… the way inspect_os() just knows what operating systems are on the disk? iconic. no notes. 💅

👀 SEE ALSO

go read these too bestie, they're all part of the fam 🫶

👑 AUTHORS

This one was written by Richard W.M. Jones (rjones at redhat dot com). king behaviour, honestly ✨

Copyright (C) 2011-2025 Red Hat Inc.

🎀 LICENSE

okay so here's the sweet part: this manual page contains examples which we hope you will use in your programs. The examples may be freely copied, modified and distributed for any purpose without any restrictions. no cap. go wild. it's yours. 🦋

🐛 BUGS

found a bug? we wanna know, fr fr 💜

To get a list of bugs against libguestfs, use this link:

https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link:

https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

  • The version of libguestfs.
  • Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
  • Describe the bug accurately and give a way to reproduce it.
  • Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.
bestie listen — that last one is not optional. paste the complete, unedited output. do not trim it, do not crop it, do not "clean it up". the whole thing. 🙈

okay that's the whole page, we made it to the end, absolutely ate 💅 this is libguestfs-1.60.1, dated 2026-07-14, and it's the guestfs-java(3) page 🌸 thank you for coming to my ted talk, now go inspect some disks bestie 🦋💖

📦 where this page comes from