filters/fua/nbdkit-fua-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-fua-filter - modify nbdkit flush and Forced Unit Access (FUA)
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit --filter=fua plugin [fuamode=MODE] [plugin-args...]
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-fua-filter> is a filter that intentionally modifies handling
  12 of the S<“Forced Unit Access”> (FUA) flag across the NBD protocol.
  13
  14 This filter can be used to disable FUA and flush requests for speed
  15 (although this is unsafe).  Also it can be used to test client or
  16 server fallbacks, and for evaluating timing differences between proper
  17 use of FUA compared to a full flush.
  18
  19 Note that by default, the NBD protocol does not guarantee that the use
  20 of FUA from one connection will be visible from another connection
  21 unless the server advertised NBD_FLAG_MULTI_CONN.  You may wish to
  22 combine this filter with L<nbdkit-multi-conn-filter(1)> if you plan on
  23 making multiple connections to the plugin.
  24
  25 =head1 PARAMETERS
  26
  27 The C<fuamode> parameter is optional and controls which mode the
  28 filter will use.
  29
  30 =over 4
  31
  32 =item B<fuamode=discard>
  33
  34 (nbdkit E<ge> 1.22)
  35
  36 The filter will discard FUA and flush requests.
  37
  38 B<This mode is unsafe>: If the NBD disk contains a filesystem then you
  39 will likely lose data in the event of a crash.  It should only be used
  40 for ephemeral data which you can easily recreate, such as caches,
  41 builds, test data, etc.
  42
  43 =item B<fuamode=pass>
  44
  45 (nbdkit E<ge> 1.22)
  46
  47 Pass through FUA and flush requests unchanged.  Turns the filter into
  48 a no-op.
  49
  50 =item B<fuamode=none>
  51
  52 FUA support is not advertised to the client.  Clients will not be able
  53 to issue FUA write requests, but can send flush commands if the plugin
  54 supports it.
  55
  56 This is the default if the C<fuamode> parameter is not specified.
  57
  58 =item B<fuamode=emulate>
  59
  60 The filter will emulate FUA support using the plugin’s C<.flush>
  61 callback, regardless of whether the plugin itself supports more
  62 efficient FUA.  It refuses to load if the plugin does not support
  63 flush.
  64
  65 =item B<fuamode=native>
  66
  67 The filter will advertise native FUA support to the client and earlier
  68 filters in the chain.  This is useful for comparing optimizations of
  69 FUA handling when splitting large requests into sub-requests.  It
  70 refuses to load if the plugin’s C<.can_fua> callback returns
  71 C<NBDKIT_FUA_NONE>.
  72
  73 =item B<fuamode=force>
  74
  75 The filter will request FUA on all write transactions, even when the
  76 client did not request it (“write-through” mode).  In turn client
  77 flush requests become no-ops.  It refuses to load if the plugin’s
  78 C<.can_fua> callback returns C<NBDKIT_FUA_NONE>.
  79
  80 =back
  81
  82 =head1 EXAMPLES
  83
  84 =over 4
  85
  86 =item *
  87
  88 Serve the file F<disk.img> discarding all FUA and flush requests.
  89 This can greatly improve performance, but you will likely lose data if
  90 there is a crash, so it is not safe.
  91
  92  nbdkit --filter=discard file disk.img fuamode=discard
  93
  94 =item *
  95
  96 Serve the file F<disk.img>, but force the client to submit explicit
  97 flush requests instead of using C<NBD_CMD_FLAG_FUA>:
  98
  99  nbdkit --filter=fua file disk.img
 100
 101 =item *
 102
 103 Observe that the blocksize filter optimizes its handling of the FUA
 104 flag based on whether it knows nbdkit will be emulating FUA with a
 105 flush, by comparing the log filter output on top of different fua
 106 filter modes:
 107
 108  nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
 109    maxlen=4k logfile=fua_emulated fuamode=emulate
 110  nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
 111    maxlen=4k logfile=fua_native fuamode=native
 112
 113 =item *
 114
 115 Serve the file F<disk.img> in write-through mode, where all writes
 116 from the client are immediately flushed to disk as if the client had
 117 always requested FUA:
 118
 119  nbdkit --filter=fua file disk.img fuamode=force
 120
 121 =back
 122
 123 =head1 FILES
 124
 125 =over 4
 126
 127 =item F<$filterdir/nbdkit-fua-filter.so>
 128
 129 The filter.
 130
 131 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 132
 133 =back
 134
 135 =head1 VERSION
 136
 137 C<nbdkit-fua-filter> first appeared in nbdkit 1.4.
 138
 139 =head1 SEE ALSO
 140
 141 L<nbdkit(1)>,
 142 L<nbdkit-file-plugin(1)>,
 143 L<nbdkit-filter(3)>,
 144 L<nbdkit-blocksize-filter(1)>,
 145 L<nbdkit-log-filter(1)>,
 146 L<nbdkit-multi-conn-filter(1)>,
 147 L<nbdkit-nocache-filter(1)>,
 148 L<nbdkit-noextents-filter(1)>,
 149 L<nbdkit-noparallel-filter(1)>,
 150 L<nbdkit-nozero-filter(1)>.
 151
 152 =head1 AUTHORS
 153
 154 Eric Blake
 155
 156 =head1 COPYRIGHT
 157
 158 Copyright (C) 2018 Red Hat Inc.