1nbdkit-rate-filter(1)               NBDKIT               nbdkit-rate-filter(1)
2
3
4

NAME

6       nbdkit-rate-filter - limit bandwidth by connection or server
7

SYNOPSIS

9        nbdkit --filter=rate PLUGIN [PLUGIN-ARGS...]
10                             [rate=BITSPERSEC]
11                             [connection-rate=BITSPERSEC]
12                             [rate-file=FILENAME]
13                             [connection-rate-file=FILENAME]
14                             [burstiness=SECS]
15

DESCRIPTION

17       "nbdkit-rate-filter" is a filter that limits the bandwidth that can be
18       used by the server.  Limits can be applied per connection and/or for
19       the server as a whole.
20

EXAMPLES

22       nbdkit --filter=rate memory 64M rate=1M
23           Create a 64M RAM disk and limit server bandwidth as a whole to a
24           maximum of 1 Mbps (megabit per second).
25
26       nbdkit --filter=rate memory 64M connection-rate=50K
27           Limit each connection to 50 Kbps (kilobits per second).  However as
28           there is no limit to the number of simultaneous connections this
29           does not limit overall server bandwidth.
30
31       nbdkit --filter=rate memory 64M connection-rate=50K rate=1M
32           Limit each connection to 50 Kbps.  Additionally the total bandwidth
33           across all connections to the server is limited to 1 Mbps.
34
35       nbdkit --filter=rate memory 64M rate=1M rate-file=/tmp/rate
36           Initially limit bandwidth to 1 Mbps.  While the server is running
37           the rate can be adjusted dynamically by writing a different rate
38           into /tmp/rate.
39

PARAMETERS

41       connection-rate=BITSPERSEC
42           Limit each connection to "BITSPERSEC".
43
44       rate=BITSPERSEC
45           Limit total bandwidth across all connections to "BITSPERSEC".
46
47       connection-rate-file=FILENAME
48       rate-file=FILENAME
49           Adjust the per-connection or total bandwidth dynamically by writing
50           "BITSPERSEC" into "FILENAME".  See "DYNAMIC ADJUSTMENT" below.
51
52       burstiness=SECS
53           Control the bucket capacity, expressed as a length of time in
54           "rate-equivalent seconds" that the client is allowed to burst for
55           after a period of inactivity.  The default is 2.0 seconds.  It's
56           not recommended to set this smaller than the default.
57
58       "BITSPERSEC" can be specified as a simple number, or you can use a
59       number followed by "K", "M" etc to mean kilobits, megabits and so on.
60

DYNAMIC ADJUSTMENT

62       Using the "connection-rate-file" or "rate-file" parameters you can
63       dynamically adjust the bandwidth while the server is running.
64
65       If the file is not present when the server starts up then the initial
66       rate is taken from the associated "connection-rate" or "rate" parameter
67       (or if that is not present, then it is unlimited).  If the file is
68       deleted while the server is running then the last rate read from the
69       file continues to be used.
70
71       The file should be updated atomically (eg. create a new file, then
72       rename or mv(1) the new file over the old file).
73
74       There will be a short delay between the file being updated and the new
75       rate coming into effect.
76

NOTES

78       You can specify "rate" and "connection-rate" on their own or together.
79       If you specify neither, the filter is turned off.
80
81       The rate filter approximates the bandwidth used by the NBD protocol on
82       the wire.  Some operations such as zeroing and trimming are effectively
83       free (because only a tiny NBD message is sent over the network) and so
84       do not count against the bandwidth limit.  NBD and TCP protocol
85       overhead is not included, so you may find that other tools such as
86       tc(8) and iptables(8) give more accurate results.
87
88       There are separate bandwidth limits for read and write (ie. download
89       and upload to the server).
90
91       If the size of requests made by your client is much larger than the
92       rate limit then you can see long, lumpy sleeps in this filter.  In the
93       future we may modify the filter to break up large requests
94       automatically in order to limit the length of sleeps.  Placing the
95       nbdkit-blocksize-filter(1) in front of this filter, or adjusting
96       "burstiness" upwards may help.
97

FILES

99       $filterdir/nbdkit-rate-filter.so
100           The filter.
101
102           Use "nbdkit --dump-config" to find the location of $filterdir.
103

VERSION

105       "nbdkit-rate-filter" first appeared in nbdkit 1.12.
106

SEE ALSO

108       nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-delay-filter(1),
109       nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1),
110       nbdkit-limit-filter(1), nbdkit-pause-filter(1), nbdkit-filter(3),
111       iptables(8), tc(8).
112

AUTHORS

114       Richard W.M. Jones
115
117       Copyright Red Hat
118

LICENSE

120       Redistribution and use in source and binary forms, with or without
121       modification, are permitted provided that the following conditions are
122       met:
123
124       •   Redistributions of source code must retain the above copyright
125           notice, this list of conditions and the following disclaimer.
126
127       •   Redistributions in binary form must reproduce the above copyright
128           notice, this list of conditions and the following disclaimer in the
129           documentation and/or other materials provided with the
130           distribution.
131
132       •   Neither the name of Red Hat nor the names of its contributors may
133           be used to endorse or promote products derived from this software
134           without specific prior written permission.
135
136       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
137       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
138       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
139       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
140       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
141       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
142       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
143       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
144       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
145       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
146       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
147
148
149
150nbdkit-1.34.4                     2023-09-26             nbdkit-rate-filter(1)
Impressum