plugins/file/nbdkit-file-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-file-plugin - nbdkit file plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit file [file=]FILENAME
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-file-plugin> is a file serving plugin for L<nbdkit(1)>.
  12
  13 It serves the named C<FILENAME> over NBD.  Local block devices
  14 (eg. F</dev/sda>) may also be served.
  15
  16 To concatenate multiple files, use L<nbdkit-split-plugin(1)>.
  17
  18 If you want to expose a file that resides on a file system known to
  19 have poor C<lseek(2)> performance when searching for holes (C<tmpfs>
  20 is known to be one such file system), you can use
  21 L<nbdkit-noextents-filter(1)> to avoid the penalty of probing for
  22 holes.
  23
  24 =head1 PARAMETERS
  25
  26 =over 4
  27
  28 =item [B<file=>]FILENAME
  29
  30 Serve the file named C<FILENAME>.  A local block device name can also
  31 be used here.
  32
  33 This parameter is required.
  34
  35 C<file=> is a magic config key and may be omitted in most cases.
  36 See L<nbdkit(1)/Magic parameters>.
  37
  38 =item B<rdelay>
  39
  40 =item B<wdelay>
  41
  42 These plugin parameters have been moved to the
  43 L<nbdkit-delay-filter(1)> filter.  Modify the command line to add
  44 I<--filter=delay> in order to use these parameters.
  45
  46 =back
  47
  48 =head1 DUMP-PLUGIN OUTPUT
  49
  50 You can obtain extra information about how the file plugin was
  51 compiled by doing:
  52
  53  nbdkit file --dump-plugin
  54
  55 Some of the fields which may appear are listed below.  Note these are
  56 for information only and may be changed or removed at any time in the
  57 future.
  58
  59 =over 4
  60
  61 =item C<file_blksszget=yes>
  62
  63 =item C<file_blkzeroout=yes>
  64
  65 If both set, the plugin may be able to efficiently zero ranges of
  66 block devices, where the driver and block device itself supports this.
  67
  68 =item C<file_falloc_fl_punch_hole=yes>
  69
  70 If set, the plugin may be able to punch holes (make sparse) files and
  71 block devices.
  72
  73 =item C<file_falloc_fl_zero_range=yes>
  74
  75 If set, the plugin may be able to efficiently zero ranges of files and
  76 block devices.
  77
  78 =back
  79
  80 =head1 DEBUG FLAG
  81
  82 =over 4
  83
  84 =item B<-D file.zero=1>
  85
  86 This enables very verbose debugging of the NBD zero request.  This can
  87 be used to tell if the file plugin is able to zero ranges in the file
  88 or block device efficiently or not.
  89
  90 =back
  91
  92 =head1 FILES
  93
  94 =over 4
  95
  96 =item F<$plugindir/nbdkit-file-plugin.so>
  97
  98 The plugin.
  99
 100 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 101
 102 =back
 103
 104 =head1 VERSION
 105
 106 C<nbdkit-file-plugin> first appeared in nbdkit 1.0.
 107
 108 =head1 SEE ALSO
 109
 110 L<nbdkit(1)>,
 111 L<nbdkit-plugin(3)>,
 112 L<nbdkit-split-plugin(1)>,
 113 L<nbdkit-partitioning-plugin(1)>,
 114 L<nbdkit-noextents-filter(1)>.
 115
 116 =head1 AUTHORS
 117
 118 Eric Blake
 119
 120 Nir Soffer
 121
 122 Richard W.M. Jones
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright (C) 2013-2018 Red Hat Inc.