nbdkit-blkio-plugin - Man Page

libblkio plugin for NVMe, vhost-user, vDPA, VFIO

Synopsis

 nbdkit blkio [driver=]DRIVER [path=FILENAME] [num-queues=N] ...

Description

nbdkit-blkio-plugin is an nbdkit(1) plugin for using libblkio to access various disk sources used for high performance applications and virtualization. These include: NVMe, vhost-user, vDPA and VFIO.

The first parameter after the plugin name should be the libblkio driver. For example:

 nbdkit blkio virtio-blk-vhost-user path=vhost.sock
          │              │               │
        plugin         driver       other parameters

Driver: nvme-io_uring

 nbdkit blkio nvme-io_uring path=/dev/ng0n1

Connect to an NVMe device, issuing commands through Linux io_uring (requires Linux ≥ 5.19).

Driver: virtio-blk-vfio-pci

 nbdkit blkio virtio-blk-vfio-pci path=/sys/bus/pci/devices/0000:00:01.0

Connect to a PCI device which implements virtio-blk using VFIO. The path is the path to the device's sysfs directory (see lspci(8)).

Driver: virtio-blk-vhost-user

 nbdkit blkio virtio-blk-vhost-user path=vhost.sock

Connect to a vhost-user block device, such as one exported by qemu-storage-daemon(1). The path is the vhost-user Unix domain socket. For example:

 qemu-storage-daemon \
    --blockdev driver=file,node-name=file,filename=disk.qcow2 \
    --blockdev driver=qcow2,node-name=qcow2,file=file \
    --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost.sock,node-name=qcow2,writable=on

Driver: virtio-blk-vhost-vdpa

 nbdkit blkio virtio-blk-vhost-vdpa path=chardev

Connect to a vDPA device which might be implemented in software (eg. VDUSE) or hardware. The path is the vhost-vdpa character device.

Driver: io_uring

 nbdkit blkio io_uring path=FILENAME

You can use this driver to access local files and block devices through the libblkio io_uring driver, but it is usually faster and easier to use nbdkit-file-plugin(1).

Parameters

[driver=]DRIVER

The name of the libblkio driver to use.

This parameter is required.

driver= is a magic config key and may be omitted in most cases. See "Magic parameters" in nbdkit(1).

PROPERTY=VALUE

Properties such as path, num-entries etc are translated to libblkio properties. Consult the libblkio documentation for a complete list.

get=PROPERTY

Get (print) the value of a property after connecting. The property is fetched and printed in nbdkit debug output, so you will need to use the --verbose flag. This is useful for debugging.

Files

$plugindir/nbdkit-blkio-plugin.so

The plugin.

Use nbdkit --dump-config to find the location of $plugindir.

Version

nbdkit-blkio-plugin first appeared in nbdkit 1.34.

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.

Referenced By

nbdkit(1), nbdkit-plugin(3), nbdkit-release-notes-1.34(1).

2024-04-11 nbdkit-1.39.3