libguestfs

https://libguestfs.org/
Admin
libguestfs is a set of tools and C library for accessing, inspecting, and modifying virtual machine...
Tokens:821,466
Snippets:10,822
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### 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
```

--------------------------------

### 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\>
```

--------------------------------

### 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'
```

--------------------------------

### 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'
```

--------------------------------

### 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>

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`
```

--------------------------------

### 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
```

--------------------------------

### QEMU Config Example

Source: https://libguestfs.org/guestfs-hacking.1.html

Example of how a simple QEMU option maps to a configuration file format.

```text
 [smp-opts]
   cpus = "4"
```

--------------------------------

### 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
```

--------------------------------

### 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 <<EOF
 #!/bin/sh
 mount -t proc /proc /proc
 mount -t sysfs /sys /sys
 echo Welcome to supermin
 bash -i
 EOF
 
 chmod +x init
 tar zcf /tmp/supermin.d/init.tar.gz ./init
 
 supermin --build /tmp/supermin.d -f ext2 -o /tmp/appliance.d
 
 qemu-kvm -nodefaults -nographic \
          -kernel /tmp/appliance.d/kernel \
          -initrd /tmp/appliance.d/initrd \
          -hda /tmp/appliance.d/root \
          -serial stdio -append "console=ttyS0 root=/dev/sda"
 ...
 Welcome to supermin
 bash-4.3# 
```

--------------------------------

### 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
```

--------------------------------

### Install packages at first boot

Source: https://libguestfs.org/virt-builder.1.html

Defers package installation until the guest boots, utilizing the guest's own network connection.

```bash
 virt-builder fedora-41 --firstboot-install inkscape
```

--------------------------------

### Install SYSLINUX bootloader

Source: https://libguestfs.org/guestfs-recipes.1.html

Commands to upload the MBR and configuration, then install the bootloader on a disk image.

```bash
 guestfish -a disk.img -i
 # Upload the master boot record and configuration file:
 ><fs> upload ..../mbr.bin /boot/mbr.bin
 ><fs> upload ..../syslinux.cfg /boot/syslinux.cfg
 # Put the MBR into the boot sector:
 ><fs> copy-file-to-device /boot/mbr.bin /dev/sda size:440
 # Install syslinux on the first partition:
 ><fs> extlinux /boot
 # Set the first partition as bootable:
 ><fs> part-set-bootable /dev/sda 1 true
```

--------------------------------

### Attach and run side repository installation

Source: https://libguestfs.org/virt-builder.1.html

Attaches the ISO image and executes the installation script within the guest.

```bash
 virt-builder fedora-41 \
   --attach extra-packages.iso \
   --run /tmp/install.sh
```

--------------------------------

### Get GPT partition type GUID

Source: https://libguestfs.org/guestfish.1.html

Retrieves the type GUID for a specific numbered GPT partition.

```guestfish
 part-get-gpt-type device partnum
```

--------------------------------

### Synopsis Example

Source: https://libguestfs.org/guestfs-python.3.html

A basic synopsis showing the initialization of GuestFS and adding a drive.

```python
import guestfs
g = guestfs.GuestFS(python_return_dict=True)
g.add_drive_opts("disk.img", format="raw", readonly=1)
g.launch()
```

--------------------------------

### Get GPT partition GUID

Source: https://libguestfs.org/guestfish.1.html

Retrieves the unique GUID associated with a specific numbered GPT partition.

```text
 part-get-gpt-guid device partnum
```

--------------------------------

### Install and Load Plugin by Path

Source: https://libguestfs.org/nbdkit-plugin.3.html

Install your plugin as a .so file. Users can load it by providing the full path to the plugin file when running nbdkit.

```bash
 nbdkit /path/to/plugin.so [args]
```

--------------------------------

### Get GPT partition GUID

Source: https://libguestfs.org/guestfs.3.html

Retrieves the GUID of a GPT partition as a string. The caller is responsible for freeing the returned string.

