NAME

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

SYNOPSIS

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

DESCRIPTION

       "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).  To create an empty filesystem for each client that
       connects (like a "remote tmpfs") use nbdkit-tmpdisk-plugin(1).

EXAMPLES

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

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

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.

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

       label=LABEL
           The optional label for the filesystem.

       size=SIZE
       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.

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

       type=ext2
       type=ext3
       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.

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.

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.

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

       Copyright (C) 2019 Red Hat Inc.

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.