nbdkit-ondemand-plugin(1)

📦
version 1.44.1 · 13 versions
, in opensuse-leap 16.0

💅 nbdkit-ondemand-plugin — like, the on-demand filesystem maker, bestie

Okay so this is a page from the nbdkit manual (section 1, if we're being precise 🎀). Buckle up, because this plugin is genuinely iconic: it makes filesystems on demand and honestly? It ate.

✨ NAME ✨

nbdkit-ondemand-plugin — create filesystems on demand 🦋

🌸 SYNOPSIS 🌸

nbdkit ondemand dir=EXPORTSDIR [size=]SIZE [wait=true] [share=true]
                { [type=ext4|xfs|vfat|...] [label=LABEL]
                  | command=COMMAND [VAR=VALUE ...] }

Like, that's the whole vibe. Look at it. Slay. 💅

💖 DESCRIPTION 💖

So this is a plugin for nbdkit(1) that creates persistent filesystems on demand. Clients just… connect to the server, ask for a particular export name, and boom — a brand new filesystem gets created if it doesn't already exist. And here's the cute part: clients can disconnect and reconnect with the same export name, and the same filesystem is still right there waiting for them. 🫶

Filesystems are stored in a directory on the server, which means they persist even over server restarts. Lowkey the best feature. ✨

By default each export is locked while a client is using it, so two clients can't get at the same filesystem at once (which, ngl, would absolutely cause corruption 💀).

Some similar plugins you might know, for the vibe check:

🦋 Export names 🦋

When a client requests a new export name, a sparse file with that same name gets created inside dir=EXPORTSDIR on the server. Then the file gets formatted with mkfs(8). Right now the size of that file is fixed by the size=SIZE parameter, but (this is exciting) they intend to make it client-configurable in future. The filesystem type and label can also be specified — otherwise it defaults to ext4 with no label.

Export names have rules, bestie, and we respect them:

  • They must be ≤ NAME_MAX (usually 255) bytes in length.
  • They must not contain certain characters, including . at the start, and /.
  • There may be other limitations added in future.

Client requests that don't obey these restrictions get rejected. And as a special little exception: the export name "" gets mapped to the file name default. 🎀

🔥 Security considerations 🔥

Only use this in an environment where you trust all your clients! Clients can use this plugin to consume, like, arbitrary amounts of disk space by creating unlimited exports. No cap.

So it's best to take steps to limit where clients can connect from — use nbdkit-ip-filter(1), firewalls, or TLS client certificates. Protect yourself, queen. 👑

🧚 The command parameter 🧚

Instead of running mkfs, you can run an arbitrary command or shell script to create the disk. Main character energy.

The other parameters to the plugin get turned into shell variables that are passed to the command. For example, type becomes the shell variable $type, etc. And like — any parameters you want can be passed to the plugin and they'll become shell variables (not only type and label), which makes this a very flexible method to create filesystems and disks of all kinds. Obsessed. 💜

Two special variables also get passed to the shell script fragment:

  • $disk — the absolute path of the disk file. ⚠️ This is partially controlled by the client, so you should quote it carefully. This file is not pre-created — the command has to create it, for example using:
truncate -s $size "$disk"
  • $size — the virtual size in bytes. This is the size parameter, converted to bytes. Note that the final size served to the client is whatever disk size command creates.

💀 Dead client detection 💀

Clients that "go away" without disconnecting (like, rude — think clients that reboot) may cause exports to stay locked even when they're not being used anymore. Practically, this can cause problems like the same client being unable to reconnect after a reboot. 😭

To avoid this, enable keepalives so dead clients get detected. Use the nbdkit --keepalive option, or for more fine-grained control, see the discussion of keepalives in nbdkit-service(1).

🌈 EXAMPLE 🌈

Run the server like this:

mkdir /var/tmp/exports
nbdkit ondemand dir=/var/tmp/exports 1G

Then clients can connect and create 1G ext4 filesystems on demand using commands like these (note the different export names — that's the whole point):

nbd-client server /dev/nbd0 -N export1
mount /dev/nbd0 /mnt

guestfish --format=raw -a nbd://localhost/export2 -m /dev/sda

qemu-img info nbd:localhost:10809:exportname=export2

On the server you'd see two filesystems created:

$ ls -l /var/tmp/exports
-rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export1
-rw-rw-r--. 1 rjones rjones 1073741824 Aug 13 21:40 export2
Heads up: the plugin does not clean these up. If they're no longer needed, the server admin should delete them (or use a tmp cleaner). 🙈

🎀 PARAMETERS 🎀

  • command='COMMAND' — instead of running mkfs(8) to create the initial filesystem, run COMMAND (a shell script fragment which usually must be quoted to protect it from the shell). See "The command parameter" above. ✨
  • dir=EXPORTSDIR — the directory where filesystems are saved. When you first use this plugin, point it at an empty directory. When clients connect, filesystems get created here. This parameter is required. 🫶
  • label=LABEL — select the filesystem label. The default is not set.
  • share=true — if set, the export is not locked, and two or more clients may connect to the same export. ⚠️ This usually results in filesystem corruption (if you're using a regular filesystem like ext4), so you have to use some other means to guarantee exclusive access or to make sure sharing is safe. Don't say we didn't warn you. 💀
  • [size=]SIZE — specify the virtual size of all of the filesystems. If you're using command, this is only a suggested size — the actual size of the resulting disk will be the size of the disk created by command. This parameter is required. The size= prefix may be omitted in most cases. See "Magic parameters" in nbdkit(1).
  • type=FS — select the filesystem type. The default is ext4. Most non-networked, non-cluster filesystem types supported by the mkfs(8) command can be used here. 🌸
  • wait=true — if set, and two clients try to connect at the same time to the same export, then the second client will wait for the first to disconnect. The default behaviour is to reject the second client with the error message:
filesystem is locked by another client

This setting is sometimes useful if you're making repeated connections and, at the network level, the first connection doesn't fully disconnect before the next connection starts. This can also happen as a side-effect of using guestfish --ro, which opens two NBD connections in quick succession. Note: if share=true then locking isn't used and the wait parameter has no effect. ⭐

🍓 FILES 🍓

  • $plugindir/nbdkit-ondemand-plugin.so — the plugin itself. Use nbdkit --dump-config to find the location of $plugindir. 🔍

👑 VERSION 👑

nbdkit-ondemand-plugin first appeared in nbdkit 1.22. Iconic debut, honestly.

🦋 SEE ALSO 🦋

nbdkit(1), nbdkit-plugin(3), nbdkit-file-plugin(1), nbdkit-ip-filter(1), nbdkit-limit-filter(1), nbdkit-linuxdisk-plugin(1), nbdkit-memory-plugin(1), nbdkit-tmpdisk-plugin(1), nbdkit-service(1), nbdkit-tls(1), mkfs(8), mke2fs(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 version is from nbdkit-1.44.1, dated 2025-07-07, and it's the nbdkit-ondemand-plugin(1) manual page — go forth and make filesystems on demand, mwah 🎀✨🦋

📦 where this page comes from