filters/delay/nbdkit-delay-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-delay-filter - nbdkit delay filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=delay plugin rdelay=SECS wdelay=SECS [plugin-args...]
   8
   9 =for paragraph
  10
  11  nbdkit --filter=delay plugin rdelay=NNms wdelay=NNms [plugin-args...]
  12
  13 =for paragraph
  14
  15  nbdkit --filter=delay plugin [plugin-args ...]
  16           delay-read=(SECS|NNms)
  17           delay-write=(SECS|NNms)
  18           delay-zero=(SECS|NNms)
  19           delay-trim=(SECS|NNms)
  20           delay-extents=(SECS|NNms)
  21           delay-cache=(SECS|NNms)
  22           delay-fast-zero=BOOL
  23           delay-open=(SECS|NNms)
  24           delay-close=(SECS|NNms)
  25
  26 =head1 DESCRIPTION
  27
  28 C<nbdkit-delay-filter> is a filter that delays read and write requests
  29 by some seconds or milliseconds.  This is used to simulate a slow or
  30 remote server, or to test certain kinds of race conditions in Linux.
  31 To limit server bandwidth use L<nbdkit-rate-filter(1)> instead.
  32
  33 =head1 EXAMPLES
  34
  35 Delays reads and writes by 100ms:
  36
  37  nbdkit --filter=delay file disk.img rdelay=100ms wdelay=100ms
  38
  39 Delay only zero operations by 1 second, nothing else is affected:
  40
  41  nbdkit --filter=delay file disk.img delay-zero=1
  42
  43 =head1 PARAMETERS
  44
  45 =over 4
  46
  47 =item B<rdelay=>SECS
  48
  49 =item B<rdelay=>NNB<ms>
  50
  51 =item B<delay-read=>SECS
  52
  53 =item B<delay-read=>NNB<ms>
  54
  55 Delay read operations by C<SECS> seconds or C<NN> milliseconds.
  56
  57 The two forms C<rdelay> and C<delay-read> work identically.
  58
  59 =item B<delay-write=>SECS
  60
  61 =item B<delay-write=>NNB<ms>
  62
  63 Delay write operations by C<SECS> seconds or C<NN> milliseconds.
  64
  65 =item B<delay-zero=>SECS
  66
  67 =item B<delay-zero=>NNB<ms>
  68
  69 (nbdkit E<ge> 1.10)
  70
  71 Delay zero operations by C<SECS> seconds or C<NN> milliseconds.  See
  72 also B<delay-fast-zero>.
  73
  74 =item B<delay-trim=>SECS
  75
  76 =item B<delay-trim=>NNB<ms>
  77
  78 (nbdkit E<ge> 1.10)
  79
  80 Delay trim/discard operations by C<SECS> seconds or C<NN> milliseconds.
  81
  82 =item B<delay-extents=>SECS
  83
  84 =item B<delay-extents=>NNB<ms>
  85
  86 (nbdkit E<ge> 1.12)
  87
  88 Delay block status (extents) operations by C<SECS> seconds or C<NN>
  89 milliseconds.
  90
  91 =item B<delay-cache=>SECS
  92
  93 =item B<delay-cache=>NNB<ms>
  94
  95 (nbdkit E<ge> 1.14)
  96
  97 Delay advisory cache operations by C<SECS> seconds or C<NN>
  98 milliseconds.
  99
 100 =item B<wdelay=>SECS
 101
 102 =item B<wdelay=>NNB<ms>
 103
 104 Delay write, zero and trim operations by C<SECS> seconds or C<NN>
 105 milliseconds.
 106
 107 =item B<delay-fast-zero=>BOOL
 108
 109 (nbdkit E<ge> 1.16)
 110
 111 The NBD specification documents an extension called fast zero, in
 112 which the client may request that a server should reply with
 113 C<ENOTSUP> as soon as possible if the zero operation offers no real
 114 speedup over a corresponding write.  By default, this parameter is
 115 true, and fast zero requests are serviced by the plugin after the same
 116 delay as any other zero request; but setting this parameter to false
 117 instantly fails a fast zero response without waiting for or consulting
 118 the plugin.
 119
 120 =item B<delay-open=>SECS
 121
 122 =item B<delay-open=>NNB<ms>
 123
 124 (nbdkit E<ge> 1.28)
 125
 126 Delay open (client connection) by C<SECS> seconds or C<NN>
 127 milliseconds.
 128
 129 =item B<delay-close=>SECS
 130
 131 =item B<delay-close=>NNB<ms>
 132
 133 (nbdkit E<ge> 1.28)
 134
 135 Delay close (client disconnection) by C<SECS> seconds or C<NN>
 136 milliseconds.  This can also cause server shutdown to be delayed if
 137 clients are connected at the time.  This only affects clients that
 138 gracefully disconnect (using C<NBD_CMD_DISC> / libnbd function
 139 L<nbd_shutdown(3)>).  Clients that abruptly disconnect from the server
 140 cannot be delayed.
 141
 142 =back
 143
 144 =head1 FILES
 145
 146 =over 4
 147
 148 =item F<$filterdir/nbdkit-delay-filter.so>
 149
 150 The filter.
 151
 152 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 153
 154 =back
 155
 156 =head1 VERSION
 157
 158 C<nbdkit-delay-filter> first appeared in nbdkit 1.2, based on earlier
 159 C<rdelay> and C<wdelay> options in L<nbdkit-file-plugin(1)>.
 160
 161 =head1 SEE ALSO
 162
 163 L<nbdkit(1)>,
 164 L<nbdkit-filter(3)>,
 165 L<nbdkit-pause-filter(1)>,
 166 L<nbdkit-rate-filter(1)>.
 167
 168 =head1 AUTHORS
 169
 170 Richard W.M. Jones
 171
 172 =head1 COPYRIGHT
 173
 174 Copyright Red Hat