docs/nbdkit-loop.pod

   1 =head1 NAME
   2
   3 nbdkit-loop - use nbdkit with the Linux kernel client to create loop
   4 devices and loop mounts
   5
   6 =head1 DESCRIPTION
   7
   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.
  11
  12 In addition to L<nbdkit(1)> itself, the main commands you will use
  13 are:
  14
  15 =over 4
  16
  17 =item nbd-client localhost /dev/nbd0
  18
  19 Attaches a locally running nbdkit instance to the kernel device
  20 F</dev/nbd0>.
  21
  22 =item nbd-client -unix /tmp/socket /dev/nbd0
  23
  24 Alternative method using a Unix domain socket instead of a public
  25 TCP/IP socket.  Use C<nbdkit -U /tmp/socket> to serve.
  26
  27 =item nbd-client -d /dev/nbd0
  28
  29 Detaches F</dev/nbd0>.
  30
  31 =item nbd-client -c /dev/nbd0
  32
  33 Queries whether F</dev/nbd0> is attached or not.
  34
  35 =item modprobe nbd
  36
  37 You may be need to run this command once to load the nbd client kernel
  38 module.
  39
  40 =back
  41
  42 The L<nbd-client(8)> and L<modprobe(8)> commands must be run as root.
  43
  44 =head2 Warning: Do not loop mount untrusted filesystems
  45
  46 Untrusted filesystems and untrusted disk images should not be loop
  47 mounted because they could contain exploits that attack your host
  48 kernel.  Use the tools from L<libguestfs(3)> instead since it safely
  49 isolates untrusted filesystems from the host.
  50
  51 =head2 Loop mount a filesystem from a compressed file
  52
  53 If you have a filesystem or disk image in xz-compressed format then
  54 you can use L<nbdkit-xz-filter(1)> and L<nbdkit-file-plugin(1)> to
  55 loop mount it as follows:
  56
  57  nbdkit --filter=xz file disk.xz
  58  nbd-client localhost /dev/nbd0
  59  mount /dev/nbd0p1 /mnt
  60
  61 =head2 Loop mount a filesystem from a web server
  62
  63 You can use L<nbdkit-curl-plugin(1)> to loop mount a filesystem from a
  64 disk image on a web server:
  65
  66  nbdkit [--filter=xz] curl https://example.com/disk.img
  67  nbd-client localhost /dev/nbd0
  68  mount /dev/nbd0p1 /mnt
  69
  70 Use I<--filter=xz> if the remote image is XZ-compressed.
  71
  72 =head2 Create a giant btrfs filesystem
  73
  74 nbdkit is useful for testing the limits of Linux filesystems.  Using
  75 L<nbdkit-memory-plugin(1)> you can create virtual disks stored in RAM
  76 with a virtual size up to S<2⁶³-1 bytes>, and then create filesystems
  77 on these:
  78
  79  nbdkit memory $(( 2**63 - 1 ))
  80  nbd-client localhost /dev/nbd0
  81
  82 Partition the device using GPT, creating a single partition with all
  83 default settings:
  84
  85  gdisk /dev/nbd0
  86
  87 Make a btrfs filesystem on the disk and mount it:
  88
  89  mkfs.btrfs -K /dev/nbd0p1
  90  mount /dev/nbd0p1 /mnt
  91
  92 =head2 Inject errors into Linux devices
  93
  94 Using L<nbdkit-error-filter(1)> you can see how Linux devices react to
  95 errors:
  96
  97  nbdkit --filter=error \
  98         memory 64M \
  99         error-rate=100% error-file=/tmp/inject
 100  nbd-client localhost /dev/nbd0
 101  mkfs -t ext4 /dev/nbd0
 102  mount /dev/nbd0 /mnt
 103
 104 Inject errors by touching F</tmp/inject>, and stop injecting errors by
 105 removing this file.
 106
 107 =head2 Write Linux block devices in shell script
 108
 109 Using L<nbdkit-sh-plugin(3)> you can write custom Linux block devices
 110 in shell script for testing.  For example the following shell script
 111 creates a disk which contains a bad sector:
 112
 113  #!/bin/bash -
 114  case "$1" in
 115      thread_model) echo parallel ;;
 116      get_size) echo 64M ;;
 117      pread)
 118          if [ $4 -le 100000 ] && [ $(( $4+$3 )) -gt 100000 ]; then
 119              echo EIO Bad block >&2
 120              exit 1
 121          else
 122              dd if=/dev/zero count=$3 iflag=count_bytes
 123          fi ;;
 124      *) exit 2 ;;
 125  esac
 126
 127 Create a loop from this shell script using:
 128
 129  nbdkit sh ./bad-sector.sh
 130  nbd-client localhost /dev/nbd0
 131
 132 You can then try running tests such as:
 133
 134  badblocks /dev/nbd0
 135
 136 =head1 SEE ALSO
 137
 138 L<nbdkit(1)>,
 139 L<nbdkit-client(1)>,
 140 L<nbdkit-plugin(3)>,
 141 L<loop(4)>,
 142 L<losetup(8)>,
 143 L<mount(8)>,
 144 L<nbdfuse(1)>,
 145 L<nbd-client(8)>,
 146 L<modprobe(8)>,
 147 L<libguestfs(3)>, L<http://libguestfs.org>.
 148
 149 =head1 AUTHORS
 150
 151 Richard W.M. Jones
 152
 153 =head1 COPYRIGHT
 154
 155 Copyright Red Hat