nbdkit-vddk-plugin(1)

💖 nbdkit-vddk-plugin 💖

okay bestie, welcome to nbdkit-vddk-plugin(1) — she's a whole manual page from the NBDKIT section and she's long, so hydrate and settle in 🫶

---

✨ NAME ✨

nbdkit-vddk-plugin — the nbdkit plugin for VMware VDDK, no cap 💅

---

🎀 SYNOPSIS 🎀

nbdkit vddk [[file=]FILENAME | export=WILDCARD]
            [compression=none|zlib|fastlz|skipz]
            [config=FILENAME] [cookie=COOKIE]
            [create=true] [create-adapter-type=ide|scsi-buslogic|...]
            [create-hwversion=workstation4|workstation5|...]
            [create-size=...] [create-type=monolithic-sparse|...]
            [libdir=LIBRARY] [nfchostport=PORT]
            [password=PASSWORD | password=- | password=+FILENAME |
             password=-FD]
            [port=PORT] [server=HOSTNAME]
            [single-link=true] [snapshot=MOREF]
            [thumbprint=THUMBPRINT] [transports=MODE:MODE:...]
            [unbuffered=true] [user=USERNAME] [vm=moref=ID]
nbdkit vddk --dump-plugin

---

🌸 DESCRIPTION 🌸

nbdkit-vddk-plugin is an nbdkit(1) plugin, and what she does is serve disks. Like, local VMware VMDK files, VMware ESXi servers, VMware VCenter servers, and a whole bunch of other sources. Versatile queen 👑.

The catch?? She needs VMware's proprietary VDDK library, and you have to go download that yourself. We cannot do it for you, bestie. Head to "LIBRARY LOCATION" below for the deets 🧚.

If you want an easy-to-use wrapper around this plugin that automates setting things up so you can connect to a remote VMware server, go look at:

https://gitlab.com/nbdkit/vddk-remote

---

⭐ EXAMPLES ⭐

🦋 Open a local VMDK file

$ nbdkit vddk libdir=/opt/vmware-vix-disklib-distrib \
              /absolute/path/to/file.vmdk
$ nbdinfo --size nbd://localhost
10485760
$ nbdcopy nbd://localhost outputfile.raw

So this opens file.vmdk with the plugin, and then you can use nbdinfo(1) and nbdcopy(1) to inspect and copy out the data. Literally iconic 🔥.

Heads up bestie: when you're opening local files, the filename must be an absolute path. No shortcuts, no relative vibes.

The libdir parameter points to the location of VDDK — see "LIBRARY LOCATION" below. In the examples below it's omitted for brevity (not because it's not needed, just so the lines aren't giving essay energy).

---

🌈 Create a new local VMDK file

You can use VDDK to create a VMDK file and fill it with the contents of a disk image. So, the glow-up pipeline ✨:

Note that the create-size parameter is the virtual size of the final VMDK disk image, and it must be at least as large as the input disk. If it's smaller, that's a no 💀.

nbdkit vddk \
       /absolute/path/to/output.vmdk \
       create=true create-size=100M \
       --run 'qemu-img convert input.qcow2 $uri'

---

💜 Open a file on a remote VMware ESXi hypervisor

Connect directly to a VMware ESXi hypervisor and export a particular file:

nbdkit vddk user=root password=+/tmp/rootpw \
            server=esxi.example.com thumbprint=xx:xx:xx:... \
            vm=moref=2 \
            "[datastore1] Fedora/Fedora.vmdk"

user and password must be specified. That's not optional, that's the rules 🫶. Use password=+FILENAME to provide the password securely in a file (way better than just rawdogging it on the command line, fr fr).

server is the hostname of the ESXi server.

thumbprint is the thumb print for validating the SSL certificate. How to find the thumb print of a server is described in "THUMBPRINTS" below.

vm is the Managed Object Reference ("moref") of the virtual machine. See "MANAGED OBJECT REFERENCE" below.

