nbdkit-spinning-filter(1)

✨ NAME ✨

nbdkit-spinning-filter — bestie, this is the filter that adds seek delays so you can simulate a spinning hard disk 🦋💿

Like, it's a filter for nbdkit(1), and the manual page you're reading right now is nbdkit-spinning-filter(1). Welcome, you're gonna love it here.

---

🌸 SYNOPSIS 🌸

nbdkit --filter=spinning PLUGIN [heads=N] [separate-heads=true|false]
                                [max-seek-time=N] [half-seek-time=N]
                                [min-seek-time=N]

---

💅 DESCRIPTION 💅

So nbdkit-spinning-filter is a filter for nbdkit(1) that adds seek delays, and the whole point is to simulate a spinning hard disk with a mechanical arm and a head. It's giving 2003. It's giving clicky noises. You use it to test the NBD rotational property.

In the default config, this filter simulates a disk with one head. Accesses that are close to where that head currently is? Basically no delay, she barely moved, slay. Accesses that are far away suffer increasingly larger delays as the simulated head seeks over to that position on the disk. And every single access moves the simulated position of the head. No cap.

For example, to turn nbdkit-memory-plugin(1) (a RAM disk, iconic, but way too fast to be fun) into something that behaves more like a spinning disk:

nbdkit --filter=spinning memory 1G

---

🎀 Multiple heads 🎀

You can control the number of heads and whether they can move independently or not. Setting heads=4 and separate-heads=false simulates a disk with a single mechanical arm, two platters and four heads. From the point of view of logical blocks this looks like the following, where the heads move in tandem over 4 equally spaced sections of the disk:

                                arm
                                 │                       head
             ┌────────────┬──────┴─────┬────────────┐  ↙
             ⇓            ⇓            ⇓            ⇓
        ┌─────────────────────────────────────────────────┐
        └─────────────────────────────────────────────────┘

In this mode, requests are serialized waiting for the arm to move, even if the requests are for different heads (as happens on a real disk). Everyone in the group chat waits their turn 😭

Using separate-heads=true simulates heads which move on independent arms (but each head is still confined to its quarter of the disk):

                                   range of movement for 4ᵗʰ arm/head
                                            ┌──────┴─────┐
           ⇓                 ⇓    ⇓            ⇓
        ┌─────────────────────────────────────────────────┐
        └─────────────────────────────────────────────────┘

In this mode, requests may operate in parallel if they are handled by different heads. Main character energy, no waiting around 💅

---

🌈 The rotational property 🌈

The rotational property is a boolean flag in the NBD protocol which hints to the client whether the plugin behaves like a spinning disk (if rotational is true) or like a solid state disk or RAM (if rotational is false).

This filter always advertises the rotational property, because it behaves like a spinning disk. Periodt.

Well-behaved NBD clients should observe this property and adjust their behaviour, for instance by scheduling disk accesses to reduce seeking. Be the well-behaved client bestie 🫶

You can place nbdkit-rotational-filter(1) in front of this filter if you want to simulate what happens with a spinning disk which does not advertise the property correctly:

nbdkit --filter=rotational --filter=spinning PLUGIN rotational=false

Use nbdinfo(1) to examine the rotational property of an NBD server. Go look, it's right there 👀

---

⭐ Seek times ⭐

By default, seeks to adjacent tracks take 10 milliseconds, seeking from the first sector to the last sector of the disk takes ½ second, and seeking half way across the disk takes 0.2 seconds (so the curve of seek times is mildly quadratic). Note these seek times are at least an order of magnitude larger than a typical hard disk, in order to exaggerate the effect for testing purposes. Dramatic on purpose, we love a filter that commits to the bit.

You can adjust the time taken to seek across the whole disk (max-seek-time), across half of the disk (half-seek-time), and from one track to an adjacent track (min-seek-time) in order to change this curve. For example, setting half-seek-time=500ms max-seek-time=1000ms will make seek times twice as slow as the default and approximately linear with distance. Tune it, make it yours, it's your world 💖

---

🦋 PARAMETERS 🦋

• heads=N — Set the number of simulated heads to N (default is 1).
• separate-heads=true, separate-heads=false — Simulate separate, independently moving heads (true), or heads connected together on a single arm (false). See the description above. The default is false.
• min-seek-time=N, half-seek-time=N, max-seek-time=N — Adjust the time taken to seek to an adjacent track, seek across half of the disk, and seek across the whole disk. All numbers are in seconds. The defaults are min-seek-time=10ms, half-seek-time=200ms and max-seek-time=500ms.

See nbdkit_parse_delay(3) for the precise format of these parameters.

---

🧚 FILES 🧚

• $filterdir/nbdkit-spinning-filter.so — The filter.

Use nbdkit --dump-config to find the location of $filterdir.

---

👑 VERSION 👑

nbdkit-spinning-filter first appeared in nbdkit 1.40. Baby filter, grew up so fast 😭

---

💜 SEE ALSO 💜

nbdkit(1), nbdkit-delay-filter(1), nbdkit-rate-filter(1), nbdkit-rotational-filter(1), nbdkit-memory-plugin(1), nbdinfo(1), nbdkit-filter(3), nbdkit_parse_delay(3), https://en.wikipedia.org/wiki/Hard_disk_drive, https://en.wikipedia.org/wiki/Hard_disk_drive_performance_characteristics, https://blog.stuffedcow.net/2019/09/hard-disk-geometry-microbenchmarking/

---

🌟 AUTHORS 🌟

Richard W.M. Jones

---

🎀 COPYRIGHT 🎀

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.

bestie this part is the legal bit, don't skim it, the lawyers are watching 🙈

---

okay that's the whole page!! this one's from nbdkit-1.48.1, dated 2026-08-29, and it's the nbdkit-spinning-filter(1) manual — go spin some disks, you ate 💖✨