Provided by: nbdkit_1.42.2-1ubuntu1_amd64 
NAME
nbdkit-rate-filter - limit bandwidth by connection or server
SYNOPSIS
nbdkit --filter=rate PLUGIN [PLUGIN-ARGS...]
[rate=BITSPERSEC]
[connection-rate=BITSPERSEC]
[rate-file=FILENAME]
[connection-rate-file=FILENAME]
[burstiness=SECS]
DESCRIPTION
"nbdkit-rate-filter" is a filter that limits the bandwidth that can be used by the server. Limits can be
applied per connection and/or for the server as a whole.
EXAMPLES
nbdkit --filter=rate memory 64M rate=1M
Create a 64M RAM disk and limit server bandwidth as a whole to a maximum of 1 Mbps (megabit per
second).
nbdkit --filter=rate memory 64M connection-rate=50K
Limit each connection to 50 Kbps (kilobits per second). However as there is no limit to the number
of simultaneous connections this does not limit overall server bandwidth.
nbdkit --filter=rate memory 64M connection-rate=50K rate=1M
Limit each connection to 50 Kbps. Additionally the total bandwidth across all connections to the
server is limited to 1 Mbps.
nbdkit --filter=rate memory 64M rate=1M rate-file=/tmp/rate
Initially limit bandwidth to 1 Mbps. While the server is running the rate can be adjusted
dynamically by writing a different rate into /tmp/rate.
PARAMETERS
connection-rate=BITSPERSEC
Limit each connection to "BITSPERSEC".
rate=BITSPERSEC
Limit total bandwidth across all connections to "BITSPERSEC".
connection-rate-file=FILENAME
rate-file=FILENAME
Adjust the per-connection or total bandwidth dynamically by writing "BITSPERSEC" into "FILENAME".
See "DYNAMIC ADJUSTMENT" below.
burstiness=SECS
Control the bucket capacity, expressed as a length of time in "rate-equivalent seconds" that the
client is allowed to burst for after a period of inactivity. The default is 2.0 seconds. It's not
recommended to set this smaller than the default.
"BITSPERSEC" can be specified as a simple number, or you can use a number followed by "K", "M" etc to
mean kilobits, megabits and so on.
DYNAMIC ADJUSTMENT
Using the "connection-rate-file" or "rate-file" parameters you can dynamically adjust the bandwidth while
the server is running.
If the file is not present when the server starts up then the initial rate is taken from the associated
"connection-rate" or "rate" parameter (or if that is not present, then it is unlimited). If the file is
deleted while the server is running then the last rate read from the file continues to be used.
The file should be updated atomically (eg. create a new file, then rename or mv(1) the new file over the
old file).
There will be a short delay between the file being updated and the new rate coming into effect.
NOTES
You can specify "rate" and "connection-rate" on their own or together. If you specify neither, the
filter is turned off.
The rate filter approximates the bandwidth used by the NBD protocol on the wire. Some operations such as
zeroing and trimming are effectively free (because only a tiny NBD message is sent over the network) and
so do not count against the bandwidth limit. NBD and TCP protocol overhead is not included, so you may
find that other tools such as tc(8) and iptables(8) give more accurate results.
There are separate bandwidth limits for read and write (ie. download and upload to the server).
If the size of requests made by your client is much larger than the rate limit then you can see long,
lumpy sleeps in this filter. In the future we may modify the filter to break up large requests
automatically in order to limit the length of sleeps. Placing the nbdkit-blocksize-filter(1) in front of
this filter, or adjusting "burstiness" upwards may help.
FILES
$filterdir/nbdkit-rate-filter.so
The filter.
Use "nbdkit --dump-config" to find the location of $filterdir.
VERSION
"nbdkit-rate-filter" first appeared in nbdkit 1.12.
SEE ALSO
nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-delay-filter(1), nbdkit-exitlast-filter(1),
nbdkit-exitwhen-filter(1), nbdkit-limit-filter(1), nbdkit-pause-filter(1), nbdkit-spinning-filter(1),
nbdkit-filter(3), iptables(8), tc(8).
AUTHORS
Richard W.M. Jones
COPYRIGHT
Copyright Red Hat
LICENSE
Redistribution and use in source and binary forms, with or without modification, are permitted provided
that the following conditions are met:
• Redistributions of source code must retain the above copyright notice, this list of conditions and
the following disclaimer.
• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the distribution.
• Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
nbdkit-1.42.2 2025-04-02 nbdkit-rate-filter(1)