1=head1 NAME
2
3nbdkit-linuxdisk-plugin - create virtual Linux disk from directory
4
5=head1 SYNOPSIS
6
7 nbdkit linuxdisk [dir=]DIRECTORY
8                  [label=LABEL] [type=ext2|ext3|ext4]
9                  [size=[+]SIZE]
10
11=head1 DESCRIPTION
12
13C<nbdkit-linuxdisk-plugin> is a plugin for L<nbdkit(1)> which creates
14an ext2-, ext3- or ext4-formatted disk image from a directory on the
15fly.  The files in the specified directory (and subdirectories) appear
16in the virtual disk, which is served read-only over the NBD protocol.
17
18The virtual disk is partitioned with a single GPT partition containing
19the filesystem.
20
21The virtual disk can be used as a Linux root (or other) filesystem.
22Most features of Linux filesystems are supported, such as hard links,
23symbolic links, block special devices etc.
24
25To create a FAT-formatted virtual floppy disk, see
26L<nbdkit-floppy-plugin(1)>.  To create a CD/ISO, see
27L<nbdkit-iso-plugin(1)>.  To create an empty filesystem for each
28client that connects (like a "remote tmpfs") use
29L<nbdkit-tmpdisk-plugin(1)>.
30
31=head1 EXAMPLES
32
33=over 4
34
35=item nbdkit linuxdisk /path/to/directory label=ROOTFS
36
37Create a virtual disk, giving it a filesystem label.  Note that
38clients will not be able to modify the filesystem, so it is safe to
39share it with multiple clients.
40
41=item nbdkit --filter=cow linuxdisk /path/to/directory
42
43Add a writable overlay (see L<nbdkit-cow-filter(1)>, allowing the disk
44to be written by the client.  B<Multiple clients must not be allowed
45to connect at the same time> (even if they all mount it read-only) as
46this will cause disk corruption.
47
48=item nbdkit --filter=cow linuxdisk /path/to/directory size=+1G
49
50The same but specifying that at least 1G of free space should be
51available in the filesystem (not including the space taken by the
52initial filesystem).
53
54=item nbdkit --filter=partition linuxdisk /path/to/directory partition=1
55
56Instead of serving a partitioned disk image, serve just the "naked"
57filesystem (ie. the first partition, see
58L<nbdkit-partition-filter(1)>).
59
60=item nbdkit -U - linuxdisk /path/to/directory
61--run 'qemu-img convert $nbd ext2fs.img'
62
63This serves nothing.  Instead it turns a directory into a disk image,
64writing it to F<ext2fs.img> (see L<nbdkit-captive(1)>).  The resulting
65image is a partitioned disk.
66
67=item Create a minimal virtual appliance
68
69This creates and boots a minimal L<busybox(1)>-based virtual
70appliance.  This assumes that your kernel (F</boot/vmlinuz>) contains
71the ext2 or ext4 driver compiled in, but most Linux distro kernels
72have that.
73
74 mkdir -p root/{bin,dev,proc,sbin,sys,usr/bin,usr/sbin}
75 sudo mknod root/dev/console c 5 1
76 cp /sbin/busybox root/sbin/
77 ln root/sbin/busybox root/sbin/init
78 ln root/sbin/busybox root/bin/ls
79 ln root/sbin/busybox root/bin/sh
80 nbdkit -U - linuxdisk root --run '
81   qemu-kvm -display none -kernel /boot/vmlinuz -drive file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1 rw" -serial stdio
82 '
83
84You can drop any extra files you need into the F<root/> directory and
85they will be copied into the appliance before boot.  After booting
86type these commands to complete the environmental setup:
87
88 /sbin/busybox --install
89 mount -t proc proc /proc
90 mount -t sysfs sys /sys
91
92=back
93
94=head1 PARAMETERS
95
96=over 4
97
98=item [B<dir=>]DIRECTORY
99
100Specify the directory containing files and subdirectories which will
101be added to the virtual disk.  Files inside this directory will appear
102in the root directory of the virtual disk.
103
104This parameter is required.
105
106C<dir=> is a magic config key and may be omitted in most cases.
107See L<nbdkit(1)/Magic parameters>.
108
109=item B<label=>LABEL
110
111The optional label for the filesystem.
112
113=item B<size=>SIZE
114
115=item B<size=+>SIZE
116
117The total (virtual) size of the filesystem.
118
119If the C<size> parameter is omitted the plugin will try to size the
120filesystem with just enough space to contain the files and directories
121that are initially loaded, and there will not be much extra space.
122
123Using C<size=SIZE> specifies the required virtual size of the whole
124filesystem (including initial files and extra space).  If this is set
125too small for the initial filesystem then the plugin will fail to
126start.
127
128Using C<size=+SIZE> specifies the minimum free space required after
129the initial filesystem has been loaded.  (The actual free space might
130be slightly larger).
131
132=item B<type=ext2>
133
134=item B<type=ext3>
135
136=item B<type=ext4>
137
138Select the filesystem type.  The default is C<ext2>.
139
140=back
141
142=head1 NOTES
143
144=head2 Users and groups
145
146The original file UIDs and GIDs are recreated as far as possible.
147Note that UIDs/GIDs will likely map to different users and groups when
148read by a virtual machine or other NBD client machine.
149
150=head1 ENVIRONMENT VARIABLES
151
152=over 4
153
154=item C<TMPDIR>
155
156The filesystem image is stored in a temporary file located in
157F</var/tmp> by default.  You can override this location by setting the
158C<TMPDIR> environment variable before starting nbdkit.
159
160=back
161
162=head1 FILES
163
164=over 4
165
166=item F<$plugindir/nbdkit-linuxdisk-plugin.so>
167
168The plugin.
169
170Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
171
172=back
173
174=head1 VERSION
175
176C<nbdkit-linuxdisk-plugin> first appeared in nbdkit 1.12.
177
178=head1 SEE ALSO
179
180L<mke2fs(8)>,
181L<nbdkit(1)>,
182L<nbdkit-plugin(3)>,
183L<nbdkit-captive(1)>,
184L<nbdkit-cow-filter(1)>,
185L<nbdkit-file-plugin(1)>,
186L<nbdkit-floppy-plugin(1)>,
187L<nbdkit-iso-plugin(1)>,
188L<nbdkit-partition-filter(1)>,
189L<nbdkit-partitioning-plugin(1)>,
190L<nbdkit-tmpdisk-plugin(1)>,
191
192=head1 AUTHORS
193
194Richard W.M. Jones
195
196=head1 COPYRIGHT
197
198Copyright (C) 2019 Red Hat Inc.
199