filters/nozero/nbdkit-nozero-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-nozero-filter - nbdkit nozero filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=nozero plugin [plugin-args...] \
   8    [zeromode=MODE] [fastzeromode=MODE]
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-nozero-filter> is a filter that intentionally disables
  13 efficient handling of sparse file holes (ranges of all-zero bytes)
  14 across the NBD protocol.  It is mainly useful for evaluating timing
  15 differences between naive vs. sparse-aware connections, and for
  16 testing client or server fallbacks.
  17
  18 =head1 PARAMETERS
  19
  20 The parameters C<zeromode> and C<fastzeromode> are optional and
  21 control which mode the filter will use.
  22
  23 =over 4
  24
  25 =item B<zeromode=none>
  26
  27 Zero support is not advertised to the client; clients must explicitly
  28 write any regions of zero like any other normal write.
  29
  30 This is the default if the C<zeromode> parameter is not specified.
  31
  32 =item B<zeromode=emulate>
  33
  34 Zero support is advertised, but emulated by the filter by using the
  35 plugin's C<pwrite> callback, regardless of whether the plugin itself
  36 has a more efficient C<zero> callback.
  37
  38 =item B<zeromode=notrim>
  39
  40 (nbdkit E<ge> 1.14)
  41
  42 Zero requests are forwarded on to the plugin, except that the plugin
  43 will never see the C<NBDKIT_MAY_TRIM> flag.  This can help determine
  44 if the client permitting trimming during zero operations makes a
  45 difference.  It is an error to request this mode if the plugin lacks
  46 the C<zero> callback.
  47
  48 =item B<zeromode=plugin>
  49
  50 (nbdkit E<ge> 1.16)
  51
  52 Zero requests are forwarded on to the plugin, unchanged by the filter;
  53 this mode is helpful when experimenting with the C<fastzeromode>
  54 parameter.  It is an error to request this mode if the plugin lacks
  55 the C<zero> callback.
  56
  57 =item B<fastzeromode=none>
  58
  59 (nbdkit E<ge> 1.16)
  60
  61 Support for fast zeroing is not advertised to the client.
  62
  63 =item B<fastzeromode=slow>
  64
  65 (nbdkit E<ge> 1.16)
  66
  67 Fast zero support is advertised to the client, but all fast zero
  68 requests result in an immediate C<ENOTSUP> failure rather than
  69 performing any fallback attempts.
  70
  71 =item B<fastzeromode=ignore>
  72
  73 (nbdkit E<ge> 1.16)
  74
  75 B<This mode is unsafe>: Fast zero support is advertised to the client,
  76 but all fast zero requests behave as if the fast zero flag had not
  77 been included.  This behavior is typically contrary to the NBD
  78 specification, but can be useful for comparison against the actual
  79 fast zero implementation to see if fast zeroes make a difference.
  80
  81 =item B<fastzeromode=default>
  82
  83 (nbdkit E<ge> 1.16)
  84
  85 This mode is the default.  When paired with C<zeromode=emulate>, fast
  86 zeroes are advertised but fast zero requests always fail (similar to
  87 C<slow>); when paired with C<zeromode=notrim> or C<zeromode=plugin>,
  88 fast zero support is left to the plugin (although in the latter case,
  89 the nozero filter could be omitted for the same behavior).
  90
  91 =back
  92
  93 =head1 EXAMPLES
  94
  95 Serve the file F<disk.img>, but force the client to write zeroes
  96 explicitly rather than with C<NBD_CMD_WRITE_ZEROES>:
  97
  98  nbdkit --filter=nozero file disk.img
  99
 100 Serve the file F<disk.img>, allowing the client to take advantage of
 101 less network traffic via C<NBD_CMD_WRITE_ZEROES>, but fail any fast
 102 zero requests up front and force all other zero requests to write data
 103 explicitly rather than punching any holes:
 104
 105  nbdkit --filter=nozero file zeromode=emulate disk.img
 106
 107 Serve the file F<disk.img>, but do not advertise fast zero support to
 108 the client even if the plugin supports it:
 109
 110  nbdkit --filter=nozero file zeromode=plugin fastzeromode=none disk.img
 111
 112 =head1 FILES
 113
 114 =over 4
 115
 116 =item F<$filterdir/nbdkit-nozero-filter.so>
 117
 118 The filter.
 119
 120 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 121
 122 =back
 123
 124 =head1 VERSION
 125
 126 C<nbdkit-nozero-filter> first appeared in nbdkit 1.4.
 127
 128 =head1 SEE ALSO
 129
 130 L<nbdkit(1)>,
 131 L<nbdkit-file-plugin(1)>,
 132 L<nbdkit-filter(3)>,
 133 L<nbdkit-fua-filter(1)>,
 134 L<nbdkit-multi-conn-filter(1)>,
 135 L<nbdkit-nocache-filter(1)>,
 136 L<nbdkit-noparallel-filter(1)>,
 137 L<nbdkit-noextents-filter(1)>.
 138
 139 =head1 AUTHORS
 140
 141 Eric Blake
 142
 143 =head1 COPYRIGHT
 144
 145 Copyright Red Hat