=head1 NAME

nbdkit-file-plugin - nbdkit file plugin

=head1 SYNOPSIS

 nbdkit file [file=]FILENAME

=head1 DESCRIPTION

C<nbdkit-file-plugin> is a file serving plugin for L<nbdkit(1)>.

It serves the named C<FILENAME> over NBD.  Local block devices
(eg. F</dev/sda>) may also be served.

To concatenate multiple files, use L<nbdkit-split-plugin(1)>.

If you want to expose a file that resides on a file system known to
have poor C<lseek(2)> performance when searching for holes (C<tmpfs>
is known to be one such file system), you can use
L<nbdkit-noextents-filter(1)> to avoid the penalty of probing for
holes.

=head1 PARAMETERS

=over 4

=item [B<file=>]FILENAME

Serve the file named C<FILENAME>.  A local block device name can also
be used here.

This parameter is required.

C<file=> is a magic config key and may be omitted in most cases.
See L<nbdkit(1)/Magic parameters>.

=item B<rdelay>

=item B<wdelay>

These plugin parameters have been moved to the
L<nbdkit-delay-filter(1)> filter.  Modify the command line to add
I<--filter=delay> in order to use these parameters.

=back

=head1 DUMP-PLUGIN OUTPUT

You can obtain extra information about how the file plugin was
compiled by doing:

 nbdkit file --dump-plugin

Some of the fields which may appear are listed below.  Note these are
for information only and may be changed or removed at any time in the
future.

=over 4

=item C<file_blksszget=yes>

=item C<file_blkzeroout=yes>

If both set, the plugin may be able to efficiently zero ranges of
block devices, where the driver and block device itself supports this.

=item C<file_falloc_fl_punch_hole=yes>

If set, the plugin may be able to punch holes (make sparse) files and
block devices.

=item C<file_falloc_fl_zero_range=yes>

If set, the plugin may be able to efficiently zero ranges of files and
block devices.

=back

=head1 DEBUG FLAG

=over 4

=item B<-D file.zero=1>

This enables very verbose debugging of the NBD zero request.  This can
be used to tell if the file plugin is able to zero ranges in the file
or block device efficiently or not.

=back

=head1 FILES

=over 4

=item F<$plugindir/nbdkit-file-plugin.so>

The plugin.

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

=back

=head1 VERSION

C<nbdkit-file-plugin> first appeared in nbdkit 1.0.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-plugin(3)>,
L<nbdkit-split-plugin(1)>,
L<nbdkit-partitioning-plugin(1)>,
L<nbdkit-noextents-filter(1)>.

=head1 AUTHORS

Eric Blake

Nir Soffer

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2013-2018 Red Hat Inc.
