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-filter(3), iptables(8), tc(8).

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2019 Red Hat Inc.

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.