### Run nbdkit ondemand server Source: https://libguestfs.org/nbdkit-ondemand-plugin.1.html Example setup for the server directory and starting the nbdkit process. ```bash mkdir /var/tmp/exports nbdkit ondemand dir=/var/tmp/exports 1G ``` -------------------------------- ### Setup APT Repository and Install Package Source: https://libguestfs.org/virt-builder.1.html Script to mount an ISO, configure an APT repository, and install a package. Requires the ISO to be attached to the build. ```bash mkdir /tmp/mount mount LABEL=EXTRA /tmp/mount apt-cdrom -d=/tmp/mount add apt-get -y install famousdatabase ``` -------------------------------- ### Booting Debian installer via torrent Source: https://libguestfs.org/nbdkit-torrent-plugin.1.html Example of using nbdkit to serve a Debian installer ISO from a torrent and booting it in QEMU. ```bash url=https://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-10.4.0-amd64-DVD-1.iso.torrent wget $url nbdkit torrent debian-*.torrent \ --run 'qemu-system-x86_64 -m 2048 -cdrom "$uri" -boot d' ``` -------------------------------- ### Booting Fedora installer via torrent Source: https://libguestfs.org/nbdkit-torrent-plugin.1.html Example of using nbdkit to serve a Fedora installer ISO from a torrent and booting it in QEMU. ```bash url=https://torrent.fedoraproject.org/torrents/Fedora-Server-dvd-x86_64-32.torrent wget $url nbdkit torrent Fedora-Server-*.torrent \ --run 'qemu-system-x86_64 -m 2048 -cdrom "$uri" -boot d' ``` -------------------------------- ### Interactive Session Example Source: https://libguestfs.org/hivexsh.1.html Example of starting the shell without arguments and loading a hive file manually. ```text $ hivexsh Welcome to hivexsh, the hivex interactive shell for examining Windows Registry binary hive files. Type: 'help' for help with commands 'quit' to quit the shell > load software software\> ``` -------------------------------- ### Basic libguestfs Setup and Launch Source: https://libguestfs.org/guestfs-examples.3.html Demonstrates the fundamental steps to initialize a libguestfs handle, add a read-only drive, and launch the backend. This is a common starting point for many libguestfs operations. ```c #include guestfs_h *g = guestfs_create (); guestfs_add_drive_ro (g, "disk.img"); guestfs_launch (g); ``` ```bash cc prog.c -o prog -lguestfs or: cc prog.c -o prog `pkg-config libguestfs --cflags --libs` ``` -------------------------------- ### Starting with a Prepared Disk Image Source: https://libguestfs.org/guestfish.1.html Example of launching guestfish with a pre-prepared disk image. This is useful when you have a specific disk structure or filesystem already set up. ```shell guestfish disk.img ``` -------------------------------- ### Start nbdkit with example4 plugin Source: https://libguestfs.org/nbdkit-example4-plugin.1.html Use this command to start the nbdkit server with the example4 plugin. The size parameter specifies the disk size in bytes. This is useful for testing and as an example of nbdkit plugins written in Perl. ```bash nbdkit example4 size=1048576 ``` -------------------------------- ### Setup DNF Repository and Install Package Source: https://libguestfs.org/virt-builder.1.html Script to mount an ISO, configure a DNF repository, and install a package. Requires the ISO to be attached to the build. ```bash mkdir /tmp/mount mount LABEL=EXTRA /tmp/mount cat <<'EOF' > /etc/yum.repos.d/extra.repo [extra] name=extra baseurl=file:///tmp/mount enabled=1 EOF dnf -y install famousdatabase ``` -------------------------------- ### Access guest disk with guestfish Source: https://libguestfs.org/nbdkit-libvirt-plugin.1.html Example of starting the plugin and accessing the disk via guestfish in read-only mode. ```bash nbdkit libvirt domain=MyGuest disk=sda guestfish --ro --format=raw -a nbd://localhost ``` -------------------------------- ### Start nbdkit example3 plugin Source: https://libguestfs.org/nbdkit-example3-plugin.1.html Starts the nbdkit server using the example3 plugin with a specified size. ```bash nbdkit example3 [size=SIZE] ``` -------------------------------- ### Example workflow Source: https://libguestfs.org/nbdublk.1.html A complete example of connecting, listing, and disconnecting an NBD device. ```bash # nbdublk /dev/ublkb0 nbd://server ``` ```bash # ublk list dev id 0: nr_hw_queues 4 queue_depth 64 block size 1 dev_capacity 0 max rq size 67108864 daemon pid 32382 flags 0x0 state LIVE ``` ```bash # ublk del -n 0 ``` -------------------------------- ### PXELinux Configuration Example Source: https://libguestfs.org/virt-p2v.1.html Example of how to set kernel command line arguments in a pxelinux.cfg file for physical to virtual machine conversion. ```bash DEFAULT p2v TIMEOUT 20 PROMPT 0 LABEL p2v KERNEL vmlinuz0 APPEND initrd=initrd0.img [....] p2v.server=conv.example.com p2v.password=secret p2v.o=libvirt ``` -------------------------------- ### Complete Environmental Setup within Appliance Source: https://libguestfs.org/nbdkit-linuxdisk-plugin.1.html These commands are executed inside the booted virtual appliance to finalize the environment setup, including installing busybox applets and mounting proc and sysfs. ```bash /sbin/busybox --install mount -t proc proc /proc mount -t sysfs sys /sys ``` -------------------------------- ### Mountinfo File Example Source: https://libguestfs.org/TODO.txt Shows an example of the /proc/self/mountinfo file format, which contains information about mounted filesystems. ```text 16 21 0:3 / /proc rw,relatime - proc /proc rw 17 21 0:16 / /sys rw,relatime - sysfs /sys rw,seclabel 18 23 0:5 / /dev rw,relatime - devtmpfs udev rw,seclabel,size=1906740k,nr_inodes=476685,mode=755 26 21 253:3 / /home rw,relatime - ext4 /dev/mapper/vg_home rw,seclabel,barrier=1,data=ordered ``` -------------------------------- ### Attach ISO and Run Installation Script Source: https://libguestfs.org/virt-builder.1.html Use virt-builder to attach an ISO image and execute an installation script within the guest. ```bash virt-builder fedora-41 \ --attach extra-packages.iso \ --run /tmp/install.sh ``` -------------------------------- ### Install First Boot Script Source: https://libguestfs.org/virt-builder.1.html Installs a script within the guest to be executed automatically when the guest first boots up. ```APIDOC ## --firstboot SCRIPT ### Description Install `SCRIPT` inside the guest, so that when the guest first boots up, the script runs (as root, late in the boot process). The script is automatically chmod +x after installation in the guest. Multiple `--firstboot` options can be used. ### Method Not Applicable (Command-line option) ### Endpoint Not Applicable ### Parameters #### Path Parameters - **SCRIPT** (string) - Required - The path to the script file to be installed and executed in the guest. ### Request Example ``` --firstboot /path/to/guest/script.sh ``` ### Response Not Applicable (Modifies disk image directly) ``` -------------------------------- ### Full Supermin Workflow Example Source: https://libguestfs.org/febootstrap.8.html A complete example demonstrating preparing an appliance, creating an init script, building the appliance, and booting it with QEMU. ```bash supermin --prepare bash util-linux -o /tmp/supermin.d cat > init < #include #include #include int main (int argc, char *argv[]) { struct nbd_handle *nbd; char wbuf[512], rbuf[512]; size_t i; /* Create the libnbd handle. */ nbd = nbd_create (); if (nbd == NULL) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Run nbdkit as a subprocess. */ char *args[] = { "nbdkit", /* You must use ‘-s’ (which tells nbdkit to serve * a single connection on stdin/stdout). */ "-s", /* It is recommended to use ‘--exit-with-parent’ * to ensure nbdkit is always cleaned up even * if the main program crashes. */ "--exit-with-parent", /* Use this to enable nbdkit debugging. */ "-v", /* The nbdkit plugin name - this is a RAM disk. */ "memory", "size=1M", /* Use NULL to terminate the arg list. */ NULL }; if (nbd_connect_command (nbd, args) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Write some random data to the first sector. */ for (i = 0; i < sizeof wbuf; ++i) wbuf[i] = i % 13; if (nbd_pwrite (nbd, wbuf, sizeof wbuf, 0, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Read the first sector back. */ if (nbd_pread (nbd, rbuf, sizeof rbuf, 0, 0) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Close the libnbd handle. */ nbd_close (nbd); /* What was read must be exactly the same as what * was written. */ if (memcmp (rbuf, wbuf, sizeof rbuf) != 0) { fprintf (stderr, "FAILED: " "read data did not match written data\n"); exit (EXIT_FAILURE); } exit (EXIT_SUCCESS); } ``` -------------------------------- ### Configure nbdkit-rate-filter Source: https://libguestfs.org/nbdkit-rate-filter.1.html Examples of starting nbdkit with various rate-limiting configurations. ```bash nbdkit --filter=rate memory 64M rate=1M ``` ```bash nbdkit --filter=rate memory 64M connection-rate=50K ``` ```bash nbdkit --filter=rate memory 64M connection-rate=50K rate=1M ``` ```bash nbdkit --filter=rate memory 64M rate=1M rate-file=/tmp/rate ``` -------------------------------- ### GET inspect-list-applications2 Source: https://libguestfs.org/guestfish.1.html Retrieves a list of applications installed in the operating system. ```APIDOC ## GET inspect-list-applications2 ### Description Returns the list of applications installed in the operating system. Note: This requires prior calls to inspect-os and mounting the disks. ### Method GET ### Endpoint /inspect-list-applications2 ### Parameters #### Path Parameters - **root** (string) - Required - The root filesystem identifier. ### Response #### Success Response (200) - **applications** (list) - A list of application structures containing fields such as app2_name, app2_display_name, app2_version, and app2_install_path. ``` -------------------------------- ### Create and Format a Disk Image Source: https://libguestfs.org/guestfs-examples.3.html Shows how to create a new disk image, partition it, create a filesystem, mount it, and add files. This example covers disk creation, partitioning, filesystem formatting, and basic file operations. ```c /* Example showing how to create a disk image. */ #include #include #include #include #include #include int main (int argc, char *argv[]) { guestfs_h *g; size_t i; g = guestfs_create (); if (g == NULL) { perror ("failed to create libguestfs handle"); exit (EXIT_FAILURE); } /* Set the trace flag so that we can see each libguestfs call. */ guestfs_set_trace (g, 1); /* Create a raw-format sparse disk image, 512 MB in size. */ if (guestfs_disk_create (g, "disk.img", "raw", UINT64_C(512)*1024*1024, -1) == -1) exit (EXIT_FAILURE); /* Add the disk image to libguestfs. */ if (guestfs_add_drive_opts (g, "disk.img", GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw", /* raw format */ GUESTFS_ADD_DRIVE_OPTS_READONLY, 0, /* for write */ -1) /* this marks end of optional arguments */ == -1) exit (EXIT_FAILURE); /* Run the libguestfs back-end. */ if (guestfs_launch (g) == -1) exit (EXIT_FAILURE); /* Get the list of devices. Because we only added one drive * above, we expect that this list should contain a single * element. */ char **devices = guestfs_list_devices (g); if (devices == NULL) exit (EXIT_FAILURE); if (devices[0] == NULL || devices[1] != NULL) { fprintf (stderr, "error: expected a single device from list-devices\n"); exit (EXIT_FAILURE); } /* Partition the disk as one single MBR partition. */ if (guestfs_part_disk (g, devices[0], "mbr") == -1) exit (EXIT_FAILURE); /* Get the list of partitions. We expect a single element, which * is the partition we have just created. */ char **partitions = guestfs_list_partitions (g); if (partitions == NULL) exit (EXIT_FAILURE); if (partitions[0] == NULL || partitions[1] != NULL) { fprintf (stderr, "error: expected a single partition from list-partitions\n"); exit (EXIT_FAILURE); } /* Create a filesystem on the partition. */ if (guestfs_mkfs (g, "ext4", partitions[0]) == -1) exit (EXIT_FAILURE); /* Now mount the filesystem so that we can add files. */ if (guestfs_mount (g, partitions[0], "/") == -1) exit (EXIT_FAILURE); /* Create some files and directories. */ if (guestfs_touch (g, "/empty") == -1) exit (EXIT_FAILURE); const char *message = "Hello, world\n"; if (guestfs_write (g, "/hello", message, strlen (message)) == -1) exit (EXIT_FAILURE); if (guestfs_mkdir (g, "/foo") == -1) exit (EXIT_FAILURE); /* This one uploads the local file /etc/resolv.conf into * the disk image. */ if (guestfs_upload (g, "/etc/resolv.conf", "/foo/resolv.conf") == -1) exit (EXIT_FAILURE); /* Because we wrote to the disk and we want to detect write * errors, call guestfs_shutdown. You don't need to do this: * guestfs_close will do it implicitly. */ if (guestfs_shutdown (g) == -1) exit (EXIT_FAILURE); guestfs_close (g); /* Free up the lists. */ for (i = 0; devices[i] != NULL; ++i) free (devices[i]); free (devices); for (i = 0; partitions[i] != NULL; ++i) free (partitions[i]); free (partitions); exit (EXIT_SUCCESS); } ``` -------------------------------- ### Create and Inspect Disk Image with OCaml Source: https://libguestfs.org/guestfs-ocaml.3.html Example demonstrating how to create a raw disk image, partition it, create a filesystem, mount it, and add files using libguestfs in OCaml. Ensure the /etc/resolv.conf file exists locally. ```ocaml (* Example showing how to create a disk image. *) open Unix open Printf let output = "disk.img" let () = let g = new Guestfs.guestfs () in (* Create a raw-format sparse disk image, 512 MB in size. *) g#disk_create output "raw" (Int64.of_int (512 * 1024 * 1024)); (* Set the trace flag so that we can see each libguestfs call. *) g#set_trace true; (* Attach the disk image to libguestfs. *) g#add_drive_opts ~format:"raw" ~readonly:false output; (* 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. *) let devices = g#list_devices () in if Array.length devices <> 1 then failwith "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. *) let partitions = g#list_partitions () in if Array.length partitions <> 1 then failwith "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"; let message = "Hello, world\n" in g#write "/hello" message; 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 () ``` -------------------------------- ### Example: Exit when a file is created Source: https://libguestfs.org/nbdkit-exitwhen-filter.1.html This example demonstrates how to configure nbdkit to exit gracefully after the file '/tmp/stop' is created. If the file already exists when nbdkit starts, it will exit immediately. ```bash nbdkit --filter=exitwhen memory 1G exit-when-file-created=/tmp/stop ``` -------------------------------- ### Run nbdkit example3 and connect with guestfish Source: https://libguestfs.org/nbdkit-example3-plugin.1.html Starts the plugin with a 1GB size and connects to the resulting NBD export using guestfish. ```bash nbdkit example3 size=1G guestfish --ro --format=raw -a nbd://localhost ``` -------------------------------- ### Configure stride pattern Source: https://libguestfs.org/nbdkit-pattern-plugin.1.html Example of using the stride parameter to place integers at the start of each block. ```text offset data 0000: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 0010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... ... block at offset 0x1000 (4k) ... ↙ 1000: 00 00 00 00 00 00 10 00 00 00 00 00 00 00 00 00 1010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ... ... block at offset 0x2000 (8k) ... ↙ 2000: 00 00 00 00 00 00 20 00 00 00 00 00 00 00 00 00 2010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ``` -------------------------------- ### Serve part of a file Source: https://libguestfs.org/nbdkit-offset-filter.1.html Example of serving a 100M segment of a file starting at a 1M offset. ```bash nbdkit --filter=offset file disk.img offset=1M range=100M ``` -------------------------------- ### QEMU Option to Config File Example Source: https://libguestfs.org/guestfs-hacking.1.html Illustrates the conversion of a QEMU command-line option to its configuration file equivalent. Note the difference in representation for the SMP option. ```text -smp 4 becomes: [smp-opts] cpus = "4" ``` -------------------------------- ### Serve "Hello, world" using nbdkit-data-plugin Source: https://libguestfs.org/nbdkit-data-plugin.1.html Demonstrates serving a raw string and retrieving it via nbdcopy. ```bash $ nbdkit data raw='Hello, world!' --run 'nbdcopy "$uri" - | cat' Hello, world! ``` -------------------------------- ### Create and Partition Disk Image Source: https://libguestfs.org/guestfs-python.3.html Example demonstrating the creation of a raw disk image, partitioning it with MBR, and creating an ext4 filesystem. Ensure to use python_return_dict=True for the GuestFS constructor. ```python # Example showing how to create a disk image. import guestfs output = "disk.img" # All new Python code should pass python_return_dict=True # to the constructor. It indicates that your program wants # to receive Python dicts for methods in the API that return # hashtables. g = guestfs.GuestFS(python_return_dict=True) # Create a raw-format sparse disk image, 512 MB in size. g.disk_create(output, "raw", 512 * 1024 * 1024) # Set the trace flag so that we can see each libguestfs call. g.set_trace(1) # Attach the disk image to libguestfs. g.add_drive_opts(output, format="raw", readonly=0) # 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. devices = g.list_devices() assert (len(devices) == 1) # 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. partitions = g.list_partitions() assert (len(partitions) == 1) # 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") message = "Hello, world\n" g.write("/hello", message) 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 reference counting. You only need to call close # if you want to close the handle right away. g.close() ``` -------------------------------- ### Get volumes in a disk group Source: https://libguestfs.org/guestfish.1.html Requires the ldm feature. Returns volumes for the specified disk group GUID. ```shell ldmtool-diskgroup-volumes diskgroup ``` -------------------------------- ### Boot a newly built guest Source: https://libguestfs.org/guestfs-testing.1.html Boot a guest using qemu-kvm with the disk image created by virt-builder. Ensure the guest boots successfully. ```bash qemu-kvm -cpu host -m 2048 -drive file=disk.img,format=raw ``` -------------------------------- ### Example Output of nbdkit_debug_hexdiff Source: https://libguestfs.org/nbdkit_debug_hexdump.3.html Shows the output format for nbdkit_debug_hexdiff when differences are found between two buffers. Lines starting with '-' show the content of the first buffer, and lines starting with '+' show the content of the second buffer. ```text -00000000: 31 32 33 34 35 36 37 38 31 32 33 34 35 36 37 38 |1234567812345678| +00000000: 39 38 37 36 34 33 32 | 9876 432| ``` -------------------------------- ### Test nbdkit version requirements Source: https://libguestfs.org/nbdkit-probing.1.html Scripting example to programmatically verify if the installed nbdkit meets a minimum version requirement. ```bash $ nbdkit --dump-config | grep ^version_minor version_minor=20 $ major=$( nbdkit --dump-config | grep ^version_major | cut -d= -f2 ) $ minor=$( nbdkit --dump-config | grep ^version_minor | cut -d= -f2 ) $ if [ $major -eq 1 ] && [ $minor -lt 12 ] then echo 'nbdkit >= 1.12 is required'; exit 1; fi ``` -------------------------------- ### Run nbdkit with xz filter Source: https://libguestfs.org/nbdkit-xz-filter.1.html Examples of starting nbdkit with the xz filter using local files or remote URLs. ```bash nbdkit --filter=xz file FILENAME.xz ``` ```bash nbdkit --filter=xz curl https://example.com/FILENAME.xz ``` -------------------------------- ### GET inspect-list-applications Source: https://libguestfs.org/guestfish.1.html Retrieves the list of applications installed in the operating system. Note: This function is deprecated; use inspect-list-applications2 instead. ```APIDOC ## GET inspect-list-applications ### Description Returns the list of applications installed in the operating system. This call requires that the guest OS has been inspected and its disks mounted. ### Method GET ### Endpoint inspect-list-applications ### Parameters #### Path Parameters - **root** (string) - Required - The root device identifier of the guest operating system. ### Response #### Success Response (200) - **app_name** (string) - The name of the application. - **app_display_name** (string) - The display name of the application. - **app_epoch** (integer) - The epoch of the package. - **app_version** (string) - The version string of the application. - **app_release** (string) - The release string of the application. - **app_install_path** (string) - The installation path on the guest OS. - **app_trans_path** (string) - The install path translated into a libguestfs path. - **app_publisher** (string) - The name of the publisher. - **app_url** (string) - The upstream URL of the application. - **app_source_package** (string) - The name of the source package. - **app_summary** (string) - A short description of the application. - **app_description** (string) - A longer description of the application. ``` -------------------------------- ### Install a first-boot script Source: https://libguestfs.org/virt-v2v.1.html Installs a script to be executed when the guest first boots up. The script runs as root and is automatically made executable. Multiple scripts can be added and run in order. ```bash --firstboot SCRIPT ``` -------------------------------- ### Get default VDDK library directory Source: https://libguestfs.org/nbdkit-vddk-plugin.1.html Use this command to find the default directory where the VDDK library is expected to be installed. ```bash $ nbdkit vddk --dump-plugin | grep ^vddk_default_libdir vddk_default_libdir=/usr/lib64/vmware-vix-disklib ``` -------------------------------- ### Example Usage of nbdkit_debug_hexdump in C Source: https://libguestfs.org/nbdkit_debug_hexdump.3.html Demonstrates how to use nbdkit_debug_hexdump to display a string buffer. An optional prefix and starting offset can be provided. ```c char buf[33] = "12345678123456781234567812345678"; nbdkit_debug_hexdump (buf, 32, "data: ", 0); ``` -------------------------------- ### Access boot benchmark documentation Source: https://libguestfs.org/guestfs-performance.1.html Display the manual for the boot-benchmark-range.pl script. ```bash ./boot-benchmark/boot-benchmark-range.pl --man ``` -------------------------------- ### Get Windows dynamic disk group name Source: https://libguestfs.org/guestfish.1.html Requires the ldm feature. The diskgroup parameter must be a GUID obtained from ldmtool-scan. ```shell ldmtool-diskgroup-name diskgroup ``` -------------------------------- ### Create a Raw Disk Image with Ruby and GuestFS Source: https://libguestfs.org/guestfs-ruby.3.html Demonstrates creating a new raw disk image, partitioning it, creating a filesystem, mounting it, and adding files using libguestfs in Ruby. This example requires write access to the output file path. It includes detailed steps for disk manipulation and file operations. ```ruby # Example showing how to create a disk image. require 'guestfs' output = "disk.img" g = Guestfs::Guestfs.new() # Create a raw-format sparse disk image, 512 MB in size. g.disk_create (output, "raw", 512 * 1024 * 1024) # Set the trace flag so that we can see each libguestfs call. g.set_trace(1) # Attach the disk image to libguestfs. g.add_drive_opts(output, :format => "raw") # 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. devices = g.list_devices() if devices.length != 1 then raise "error: expected a single device from list-devices" end # 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. partitions = g.list_partitions() if partitions.length != 1 then raise "error: expected a single partition from list-partitions" end # 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") message = "Hello, world\n" g.write("/hello", message) 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() ``` -------------------------------- ### Get Notes for an OS Version Source: https://libguestfs.org/virt-builder.1.html Before building a VM, check for any specific installation notes or requirements for a particular operating system version. ```bash virt-builder --notes fedora-41 ``` -------------------------------- ### Create initial repository with GPG signing and interactive mode Source: https://libguestfs.org/virt-builder-repository.1.html This example demonstrates creating a new virt-builder repository. It specifies a GPG key for signing the index file and runs in interactive mode to prompt for any missing image metadata. Ensure the folder contains your disk image template files. ```bash virt-builder-repository --gpg-key "joe@hacker.org" -i /path/to/folder ``` -------------------------------- ### QEMU Direct NBD URI Attachment Source: https://libguestfs.org/nbdkit-client.1.html Example of starting an NBD server with nbdkit and then attaching it directly to QEMU using its NBD URI. ```shell $ nbdkit -f -U - --print-uri memory 1G nbd+unix://?socket=/tmp/nbdkitTV6kS8/socket Shell-quoted URI: "nbd+unix://?socket=/tmp/nbdkitTV6kS8/socket" Command to query the NBD endpoint: nbdinfo "nbd+unix://?socket=/tmp/nbdkitTV6kS8/socket" $ qemu-system-x86_64 [...] \ -drive file="nbd+unix://?socket=/tmp/nbdkitTV6kS8/socket",format=raw,if=virtio ``` -------------------------------- ### Get nbdkit Plugindir with pkg-config Source: https://libguestfs.org/nbdkit-plugin.3.html Retrieve the plugin directory path using pkg-config. This variable can be used in Makefiles to correctly install plugins. ```bash PKG_CHECK_VAR([NBDKIT_PLUGINDIR], [nbdkit], [plugindir]) ``` -------------------------------- ### Example: Connect to NBD Server and Get Size Source: https://libguestfs.org/nbd_get_size.3.html This C example demonstrates how to create a libnbd handle, connect to an NBD server via a Unix domain socket, retrieve the export size using nbd_get_size, and print it. Ensure the server is running and accessible. ```c /* This example shows how to connect to an NBD * server and read the size of the disk. * * You can test it with nbdkit like this: * * nbdkit -U - memory 1M \ * --run './get-size $unixsocket' */ #include #include #include #include #include int main (int argc, char *argv[]) { struct nbd_handle *nbd; int64_t size; if (argc != 2) { fprintf (stderr, "%s socket\n", argv[0]); exit (EXIT_FAILURE); } /* Create the libnbd handle. */ nbd = nbd_create (); if (nbd == NULL) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Connect to the NBD server over a * Unix domain socket. */ if (nbd_connect_unix (nbd, argv[1]) == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } /* Read the size in bytes and print it. */ size = nbd_get_size (nbd); if (size == -1) { fprintf (stderr, "%s\n", nbd_get_error ()); exit (EXIT_FAILURE); } printf ("%s: size = %" PRIi64 " bytes\n", argv[1], size); /* Close the libnbd handle. */ nbd_close (nbd); exit (EXIT_SUCCESS); } ``` -------------------------------- ### Create and Populate Disk Image with Go Source: https://libguestfs.org/guestfs-golang.3.html Demonstrates creating a raw disk image, partitioning it, creating a filesystem, and adding files using the libguestfs Go API. Ensure libguestfs is installed and accessible. ```go /* Example showing how to create a disk image. */ package main import ( "fmt" "libguestfs.org/guestfs" ) func main() { output := "disk.img" g, errno := guestfs.Create () if errno != nil { panic (errno) } defer g.Close () /* Create a raw-format sparse disk image, 512 MB in size. */ if err := g.Disk_create (output, "raw", 512 * 1024 * 1024); err != nil { panic (err) } /* Set the trace flag so that we can see each libguestfs call. */ g.Set_trace (true) /* Attach the disk image to libguestfs. */ optargs := guestfs.OptargsAdd_drive{ Format_is_set: true, Format: "raw", Readonly_is_set: true, Readonly: false, } if err := g.Add_drive (output, &optargs); err != nil { panic (err) } /* Run the libguestfs back-end. */ if err := g.Launch (); err != nil { panic (err) } /* Get the list of devices. Because we only added one drive * above, we expect that this list should contain a single * element. */ devices, err := g.List_devices () if err != nil { panic (err) } if len(devices) != 1 { panic ("expected a single device from list-devices") } /* Partition the disk as one single MBR partition. */ err = g.Part_disk (devices[0], "mbr") if err != nil { panic (err) } /* Get the list of partitions. We expect a single element, which * is the partition we have just created. */ partitions, err := g.List_partitions () if err != nil { panic (err) } if len(partitions) != 1 { panic ("expected a single partition from list-partitions") } /* Create a filesystem on the partition. */ err = g.Mkfs ("ext4", partitions[0], nil) if err != nil { panic (err) } /* Now mount the filesystem so that we can add files. */ err = g.Mount (partitions[0], "/") if err != nil { panic (err) } /* Create some files and directories. */ err = g.Touch ("/empty") if err != nil { panic (err) } message := []byte("Hello, world\n") err = g.Write ("/hello", message) if err != nil { panic (err) } err = g.Mkdir ("/foo") if err != nil { panic (err) } /* This one uploads the local file /etc/resolv.conf into * the disk image. */ err = g.Upload ("/etc/resolv.conf", "/foo/resolv.conf") if err != nil { panic (err) } /* 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. */ if err = g.Shutdown (); err != nil { panic (fmt.Sprintf ("write to disk failed: %s", err)) } } ``` -------------------------------- ### Create a Disk Image with Libguestfs Source: https://libguestfs.org/guestfs-lua.3.html This example shows how to create a raw-format sparse disk image, partition it, create an ext4 filesystem, and add files using libguestfs. ```lua -- Example showing how to create a disk image. local G = require "guestfs" local output = "disk.img" local g = G.create () -- Create a raw-format sparse disk image, 512 MB in size. file = io.open (output, "w") file:seek ("set", 512 * 1024 * 1024) file:write (' ') file:close () -- Set the trace flag so that we can see each libguestfs call. g:set_trace (true) -- Attach the disk image to libguestfs. g:add_drive (output, { format = "raw", readonly = false }) -- 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. devices = g:list_devices () if table.getn (devices) ~= 1 then error "expected a single device from list-devices" end -- Partition the disk as one single MBR partition. g:part_disk (devices[1], "mbr") -- Get the list of partitions. We expect a single element, which -- is the partition we have just created. partitions = g:list_partitions () if table.getn (partitions) ~= 1 then error "expected a single partition from list-partitions" end -- Create a filesystem on the partition. g:mkfs ("ext4", partitions[1]) -- Now mount the filesystem so that we can add files. g:mount (partitions[1], "/") -- Create some files and directories. g:touch ("/empty") message = "Hello, world\n" g:write ("/hello", message) 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 () ``` -------------------------------- ### Get NBD Export Name (OCaml) Source: https://libguestfs.org/nbdkit_export_name.3.html The OCaml binding for retrieving the NBD export name. No specific setup is required beyond importing the NBDKit module. ```ocaml NBDKit.export_name : unit -> string ``` -------------------------------- ### SYSLINUX configuration file Source: https://libguestfs.org/guestfs-recipes.1.html Example configuration for the SYSLINUX bootloader. ```text DEFAULT linux LABEL linux SAY Booting the kernel KERNEL vmlinuz INITRD initrd APPEND ro root=/dev/sda3 ``` -------------------------------- ### Copy Wildcarded Host Files Source: https://libguestfs.org/febootstrap.8.html Use wildcards in hostfiles to copy multiple files matching a pattern. Ensure paths start with '/'. Example: `/etc/yum.repos.d/*.repo`. ```bash /etc/yum.repos.d/*.repo ```