```c
 char *
 guestfs_part_get_gpt_guid (guestfs_h *g,
                            const char *device,
                            int partnum);
```

--------------------------------

### Create Minimal Virtual Appliance

Source: https://libguestfs.org/nbdkit-linuxdisk-plugin.1.html

This snippet demonstrates setting up a minimal virtual appliance by creating a directory structure, copying busybox, and then serving it with nbdkit to be booted by QEMU.

```bash
mkdir -p root/{bin,dev,proc,sbin,sys,usr/bin,usr/sbin}
sudo mknod root/dev/console c 5 1
cp /sbin/busybox root/sbin/
ln root/sbin/busybox root/sbin/init
ln root/sbin/busybox root/bin/ls
ln root/sbin/busybox root/bin/sh
nbdkit linuxdisk root --run '
  qemu-kvm -display none -kernel /boot/vmlinuz -drive file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1 rw" -serial stdio
 '
```

--------------------------------

### View installation notes for a template

Source: https://libguestfs.org/virt-builder.1.html

Checks for specific installation notes associated with a chosen guest template.

```bash
 virt-builder --notes fedora-41
```

--------------------------------

### Golang Examples for Copying Data

Source: https://libguestfs.org/libnbd-release-notes-1.12.1.html

Provides simple and asynchronous examples for copying data using Golang bindings.

```go
simple_copy
```

```go
aio_copy
```

--------------------------------

### 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 <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <unistd.h>
#include <guestfs.h>

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);
 }
```

--------------------------------

### Get GPT partition type GUID

Source: https://libguestfs.org/guestfs.3.html

Retrieves the type GUID of a GPT partition. The caller must free the returned string.

```c
 char *
 guestfs_part_get_gpt_type (guestfs_h *g,
                            const char *device,
                            int partnum);
```

--------------------------------

### 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 ()
```

--------------------------------

### Get GPT disk GUID

Source: https://libguestfs.org/guestfish.1.html

Retrieves the disk identifier (GUID) for a GPT-partitioned device. Behavior is undefined for non-GPT partition types.

```text
 part-get-disk-guid device
```

--------------------------------

### New Features and Usage Examples

Source: https://libguestfs.org/guestfs-release-notes-1.4.1.html

Examples of new command-line options and syntax for guestfish and related tools.

```text
 - guestfish lets you choose a prepared disk image, eg:
     guestfish -N fs:ext4

 - Add write support to guestmount (FUSE) module.

 - virt-resize can now resize the content of partitions and logical
   volumes in the guest, and we have better support for shrinking guests.

 - Bash tab-completion script for guestfish.

 - Add ZFS support to virt-rescue.

 - New tool 'virt-make-fs' for creating filesystems with content.

 - Allow suffixes on any guestfish number parameter, eg. "1M".

 - guestfish 'man' command opens the manual page.

 - guestfish supports a "heredoc" syntax for uploading files:
     upload -<<_end_ /foo
     content
     _end_

 - Some guestfish commands now print their output in octal or hex
   where appropriate (RHBZ#583242).

 - Allow dash prefix on guestfish command line.  This ignores any
   error from the second command:                   (RHBZ#578407)
     guestfish -- cmd1 : -cmd2 : cmd3

 - guestfish -h / help command now returns an error for non-existent
   commands (RHBZ#597145).

 - New 'supported' command in guestfish to list optional groups of
   commands which are supported by the daemon / configuration.

 - virt-inspector and guestfish -i now work for filenames which
   contain spaces (RHBZ#507810).

 - Change the protocol to use link-local addresses, to avoid
   conflicting with any address that the host might be using
   (RHBZ#588763).

 - libguestfs now sets the correct time and timezone on filesystem
   modifications.

 - Sort the domains into alphabetical order in virt-df.

 - Make mkfs-b command work for FAT and NTFS by mapping the blocksize
   parameter to the cluster size (RHBZ#599464).

 - Add version numbers to Perl modules (RHBZ#521674).

 - Localization now works for all the libguestfs tools (RHBZ#559963).

 - Tools now support filesystem-on-image VMs (RHBZ#590167).

 - virt-list-partitions has a '-t' option to show the total size of disks.

 - Include extra Augeas lenses in the supermin appliance (Matthew Booth).

 - Add error and close callbacks.

 - Add explicit close method in the Perl API.

 - Multiple fixes for RHEL 5 compatibility.

 - Multiple fixes for Debian/Ubuntu compatibility.

 - Multiple revisions to improve the documentation.
```

