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 -b 512 localhost /dev/nbd0
  18
  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>.
  22
  23 =item nbd-client -d /dev/nbd0
  24
  25 which detaches F</dev/nbd0>, and:
  26
  27 =item nbd-client -c /dev/nbd0
  28
  29 which queries whether F</dev/nbd0> is attached or not.
  30
  31 =item modprobe nbd
  32
  33 which may be needed to load the nbd client kernel module.
  34
  35 =back
  36
  37 The L<nbd-client(8)> and L<modprobe(8)> commands must be run as root.
  38
  39 =head2 Warning: Do not loop mount untrusted filesystems
  40
  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.
  45
  46 =head2 Loop mount a filesystem from a compressed file
  47
  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:
  51
  52  nbdkit --filter=xz file disk.xz
  53  nbd-client -b 512 localhost /dev/nbd0
  54  mount /dev/nbd0p1 /mnt
  55
  56 =head2 Loop mount a filesystem from a web server
  57
  58 You can use L<nbdkit-curl-plugin(1)> to loop mount a filesystem from a
  59 disk image on a web server:
  60
  61  nbdkit [--filter=xz] curl https://example.com/disk.img
  62  nbd-client -b 512 localhost /dev/nbd0
  63  mount /dev/nbd0p1 /mnt
  64
  65 Use I<--filter=xz> if the remote image is XZ-compressed.
  66
  67 =head2 Create a giant btrfs filesystem
  68
  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
  72 on these:
  73
  74  nbdkit memory $(( 2**63 - 1 ))
  75  nbd-client -b 512 localhost /dev/nbd0
  76
  77 Partition the device using GPT, creating a single partition with all
  78 default settings:
  79
  80  gdisk /dev/nbd0
  81
  82 Make a btrfs filesystem on the disk and mount it:
  83
  84  mkfs.btrfs -K /dev/nbd0p1
  85  mount /dev/nbd0p1 /mnt
  86
  87 =head2 Inject errors into Linux devices
  88
  89 Using L<nbdkit-error-filter(1)> you can see how Linux devices react to
  90 errors:
  91
  92  nbdkit --filter=error \
  93         memory 64M \
  94         error-rate=100% error-file=/tmp/inject
  95  nbd-client -b 512 localhost /dev/nbd0
  96  mkfs -t ext4 /dev/nbd0
  97  mount /dev/nbd0 /mnt
  98
  99 Inject errors by touching F</tmp/inject>, and stop injecting errors by
 100 removing this file.
 101
 102 =head2 Write Linux block devices in shell script
 103
 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:
 107
 108  #!/bin/bash -
 109  case "$1" in
 110      thread_model) echo parallel ;;
 111      get_size) echo 64M ;;
 112      pread)
 113          if [ $4 -le 100000 ] && [ $(( $4+$3 )) -gt 100000 ]; then
 114              echo EIO Bad block >&2
 115              exit 1
 116          else
 117              dd if=/dev/zero count=$3 iflag=count_bytes
 118          fi ;;
 119      *) exit 2 ;;
 120  esac
 121
 122 Create a loop from this shell script using:
 123
 124  nbdkit sh ./bad-sector.sh
 125  nbd-client -b 512 localhost /dev/nbd0
 126
 127 You can then try running tests such as:
 128
 129  badblocks /dev/nbd0
 130
 131 =head1 SEE ALSO
 132
 133 L<nbdkit(1)>,
 134 L<nbdkit-plugin(3)>,
 135 L<loop(4)>,
 136 L<losetup(8)>,
 137 L<mount(8)>,
 138 L<nbd-client(8)>,
 139 L<modprobe(8)>,
 140 L<libguestfs(3)>, L<http://libguestfs.org>.
 141
 142 =head1 AUTHORS
 143
 144 Richard W.M. Jones
 145
 146 =head1 COPYRIGHT
 147
 148 Copyright (C) 2013-2018 Red Hat Inc.