nbdkit-exportname-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 nbdkit-exportname-filter(1) 💖

okay so bestie, welcome to the manual page for nbdkit-exportname-filter — the filter that adjusts export names between the client and the plugin. yes that's the whole NAME situation, and yes it's iconic. 🎀

✨ SYNOPSIS ✨

 nbdkit --filter=exportname plugin [default-export=NAME]
  [exportname-list=MODE] [exportname-strict=true] [exportname=NAME]...
  [exportdesc=DESC]

🌸 DESCRIPTION 🌸

so like, some plugins — think nbdkit-file-plugin(1) — and some filters — think nbdkit-ext2-filter(1) — can literally serve different content depending on the export name the client asks for. and the NBD protocol? it lets a server advertise the whole set of export names it's serving. slay.

but here's the tea 🍓: the list that gets advertised (or the fact that nothing gets advertised at all) from the plugin might not be what you actually want an actual client to see. that's the vibe check this filter is here to fix.

so this filter can:

  • alter the advertised list, and
  • configure which export gets treated as the default when the client requests the empty string ("") as an export name.

periodt. 💅

🦋 PARAMETERS 🦋

  • default-export=NAME — when the client asks for the default export name (""), this makes us request the export "NAME" from the underlying plugin instead of just trusting whatever the plugin decided its default export should be. and if you set NAME to the empty string? that's the same thing as not passing this parameter at all. no notes. ✨
  • exportname-list=keep
  • exportname-list=error
  • exportname-list=empty
  • exportname-list=defaultonly
  • exportname-list=explicit — this parameter decides which exports get advertised to a guest that asks for a listing via NBD_OPT_LIST. the default mode is keep, which advertises whatever the underlying plugin reports. mode error makes clients see an error instead of an export list. mode empty returns an empty list (nothing, nada, zero). mode defaultonly returns a list with only the canonical name of the default export. mode explicit returns only the exports you set with exportname=. 👑
heads up bestie: the list of advertised exports does not have to reflect reality. an advertised name can still get rejected, and a client can totally connect to an export name that was never advertised but that it learned through other means. it's giving "the list is a vibe, not a contract". 💀
  • exportname-strict=false
  • exportname-strict=true — normally a client can pass literally whatever export name it wants, advertised or not, no questions asked. but setting this to true makes the connection fail if a client requests an export name that wasn't included via an exportname= parameter. at this time, it is not possible to restrict a client to exports advertised by the plugin without repeating that list via exportname; this technical limitation may be lifted in the future. so like, we're doing our best. 🙈
  • exportname=NAME — adds "NAME" to the list of advertised exports. you can set this multiple times, stack 'em up. 🌈
  • exportdesc=keep
  • exportdesc=none
  • exportdesc=fixed:STRING
  • exportdesc=script:SCRIPT — the exportdesc parameter controls what optional descriptions get sent alongside an export name.
    • keep (the default): descriptions are determined by the plugin.
    • none: descriptions from the plugin are ignored — useful if you're worried about a potential information leak. 🫣
    • fixed:STRING: the same fixed string description is offered for every export.
    • script:SCRIPT: this filter executes script with $name set to the export to be described, and uses the output of that command as the description. main character scripting energy. 💅

💜 EXAMPLES 💜

okay so imagine the directory /path/to/dir contains permanent files named file1, file2, and file3. the following commands show various ways to alter the use of export names while serving that directory:

allow a client requesting "" to get the contents of file2, rather than an error:

 nbdkit --filter=exportname file dir=/path/to/dir default-export=file2

do not advertise any exports; a client must know in advance what export names to try:

 nbdkit --filter=exportname file dir=/path/to/dir exportname-list=empty

allow clients to connect to file1 and file3, but not file2:

 nbdkit --filter=exportname file dir=/path/to/dir \
   exportname-list=explicit exportname-strict=true \
   exportname=file1 exportname=file3

offer ls(3) long descriptions alongside each export name:

 nbdkit --filter=exportname file dir=/path/to/dir \
   exportdesc=script:'ls -l /path/to/dir/"$name"'

🎀 FILES 🎀

  • $filterdir/nbdkit-exportname-filter.so — the filter itself, the whole point of this page.

use nbdkit --dump-config to find the location of $filterdir. iykyk. ✨

⭐ VERSION ⭐

nbdkit-exportname-filter first appeared in nbdkit 1.24. a legend was born. 👑

🌈 SEE ALSO 🌈

nbdkit(1), nbdkit-filter(3), nbdkit-ext2-filter(1), nbdkit-extentlist-filter(1), nbdkit-fua-filter(1), nbdkit-nocache-filter(1), nbdkit-noparallel-filter(1), nbdkit-nozero-filter(1), nbdkit-file-plugin(1), nbdkit-info-plugin(1).

go read those too bestie, the whole filter family is eating. 🫶

👑 AUTHORS 👑

Eric Blake

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 lil masterpiece ships as nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-exportname-filter(1) manual. go forth and rename exports. mwah 🫶✨💖

📦 where this page comes from