The file parameter is the file you want to open, usually in the form "[datastore] vmname/vmname.vmdk". See "FILE PARAMETER" below.

---

🎀 Open a file on a remote VMware vCenter server

Connect via VMware vCenter and export a particular file:

nbdkit vddk user=root password=vmware \
            server=vcenter.example.com thumbprint=xx:xx:xx:... \
            vm=moref=vm-16 \
            "[datastore1] Fedora/Fedora.vmdk"

user and password must be specified. Again — mandatory, bestie, no skipping. Use password=+FILENAME to provide the password securely in a file.

server is the hostname of the vCenter server.

thumbprint is the thumb print for validating the SSL certificate. How to find the thumb print of a server is described in "THUMBPRINTS" below.

vm is the Managed Object Reference ("moref") of the virtual machine. See "MANAGED OBJECT REFERENCE" below.

The file parameter is the file you want to open, usually in the form "[datastore] vmname/vmname.vmdk". See "FILE PARAMETER" below.

---

🧚 Allow the client to choose the filename

Same energy as the previous example, but now you let the client choose which file to serve, using the export=WILDCARD parameter:

nbdkit vddk user=root password=vmware \
            server=vcenter.example.com thumbprint=xx:xx:xx:... \
            vm=moref=vm-16 \
            export='\[datastore1\] Fedora/*.vmdk'

So now the client picks the specific filename, as long as it matches the wildcard given on the nbdkit command line. For example:

$ nbdsh
nbd> h.set_export_name("[datastore1] Fedora/Fedora.vmdk")
nbd> h.connect_tcp("localhost", "nbd")

or the same thing using an NBD URI with usual URL encoding:

nbdinfo 'nbd://localhost/%5bdatastore1%5d%20Fedora/Fedora.vmdk'

slay 💅✨

💅 PARAMETERS 💅

Okay bestie, this is where it gets detailed. Buckle up. 🎀

For opening a local VMDK file, the file parameter is required and it must be an absolute path. No relative paths, no vibes-based guessing, we need the whole thing.

For opening a remote connection, server, thumbprint, user, password and vm are all required. And you need either file or export (one of them, bestie, not neither). ✨

Everything else? Optional. Slay.

---

• compression=none
• compression=zlib
• compression=fastlz
• compression=skipz

(nbdkit ≥ 1.24, vSphere ≥ 6.5)

Pick the compression type used over the network between VDDK and the VMware server. Default is none. See the VMware document “Best Practices for NBD Transport” if you want the whole tea. 🍓

• config=FILENAME — the name of the VDDK configuration file.

This file controls the rarely-adjusted VDDK settings like log level, caching and timeouts. Peep the VDDK documentation for the full list of settings. 📋

VDDK itself looks in a few default locations for the config file, usually including /etc/vmware/config and $HOME/.vmware/config. Using config overrides those defaults. 💅

• cookie=COOKIE — (vSphere ≥ 6.7)

A cookie from an existing authenticated session on the host. 👑

This changes the authentication type from VIXDISKLIB_CRED_UID to VIXDISKLIB_CRED_SESSIONID, which can improve performance. You can find the cookie by connecting to a VCenter Server over HTTPS and retrieving the vmware_soap_session cookie. 🍪✨

• create=true — (nbdkit ≥ 1.30)

Create a new, local VMDK file. Instead of opening an existing VMDK, a fresh one gets created and opened. The filename is given by the file parameter (see below). The file must not already exist — like, it has to be brand new, okay? And ngl, it is not possible to create a remote file using nbdkit. 🙈

If you use this, the create-size parameter is required to specify the virtual size of the disk. Other create-* parameters (see below) can be used to control the VMDK sub-format.

• create-adapter-type=ide
• create-adapter-type=scsi-buslogic
• create-adapter-type=scsi-lsilogic

(nbdkit ≥ 1.30)

Specify the VMDK disk adapter type. Default is scsi-buslogic. 🧚

