1nbdkit-loop(1) NBDKIT nbdkit-loop(1)
2
6 nbdkit-loop - use nbdkit with the Linux kernel client to create loop
7 devices and loop mounts
8
10 nbdkit (server) can be used with the Linux kernel nbd (client) in a
11 loop mode allowing any of the plugins supported by nbdkit to be turned
12 into Linux block devices.
13 In addition to nbdkit(1) itself, the main commands you will use are:
15 nbd-client -b 512 localhost /dev/nbd0
17 Attaches a locally running nbdkit instance to the kernel device
18 /dev/nbd0. -b 512 can be omitted when using nbd-client(8) ≥ 3.19.
19 nbd-client -b 512 -unix /tmp/socket /dev/nbd0
21 Alternative method using a Unix domain socket instead of a public
22 TCP/IP socket. Use "nbdkit -U /tmp/socket" to serve.
23 nbd-client -d /dev/nbd0
25 Detaches /dev/nbd0.
26 nbd-client -c /dev/nbd0
28 Queries whether /dev/nbd0 is attached or not.
29 modprobe nbd
31 You may be need to run this command once to load the nbd client
32 kernel module.
33 The nbd-client(8) and modprobe(8) commands must be run as root.
35 Warning: Do not loop mount untrusted filesystems
37 Untrusted filesystems and untrusted disk images should not be loop
38 mounted because they could contain exploits that attack your host
39 kernel. Use the tools from libguestfs(3) instead since it safely
40 isolates untrusted filesystems from the host.
41 Loop mount a filesystem from a compressed file
43 If you have a filesystem or disk image in xz-compressed format then you
44 can use nbdkit-xz-filter(1) and nbdkit-file-plugin(1) to loop mount it
45 as follows:
46 nbdkit --filter=xz file disk.xz
48 nbd-client -b 512 localhost /dev/nbd0
49 mount /dev/nbd0p1 /mnt
50 Loop mount a filesystem from a web server
52 You can use nbdkit-curl-plugin(1) to loop mount a filesystem from a
53 disk image on a web server:
54 nbdkit [--filter=xz] curl https://example.com/disk.img
56 nbd-client -b 512 localhost /dev/nbd0
57 mount /dev/nbd0p1 /mnt
58 Use --filter=xz if the remote image is XZ-compressed.
60 Create a giant btrfs filesystem
62 nbdkit is useful for testing the limits of Linux filesystems. Using
63 nbdkit-memory-plugin(1) you can create virtual disks stored in RAM with
64 a virtual size up to 2⁶³-1 bytes, and then create filesystems on these:
65 nbdkit memory $(( 2**63 - 1 ))
67 nbd-client -b 512 localhost /dev/nbd0
68 Partition the device using GPT, creating a single partition with all
70 default settings:
71 gdisk /dev/nbd0
73 Make a btrfs filesystem on the disk and mount it:
75 mkfs.btrfs -K /dev/nbd0p1
77 mount /dev/nbd0p1 /mnt
78 Inject errors into Linux devices
80 Using nbdkit-error-filter(1) you can see how Linux devices react to
81 errors:
82 nbdkit --filter=error \
84 memory 64M \
85 error-rate=100% error-file=/tmp/inject
86 nbd-client -b 512 localhost /dev/nbd0
87 mkfs -t ext4 /dev/nbd0
88 mount /dev/nbd0 /mnt
89 Inject errors by touching /tmp/inject, and stop injecting errors by
91 removing this file.
92 Write Linux block devices in shell script
94 Using nbdkit-sh-plugin(3) you can write custom Linux block devices in
95 shell script for testing. For example the following shell script
96 creates a disk which contains a bad sector:
97 #!/bin/bash -
99 case "$1" in
100 thread_model) echo parallel ;;
101 get_size) echo 64M ;;
102 pread)
103 if [ $4 -le 100000 ] && [ $(( $4+$3 )) -gt 100000 ]; then
104 echo EIO Bad block >&2
105 exit 1
106 else
107 dd if=/dev/zero count=$3 iflag=count_bytes
108 fi ;;
109 *) exit 2 ;;
110 esac
111 Create a loop from this shell script using:
113 nbdkit sh ./bad-sector.sh
115 nbd-client -b 512 localhost /dev/nbd0
116 You can then try running tests such as:
118 badblocks /dev/nbd0
120
122 nbdkit(1), nbdkit-client(1), nbdkit-plugin(3), loop(4), losetup(8),
123 mount(8), nbdfuse(1), nbd-client(8), modprobe(8), libguestfs(3),
124 http://libguestfs.org.
125
127 Richard W.M. Jones
128
130 Copyright (C) 2013-2020 Red Hat Inc.
131
133 Redistribution and use in source and binary forms, with or without
134 modification, are permitted provided that the following conditions are
135 met:
136 • Redistributions of source code must retain the above copyright
138 notice, this list of conditions and the following disclaimer.
139 • Redistributions in binary form must reproduce the above copyright
141 notice, this list of conditions and the following disclaimer in the
142 documentation and/or other materials provided with the
143 distribution.
144 • Neither the name of Red Hat nor the names of its contributors may
146 be used to endorse or promote products derived from this software
147 without specific prior written permission.
148 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
150 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
151 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
152 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
153 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
154 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
155 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
156 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
157 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
158 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
159 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
160nbdkit-1.25.8 2021-05-25 nbdkit-loop(1)