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

NAME

6       nbdkit-nozero-filter - nbdkit nozero filter
7

SYNOPSIS

9        nbdkit --filter=nozero plugin [plugin-args...] \
10          [zeromode=MODE] [fastzeromode=MODE]
11

DESCRIPTION

13       "nbdkit-nozero-filter" is a filter that intentionally disables
14       efficient handling of sparse file holes (ranges of all-zero bytes)
15       across the NBD protocol.  It is mainly useful for evaluating timing
16       differences between naive vs. sparse-aware connections, and for testing
17       client or server fallbacks.
18

PARAMETERS

20       The parameters "zeromode" and "fastzeromode" are optional and control
21       which mode the filter will use.
22
23       zeromode=none
24           Zero support is not advertised to the client; clients must
25           explicitly write any regions of zero like any other normal write.
26
27           This is the default if the "zeromode" parameter is not specified.
28
29       zeromode=emulate
30           Zero support is advertised, but emulated by the filter by using the
31           plugin's "pwrite" callback, regardless of whether the plugin itself
32           has a more efficient "zero" callback.
33
34       zeromode=notrim
35           (nbdkit ≥ 1.14)
36
37           Zero requests are forwarded on to the plugin, except that the
38           plugin will never see the "NBDKIT_MAY_TRIM" flag.  This can help
39           determine if the client permitting trimming during zero operations
40           makes a difference.  It is an error to request this mode if the
41           plugin lacks the "zero" callback.
42
43       zeromode=plugin
44           (nbdkit ≥ 1.16)
45
46           Zero requests are forwarded on to the plugin, unchanged by the
47           filter; this mode is helpful when experimenting with the
48           "fastzeromode" parameter.  It is an error to request this mode if
49           the plugin lacks the "zero" callback.
50
51       fastzeromode=none
52           (nbdkit ≥ 1.16)
53
54           Support for fast zeroing is not advertised to the client.
55
56       fastzeromode=slow
57           (nbdkit ≥ 1.16)
58
59           Fast zero support is advertised to the client, but all fast zero
60           requests result in an immediate "ENOTSUP" failure rather than
61           performing any fallback attempts.
62
63       fastzeromode=ignore
64           (nbdkit ≥ 1.16)
65
66           This mode is unsafe: Fast zero support is advertised to the client,
67           but all fast zero requests behave as if the fast zero flag had not
68           been included.  This behavior is typically contrary to the NBD
69           specification, but can be useful for comparison against the actual
70           fast zero implementation to see if fast zeroes make a difference.
71
72       fastzeromode=default
73           (nbdkit ≥ 1.16)
74
75           This mode is the default.  When paired with "zeromode=emulate",
76           fast zeroes are advertised but fast zero requests always fail
77           (similar to "slow"); when paired with "zeromode=notrim" or
78           "zeromode=plugin", fast zero support is left to the plugin
79           (although in the latter case, the nozero filter could be omitted
80           for the same behavior).
81

EXAMPLES

83       Serve the file disk.img, but force the client to write zeroes
84       explicitly rather than with "NBD_CMD_WRITE_ZEROES":
85
86        nbdkit --filter=nozero file disk.img
87
88       Serve the file disk.img, allowing the client to take advantage of less
89       network traffic via "NBD_CMD_WRITE_ZEROES", but fail any fast zero
90       requests up front and force all other zero requests to write data
91       explicitly rather than punching any holes:
92
93        nbdkit --filter=nozero file zeromode=emulate disk.img
94
95       Serve the file disk.img, but do not advertise fast zero support to the
96       client even if the plugin supports it:
97
98        nbdkit --filter=nozero file zeromode=plugin fastzeromode=none disk.img
99

FILES

101       $filterdir/nbdkit-nozero-filter.so
102           The filter.
103
104           Use "nbdkit --dump-config" to find the location of $filterdir.
105

VERSION

107       "nbdkit-nozero-filter" first appeared in nbdkit 1.4.
108

SEE ALSO

110       nbdkit(1), nbdkit-file-plugin(1), nbdkit-filter(3),
111       nbdkit-fua-filter(1), nbdkit-multi-conn-filter(1),
112       nbdkit-nocache-filter(1), nbdkit-noparallel-filter(1),
113       nbdkit-noextents-filter(1).
114

AUTHORS

116       Eric Blake
117
119       Copyright Red Hat
120

LICENSE

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