• create-hwversion=workstation4
• create-hwversion=workstation5
• create-hwversion=workstation6
• create-hwversion=esx30
• create-hwversion=esx4x
• create-hwversion=esx50
• create-hwversion=esx51
• create-hwversion=esx55
• create-hwversion=esx60
• create-hwversion=esx65
• create-hwversion=N

(nbdkit ≥ 1.30)

Specify the VMDK virtual hardware version. You can give either the named version or the equivalent 16 bit number. 🔢

Default is workstation5 (N = 4).

• create-size=SIZE — (nbdkit ≥ 1.30)

Specify the virtual size of the created disk. SIZE can use modifiers like 100M etc. It must be a multiple of 512 bytes because VMware only supports sector sizes. 📏

If you use create=true then this parameter is required.

• create-type=monolithic-sparse
• create-type=monolithic-flat
• create-type=split-sparse
• create-type=split-flat
• create-type=vmfs-flat
• create-type=stream-optimized
• create-type=vmfs-thin
• create-type=vmfs-sparse

(nbdkit ≥ 1.30)

Specify the VMDK sub-format. Default is monolithic-sparse. 🌸

Heads up: some VMDK sub-formats use multiple files, where the file parameter specifies the “Disk Descriptor File” and the disk contents are stored in adjacent files. So it's giving… a whole little file family. 💀

• export=WILDCARD — (nbdkit ≥ 1.44)

For remote connections, let the client choose which file to serve, using the NBD protocol export name. The export name must match WILDCARD. This is an alternative to specifying a single, exact filename — see file below. 🦋

[ and ] are special characters in wildcards and must be escaped as \[ and \]. Also you may have to quote the whole wildcard to protect it from the shell. 😭

The wildcard provides some security, but it is unwise to allow untrusted clients to connect when using this option. Like, don't. Periodt.

• [file=]FILENAME
• [file=][datastore] vmname/vmname.vmdk

Set the name of the VMDK file to serve. 📁

For local files you must supply an absolute path. For remote files, see the FILE PARAMETER section below.

The file= prefix may be omitted in most cases. See “Magic parameters” in nbdkit(1). ✨

• libdir=PATHNAME — sets the path of the VMware VDDK distribution.

VDDK uses this to load its own plugins. If this path is unspecified or wrong, then VDDK will work with reduced functionality. See LIBRARY LOCATION below. 💅

• nfchostport=PORT — the port used to establish an NFC connection to ESXi. Defaults to 902. 🔌
• password=PASSWORD — set the password to use when connecting to the remote server.

Note that passing this on the command line is not secure on shared machines. Like, everyone can see it in the process list bestie. 🙈

• password=- — ask for the password (interactively) when nbdkit starts up. 🫶
• password=+FILENAME — read the password from the named file. This is a secure method to supply a password, as long as you set the permissions on the file appropriately. 🔐
• password=-FD — read the password from file descriptor number FD, inherited from the parent process when nbdkit starts up. This is also a secure method to supply a password. ✨
• port=PORT — the port on the VCenter/ESXi host. Defaults to 443. 🔌
• server=HOSTNAME — the hostname or IP address of the VCenter or ESXi host. 🌐
• single-link=true — (nbdkit ≥ 1.12)

Open the current link, not the entire chain. This corresponds to the VIXDISKLIB_FLAG_OPEN_SINGLE_LINK flag. ⛓️

• snapshot=MOREF — the Managed Object Reference of the snapshot. See MANAGED OBJECT REFERENCE below. 📸
• thumbprint=THUMBPRINT — the SSL (SHA1) thumbprint for validating the SSL certificate. 🔐

The format is xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx (20 hex digit pairs).

See THUMBPRINTS below for how to get this.

• transports=MODE:MODE:... — list of one or more transport modes to use. Possible values include ‘nbd’, ‘nbdssl’, ‘san’, ‘hotadd’, ‘file’ (see DUMP-PLUGIN OUTPUT below). If not given, VDDK will try to choose the best transport mode. 🚀
• unbuffered=true — (nbdkit ≥ 1.12)

