Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
181 lines (121 sloc) 5.08 KB


nbdkit-linuxdisk-plugin - create virtual Linux disk from directory


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


nbdkit-linuxdisk-plugin is a plugin for nbdkit(1) which creates an ext2-, ext3- or ext4-formatted disk image from a directory on the fly. The files in the specified directory (and subdirectories) appear in the virtual disk, which is served read-only over the NBD protocol.

The virtual disk is partitioned with a single GPT partition containing the filesystem.

The virtual disk can be used as a Linux root (or other) filesystem. Most features of Linux filesystems are supported, such as hard links, symbolic links, block special devices etc.

To create a FAT-formatted virtual floppy disk, see nbdkit-floppy-plugin(1). To create a CD/ISO, see nbdkit-iso-plugin(1).


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.

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.

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

nbdkit -U - linuxdisk /path/to/directory --run 'qemu-img convert $nbd 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.

mkdir root root/bin root/dev root/proc root/sbin root/sys
mkdir root/usr root/usr/bin root/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 -U - 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



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.

dir= is a magic config key and may be omitted in most cases. See "Magic parameters" in nbdkit(1).


The optional label for the filesystem.


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.

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.

Using size=+SIZE specifies the minimum free space required after the initial filesystem has been loaded. (The actual free space might be slightly larger).


Select the filesystem type. The default is ext2.


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.



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.


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


Richard W.M. Jones


Copyright (C) 2019 Red Hat Inc.

You can’t perform that action at this time.