--------------------------------

### Example Usage of nbd_connect_command

Source: https://libguestfs.org/nbd_connect_command.3.html

A complete example demonstrating how to run nbdkit as a subprocess using nbd_connect_command and perform read/write operations.

```c
 /* This example shows how to run an NBD server
  * (nbdkit) as a subprocess of libnbd.
  */

 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

 #include <libnbd.h>

 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
```

--------------------------------

### 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
```

--------------------------------

### 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!
```

--------------------------------

### Get disk image format with guestfs_inspect_get_format

Source: https://libguestfs.org/guestfs.3.html

Deprecated function used to identify if a disk image is an installed OS or an installer. The caller must free the returned string after use.

```C
 char *
 guestfs_inspect_get_format (guestfs_h *g,
                             const char *root);
```

--------------------------------

### Get device index

Source: https://libguestfs.org/guestfish.1.html

Returns the index of a specified device name, starting from 0.

```text
 device-index device
```

--------------------------------

### Create a SYSLINUX configuration file

Source: https://libguestfs.org/guestfs-recipes.1.html

Example configuration for a SYSLINUX bootloader.

```text
 DEFAULT linux
 LABEL linux
   SAY Booting the kernel
   KERNEL vmlinuz
   INITRD initrd
   APPEND ro root=/dev/sda3
```

--------------------------------

### Install SYSLINUX bootloader

Source: https://libguestfs.org/guestfish.1.html

Installs the SYSLINUX bootloader on the specified device. Requires a FAT filesystem and specific partition configuration.

```guestfish
 syslinux device [directory:..]
```

--------------------------------

### Connect with TLS-PSK encryption example

Source: https://libguestfs.org/nbd_set_tls_psk_file.3.html

A complete example demonstrating how to connect to a server using TLS-PSK encryption with libnbd and nbdkit.

```c
 /* An example showing how to connect to a server which is
  * using TLS encryption.
  *
  * This requires nbdkit, and psktool from gnutls.
  *
  * Both libnbd and nbdkit support TLS-PSK which is a
  * simpler-to-deploy form of encryption.  (Of course
  * certificate-based encryption is also supported, but
  * it’s harder to make a self-contained example).
  */

 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>

 #include <libnbd.h>

 #define TMPDIR "/tmp/XXXXXX"
 #define KEYS "keys.psk"
 #define USERNAME "alice"

 static char dir[] = TMPDIR;
 static char keys[] = TMPDIR "/" KEYS;
 static char cmd[] =
   "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;

 /* Remove the temporary keys file when the program
  * exits.
  */
 static void
 cleanup_keys (void)
 {
   unlink (keys);
   rmdir (dir);
 }

 /* Create the temporary keys file to share with the
  * server.
  */
 static void
 create_keys (void)
 {
   size_t i;

   if (mkdtemp (dir) == NULL) {
     perror ("mkdtemp");
     exit (EXIT_FAILURE);
   }
   i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
   memcpy (&cmd[i], dir, strlen (TMPDIR));
   memcpy (keys, dir, strlen (TMPDIR));

   if (system (cmd) != 0) {
     fprintf (stderr, "psktool command failed\n");
     exit (EXIT_FAILURE);
   }

   atexit (cleanup_keys);
 }

 int
 main (int argc, char *argv[])
 {
   struct nbd_handle *nbd;
   char buf[512];

   create_keys ();

   /* Create the libnbd handle. */
   nbd = nbd_create ();
   if (nbd == NULL) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Enable TLS in the client. */
   if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Enable TLS-PSK and pass the keys filename. */
   if (nbd_set_tls_psk_file (nbd, keys) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Set the local username for authentication. */
   if (nbd_set_tls_username (nbd, USERNAME) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Run nbdkit as a subprocess, enabling and requiring
    * TLS-PSK encryption.
    */
   char *args[] = {
     "nbdkit", "-s", "--exit-with-parent",
     "--tls", "require", "--tls-psk", keys,
     "pattern", "size=1M", NULL
   };
   if (nbd_connect_command (nbd, args) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Read the first sector. */
   if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* TLS connections must be shut down. */
   if (nbd_shutdown (nbd, 0) == -1) {
     fprintf (stderr, "%s\n", nbd_get_error ());
     exit (EXIT_FAILURE);
   }

   /* Close the libnbd handle. */
   nbd_close (nbd);

   exit (EXIT_SUCCESS);
 }
```

