.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.36.3 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-linuxdisk-plugin 1"
.TH nbdkit-linuxdisk-plugin 1 2024-01-17 nbdkit-1.36.3 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-linuxdisk\-plugin \- create virtual Linux disk from directory
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& nbdkit linuxdisk [dir=]DIRECTORY
\&                  [label=LABEL] [type=ext2|ext3|ext4]
\&                  [size=[+]SIZE]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-linuxdisk\-plugin\*(C'\fR is a plugin for \fBnbdkit\fR\|(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.
.PP
The virtual disk is partitioned with a single GPT partition containing
the filesystem.
.PP
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.
.PP
To create a FAT-formatted virtual floppy disk, see
\&\fBnbdkit\-floppy\-plugin\fR\|(1).  To create a CD/ISO, see
\&\fBnbdkit\-iso\-plugin\fR\|(1).  To create an empty filesystem for each
client that connects (like a "remote tmpfs") use
\&\fBnbdkit\-tmpdisk\-plugin\fR\|(1).
.SH EXAMPLES
.IX Header "EXAMPLES"
.IP "nbdkit linuxdisk /path/to/directory label=ROOTFS" 4
.IX Item "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.
.IP "nbdkit \-\-filter=cow linuxdisk /path/to/directory" 4
.IX Item "nbdkit --filter=cow linuxdisk /path/to/directory"
Add a writable overlay (see \fBnbdkit\-cow\-filter\fR\|(1), allowing the disk
to be written by the client.  \fBMultiple clients must not be allowed
to connect at the same time\fR (even if they all mount it read-only) as
this will cause disk corruption.
.IP "nbdkit \-\-filter=cow linuxdisk /path/to/directory size=+1G" 4
.IX Item "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).
.IP "nbdkit \-\-filter=partition linuxdisk /path/to/directory partition=1" 4
.IX Item "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
\&\fBnbdkit\-partition\-filter\fR\|(1)).
.IP "nbdkit linuxdisk /path/to/directory \-\-run 'nbdcopy ""$uri"" ext2fs.img'" 4
.IX Item "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 \fIext2fs.img\fR (see \fBnbdkit\-captive\fR\|(1)).  The resulting
image is a partitioned disk.
.IP "Create a minimal virtual appliance" 4
.IX Item "Create a minimal virtual appliance"
This creates and boots a minimal \fBbusybox\fR\|(1)\-based virtual
appliance.  This assumes that your kernel (\fI/boot/vmlinuz\fR) contains
the ext2 or ext4 driver compiled in, but most Linux distro kernels
have that.
.Sp
.Vb 9
\& 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 \*(Aq
\&   qemu\-kvm \-display none \-kernel /boot/vmlinuz \-drive file=nbd:unix:$unixsocket,snapshot=on \-append "console=ttyS0 root=/dev/sda1 rw" \-serial stdio
\& \*(Aq
.Ve
.Sp
You can drop any extra files you need into the \fIroot/\fR directory and
they will be copied into the appliance before boot.  After booting
type these commands to complete the environmental setup:
.Sp
.Vb 3
\& /sbin/busybox \-\-install
\& mount \-t proc proc /proc
\& mount \-t sysfs sys /sys
.Ve
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP [\fBdir=\fR]DIRECTORY 4
.IX Item "[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.
.Sp
This parameter is required.
.Sp
\&\f(CW\*(C`dir=\*(C'\fR is a magic config key and may be omitted in most cases.
See "Magic parameters" in \fBnbdkit\fR\|(1).
.IP \fBlabel=\fRLABEL 4
.IX Item "label=LABEL"
The optional label for the filesystem.
.IP \fBsize=\fRSIZE 4
.IX Item "size=SIZE"
.PD 0
.IP \fBsize=+\fRSIZE 4
.IX Item "size=+SIZE"
.PD
The total (virtual) size of the filesystem.
.Sp
If the \f(CW\*(C`size\*(C'\fR 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.
.Sp
Using \f(CW\*(C`size=SIZE\*(C'\fR 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.
.Sp
Using \f(CW\*(C`size=+SIZE\*(C'\fR specifies the minimum free space required after
the initial filesystem has been loaded.  (The actual free space might
be slightly larger).
.IP \fBtype=ext2\fR 4
.IX Item "type=ext2"
.PD 0
.IP \fBtype=ext3\fR 4
.IX Item "type=ext3"
.IP \fBtype=ext4\fR 4
.IX Item "type=ext4"
.PD
Select the filesystem type.  The default is \f(CW\*(C`ext2\*(C'\fR.
.SH NOTES
.IX Header "NOTES"
.SS "Users and groups"
.IX Subsection "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.
.SH "ENVIRONMENT VARIABLES"
.IX Header "ENVIRONMENT VARIABLES"
.ie n .IP """TMPDIR""" 4
.el .IP \f(CWTMPDIR\fR 4
.IX Item "TMPDIR"
The filesystem image is stored in a temporary file located in
\&\fI/var/tmp\fR by default.  You can override this location by setting the
\&\f(CW\*(C`TMPDIR\*(C'\fR environment variable before starting nbdkit.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$plugindir\fR\fI/nbdkit\-linuxdisk\-plugin.so\fR 4
.el .IP \fR\f(CI$plugindir\fR\fI/nbdkit\-linuxdisk\-plugin.so\fR 4
.IX Item "$plugindir/nbdkit-linuxdisk-plugin.so"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-linuxdisk\-plugin\*(C'\fR first appeared in nbdkit 1.12.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBmke2fs\fR\|(8),
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBnbdkit\-captive\fR\|(1),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-floppy\-plugin\fR\|(1),
\&\fBnbdkit\-iso\-plugin\fR\|(1),
\&\fBnbdkit\-partition\-filter\fR\|(1),
\&\fBnbdkit\-partitioning\-plugin\fR\|(1),
\&\fBnbdkit\-tmpdisk\-plugin\fR\|(1),
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.