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 (C) 2020 Red Hat Inc.

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.