3 nbdkit-loop - use nbdkit with the Linux kernel client to create loop
4 devices and loop mounts
8 nbdkit (server) can be used with the Linux kernel nbd (client) in a
9 loop mode allowing any of the plugins supported by nbdkit to be turned
10 into Linux block devices.
12 In addition to L<nbdkit(1)> itself, the main commands you will use
17 =item nbd-client -b 512 localhost /dev/nbd0
19 which attaches a locally running nbdkit instance to the kernel device
20 F</dev/nbd0>. I<-b 512> can be omitted when using
21 S<L<nbd-client(8)> E<ge> 3.19>.
23 =item nbd-client -d /dev/nbd0
25 which detaches F</dev/nbd0>, and:
27 =item nbd-client -c /dev/nbd0
29 which queries whether F</dev/nbd0> is attached or not.
33 which may be needed to load the nbd client kernel module.
37 The L<nbd-client(8)> and L<modprobe(8)> commands must be run as root.
39 =head2 Warning: Do not loop mount untrusted filesystems
41 Untrusted filesystems and untrusted disk images should not be loop
42 mounted because they could contain exploits that attack your host
43 kernel. Use the tools from L<libguestfs(3)> instead since it safely
44 isolates untrusted filesystems from the host.
46 =head2 Loop mount a filesystem from a compressed file
48 If you have a filesystem or disk image in xz-compressed format then
49 you can use L<nbdkit-xz-filter(1)> and L<nbdkit-file-plugin(1)> to
50 loop mount it as follows:
52 nbdkit --filter=xz file disk.xz
53 nbd-client -b 512 localhost /dev/nbd0
54 mount /dev/nbd0p1 /mnt
56 =head2 Loop mount a filesystem from a web server
58 You can use L<nbdkit-curl-plugin(1)> to loop mount a filesystem from a
59 disk image on a web server:
61 nbdkit [--filter=xz] curl https://example.com/disk.img
62 nbd-client -b 512 localhost /dev/nbd0
63 mount /dev/nbd0p1 /mnt
65 Use I<--filter=xz> if the remote image is XZ-compressed.
67 =head2 Create a giant btrfs filesystem
69 nbdkit is useful for testing the limits of Linux filesystems. Using
70 L<nbdkit-memory-plugin(1)> you can create virtual disks stored in RAM
71 with a virtual size up to S<2⁶³-1 bytes>, and then create filesystems
74 nbdkit memory $(( 2**63 - 1 ))
75 nbd-client -b 512 localhost /dev/nbd0
77 Partition the device using GPT, creating a single partition with all
82 Make a btrfs filesystem on the disk and mount it:
84 mkfs.btrfs -K /dev/nbd0p1
85 mount /dev/nbd0p1 /mnt
87 =head2 Inject errors into Linux devices
89 Using L<nbdkit-error-filter(1)> you can see how Linux devices react to
92 nbdkit --filter=error \
94 error-rate=100% error-file=/tmp/inject
95 nbd-client -b 512 localhost /dev/nbd0
96 mkfs -t ext4 /dev/nbd0
99 Inject errors by touching F</tmp/inject>, and stop injecting errors by
102 =head2 Write Linux block devices in shell script
104 Using L<nbdkit-sh-plugin(3)> you can write custom Linux block devices
105 in shell script for testing. For example the following shell script
106 creates a disk which contains a bad sector:
110 get_size) echo 64M ;;
112 if [ $4 -le 100000 ] && [ $(( $4+$3 )) -gt 100000 ]; then
113 echo EIO Bad block >&2
116 dd if=/dev/zero count=$3 iflag=count_bytes
121 Create a loop from this shell script using:
123 nbdkit sh ./bad-sector.sh
124 nbd-client -b 512 localhost /dev/nbd0
126 You can then try running tests such as:
139 L<libguestfs(3)>, L<http://libguestfs.org>.
147 Copyright (C) 2013-2018 Red Hat Inc.