=head1 NAME

nbdkit-fua-filter - nbdkit FUA filter

=head1 SYNOPSIS

 nbdkit --filter=fua plugin [fuamode=MODE] [plugin-args...]

=head1 DESCRIPTION

C<nbdkit-fua-filter> is a filter that intentionally modifies handling
of the 'Forced Unit Access' (FUA) flag across the NBD protocol.  It is
mainly useful for testing client or server fallbacks, and for
evaluating timing differences between proper use of FUA compared to a
full flush.

=head1 PARAMETERS

=over 4

=item B<fuamode=none>

=item B<fuamode=emulate>

=item B<fuamode=native>

=item B<fuamode=force>

Optional, controls which mode the filter will use.  Mode B<none>
(default) means that FUA support is not advertised to the client.
Mode B<emulate> causes the filter to emulate FUA support using the
plugin's C<flush> callback, regardless of whether the plugin itself
supports more efficient FUA (or refuses to load if the plugin's
C<can_flush> callback returns false).  Mode B<native> causes the
filter to advertise native FUA support to earlier filters, useful for
comparing optimizations of FUA handling when splitting large requests
into sub-requests (or refuses to load if the plugin's C<can_fua>
callback returns C<NBDKIT_FUA_NONE>).  Mode B<force> causes the filter
to request FUA on all write transactions, even when the client did not
request it, and in turn treats client flush requests as a no-op (or
refuses to load if the plugin's C<can_fua> callback returns
C<NBDKIT_FUA_NONE>).

=back

=head1 EXAMPLES

Serve the file F<disk.img>, but force the client to submit explicit
flush requests instead of using C<NBD_CMD_FLAG_FUA>:

 nbdkit --filter=fua file disk.img

Observe that the blocksize filter optimizes its handling of the FUA
flag based on whether it knows nbdkit will be emulating FUA with a
flush, by comparing the log filter output on top of different fua
filter modes:

 nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
   maxlen=4k logfile=fua_emulated fuamode=emulate
 nbdkit --filter=blocksize --filter=log --filter=fua file disk.img \
   maxlen=4k logfile=fua_native fuamode=native

Serve the file F<disk.img> in write-through mode, where all writes
from the client are immediately flushed to disk as if the client had
always requested FUA:

 nbdkit --filter=fua file fuamode=force disk.img

=head1 FILES

=over 4

=item F<$filterdir/nbdkit-fua-filter.so>

The filter.

Use C<nbdkit --dump-config> to find the location of C<$filterdir>.

=back

=head1 VERSION

C<nbdkit-fua-filter> first appeared in nbdkit 1.2.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-file-plugin(1)>,
L<nbdkit-filter(3)>,
L<nbdkit-blocksize-filter(1)>,
L<nbdkit-log-filter(1)>,
L<nbdkit-nocache-filter(1)>,
L<nbdkit-noextents-filter(1)>,
L<nbdkit-noparallel-filter(1)>,
L<nbdkit-nozero-filter(1)>.

=head1 AUTHORS

Eric Blake

=head1 COPYRIGHT

Copyright (C) 2018 Red Hat Inc.
