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

EXAMPLES

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

PARAMETERS

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

NOTES

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

ENVIRONMENT VARIABLES

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

FILES

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

VERSION

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

AUTHORS

146       Richard W.M. Jones
147

COPYRIGHT

149       Copyright (C) 2019 Red Hat Inc.
150

LICENSE

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