1nbdkit-rate-filter(1) NBDKIT nbdkit-rate-filter(1)
2
6 nbdkit-rate-filter - limit bandwidth by connection or server
7
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
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
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 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 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 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
41 connection-rate=BITSPERSEC
42 Limit each connection to "BITSPERSEC".
43 rate=BITSPERSEC
45 Limit total bandwidth across all connections to "BITSPERSEC".
46 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 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 "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
62 Using the "connection-rate-file" or "rate-file" parameters you can
63 dynamically adjust the bandwidth while the server is running.
64 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 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 There will be a short delay between the file being updated and the new
75 rate coming into effect.
76
78 You can specify "rate" and "connection-rate" on their own or together.
79 If you specify neither, the filter is turned off.
80 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 There are separate bandwidth limits for read and write (ie. download
89 and upload to the server).
90 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
99 $filterdir/nbdkit-rate-filter.so
100 The filter.
101 Use "nbdkit --dump-config" to find the location of $filterdir.
103
105 "nbdkit-rate-filter" first appeared in nbdkit 1.12.
106
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
114 Richard W.M. Jones
115
117 Copyright (C) 2019 Red Hat Inc.
118
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 • Redistributions of source code must retain the above copyright
125 notice, this list of conditions and the following disclaimer.
126 • 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 • 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 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.
147nbdkit-1.32.5 2023-01-03 nbdkit-rate-filter(1)