filters/scan/nbdkit-scan-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-scan-filter - scan disk prefetching data ahead of sequential reads
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=scan PLUGIN [scan-ahead=false] [scan-clock=false]
   8                              [scan-forever=true] [scan-size=]NN
   9
  10 =for paragraph
  11
  12  nbdkit --filter=scan --filter=cache PLUGIN
  13
  14 =for paragraph
  15
  16  nbdkit --filter=scan --filter=cow PLUGIN cow-on-cache=true
  17
  18 =head1 DESCRIPTION
  19
  20 C<nbdkit-scan-filter> is a filter that scans the disk prefetching
  21 data.  It is sometimes useful if you expect that the client will read
  22 the disk sequentially.
  23
  24 The basic operation of the filter is that when a client connects, the
  25 filter will start issuing C<.cache> (prefetch) requests to the plugin
  26 across the whole disk.  Plugins which support this command will
  27 prefetch the data, making subsequent reads faster.  For plugins which
  28 do not support this command, you can inject L<nbdkit-cache-filter(1)>
  29 below (after) this filter, giving approximately the same effect.
  30 L<nbdkit-cow-filter(1)> can be used instead of nbdkit-cache-filter, if
  31 you add the C<cow-on-cache=true> option.
  32
  33 Various parameters can be used to tune scanning, although the defaults
  34 should be suitable in most cases.
  35
  36 A similar filter is L<nbdkit-readahead-filter(1)>.
  37
  38 =head2 Limitations
  39
  40 In a number of significant cases this filter will do nothing.  The
  41 filter will print a warning message if this happens.
  42
  43 =over 4
  44
  45 =item Thread model must be parallel*
  46
  47 For example L<nbdkit-curl-plugin(1)> only supports
  48 C<serialize_requests>, and so this filter cannot perform prefetches in
  49 parallel with the read requests.
  50
  51 =item Only scans while clients are connected*
  52
  53 The current filter only scans while there is at least one client
  54 connected.
  55
  56 =item Only scans the default export*
  57
  58 The current filter only scans the default export and ignores all
  59 clients connecting to the non-default export name.
  60
  61 *We may be able to lift these restrictions in future.
  62
  63 =item Underlying filters or plugin must support C<.cache> (prefetch)
  64
  65 Very many plugins do not have the concept of prefetching and/or
  66 do not implement the C<.cache> callback, and so there is no
  67 way for this filter to issue prefetches.
  68
  69 You can usually get around this by adding I<--filter=cache> after this
  70 filter as explained above.
  71
  72 =item Prefetching the whole disk may load it all into cache
  73
  74 In particular if you use this filter together with
  75 L<nbdkit-cache-filter(1)> or L<nbdkit-cow-filter(1)>, they will cache
  76 the whole content of the plugin into a temporary file.  This may be
  77 many gigabytes of data, consuming all space in F</var/tmp>.  Of course
  78 this is the whole point of using this filter, but you should be aware
  79 of it.
  80
  81 If using the cache filter, the total size of the cache can be limited
  82 (see L<nbdkit-cache-filter(1)/CACHE MAXIMUM SIZE>).
  83
  84 =back
  85
  86 =head1 PARAMETERS
  87
  88 =over 4
  89
  90 =item B<scan-ahead=false>
  91
  92 By default the filter tries to stay ahead of incoming read requests.
  93 That is to say, it starts prefetching at the beginning of the disk and
  94 continues incrementally, but if the client issues a read beyond the
  95 current prefetch point then the filter skips forward and begins
  96 prefetching after the read.
  97
  98 However if you set this parameter to false, then this behaviour is
  99 disabled.  The filter simply prefetches sequentially regardless of
 100 client requests.
 101
 102 =item B<scan-clock=false>
 103
 104 By default, if all clients disconnect and then another client
 105 connects, prefetching resumes at the same place in the disk.  (Like
 106 stopping and starting a clock.)
 107
 108 If you set this parameter to false, then the filter starts prefetching
 109 from the beginning of the disk again.
 110
 111 =item B<scan-forever=true>
 112
 113 By default the filter scans over the disk once and then stops.
 114
 115 If you set this parameter to true, then after the disk has been
 116 prefetched completely, the filter goes back to the beginning and
 117 starts over, repeating this for as long as nbdkit is running and there
 118 are clients connected.
 119
 120 =item B<scan-size=>NN
 121
 122 This parameter controls the prefetch block size.  The default is
 123 C<2M>.  This must be a power of 2 and most plugins will have their own
 124 limits on the amount of data they can prefetch in a single request.
 125
 126 =back
 127
 128 =head1 FILES
 129
 130 =over 4
 131
 132 =item F<$filterdir/nbdkit-scan-filter.so>
 133
 134 The filter.
 135
 136 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 137
 138 =back
 139
 140 =head1 VERSION
 141
 142 C<nbdkit-scan-filter> first appeared in nbdkit 1.32.
 143
 144 =head1 SEE ALSO
 145
 146 L<nbdkit(1)>,
 147 L<nbdkit-cache-filter(1)>,
 148 L<nbdkit-cow-filter(1)>,
 149 L<nbdkit-file-plugin(1)>,
 150 L<nbdkit-readahead-filter(1)>,
 151 L<nbdkit-retry-filter(1)>,
 152 L<nbdkit-torrent-plugin(1)>,
 153 L<nbdkit-vddk-plugin(1)>,
 154 L<nbdkit-filter(3)>,
 155 L<qemu-img(1)>.
 156
 157 =head1 AUTHORS
 158
 159 Richard W.M. Jones
 160
 161 =head1 COPYRIGHT
 162
 163 Copyright Red Hat