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