1nbdkit-linuxdisk-plugin(1) NBDKIT nbdkit-linuxdisk-plugin(1)
2
3
4
6 nbdkit-linuxdisk-plugin - create virtual Linux disk from directory
7
9 nbdkit linuxdisk [dir=]DIRECTORY
10 [label=LABEL] [type=ext2|ext3|ext4]
11 [size=[+]SIZE]
12
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
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 -U - linuxdisk /path/to/directory --run 'nbdcopy "$uri"
54 ext2fs.img'
55 This serves nothing. Instead it turns a directory into a disk
56 image, writing it to ext2fs.img (see nbdkit-captive(1)). The
57 resulting image is a partitioned disk.
58
59 Create a minimal virtual appliance
60 This creates and boots a minimal busybox(1)-based virtual
61 appliance. This assumes that your kernel (/boot/vmlinuz) contains
62 the ext2 or ext4 driver compiled in, but most Linux distro kernels
63 have that.
64
65 mkdir -p root/{bin,dev,proc,sbin,sys,usr/bin,usr/sbin}
66 sudo mknod root/dev/console c 5 1
67 cp /sbin/busybox root/sbin/
68 ln root/sbin/busybox root/sbin/init
69 ln root/sbin/busybox root/bin/ls
70 ln root/sbin/busybox root/bin/sh
71 nbdkit -U - linuxdisk root --run '
72 qemu-kvm -display none -kernel /boot/vmlinuz -drive file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1 rw" -serial stdio
73 '
74
75 You can drop any extra files you need into the root/ directory and
76 they will be copied into the appliance before boot. After booting
77 type these commands to complete the environmental setup:
78
79 /sbin/busybox --install
80 mount -t proc proc /proc
81 mount -t sysfs sys /sys
82
84 [dir=]DIRECTORY
85 Specify the directory containing files and subdirectories which
86 will be added to the virtual disk. Files inside this directory
87 will appear in the root directory of the virtual disk.
88
89 This parameter is required.
90
91 "dir=" is a magic config key and may be omitted in most cases. See
92 "Magic parameters" in nbdkit(1).
93
94 label=LABEL
95 The optional label for the filesystem.
96
97 size=SIZE
98 size=+SIZE
99 The total (virtual) size of the filesystem.
100
101 If the "size" parameter is omitted the plugin will try to size the
102 filesystem with just enough space to contain the files and
103 directories that are initially loaded, and there will not be much
104 extra space.
105
106 Using "size=SIZE" specifies the required virtual size of the whole
107 filesystem (including initial files and extra space). If this is
108 set too small for the initial filesystem then the plugin will fail
109 to start.
110
111 Using "size=+SIZE" specifies the minimum free space required after
112 the initial filesystem has been loaded. (The actual free space
113 might be slightly larger).
114
115 type=ext2
116 type=ext3
117 type=ext4
118 Select the filesystem type. The default is "ext2".
119
121 Users and groups
122 The original file UIDs and GIDs are recreated as far as possible. Note
123 that UIDs/GIDs will likely map to different users and groups when read
124 by a virtual machine or other NBD client machine.
125
127 "TMPDIR"
128 The filesystem image is stored in a temporary file located in
129 /var/tmp by default. You can override this location by setting the
130 "TMPDIR" environment variable before starting nbdkit.
131
133 $plugindir/nbdkit-linuxdisk-plugin.so
134 The plugin.
135
136 Use "nbdkit --dump-config" to find the location of $plugindir.
137
139 "nbdkit-linuxdisk-plugin" first appeared in nbdkit 1.12.
140
142 mke2fs(8), nbdkit(1), nbdkit-plugin(3), nbdkit-captive(1),
143 nbdkit-cow-filter(1), nbdkit-file-plugin(1), nbdkit-floppy-plugin(1),
144 nbdkit-iso-plugin(1), nbdkit-partition-filter(1),
145 nbdkit-partitioning-plugin(1), nbdkit-tmpdisk-plugin(1),
146
148 Richard W.M. Jones
149
151 Copyright (C) 2019 Red Hat Inc.
152
154 Redistribution and use in source and binary forms, with or without
155 modification, are permitted provided that the following conditions are
156 met:
157
158 • Redistributions of source code must retain the above copyright
159 notice, this list of conditions and the following disclaimer.
160
161 • Redistributions in binary form must reproduce the above copyright
162 notice, this list of conditions and the following disclaimer in the
163 documentation and/or other materials provided with the
164 distribution.
165
166 • Neither the name of Red Hat nor the names of its contributors may
167 be used to endorse or promote products derived from this software
168 without specific prior written permission.
169
170 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
171 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
172 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
173 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
174 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
175 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
176 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
177 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
178 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
179 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
180 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
181
182
183
184nbdkit-1.25.8 2021-05-25 nbdkit-linuxdisk-plugin(1)