Disable host caching. This corresponds to the VIXDISKLIB_FLAG_OPEN_UNBUFFERED flag. 💨

• user=USERNAME — the username to connect to the remote server as. 👤
• vm=moref=ID — the Managed Object Reference (moref) of the virtual machine. See MANAGED OBJECT REFERENCE below. 🖥️
• vimapiver=APIVER — this parameter is ignored for backwards compatibility. It's just vibing there, doing nothing. 💀

---

📚 LIBRARY LOCATION 📚

Okay so important tea: the VDDK library should NOT be placed on a system library path such as /usr/lib. Why? Because the VDDK library ships with recompiled libraries like libcrypto.so and libstdc++.so that conflict with system libraries. Like, they will fight. It's giving messy. 😭

You have two choices, bestie:

• Place VDDK in the default libdir which is compiled into this plugin, for example:

$ nbdkit vddk --dump-plugin | grep ^vddk_default_libdir
vddk_default_libdir=/usr/lib64/vmware-vix-disklib

• But the best advice is to unpack the VDDK tarball anywhere you like and set libdir=/path/to/vmware-vix-disklib-distrib. For example:

nbdkit vddk \
       libdir=/opt/vmware-vix-disklib-distrib \
       /path/to/file.vmdk

🌈 No need to set LD_LIBRARY_PATH 🌈

In nbdkit ≤ 1.16 you had to set the environment variable LD_LIBRARY_PATH when using this plugin. In nbdkit ≥ 1.18 this is not recommended. We've grown, bestie. We evolved. 🦋✨

---

⭐ SUPPORTED VERSIONS OF VDDK ⭐

• VDDK ≥ 6.7 (released Apr 2018) — this is the minimum version of VDDK supported. Older versions will not work. Periodt. 🚫

This is also the first version that supported the VixDiskLib_QueryAllocatedBlocks API. This is used to provide sparseness (extent) information over NBD. 🎀

• VDDK 9.0.1.0 (released Sep 2025) — this is the latest version of VDDK that we have tested at the time of writing, but the plugin should work with future versions. 👑

This plugin is only supported on the x86-64 architecture. Just so you know. 💅

---

🦋 FILE PARAMETER 🦋

The file parameter can either be a local file, in which case it must be the absolute path. Or it can refer to a remote file on the VMware server in the format [datastore] vmname/vmname.vmdk. Two paths, one parameter, we love versatility. ✨

🔍 Finding the remote filename

For remote files you can find the path using virsh(1). For ESXi:

$ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
...
 <disk type='file' device='disk'>
   <source file='[datastore] vmname/vmname.vmdk'/>
...

For vCenter the command is the same but the URI starts with vpx://:

$ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
        dumpxml guestname

See also: https://libvirt.org/drvesx.html 🌐

✨ Optional file= prefix

The file= part is optional, so these commands are equivalent — literally twins:

nbdkit vddk file=/path/to/file.vmdk
nbdkit vddk /path/to/file.vmdk

💜 Relationship to the export parameter

Instead of file, you can use the export=WILDCARD parameter to allow the client to choose the filename, as long as it matches the given wildcard. Choose your fighter, bestie. 🥊

💅 THUMBPRINTS 💅

okay bestie so listen — the thumbprint is a 20 byte string containing the SSL (SHA1) fingerprint of the remote VMware server, and you literally need it when you're making a remote connection. no thumbprint, no vibes. here's every way to get one 🫶

🌸 Using a web browser 🌸

Go visit https://SERVER-NAME/folder and log in. click the little lock icon next to the URL bar 🔒 and navigate to the SHA-1 fingerprint of the site's certificate. that 20 hex digit pair string? you can copy it directly into the thumbprint= parameter. slay, done.

🦋 Using openssl remotely 🦋

this command prints the thumbprint of a VMware server called SERVER-NAME:

$ openssl s_client -connect SERVER-NAME:443 </dev/null |
  openssl x509 -in /dev/stdin -fingerprint -sha1 -noout

