1nbdkit-nozero-filter(1) NBDKIT nbdkit-nozero-filter(1)
2
6 nbdkit-nozero-filter - nbdkit nozero filter
7
9 nbdkit --filter=nozero plugin [plugin-args...] \
10 [zeromode=MODE] [fastzeromode=MODE]
11
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
20 The parameters "zeromode" and "fastzeromode" are optional and control
21 which mode the filter will use.
22 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 This is the default if the "zeromode" parameter is not specified.
28 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 zeromode=notrim
35 (nbdkit ≥ 1.14)
36 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 zeromode=plugin
44 (nbdkit ≥ 1.16)
45 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 fastzeromode=none
52 (nbdkit ≥ 1.16)
53 Support for fast zeroing is not advertised to the client.
55 fastzeromode=slow
57 (nbdkit ≥ 1.16)
58 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 fastzeromode=ignore
64 (nbdkit ≥ 1.16)
65 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 fastzeromode=default
73 (nbdkit ≥ 1.16)
74 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
83 Serve the file disk.img, but force the client to write zeroes
84 explicitly rather than with "NBD_CMD_WRITE_ZEROES":
85 nbdkit --filter=nozero file disk.img
87 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 nbdkit --filter=nozero file zeromode=emulate disk.img
94 Serve the file disk.img, but do not advertise fast zero support to the
96 client even if the plugin supports it:
97 nbdkit --filter=nozero file zeromode=plugin fastzeromode=none disk.img
99
101 $filterdir/nbdkit-nozero-filter.so
102 The filter.
103 Use "nbdkit --dump-config" to find the location of $filterdir.
105
107 "nbdkit-nozero-filter" first appeared in nbdkit 1.4.
108
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
116 Eric Blake
117
119 Copyright Red Hat
120
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 • Redistributions of source code must retain the above copyright
127 notice, this list of conditions and the following disclaimer.
128 • 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 • 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 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.
149nbdkit-1.36.2 2023-11-26 nbdkit-nozero-filter(1)