1nbdkit-exportname-filter(1)         NBDKIT         nbdkit-exportname-filter(1)
2
3
4

NAME

6       nbdkit-exportname-filter - adjust export names between client and
7       plugin
8

SYNOPSIS

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

DESCRIPTION

15       Some plugins (such as "nbdkit-file-plugin(1)" and filters (such as
16       "nbdkit-ext2-filter(1)" are able to serve different content based on
17       the export name requested by the client.  The NBD protocol allows a
18       server to advertise the set of export names it is serving.  However,
19       the list advertised (or absent) from the plugin may not always match
20       what you want an actual client to see.  This filter can be used to
21       alter the advertised list, as well as configuring which export should
22       be treated as the default when the client requests the empty string
23       ("") as an export name.
24

PARAMETERS

26       default-export=NAME
27           When the client requests the default export name (""), request the
28           export "NAME" from the underlying plugin instead of relying on the
29           plugin's choice of default export.  Setting NAME to the empty
30           string has the same effect as omitting this parameter.
31
32       exportname-list=keep
33       exportname-list=error
34       exportname-list=empty
35       exportname-list=defaultonly
36       exportname-list=explicit
37           This parameter determines which exports are advertised to a guest
38           that requests a listing via "NBD_OPT_LIST".  The default mode is
39           "keep" to advertise whatever the underlying plugin reports.  Mode
40           "error" causes clients to see an error rather than an export list.
41           Mode "empty" returns an empty list.  Mode "defaultonly" returns a
42           list that contains only the canonical name of the default export.
43           Mode "explicit" returns only the exports set by "exportname=".
44           Note that the list of advertised exports need not reflect reality:
45           an advertised name may be rejected, or a client may connect to an
46           export name that was not advertised, but learned through other
47           means.
48
49       exportname-strict=false
50       exportname-strict=true
51           Normally, a client can pass whatever export name it wants,
52           regardless of whether that name is advertised.  But setting this
53           parameter to true will cause the connection to fail if a client
54           requests an export name that was not included via an exportname=
55           parameter.  At this time, it is not possible to restrict a client
56           to exports advertised by the plugin without repeating that list via
57           exportname; this technical limitation may be lifted in the future.
58
59       exportname=NAME
60           This parameter adds "NAME" to the list of advertised exports; it
61           may be set multiple times.
62
63       exportdesc=keep
64       exportdesc=none
65       exportdesc=fixed:STRING
66       exportdesc=script:SCRIPT
67           The "exportdesc" parameter controls what optional descriptions are
68           sent alongside an export name.  If set to "keep" (the default),
69           descriptions are determined by the plugin.  If set to "none",
70           descriptions from the plugin are ignored (useful if you are worried
71           about a potential information leak).  If set to "fixed:STRING", the
72           same fixed string description is offered for every export.  If set
73           to "script:SCRIPT", this filter executes script with $name set to
74           the export to be described, and uses the output of that command as
75           the description.
76

EXAMPLES

78       Suppose that the directory /path/to/dir contains permanent files named
79       file1, file2, and file3.  The following commands show various ways to
80       alter the use of export names while serving that directory:
81
82       Allow a client requesting "" to get the contents of file2, rather than
83       an error:
84
85        nbdkit --filter=exportname file dir=/path/to/dir default-export=file2
86
87       Do not advertise any exports; a client must know in advance what export
88       names to try:
89
90        nbdkit --filter=exportname file dir=/path/to/dir exportname-list=empty
91
92       Allow clients to connect to file1 and file3, but not file2:
93
94        nbdkit --filter=exportname file dir=/path/to/dir \
95          exportname-list=explicit exportname-strict=true \
96          exportname=file1 exportname=file3
97
98       Offer ls(3) long descriptions alongside each export name:
99
100        nbdkit --filter=exportname file dir=/path/to/dir \
101          exportdesc=script:'ls -l /path/to/dir/"$name"'
102

FILES

104       $filterdir/nbdkit-exportname-filter.so
105           The filter.
106
107           Use "nbdkit --dump-config" to find the location of $filterdir.
108

VERSION

110       "nbdkit-exportname-filter" first appeared in nbdkit 1.24.
111

SEE ALSO

113       nbdkit(1), nbdkit-filter(3), nbdkit-ext2-filter(1),
114       nbdkit-extentlist-filter(1), nbdkit-fua-filter(1),
115       nbdkit-nocache-filter(1), nbdkit-noparallel-filter(1),
116       nbdkit-nozero-filter(1), nbdkit-file-plugin(1), nbdkit-info-plugin(1).
117

AUTHORS

119       Eric Blake
120
122       Copyright (C) 2020 Red Hat Inc.
123

LICENSE

125       Redistribution and use in source and binary forms, with or without
126       modification, are permitted provided that the following conditions are
127       met:
128
129       •   Redistributions of source code must retain the above copyright
130           notice, this list of conditions and the following disclaimer.
131
132       •   Redistributions in binary form must reproduce the above copyright
133           notice, this list of conditions and the following disclaimer in the
134           documentation and/or other materials provided with the
135           distribution.
136
137       •   Neither the name of Red Hat nor the names of its contributors may
138           be used to endorse or promote products derived from this software
139           without specific prior written permission.
140
141       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
142       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
143       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
144       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
145       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
146       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
147       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
148       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
149       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
150       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
151       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
152
153
154
155nbdkit-1.25.8                     2021-05-25       nbdkit-exportname-filter(1)
Impressum