🎀 By logging in to the ESXi or vCenter server 🎀

log in to the ESXi hypervisor shell and run this:

# openssl x509 -in /etc/vmware/ssl/rui.crt -fingerprint -sha1 -noout

for VMware vCenter servers, the thumbprint is printed on the text console of the server, or you can get it by logging in to the server and using this command:

# openssl x509 -in /etc/vmware-vpx/ssl/rui.crt -fingerprint -sha1 -noout

✨ Trick: Get VDDK to tell you the thumbprint ✨

another way to snag a server's thumbprint is to connect with a bogus thumbprint and debugging turned on:

nbdkit -fv vddk server=esxi.example.com [...] thumbprint=12 \
       --run 'qemu-img info "$uri"'

the nbdkit process will try to connect (and fail, because the thumbprint is wrong, obviously 💀). but in the debug output there'll be a message like this:

nbdkit: debug: VixDiskLibVim: Failed to verify SSL certificate: actual thumbprint=B2:31:BD:DE:9F:DB:9D:E0:78:EF:30:42:8A:41:B0:28:92:93:C8:DD expected=12

and boom, that's the server's real thumbprint 🎉 of course this method is not secure since it allows a Man-in-the-Middle (MITM) attack. so like, use with caution, queen.

---

🔥 MANAGED OBJECT REFERENCE 🔥

some use cases need you to pass in the Managed Object Reference (moref) of an object on the VMware server. iykyk.

for VMware ESXi hypervisors, the vm moref is a number (eg. vm=moref=2). for VMware VCenter it's a string beginning with vm-) (eg. vm=moref=vm-16). and heads up — across ESXi and vCenter the numbers are different even for the same virtual machine. no cap.

if you have libvirt ≥ 3.7, the moref is available in the virsh(1) dumpxml output:

$ virsh -c 'esx://esxi.example.com?no_verify=1' dumpxml guestname
...
<vmware:moref>2</vmware:moref>
...

or:

$ virsh -c 'vpx://vcenter.example.com/Datacenter/esxi.example.com?no_verify=1' \
      dumpxml guestname
...
<vmware:moref>vm-16</vmware:moref>
...