--------------------------------

### 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
```

--------------------------------

### 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()
```

--------------------------------

### Install and run libguestfs tools

Source: https://libguestfs.org

Commands to install the toolset on common Linux distributions and launch the guestfish shell in read-only mode for a disk image.

```bash
sudo yum install libguestfs-tools      # Fedora/RHEL/CentOS
sudo apt-get install libguestfs-tools  # Debian/Ubuntu
guestfish --ro -i -a disk.img
```

--------------------------------

### 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
```

--------------------------------

### Troubleshoot libvirt connection errors

Source: https://libguestfs.org/virt-v2v.1.html

Example of error messages encountered when libvirt daemons are not running after installation.

```text
 Failed to connect socket to '/var/run/libvirt/virtqemud-sock': No such file or directory
 Failed to connect socket to '/var/run/libvirt/virtqemud-sock-ro': Connection refused
```

--------------------------------

### Configure Puppet agent with virt-builder

Source: https://libguestfs.org/virt-builder.1.html

Example command to install and configure the Puppet agent on a Fedora guest image.

```bash
 virt-builder fedora-41 \
   --hostname client.example.com \
   --update \
   --install puppet \
   --append-line '/etc/puppet/puppet.conf:[agent]' \
   --append-line '/etc/puppet/puppet.conf:server = puppetmaster.example.com/' \
   --run-command 'systemctl enable puppet'
```

--------------------------------

### Start Argument List for QEMU Options

Source: https://libguestfs.org/guestfs-hacking.1.html

Begins the construction of a comma-separated argument list.

```c
 int
 qemuopts_start_arg_list (struct qemuopts *qopts, const char *flag)
```

```c
 qemuopts_start_arg_list (qopts, "-drive");
 qemuopts_append_arg_list (qopts, "file=foo");
 qemuopts_append_arg_list_format (qopts, "if=%s", "ide");
 qemuopts_end_arg_list (qopts);
```

--------------------------------

### 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
```

--------------------------------

### 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()
```

--------------------------------

### 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 Windows dynamic disk group name

Source: https://libguestfs.org/guestfish.1.html

Retrieves the name of a Windows dynamic disk group using its GUID.

```bash
 ldmtool-diskgroup-name diskgroup
```

--------------------------------

### 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
```

--------------------------------

### 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);
```

--------------------------------

### Basic libnbd connection and read example

Source: https://libguestfs.org/libnbd.3.html

Demonstrates the standard workflow of creating a handle, connecting to a server, reading data, and closing the handle.

```c
 #include <libnbd.h>

 struct nbd_handle *nbd;
 char buf[512];

 if ((nbd = nbd_create ()) == NULL ||
     nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1 ||
     nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1)
   fprintf (stderr, "%s\n", nbd_get_error ());
   nbd_close (nbd);
   exit (EXIT_FAILURE);
 }
 nbd_close (nbd);
```

--------------------------------

### 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])
```

--------------------------------

### 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))
       }
 }
```
Tokens:
Raw