nbdkit-rate-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 nbdkit-rate-filter 💖

okay bestie, welcome to the nbdkit-rate-filter manual page — it's part of the nbdkit family of manual pages, and it's literally the traffic cop of your NBD server. 🚦✨

✨ 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 🌸

so nbdkit-rate-filter is a filter that caps the bandwidth your server is allowed to use. no cap. and you get to choose the vibe: limits can go per connection and/or for the server as a whole. both at once? also yes, she's flexible. 💅

🌈 EXAMPLES 🌈

  • nbdkit --filter=rate memory 64M rate=1M make a 64M RAM disk and limit the server bandwidth as a whole to a max of 1 Mbps (megabit per second). 🍓
  • nbdkit --filter=rate memory 64M connection-rate=50K limit each connection to 50 Kbps (kilobits per second). but bestie, heads up: since there's no limit on the number of simultaneous connections, this does not limit the overall server bandwidth. the more connections, the more total juice. 😭
  • nbdkit --filter=rate memory 64M connection-rate=50K rate=1M limit each connection to 50 Kbps, and additionally cap the total bandwidth across all connections to the server at 1 Mbps. iconique. double protection. 👑
  • nbdkit --filter=rate memory 64M rate=1M rate-file=/tmp/rate start out limiting bandwidth to 1 Mbps, and while the server is running you can dynamically adjust the rate by writing a different rate into /tmp/rate. main character energy, changing her mind mid-scene. ✨

🦋 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. peek at DYNAMIC ADJUSTMENT below for the whole story. 📝
  • burstiness=SECS — controls 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. and ngl, it's not recommended to set this smaller than the default. 🙈

and btw, BITSPERSEC can be a simple number, or you can do a number followed by K, M etc to mean kilobits, megabits and so on. cute and easy. 💖

💜 DYNAMIC ADJUSTMENT 💜

using the connection-rate-file or rate-file parameters you can dynamically adjust the bandwidth while the server is running. live tweaking, we love to see it. 🎀

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's not present either, then it's unlimited. if the file gets deleted while the server is running, then the last rate read from the file keeps being used. she remembers. 🫶

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. patience, bestie. 😭

⭐ NOTES ⭐

you can specify rate and connection-rate on their own or together. if you specify neither, the filter is turned off. bye. 💀

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). two lanes, two speed limits. 🌈

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. throwback era fr fr. 💅

🌟 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 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.

and that's the whole page bestie!! 🌈 this one came from nbdkit-1.48.1, dated 2026-08-29. periodt. 💅✨🦋

📦 where this page comes from