Provided by: nbdkit_1.36.3-1ubuntu10_amd64 
NAME
nbdkit-exportname-filter - adjust export names between client and plugin
SYNOPSIS
nbdkit --filter=exportname plugin [default-export=NAME]
[exportname-list=MODE] [exportname-strict=true] [exportname=NAME]...
[exportdesc=DESC]
DESCRIPTION
Some plugins (such as nbdkit-file-plugin(1) and filters (such as nbdkit-ext2-filter(1) are able to serve
different content based on the export name requested by the client. The NBD protocol allows a server to
advertise the set of export names it is serving. However, the list advertised (or absent) from the
plugin may not always match what you want an actual client to see. This filter can be used to alter the
advertised list, as well as configuring which export should be treated as the default when the client
requests the empty string ("") as an export name.
PARAMETERS
default-export=NAME
When the client requests the default export name (""), request the export "NAME" from the underlying
plugin instead of relying on the plugin's choice of default export. Setting NAME to the empty string
has the same effect as omitting this parameter.
exportname-list=keep
exportname-list=error
exportname-list=empty
exportname-list=defaultonly
exportname-list=explicit
This parameter determines which exports are advertised to a guest that requests a listing via
"NBD_OPT_LIST". The default mode is "keep" to advertise whatever the underlying plugin reports.
Mode "error" causes clients to see an error rather than an export list. Mode "empty" returns an
empty list. Mode "defaultonly" returns a list that contains only the canonical name of the default
export. Mode "explicit" returns only the exports set by "exportname=". Note that the list of
advertised exports need not reflect reality: an advertised name may be rejected, or a client may
connect to an export name that was not advertised, but learned through other means.
exportname-strict=false
exportname-strict=true
Normally, a client can pass whatever export name it wants, regardless of whether that name is
advertised. But setting this parameter to true will cause the connection to fail if a client
requests an export name that was not 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.
exportname=NAME
This parameter adds "NAME" to the list of advertised exports; it may be set multiple times.
exportdesc=keep
exportdesc=none
exportdesc=fixed:STRING
exportdesc=script:SCRIPT
The "exportdesc" parameter controls what optional descriptions are sent alongside an export name. If
set to "keep" (the default), descriptions are determined by the plugin. If set to "none",
descriptions from the plugin are ignored (useful if you are worried about a potential information
leak). If set to "fixed:STRING", the same fixed string description is offered for every export. If
set to "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.
EXAMPLES
Suppose that 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.
Use "nbdkit --dump-config" to find the location of $filterdir.
VERSION
"nbdkit-exportname-filter" first appeared in nbdkit 1.24.
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).
AUTHORS
Eric Blake
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.
nbdkit-1.36.3 2024-03-31 nbdkit-exportname-filter(1)