filters/cow/nbdkit-cow-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-cow-filter - nbdkit copy-on-write (COW) filter
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=cow plugin [plugin-args...]
   8                             [cow-block-size=N]
   9                             [cow-on-cache=false|true]
  10                             [cow-on-read=false|true|/PATH]
  11
  12 =head1 DESCRIPTION
  13
  14 C<nbdkit-cow-filter> is a filter that makes a temporary writable copy
  15 on top of a plugin.  It can also be used to enable writes for plugins
  16 which are read-only.
  17
  18 The underlying plugin is opened read-only.  This filter does not pass
  19 any writes or write-like operations (like trim and zero) through to
  20 the underlying plugin.
  21
  22 B<Note that anything written is thrown away as soon as nbdkit exits.>
  23 If you want to save changes, either copy out the whole disk using a
  24 tool like L<nbdcopy(1)>, or use the method described in L</NOTES>
  25 below to create a diff.
  26
  27 Limitations of the filter include:
  28
  29 =over 4
  30
  31 =item *
  32
  33 The underlying file/device must not be resized.
  34
  35 =item *
  36
  37 The underlying plugin must behave “normally”, meaning that it must
  38 serve the same data to each client.
  39
  40 =back
  41
  42 =head1 PARAMETERS
  43
  44 =over 4
  45
  46 =item B<cow-block-size=>N
  47
  48 Set the block size used by the filter.  This has to be a power of two
  49 and the minimum block size is 4K.  The maximum block size depends on
  50 the plugin, but a block size larger than a few megabytes is not
  51 usually a good idea.
  52
  53 The default is 64K.
  54
  55 =item B<cow-on-cache=false>
  56
  57 Do not save data from cache (prefetch) requests in the overlay.  This
  58 leaves the overlay as small as possible.  This is the default.
  59
  60 =item B<cow-on-cache=true>
  61
  62 When the client issues a cache (prefetch) request, preemptively save
  63 the data from the plugin into the overlay.
  64
  65 =item B<cow-on-read=false>
  66
  67 Do not save data from read requests in the overlay.  This leaves the
  68 overlay as small as possible.  This is the default.
  69
  70 =item B<cow-on-read=true>
  71
  72 When the client issues a read request, copy the data into the overlay
  73 so that the same data can be served more quickly later.
  74
  75 =item B<cow-on-read=/PATH>
  76
  77 When F</PATH> (which must be an absolute path) exists, this behaves
  78 like C<cow-on-read=true>, and when it does not exist like
  79 C<cow-on-read=false>.  This allows you to control the C<cow-on-read>
  80 behaviour while nbdkit is running.
  81
  82 =back
  83
  84 =head1 EXAMPLES
  85
  86 =head2 nbdkit --filter=cow file disk.img
  87
  88 Serve the file F<disk.img>, allowing writes, but do not save any
  89 changes into the file.
  90
  91 =head2 nbdkit --filter=cow --filter=xz file disk.xz cow-on-read=true
  92
  93 L<nbdkit-xz-filter(1)> only supports read access, but you can provide
  94 temporary write access by using the command above.  Because xz
  95 decompression is slow, using C<cow-on-read=true> causes reads to be
  96 cached as well as writes, improving performance at the expense of
  97 using more temporary space.  Note that writes are thrown away when
  98 nbdkit exits and do not get saved into the file.
  99
 100 =head1 NOTES
 101
 102 =head2 Creating a diff with qemu-img
 103
 104 Although nbdkit-cow-filter itself cannot save the differences, it is
 105 possible to do this using an obscure feature of L<qemu-img(1)>.
 106 B<nbdkit must remain continuously running during the whole operation,
 107 otherwise all changes will be lost>.
 108
 109 Run nbdkit:
 110
 111  nbdkit --filter=cow file disk.img
 112
 113 and then connect with a client and make whatever changes you need.
 114 At the end, disconnect the client.
 115
 116 Run these C<qemu-img> commands to construct a qcow2 file containing
 117 the differences:
 118
 119  qemu-img create -F raw -b nbd:localhost -f qcow2 diff.qcow2
 120  qemu-img rebase -F raw -b disk.img -f qcow2 diff.qcow2
 121
 122 F<diff.qcow2> now contains the differences between the base
 123 (F<disk.img>) and the changes stored in nbdkit-cow-filter.  C<nbdkit>
 124 can now be killed.
 125
 126 =head2 Compared to nbd-server -c option
 127
 128 All connections to the nbdkit instance see the same view of the disk.
 129 This is different from L<nbd-server(1)> I<-c> option where each
 130 connection sees its own copy-on-write overlay and simply disconnecting
 131 the client throws that away.  It also allows us to create diffs as
 132 above.
 133
 134 =head1 ENVIRONMENT VARIABLES
 135
 136 =over 4
 137
 138 =item C<TMPDIR>
 139
 140 The copy-on-write changes are stored in a temporary file located in
 141 F</var/tmp> by default.  You can override this location by setting the
 142 C<TMPDIR> environment variable before starting nbdkit.
 143
 144 =back
 145
 146 =head1 FILES
 147
 148 =over 4
 149
 150 =item F<$filterdir/nbdkit-cow-filter.so>
 151
 152 The filter.
 153
 154 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 155
 156 =back
 157
 158 =head1 VERSION
 159
 160 C<nbdkit-cow-filter> first appeared in nbdkit 1.2.
 161
 162 =head1 SEE ALSO
 163
 164 L<nbdkit(1)>,
 165 L<nbdkit-file-plugin(1)>,
 166 L<nbdkit-cache-filter(1)>,
 167 L<nbdkit-cacheextents-filter(1)>,
 168 L<nbdkit-xz-filter(1)>,
 169 L<nbdkit-filter(3)>,
 170 L<nbdcopy(1)>,
 171 L<qemu-img(1)>.
 172
 173 =head1 AUTHORS
 174
 175 Eric Blake
 176
 177 Richard W.M. Jones
 178
 179 =head1 COPYRIGHT
 180
 181 Copyright Red Hat