nbdkit-retry-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 nbdkit-retry-filter(1) 💖

okay bestie, welcome to the nbdkit-retry-filter page — this is part of the nbdkit manual, and it's lowkey one of the most useful filters ever, no cap. it's giving "your connection died but we're not even fazed". let's get into it 🫶

✨ NAME ✨

nbdkit-retry-filter — reopen connection on error 🔁

✨ SYNOPSIS ✨

 nbdkit --filter=retry PLUGIN [retries=N] [retry-delay=N]
                              [retry-exponential=yes|no]
                              [retry-readonly=yes|no]

✨ DESCRIPTION ✨

so nbdkit-retry-filter is literally a filter that transparently reopens the plugin connection when an error shows up. like, it just quietly handles it for you 💅. you'd use it to make long-running copy operations reliable even when there are temporary network failures, and the best part? you don't have to change anything in the plugin or the NBD client. zero. nada. iconic.

if you want something more fine-grained, there's an alternative filter: nbdkit-retry-request-filter(1), which only retries single requests that fail. so like, pick your fighter 🥊.

there are several optional parameters you can use to control:

  • how many times we retry,
  • the delay between retries, and whether we wait longer each time (this is called "exponential back-off", iykyk),
  • whether we reopen the plugin in read-only mode after the first failure.

the default (aka no parameters at all) is designed to be a happy medium — good at recovering from short temporary failures, but not doing anything too chaotic when permanent or unrecoverable failures happen. the default behaviour is: we retry 5 times with exponential back-off, waiting in total about 1 minute before we give up. periodt.

🌸 EXAMPLE 🌸

in this example we copy and convert a large file using nbdkit-ssh-plugin(1), qemu-img(1) and nbdkit-captive(1). watch this 🎀

 nbdkit \
   ssh host=remote.example.com /var/tmp/test.iso \
   --filter=retry \
   --run 'qemu-img convert -p -f raw "$uri" -O qcow2 test.qcow2'

without --filter=retry, a temporary failure would cause the copy to fail — like, say the remote host's firewall gets restarted and the SSH connection just drops 😭. adding this filter means it may be possible to transparently recover. slay.

✨ PARAMETERS ✨

  • retries=N — the number of times any single operation will be retried before we give up and fail the operation. the default is 5. five chances, bestie, use them wisely 💅
  • retry-delay=N — the number of seconds to wait before retrying. the default is 2 seconds. any format supported by nbdkit_parse_delay(3) is allowed here, so go off ✨
  • retry-exponential=yes — use exponential back-off. the retry delay is doubled between each retry. this is the default, and honestly? it's the moment 👑
  • retry-exponential=no — do not use exponential back-off. the retry delay is the same between each retry. steady vibes only 🌈
  • retry-readonly=yes — as soon as a failure occurs, switch the underlying plugin to read-only mode for the rest of this connection. (a new NBD client connection will still open the plugin in the original mode, so don't stress 🫶)
  • retry-readonly=no — do not change the read-write/read-only mode of the plugin when retrying. this is the default.

🦋 FILES 🦋

  • $filterdir/nbdkit-retry-filter.so — the filter itself. the main character 💖

use nbdkit --dump-config to find the location of $filterdir. (yes, literally run that, it'll tell you where it lives 🏠)

⭐ VERSION ⭐

nbdkit-retry-filter first appeared in nbdkit 1.16. a classic. an OG. we love her 🥹

🔥 SEE ALSO 🔥

nbdkit(1), nbdkit-filter(3), nbdkit-openonce-filter(1), nbdkit-readahead-filter(1), nbdkit-retry-request-filter(1), nbdkit_parse_delay(3).

👑 AUTHORS 👑

Richard W.M. Jones — the legend himself, we stan 🙌

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 was nbdkit-1.48.1, dated 2026-08-29, from the nbdkit-retry-filter(1) manual. go forth and retry responsibly 🎀✨ bye!! 🦋

📦 where this page comes from