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              [cache=default|none] [fadvise=normal|random|sequential]
   9
  10 =for paragraph
  11
  12  nbdkit file dir=DIRECTORY
  13
  14 =for paragraph
  15
  16  nbdkit file fd=FILE_DESCRIPTOR
  17
  18 =for paragraph
  19
  20  nbdkit file dirfd=FILE_DESCRIPTOR
  21
  22 =head1 DESCRIPTION
  23
  24 C<nbdkit-file-plugin> is a file serving plugin for L<nbdkit(1)>.
  25
  26 It serves the named C<FILENAME> over NBD.  Local block devices
  27 (eg. F</dev/sda>) may also be served.
  28
  29 If you use the C<dir> parameter the plugin works in a different mode
  30 where it serves files from the given C<DIRECTORY>, chosen by the
  31 client using the NBD export name.
  32
  33 If you use the C<fd> or C<dirfd> parameter then you can pass the file
  34 descriptor of a single disk or a directory to the plugin, inherited
  35 from the parent process.  This can be useful where special permissions
  36 or capabilities are needed to open the file descriptor, or you want to
  37 run nbdkit in a sandboxed environment.
  38
  39 =head1 PARAMETERS
  40
  41 Exactly one of B<file>, B<dir>, B<fd> or B<dirfd> must be given.  This
  42 controls the mode of the plugin, either serving a single file, the
  43 files in a directory, a single file descriptor, or the files in the
  44 directory of the file descriptor.
  45
  46 =over 4
  47
  48 =item B<cache=default>
  49
  50 =item B<cache=none>
  51
  52 (nbdkit E<ge> 1.22, not Windows)
  53
  54 Using C<cache=none> tries to prevent the kernel from keeping parts of
  55 the file that have already been read or written in the page cache.
  56
  57 =item B<dir=>DIRECTORY
  58
  59 (nbdkit E<ge> 1.22, not Windows)
  60
  61 Serve all regular files and block devices located directly inside the
  62 directory named C<DIRECTORY>, including those found by following
  63 symbolic links.  Other special files in the directory (such as
  64 subdirectories, pipes, or Unix sockets) are ignored.
  65
  66 When this mode is used, the file to be served is chosen by the export
  67 name passed by the client, where the client can request a list of
  68 available exports using NBD_OPT_LIST.  A client that requests the
  69 default export (C<"">) will be rejected.  However, you can use
  70 L<nbdkit-exportname-filter(1)> to adjust what export names the client
  71 sees or uses as a default.  For security, when using directory mode,
  72 this plugin will not accept export names containing slash (C</>).
  73
  74 =item B<dirfd=>FILE_DESCRIPTOR
  75
  76 (nbdkit E<ge> 1.34, not Windows)
  77
  78 This is like the I<dir> option, but instead of specifying the
  79 directory by name, the parent process should open the directory and
  80 pass this file descriptor by inheritance to nbdkit.
  81
  82 =item B<fadvise=normal>
  83
  84 =item B<fadvise=random>
  85
  86 =item B<fadvise=sequential>
  87
  88 (nbdkit E<ge> 1.22, not Windows)
  89
  90 This optional flag hints to the kernel that you will access the file
  91 normally, or in a random order, or sequentially.  The exact behaviour
  92 depends on your operating system, but for Linux using C<normal> causes
  93 the kernel to read-ahead, C<sequential> causes the kernel to
  94 read-ahead twice as much as C<normal>, and C<random> turns off
  95 read-ahead.  See also L<posix_fadvise(2)>.
  96
  97 The default is C<normal>.
  98
  99 =item B<fd=>FILE_DESCRIPTOR
 100
 101 (nbdkit E<ge> 1.34, not Windows)
 102
 103 The parameter is the number of a file descriptor.  Serve the file or
 104 device already open on this file descriptor.  The file descriptor is
 105 usually inherited from the parent process.
 106
 107 =item [B<file=>]FILENAME
 108
 109 Serve the file named C<FILENAME>.  A local block device name can also
 110 be used here.  When this mode is used, the export name requested by
 111 the client is ignored.
 112
 113 C<file=> is a magic config key and may be omitted in most cases.
 114 See L<nbdkit(1)/Magic parameters>.
 115
 116 =item [B<file=>]B<\\.\>CB<:>
 117
 118 =item [B<file=>]B<\\.\>Volume
 119
 120 =item [B<file=>]B<\\.\PhysicalDisk>I<N>
 121
 122 =item [B<file=>]B<\\.\CdRom>I<N>
 123
 124 (Windows only)
 125
 126 Serve the Windows volume specified by the device name.  See:
 127 L<https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-device-namespaces>.
 128
 129 =back
 130
 131 =head1 NOTES
 132
 133 =head2 Optimizing for random or sequential access
 134
 135 If you know in advance that the NBD client will access the file
 136 randomly or only sequentially then you can hint that to the kernel
 137 using:
 138
 139  nbdkit file disk.img fadvise=random
 140  nbdkit file disk.img fadvise=sequential
 141
 142 As described in the L</PARAMETERS> section above, on Linux this
 143 disables or increases the amount of read-ahead that the kernel does.
 144
 145 =head2 Reducing evictions from the page cache
 146
 147 If the file is very large and you know the client will only read/write
 148 the file sequentially one time (eg for making a single copy or backup)
 149 then this will stop other processes from being evicted from the page
 150 cache:
 151
 152  nbdkit file disk.img fadvise=sequential cache=none
 153
 154 Only use fadvise=sequential if reading, and the reads are mainly
 155 sequential.
 156
 157 =head2 Files on tmpfs
 158
 159 If you want to expose a file that resides on a file system known to
 160 have poor C<lseek(2)> performance when searching for holes (C<tmpfs>
 161 is known to be one such file system), you can use
 162 L<nbdkit-noextents-filter(1)> to avoid the penalty of probing for
 163 holes.
 164
 165 =head2 Plugin I<--dump-plugin> output
 166
 167 You can obtain extra information about how the file plugin was
 168 compiled by doing:
 169
 170  nbdkit file --dump-plugin
 171
 172 Some of the fields which may appear are listed below.  Note these are
 173 for information only and may be changed or removed at any time in the
 174 future.
 175
 176 =over 4
 177
 178 =item C<file_blksszget=yes>
 179
 180 =item C<file_blkzeroout=yes>
 181
 182 If both set, the plugin may be able to efficiently zero ranges of
 183 block devices, where the driver and block device itself supports this.
 184
 185 =item C<file_extents=yes>
 186
 187 If set, the plugin can read file extents.
 188
 189 =item C<file_falloc_fl_punch_hole=yes>
 190
 191 If set, the plugin may be able to punch holes (make sparse) files and
 192 block devices.
 193
 194 =item C<file_falloc_fl_zero_range=yes>
 195
 196 If set, the plugin may be able to efficiently zero ranges of files and
 197 block devices.
 198
 199 =item C<winfile=yes>
 200
 201 If present, this is the Windows version of the file plugin with
 202 reduced functionality and some special Windows-only features, as noted
 203 in this manual.
 204
 205 =back
 206
 207 =head2 Windows sparse files
 208
 209 This plugin supports sparse files on Windows (with hole punching).
 210 However for this to work the files must already have the sparse
 211 property, the plugin will not make existing files sparse.  Use the
 212 S<C<fsutil sparse>> command to control the sparseness property of
 213 files.
 214
 215 =head2 Old C<rdelay> and C<wdelay> parameters.
 216
 217 Before nbdkit supported filters (E<lt> 1.2) this plugin had extra
 218 parameters C<rdelay> and C<wdelay> to insert delays.  These parameters
 219 have been moved to L<nbdkit-delay-filter(1)>.  Modify the command line
 220 to add I<--filter=delay> in order to use these parameters.
 221
 222 =head2 Concatenating files
 223
 224 To concatenate and export multiple files, use
 225 L<nbdkit-split-plugin(1)>.
 226
 227 =head1 DEBUG FLAG
 228
 229 =over 4
 230
 231 =item B<-D file.zero=1>
 232
 233 This enables very verbose debugging of the NBD zero request.  This can
 234 be used to tell if the file plugin is able to zero ranges in the file
 235 or block device efficiently or not.
 236
 237 =back
 238
 239 =head1 FILES
 240
 241 =over 4
 242
 243 =item F<$plugindir/nbdkit-file-plugin.so>
 244
 245 The plugin.
 246
 247 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 248
 249 =back
 250
 251 =head1 VERSION
 252
 253 C<nbdkit-file-plugin> first appeared in nbdkit 1.0.
 254
 255 =head1 SEE ALSO
 256
 257 L<nbdkit(1)>,
 258 L<nbdkit-plugin(3)>,
 259 L<nbdkit-split-plugin(1)>,
 260 L<nbdkit-partitioning-plugin(1)>,
 261 L<nbdkit-tmpdisk-plugin(1)>,
 262 L<nbdkit-exportname-filter(1)>,
 263 L<nbdkit-fua-filter(1)>,
 264 L<nbdkit-luks-filter(1)>,
 265 L<nbdkit-noextents-filter(1)>.
 266
 267 =head1 AUTHORS
 268
 269 Eric Blake
 270
 271 Nir Soffer
 272
 273 Richard W.M. Jones
 274
 275 =head1 COPYRIGHT
 276
 277 Copyright Red Hat