nbdkit-extentlist-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 NAME 💖

nbdkit-extentlist-filter — bestie, it literally just places an extent list over a plugin. that's the whole vibe ✨

🌸 SYNOPSIS 🌸

nbdkit -r --filter=extentlist plugin extentlist=FILENAME

🦋 DESCRIPTION 🦋

okay so "nbdkit-extentlist-filter" is an nbdkit filter, and what it does is let you slap a static list of extents on top of whatever plugin you already have. and extents? they're the receipts that record whether specific parts of the disk are allocated or sparse. 🎀

this is your girl when the plugin can't get extent info by itself but you can get that info from somewhere else. iconic use case: nbdkit-ssh-plugin(1), because the sftp protocol simply does not support reading sparseness info 😭 — but you might be able to pull that info straight from the source disk on the remote server using commands like xfs_bmap(8). same situation, different day, with nbdkit-curl-plugin(1).

⚠️ not me being the bearer of bad news but — the extent list is read-only. this filter does not monitor writes and trims to update the extent list. so what can happen is you write to a "hole" in the disk, but then you can't read it back, because the NBD client still thinks that part of the disk is a hole. so it's generally only safe to use this filter in read-only mode (the -r option). periodt. 💅

🎀 FILE FORMAT 🎀

the extent list lives in a text file, one extent per line. every line — except blank lines and comment lines that begin with # — has this shape:

offset length type

the offset and length fields can use any format understood by nbdkit_parse_size(3). the optional type field can be:

  • an integer, or
  • missing (which is the same as 0), or
  • a comma-separated list of the words hole and zero.

(these fields line up exactly with the inputs of the nbdkit_add_extent function — go peek at nbdkit-plugin(3) if you want the lore 📖)

here's a valid set of extents covering a 10M disk, where the first megabyte only is allocated data:

0  1M
1M 9M  hole,zero

or you could just omit the hole,zero extent, since any gaps are assumed to be holes with that type:

0  1M

the extent list doesn't need to cover the whole disk, and it doesn't need to be in ascending order — but bestie, it must not contain overlapping extents. no cap. 🚫

⭐ Parsing qemu-img map ⭐

the output of qemu-img(1) map is a list of allocated blocks, looking like this:

Offset          Length          Mapped to       File
0               0x10000         0               disk.img
0x100000        0x20000         0x100000        disk.img

you can ignore the third and fourth columns, and remove the header line, and boom 💥 you've got input that can be directly imported into this filter.

for example, to make a disk which has the same "shape" (but different data) as an existing disk image:

disk=disk.img
size=$( qemu-img info $disk --output=json | jq '.["virtual-size"]' )
qemu-img map $disk |
    tr -s " " | cut -d " " -f 1-2 | tail -n +2 > extents.txt
nbdkit -r ones $size --filter=extentlist extentlist=extents.txt

✨ PARAMETERS ✨

  • extentlist=FILENAME — point this at the file holding the extent list, in the format described up in FILE FORMAT. that's it, that's the parameter. 🫶

💜 FILES 💜

  • $filterdir/nbdkit-extentlist-filter.so — the filter itself, the main character. 👑

use nbdkit --dump-config to find out where $filterdir actually is, iykyk.

🌈 VERSION 🌈

"nbdkit-extentlist-filter" first appeared in nbdkit 1.18. a classic. a legend. 🕰️

🔥 SEE ALSO 🔥

nbdkit(1), nbdkit-noextents-filter(1), nbdkit-filter(3), nbdkit-plugin(3).

go read them, they're giving very much required reading. 📚

🫶 AUTHORS 🫶

Richard W.M. Jones

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 one's from nbdkit-1.48.1, dated 2026-08-29 — go forth and place those extents, you absolute icon. ✨🎀🦋

📦 where this page comes from