NAME

       nbdkit-nozero-filter - nbdkit nozero filter

SYNOPSIS

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

DESCRIPTION

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

PARAMETERS

       The parameters "zeromode" and "fastzeromode" are optional and control which mode the filter will use.

       zeromode=none
           Zero  support is not advertised to the client; clients must explicitly write any regions of zero like
           any other normal write.

           This is the default if the "zeromode" parameter is not specified.

       zeromode=emulate
           Zero support is advertised, but emulated by the filter  by  using  the  plugin's  "pwrite"  callback,
           regardless of whether the plugin itself has a more efficient "zero" callback.

       zeromode=notrim
           (nbdkit ≥ 1.14)

           Zero  requests  are  forwarded  on  to  the  plugin,  except  that  the  plugin  will  never  see the
           "NBDKIT_MAY_TRIM" flag.  This can help determine  if  the  client  permitting  trimming  during  zero
           operations  makes  a  difference.  It is an error to request this mode if the plugin lacks the "zero"
           callback.

       zeromode=plugin
           (nbdkit ≥ 1.16)

           Zero requests are forwarded on to the plugin, unchanged by the filter;  this  mode  is  helpful  when
           experimenting  with  the "fastzeromode" parameter.  It is an error to request this mode if the plugin
           lacks the "zero" callback.

       fastzeromode=none
           (nbdkit ≥ 1.16)

           Support for fast zeroing is not advertised to the client.

       fastzeromode=slow
           (nbdkit ≥ 1.16)

           Fast zero support is advertised to the client, but all fast zero  requests  result  in  an  immediate
           "ENOTSUP" failure rather than performing any fallback attempts.

       fastzeromode=ignore
           (nbdkit ≥ 1.16)

           This mode is unsafe: Fast zero support is advertised to the client, but all fast zero requests behave
           as  if  the  fast  zero  flag  had not been included.  This behavior is typically contrary to the NBD
           specification, but can be useful for comparison against the actual fast zero implementation to see if
           fast zeroes make a difference.

       fastzeromode=default
           (nbdkit ≥ 1.16)

           This mode is the default.  When paired with "zeromode=emulate", fast zeroes are advertised  but  fast
           zero   requests   always   fail   (similar   to   "slow");  when  paired  with  "zeromode=notrim"  or
           "zeromode=plugin", fast zero support is left to the plugin (although in the latter case,  the  nozero
           filter could be omitted for the same behavior).

EXAMPLES

       Serve   the   file  disk.img,  but  force  the  client  to  write  zeroes  explicitly  rather  than  with
       "NBD_CMD_WRITE_ZEROES":

        nbdkit --filter=nozero file disk.img

       Serve  the  file  disk.img,  allowing  the  client  to  take  advantage  of  less  network  traffic   via
       "NBD_CMD_WRITE_ZEROES",  but  fail  any  fast zero requests up front and force all other zero requests to
       write data explicitly rather than punching any holes:

        nbdkit --filter=nozero file zeromode=emulate disk.img

       Serve the file disk.img, but do not advertise fast zero support to the client even if the plugin supports
       it:

        nbdkit --filter=nozero file zeromode=plugin fastzeromode=none disk.img

FILES

       $filterdir/nbdkit-nozero-filter.so
           The filter.

           Use "nbdkit --dump-config" to find the location of $filterdir.

VERSION

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

SEE ALSO

       nbdkit(1), nbdkit-file-plugin(1),  nbdkit-filter(3),  nbdkit-fua-filter(1),  nbdkit-multi-conn-filter(1),
       nbdkit-nocache-filter(1), nbdkit-noparallel-filter(1), nbdkit-noextents-filter(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-nozero-filter(1)