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

DESCRIPTION

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

EXAMPLES

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

PARAMETERS

40       connection-rate=BITSPERSEC
41           Limit each connection to "BITSPERSEC".
42
43       rate=BITSPERSEC
44           Limit total bandwidth across all connections to "BITSPERSEC".
45
46       connection-rate-file=FILENAME
47       rate-file=FILENAME
48           Adjust the per-connection or total bandwidth dynamically by writing
49           "BITSPERSEC" into "FILENAME".  See "DYNAMIC ADJUSTMENT" below.
50
51       "BITSPERSEC" can be specified as a simple number, or you can use a
52       number followed by "K", "M" etc to mean kilobits, megabits and so on.
53

DYNAMIC ADJUSTMENT

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

NOTES

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

FILES

92       $filterdir/nbdkit-rate-filter.so
93           The filter.
94
95           Use "nbdkit --dump-config" to find the location of $filterdir.
96

VERSION

98       "nbdkit-rate-filter" first appeared in nbdkit 1.12.
99

SEE ALSO

101       nbdkit(1), nbdkit-blocksize-filter(1), nbdkit-delay-filter(1),
102       nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1),
103       nbdkit-limit-filter(1), nbdkit-pause-filter(1), nbdkit-filter(3),
104       iptables(8), tc(8).
105

AUTHORS

107       Richard W.M. Jones
108
110       Copyright (C) 2019 Red Hat Inc.
111

LICENSE

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