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