filters/rate/nbdkit-rate-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-rate-filter - limit bandwidth by connection or server
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=rate PLUGIN [PLUGIN-ARGS...]
   8                       [rate=BITSPERSEC]
   9                       [connection-rate=BITSPERSEC]
  10                       [rate-file=FILENAME]
  11                       [connection-rate-file=FILENAME]
  12                       [burstiness=SECS]
  13
  14 =head1 DESCRIPTION
  15
  16 C<nbdkit-rate-filter> is a filter that limits the bandwidth that can
  17 be used by the server.  Limits can be applied per connection and/or
  18 for the server as a whole.
  19
  20 =head1 EXAMPLES
  21
  22 =over 4
  23
  24 =item nbdkit --filter=rate memory 64M rate=1M
  25
  26 Create a 64M RAM disk and limit server bandwidth as a whole to a
  27 maximum of S<1 Mbps> (megabit per second).
  28
  29 =item nbdkit --filter=rate memory 64M connection-rate=50K
  30
  31 Limit each connection to S<50 Kbps> (kilobits per second).  However as
  32 there is no limit to the number of simultaneous connections this does
  33 not limit overall server bandwidth.
  34
  35 =item nbdkit --filter=rate memory 64M connection-rate=50K rate=1M
  36
  37 Limit each connection to S<50 Kbps>.  Additionally the total bandwidth
  38 across all connections to the server is limited to S<1 Mbps>.
  39
  40 =item nbdkit --filter=rate memory 64M rate=1M rate-file=/tmp/rate
  41
  42 Initially limit bandwidth to S<1 Mbps>.  While the server is running
  43 the rate can be adjusted dynamically by writing a different rate into
  44 F</tmp/rate>.
  45
  46 =back
  47
  48 =head1 PARAMETERS
  49
  50 =over 4
  51
  52 =item B<connection-rate=>BITSPERSEC
  53
  54 Limit each connection to C<BITSPERSEC>.
  55
  56 =item B<rate=>BITSPERSEC
  57
  58 Limit total bandwidth across all connections to C<BITSPERSEC>.
  59
  60 =item B<connection-rate-file=>FILENAME
  61
  62 =item B<rate-file=>FILENAME
  63
  64 Adjust the per-connection or total bandwidth dynamically by writing
  65 C<BITSPERSEC> into C<FILENAME>.  See L</DYNAMIC ADJUSTMENT> below.
  66
  67 =item B<burstiness=>SECS
  68
  69 Control the bucket capacity, expressed as a length of time in
  70 "rate-equivalent seconds" that the client is allowed to burst for
  71 after a period of inactivity.  The default is 2.0 seconds.  It's not
  72 recommended to set this smaller than the default.
  73
  74 =back
  75
  76 C<BITSPERSEC> can be specified as a simple number, or you can use a
  77 number followed by C<K>, C<M> etc to mean kilobits, megabits and so
  78 on.
  79
  80 =head1 DYNAMIC ADJUSTMENT
  81
  82 Using the C<connection-rate-file> or C<rate-file> parameters you can
  83 dynamically adjust the bandwidth while the server is running.
  84
  85 If the file is not present when the server starts up then the initial
  86 rate is taken from the associated C<connection-rate> or C<rate>
  87 parameter (or if that is not present, then it is unlimited).  If the
  88 file is deleted while the server is running then the last rate read
  89 from the file continues to be used.
  90
  91 The file should be updated atomically (eg. create a new file, then
  92 rename or L<mv(1)> the new file over the old file).
  93
  94 There will be a short delay between the file being updated and the new
  95 rate coming into effect.
  96
  97 =head1 NOTES
  98
  99 You can specify C<rate> and C<connection-rate> on their own or
 100 together.  If you specify neither, the filter is turned off.
 101
 102 The rate filter approximates the bandwidth used by the NBD protocol on
 103 the wire.  Some operations such as zeroing and trimming are
 104 effectively free (because only a tiny NBD message is sent over the
 105 network) and so do not count against the bandwidth limit.  NBD and TCP
 106 protocol overhead is not included, so you may find that other tools
 107 such as L<tc(8)> and L<iptables(8)> give more accurate results.
 108
 109 There are separate bandwidth limits for read and write (ie. download
 110 and upload to the server).
 111
 112 If the size of requests made by your client is much larger than the
 113 rate limit then you can see long, lumpy sleeps in this filter.  In the
 114 future we may modify the filter to break up large requests
 115 automatically in order to limit the length of sleeps.  Placing the
 116 L<nbdkit-blocksize-filter(1)> in front of this filter, or adjusting
 117 C<burstiness> upwards may help.
 118
 119 =head1 FILES
 120
 121 =over 4
 122
 123 =item F<$filterdir/nbdkit-rate-filter.so>
 124
 125 The filter.
 126
 127 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 128
 129 =back
 130
 131 =head1 VERSION
 132
 133 C<nbdkit-rate-filter> first appeared in nbdkit 1.12.
 134
 135 =head1 SEE ALSO
 136
 137 L<nbdkit(1)>,
 138 L<nbdkit-blocksize-filter(1)>,
 139 L<nbdkit-delay-filter(1)>,
 140 L<nbdkit-exitlast-filter(1)>,
 141 L<nbdkit-exitwhen-filter(1)>,
 142 L<nbdkit-limit-filter(1)>,
 143 L<nbdkit-pause-filter(1)>,
 144 L<nbdkit-filter(3)>,
 145 L<iptables(8)>,
 146 L<tc(8)>.
 147
 148 =head1 AUTHORS
 149
 150 Richard W.M. Jones
 151
 152 =head1 COPYRIGHT
 153
 154 Copyright Red Hat