nbdkit-linuxdisk-plugin(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

🌸 NAME 🌸

okay so bestie, meet nbdkit-linuxdisk-plugin — section 1 of the manual, aka the create virtual Linux disk from directory icon 💅. She's a plugin, she lives inside nbdkit(1)'s house, and she is genuinely so good at her job it's not even funny.

✨ SYNOPSIS ✨

nbdkit linuxdisk [dir=]DIRECTORY
                 [label=LABEL] [type=ext2|ext3|ext4]
                 [size=[+]SIZE]

🦋 DESCRIPTION 🦋

nbdkit-linuxdisk-plugin is a plugin for nbdkit(1) and the way that it creates an ext2-, ext3- or ext4-formatted disk image from a directory on the fly? Obsessed. The files in the directory you point at (and all its subdirectories, yes all of them) show up inside the virtual disk, and that disk gets served read-only over the NBD protocol. No cap.

The virtual disk is partitioned with a single GPT partition containing the filesystem. One partition. GPT. She's tidy like that 🎀.

You can use this virtual disk as a Linux root filesystem (or, like, any other filesystem honestly). Most features of Linux filesystems are supported — hard links, symbolic links, block special devices etc. All of it, slay 🔥.

Want a FAT-formatted virtual floppy disk instead? That's nbdkit-floppy-plugin(1). Want a CD/ISO? nbdkit-iso-plugin(1). Want an empty filesystem for each client that connects (like a "remote tmpfs")? nbdkit-tmpdisk-plugin(1). We love a supportive sibling lineup 🫶.

💖 EXAMPLES 💖

Here's the group chat receipts, bestie:

  • nbdkit linuxdisk /path/to/directory label=ROOTFS — Create a virtual disk, giving it a filesystem label. Note that clients will not be able to modify the filesystem, so it is safe to share it with multiple clients. Share her, she's fine 💅.
  • nbdkit --filter=cow linuxdisk /path/to/directory — Add a writable overlay (see nbdkit-cow-filter(1)), allowing the disk to be written by the client.
🚨 Multiple clients must not be allowed to connect at the same time (even if they all mount it read-only) as this will cause disk corruption. Fr fr, do not do this.
  • nbdkit --filter=cow linuxdisk /path/to/directory size=+1G — The same but specifying that at least 1G of free space should be available in the filesystem (not including the space taken by the initial filesystem).
  • nbdkit --filter=partition linuxdisk /path/to/directory partition=1 — Instead of serving a partitioned disk image, serve just the "naked" filesystem (ie. the first partition, see nbdkit-partition-filter(1)). She's bare, she's free ✨.
  • nbdkit linuxdisk /path/to/directory --run 'nbdcopy "$uri" ext2fs.img' — This serves nothing. Instead it turns a directory into a disk image, writing it to ext2fs.img (see nbdkit-captive(1)). The resulting image is a partitioned disk.

🌈 Create a minimal virtual appliance 🌈

This creates and boots a minimal busybox(1)-based virtual appliance. This assumes that your kernel (/boot/vmlinuz) contains the ext2 or ext4 driver compiled in, but most Linux distro kernels have that. Lucky us 💜.

mkdir -p root/{bin,dev,proc,sbin,sys,usr/bin,usr/sbin}
sudo mknod root/dev/console c 5 1
cp /sbin/busybox root/sbin/
ln root/sbin/busybox root/sbin/init
ln root/sbin/busybox root/bin/ls
ln root/sbin/busybox root/bin/sh
nbdkit linuxdisk root --run '
  qemu-kvm -display none -kernel /boot/vmlinuz -drive file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1 rw" -serial stdio
'

You can drop any extra files you need into the root/ directory and they will be copied into the appliance before boot. After booting type these commands to complete the environmental setup:

/sbin/busybox --install
mount -t proc proc /proc
mount -t sysfs sys /sys

🎀 PARAMETERS 🎀

  • [dir=]DIRECTORY — Specify the directory containing files and subdirectories which will be added to the virtual disk. Files inside this directory will appear in the root directory of the virtual disk.

This parameter is required. No directory, no disk, sorry bestie 😭.

The "dir=" prefix may be omitted in most cases. See "Magic parameters" in nbdkit(1).

  • label=LABEL — The optional label for the filesystem.
  • size=SIZE — and size=+SIZE — The total (virtual) size of the filesystem.
    • If the "size" parameter is omitted the plugin will try to size the filesystem with just enough space to contain the files and directories that are initially loaded, and there will not be much extra space. She's giving minimalism, she's giving barely-fitting 👑.
    • Using size=SIZE specifies the required virtual size of the whole filesystem (including initial files and extra space). If this is set too small for the initial filesystem then the plugin will fail to start. Not a vibe.
    • Using size=+SIZE specifies the minimum free space required after the initial filesystem has been loaded. (The actual free space might be slightly larger). Rounding up, as she should 💅.
  • type=ext2 — and type=ext3 — and type=ext4 — Select the filesystem type. The default is "ext2".

🧚 NOTES 🧚

Users and groups

The original file UIDs and GIDs are recreated as far as possible. Note that UIDs/GIDs will likely map to different users and groups when read by a virtual machine or other NBD client machine. So like, the numbers travel, but the people might be different over there 🙈.

🌟 ENVIRONMENT VARIABLES 🌟

  • "TMPDIR" — The filesystem image is stored in a temporary file located in /var/tmp by default. You can override this location by setting the "TMPDIR" environment variable before starting nbdkit. Move her wherever you want, she's flexible ✨.

💅 FILES 💅

  • $plugindir/nbdkit-linuxdisk-plugin.so — The plugin.

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

⭐ VERSION ⭐

"nbdkit-linuxdisk-plugin" first appeared in nbdkit 1.12. Baby girl's been around 💖.

🔥 SEE ALSO 🔥

mke2fs(8), nbdkit(1), nbdkit-plugin(3), nbdkit-captive(1), nbdkit-cow-filter(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1), nbdkit-iso-plugin(1), nbdkit-partition-filter(1), nbdkit-partitioning-plugin(1), nbdkit-tmpdisk-plugin(1),

👑 AUTHORS 👑

Richard W.M. Jones

Copyright Red Hat

💜 LICENSE 💜

okay this part is not cute, it's the legal bit, but we do not skip sections in this house. 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 absolute queen of a manpage is from nbdkit-1.48.1, dated 2026-08-29, and she ate, no crumbs. mwah 💅

📦 where this page comes from