an alternative way to find the moref of a VM is using the moRefFinder.pl script written by William Lam (http://www.virtuallyghetto.com/2011/11/vsphere-moref-managed-object-reference.html https://blogs.vmware.com/vsphere/2012/02/uniquely-identifying-virtual-machines-in-vsphere-and-vcloud-part-2-technical.html). 💜

---

🌈 DUMP-PLUGIN OUTPUT 🌈

to query more info about the plugin (and whether it's even working, vibe check tbh), use:

nbdkit vddk --dump-plugin

or:

nbdkit vddk --dump-plugin libdir=/opt/vmware-vix-disklib-distrib

(see LIBRARY LOCATION above 👆).

if the plugin is not present or not working you will get an error. 😭

if it works the output will include:

• vddk_default_libdir=... — the compiled-in library path. use libdir=PATHNAME to override this at runtime.
• vddk_has_nfchostport=1 — if this is printed then the nfchostport=PORT parameter is supported by this build.
• vddk_library_version=... — the VDDK major library version: 6, 7, 8, ... if this is omitted it means the library could not be loaded.
• vddk_dll=... — prints the full path to the VDDK shared library. since this requires a glibc extension it may not be available in all builds of the plugin.
• vddk_transport_modes=... — print the list of transport modes supported by VDDK. this is a colon-separated list such as file:san:hotadd:nbdssl:nbd

this is the default set of transport modes that are tried in turn, unless you override the list using the transports=... parameter.

• VixDiskLib_...=1 — for each VDDK API that the plugin uses and which is present in the VDDK library that was loaded, we print the name of the API (eg. VixDiskLib_Open=1). this lets you see which optional APIs are available, such as VixDiskLib_Flush and VixDiskLib_QueryAllocatedBlocks. if the library could not be loaded then these lines are not printed.

---

👑 NOTES 👑

💀 Sector size limitation 💀

the VDDK plugin can only answer read/write requests on whole 512 byte sector boundaries. why? because the VDDK Read and Write APIs only take sector numbers. that's just how it is bestie. if your client needs finer granularity, you can use nbdkit-blocksize-filter(1):

nbdkit vddk ... --filter=blocksize minblock=512

🙈 FileLockCreateEntryDirectory errors 🙈

when opening a local VMDK file, VDDK needs to create a lock file in the same directory. that directory must be writable, otherwise you will see errors like:

nbdkit: vddk[1]: error: FILE: FileLockCreateEntryDirectory creation
failure on '/absolute/path/to/file.vmdk.lck': Permission denied

the solution is to either make the directory / filesystem writable; or open the file read-only by adding the nbdkit -r option:

nbdkit -r vddk /absolute/path/to/file.vmdk

🍓 Out of memory errors 🍓

in the verbose log you may see errors like:

nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
received NFC error 5 from server: Failed to allocate the
requested 2097176 bytes

this seems especially common when there are multiple parallel connections open to the VMware server with large NBD reads and writes. 😵

Increase resource limits on the server

the error above can be caused by resource limits set on the VMware server. you can increase the limit for the NFC service by editing /etc/vmware/hostd/config.xml and adjusting the <maxMemory> setting:

<nfcsvc>
  <path>libnfcsvc.so</path>
  <enabled>true</enabled>
  <maxMemory>50331648</maxMemory>
  <maxStreamMemory>10485760</maxStreamMemory>
</nfcsvc>

and restarting the hostd service:

# /etc/init.d/hostd restart

for more information see https://bugzilla.redhat.com/1614276. 🔥

Limit request sizes

in addition, or as an alternative to adjusting the server configuration, you can use nbdkit-blocksize-filter(1) to limit the maximum request size. by default this plugin translates NBD requests directly into VDDK requests, and it appears that very large VDDK requests can cause the error seen above.

using:

nbdkit vddk ... --filter=blocksize minblock=512 maxdata=2M

will cause nbdkit to automatically split and combine requests so that VDDK sees only sizes in the range [512..2M]. ✨

😭 Error 1 (Unknown error) when opening a disk 😭

opening a disk fails with an error like:

nbdkit: vddk[1]: debug: VixDiskLib: VixDiskLib_OpenEx:
Cannot open disk <name>. Error 1 (Unknown error) at <line>.

this common and totally useless error message can be printed by VDDK for lots of reasons. make sure debugging is enabled and look at any debug messages printed before this to find out what is really going on. common reasons are listed below. 👇

The thumbprint parameter is wrong

verify whether the thumbprint parameter matches the SHA1 fingerprint of the remote VMware server. see THUMBPRINTS above for how to set this correctly.

The guest is using an "Independent" mode disk

in debugging output you will see messages including:

GetFileName: Cannot create disk spec for disk <name>.
Error occurred when obtaining the file name for <name>.

if the Disk Mode is Independent-Persistent or Independent-Nonpersistent, then VDDK ≥ 7 has a bug where it cannot open these disks. the only known workarounds are to use VDDK ≤ 6.7, or to change the Disk Mode to a regular dependent disk.

🌟 Troubleshooting performance problems 🌟

VDDK has very uneven performance with some operations being very slow. this plugin has options to allow you to debug performance issues. if your application has a debug or diagnostic setting, add the following nbdkit command line options:

-v -D nbdkit.backend.datapath=0 -D vddk.datapath=0 -D vddk.stats=1

-v enables verbose messages and the two datapath options disable the very verbose per-read/-write messages. -D vddk.stats=1 enables a summary when nbdkit exits of the cumulative time taken in each VDDK function, the number of times each function was called, and (for read and write) the number of bytes transferred. an example of what those stats look like can be found here: https://gitlab.com/nbdkit/nbdkit/-/commit/5c80f0d290db45a679d55baf37ff39bacb8ce7ec

you can interpret the stats as follows:

• Read — the cumulative time spent waiting for VDDK to return from VixDiskLib_Read calls, the number of times this function was called, and the total bytes read. you can use this to determine the read bandwidth to the VMware server.
• Write
• Flush — same as above, but for writing and flushing writes.
• ReadAsync
• WriteAsync — same as above, but for asynchronous read and write calls introduced in nbdkit 1.30.
• QueryAllocatedBlocks — this call is used to query information about the sparseness of the remote disk. it is only available in VDDK ≥ 6.7. the call is notably very slow in all versions of VMware we have tested. 💀
• Open
• Close
• ConnectEx
• Disconnect
• InitEx
• Exit — the cumulative time spent connecting and disconnecting from the VMware server, which can also be very slow.

🧚 Failure to load libssl.so.3 on RHEL 8 🧚

with VDDK ≥ 8.0.2 on Red Hat Enterprise Linux 8:

nbdkit: error: libssl.so.3: cannot open shared object file:
No such file or directory

this is a bug in VDDK. the workaround is to use VDDK 8.0.1. see also: https://issues.redhat.com/browse/RHEL-28533

⭐ Extents information may not be reliable for local VMDK files ⭐

the underlying QueryAllocatedBlocks call which we use to return extents information does not seem to work reliably for local VMDK files, often returning wildly incorrect information such as showing allocated files to be completely sparse. 😭 this can affect sparseness-aware tools like nbdcopy(1). if you see this you can ignore sparseness information by adding --filter=noextents on the nbdkit command line (see nbdkit-noextents-filter(1)).

🐛 DEBUG FLAGS 🐛

ngl bestie, when stuff goes sideways — like you're trying to connect to a VMware server and it's just not vibing, or you need to see the list of available transport modes, or a SAN is being a whole drama — the debug messages are gonna be your emotional support system. Turn them on like this:

nbdkit -f -v vddk file=FILENAME [...]

And then there's extra debug flags you can sprinkle on top, because of course there are:

• -D vddk.diskinfo=1 — shows you the disk information that GetInfo hands back. It's giving receipts ✨
• -D vddk.extents=1 — shows you the extents that QueryAllocatedBlocks returns. So you can see exactly what blocks are doing 💅
• -D vddk.datapath=0 — this one suppresses the debugging of datapath calls. Which datapath calls, you ask? Read, ReadAsync, Write and WriteAsync. Periodt, those four, silenced.
• -D vddk.stats=1 — when the plugin exits, it prints out some statistics about every single VDDK call. A little report card, if you will 🎀

---

📁 FILES 📁

• $plugindir/nbdkit-vddk-plugin.so — the plugin itself, the main character 👑

Wanna find where $plugindir actually lives? Just run nbdkit --dump-config and it'll tell you. Easy.

---

🌈 VERSION 🌈

nbdkit-vddk-plugin first appeared in nbdkit 1.2. Baby's first debut, iconic behavior 💖

---

👀 SEE ALSO 👀

Go read these, they're all lowkey essential:

• nbdkit(1)
• nbdkit-plugin(3)
• nbdkit-blocksize-filter(1)
• nbdkit-noextents-filter(1)
• nbdkit-readahead-filter(1)
• nbdkit-retry-filter(1)
• nbdkit-scan-filter(1)
• nbdcopy(1)
• nbdinfo(1)
• virsh(1)
• https://gitlab.com/nbdkit/vddk-remote
• https://libvirt.org/drvesx.html
• https://www.vmware.com/support/developer/vddk/
• the VMware document “Best Practices for NBD Transport”

---

🫶 AUTHORS 🫶

Richard W.M. Jones — thank you for your service, king 🙇‍♀️

---

©️ COPYRIGHT ©️

Copyright Red Hat

---

📜 LICENSE 📜

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

---

And that's the whole page, bestie 🦋 This was nbdkit-1.48.1, dated 2026-08-29, filed under nbdkit-vddk-plugin(1). Go forth and virtualize responsibly 💅✨