nbdkit-linuxdisk-plugin(1)

1nbdkit-linuxdisk-plugin(1)          NBDKIT          nbdkit-linuxdisk-plugin(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14       "nbdkit-linuxdisk-plugin" is a plugin for nbdkit(1) which creates an
15       ext2-, ext3- or ext4-formatted disk image from a directory on the fly.
16       The files in the specified directory (and subdirectories) appear in the
17       virtual disk, which is served read-only over the NBD protocol.
18
19       The virtual disk is partitioned with a single GPT partition containing
20       the filesystem.
21
22       The virtual disk can be used as a Linux root (or other) filesystem.
23       Most features of Linux filesystems are supported, such as hard links,
24       symbolic links, block special devices etc.
25
26       To create a FAT-formatted virtual floppy disk, see
27       nbdkit-floppy-plugin(1).  To create a CD/ISO, see nbdkit-iso-plugin(1).
28       To create an empty filesystem for each client that connects (like a
29       "remote tmpfs") use nbdkit-tmpdisk-plugin(1).
30

EXAMPLES

32       nbdkit linuxdisk /path/to/directory label=ROOTFS
33           Create a virtual disk, giving it a filesystem label.  Note that
34           clients will not be able to modify the filesystem, so it is safe to
35           share it with multiple clients.
36
37       nbdkit --filter=cow linuxdisk /path/to/directory
38           Add a writable overlay (see nbdkit-cow-filter(1), allowing the disk
39           to be written by the client.  Multiple clients must not be allowed
40           to connect at the same time (even if they all mount it read-only)
41           as this will cause disk corruption.
42
43       nbdkit --filter=cow linuxdisk /path/to/directory size=+1G
44           The same but specifying that at least 1G of free space should be
45           available in the filesystem (not including the space taken by the
46           initial filesystem).
47
48       nbdkit --filter=partition linuxdisk /path/to/directory partition=1
49           Instead of serving a partitioned disk image, serve just the "naked"
50           filesystem (ie. the first partition, see
51           nbdkit-partition-filter(1)).
52
53       nbdkit linuxdisk /path/to/directory --run 'nbdcopy "$uri" ext2fs.img'
54           This serves nothing.  Instead it turns a directory into a disk
55           image, writing it to ext2fs.img (see nbdkit-captive(1)).  The
56           resulting image is a partitioned disk.
57
58       Create a minimal virtual appliance
59           This creates and boots a minimal busybox(1)-based virtual
60           appliance.  This assumes that your kernel (/boot/vmlinuz) contains
61           the ext2 or ext4 driver compiled in, but most Linux distro kernels
62           have that.
63
64            mkdir -p root/{bin,dev,proc,sbin,sys,usr/bin,usr/sbin}
65            sudo mknod root/dev/console c 5 1
66            cp /sbin/busybox root/sbin/
67            ln root/sbin/busybox root/sbin/init
68            ln root/sbin/busybox root/bin/ls
69            ln root/sbin/busybox root/bin/sh
70            nbdkit linuxdisk root --run '
71              qemu-kvm -display none -kernel /boot/vmlinuz -drive file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1 rw" -serial stdio
72            '
73
74           You can drop any extra files you need into the root/ directory and
75           they will be copied into the appliance before boot.  After booting
76           type these commands to complete the environmental setup:
77
78            /sbin/busybox --install
79            mount -t proc proc /proc
80            mount -t sysfs sys /sys
81

PARAMETERS

83       [dir=]DIRECTORY
84           Specify the directory containing files and subdirectories which
85           will be added to the virtual disk.  Files inside this directory
86           will appear in the root directory of the virtual disk.
87
88           This parameter is required.
89
90           "dir=" is a magic config key and may be omitted in most cases.  See
91           "Magic parameters" in nbdkit(1).
92
93       label=LABEL
94           The optional label for the filesystem.
95
96       size=SIZE
97       size=+SIZE
98           The total (virtual) size of the filesystem.
99
100           If the "size" parameter is omitted the plugin will try to size the
101           filesystem with just enough space to contain the files and
102           directories that are initially loaded, and there will not be much
103           extra space.
104
105           Using "size=SIZE" specifies the required virtual size of the whole
106           filesystem (including initial files and extra space).  If this is
107           set too small for the initial filesystem then the plugin will fail
108           to start.
109
110           Using "size=+SIZE" specifies the minimum free space required after
111           the initial filesystem has been loaded.  (The actual free space
112           might be slightly larger).
113
114       type=ext2
115       type=ext3
116       type=ext4
117           Select the filesystem type.  The default is "ext2".
118

NOTES

120   Users and groups
121       The original file UIDs and GIDs are recreated as far as possible.  Note
122       that UIDs/GIDs will likely map to different users and groups when read
123       by a virtual machine or other NBD client machine.
124

ENVIRONMENT VARIABLES

126       "TMPDIR"
127           The filesystem image is stored in a temporary file located in
128           /var/tmp by default.  You can override this location by setting the
129           "TMPDIR" environment variable before starting nbdkit.
130

FILES

132       $plugindir/nbdkit-linuxdisk-plugin.so
133           The plugin.
134
135           Use "nbdkit --dump-config" to find the location of $plugindir.
136

VERSION

138       "nbdkit-linuxdisk-plugin" first appeared in nbdkit 1.12.
139

AUTHORS

147       Richard W.M. Jones
148

COPYRIGHT

150       Copyright Red Hat
151

LICENSE

153       Redistribution and use in source and binary forms, with or without
154       modification, are permitted provided that the following conditions are
155       met:
156
157       •   Redistributions of source code must retain the above copyright
158           notice, this list of conditions and the following disclaimer.
159
160       •   Redistributions in binary form must reproduce the above copyright
161           notice, this list of conditions and the following disclaimer in the
162           documentation and/or other materials provided with the
163           distribution.
164
165       •   Neither the name of Red Hat nor the names of its contributors may
166           be used to endorse or promote products derived from this software
167           without specific prior written permission.
168
169       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
170       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
171       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
172       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
173       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
174       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
175       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
176       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
177       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
178       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
179       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
180
181
182
183nbdkit-1.36.2                     2023-11-26        nbdkit-linuxdisk-plugin(1)