Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
nbdkit-file-plugin(1)		    NBDKIT		 nbdkit-file-plugin(1)

NAME
       nbdkit-file-plugin - nbdkit file	plugin

SYNOPSIS
	nbdkit file [file=]FILENAME
		    [fadvise=normal|random|sequential]
		    [reduce-memory-pressure=true]

	nbdkit file dir=DIRECTORY

	nbdkit file fd=FILE_DESCRIPTOR

	nbdkit file dirfd=FILE_DESCRIPTOR

DESCRIPTION
       "nbdkit-file-plugin" is a file serving plugin for nbdkit(1).

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

       If you use the "dir" parameter the plugin works in a different mode
       where it	serves files from the given "DIRECTORY", chosen	by the client
       using the NBD export name.

       If you use the "fd" or "dirfd" parameter	then you can pass the file
       descriptor of a single disk or a	directory to the plugin, inherited
       from the	parent process.	 This can be useful where special permissions
       or capabilities are needed to open the file descriptor, or you want to
       run nbdkit in a sandboxed environment.

       The file	is writable unless either the -r command line option, or
       nbdkit-readonly-filter(1) is used.

PARAMETERS
       Exactly one of file, dir, fd or dirfd must be given.  This controls the
       mode of the plugin, either serving a single file, the files in a
       directory, a single file	descriptor, or the files in the	directory of
       the file	descriptor.

       dir=DIRECTORY
	   (nbdkit  1.22, not Windows)

	   Serve all regular files and block devices located directly inside
	   the directory named "DIRECTORY", including those found by following
	   symbolic links.  Other special files	in the directory (such as
	   subdirectories, pipes, or Unix sockets) are ignored.

	   See "Serving	multiple files and block devices" below.

       dirfd=FILE_DESCRIPTOR
	   (nbdkit  1.34, not Windows)

	   This	is like	the "dir=" option, but instead of specifying the
	   directory by	name, the parent process should	open the directory and
	   pass	this file descriptor by	inheritance to nbdkit.

	   See "Serving	multiple files and block devices" below.

       fadvise=normal
       fadvise=random
       fadvise=sequential
	   (nbdkit  1.22, not Windows)

	   This	optional flag hints to the kernel that you will	access the
	   file	normally, or in	a random order,	or sequentially.  The exact
	   behaviour depends on	your operating system, but for Linux using
	   "normal" causes the kernel to read-ahead, "sequential" causes the
	   kernel to read-ahead	twice as much as "normal", and "random"	turns
	   off read-ahead.  See	also posix_fadvise(2).

	   The default is "normal".

       fd=FILE_DESCRIPTOR
	   (nbdkit  1.34, not Windows)

	   The parameter is the	number of a file descriptor.  Serve the	file
	   or device already open on this file descriptor.  The	file
	   descriptor is usually inherited from	the parent process.

       [file=]FILENAME
	   Serve the file named	"FILENAME".  A local block device name can
	   also	be used	here.  When this mode is used, the export name
	   requested by	the client is ignored.

	   "file=" prefix may be omitted in most cases.	 See "Magic
	   parameters" in nbdkit(1).

       [file=]\\.\C:
       [file=]\\.\Volume
       [file=]\\.\PhysicalDiskN
       [file=]\\.\CdRomN
	   (Windows only)

	   Serve the Windows volume specified by the device name.  See:
	   https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-device-namespaces.

       reduce-memory-pressure=true
	   (nbdkit  1.22, not Windows)

	   If the file is very large and the plugin will read or write the
	   whole file, this can	cause the file to be cached in memory (in the
	   page	cache on Linux), causing other files and processes to be
	   evicted, leading to overall slow system performance and I/O storms.

	   If you know that the	file will only be read/written once and	will
	   not be needed afterwards (so	keeping	it in memory afterwards	is
	   pointless) use "reduce-memory-pressure=true".  This causes reads
	   and writes to minimize use of the page cache.

	   The default is false, which uses the	kernel's normal	page cache
	   strategy.

	   See also "fadvise" above which can be used to hint the access
	   pattern.

	   In nbdkit 1.22 - 1.44 this option was called	"cache=none", but that
	   caused a lot	of confusion for people	used to	qemu and kernel
	   caching modes, which	are not	related	to this	setting.

NOTES
   Serving multiple files and block devices
       Using "dir=DIRECTORY" (or "dirfd=DIRFD")	you can	serve all regular
       files and block devices located directly	inside the directory named
       "DIRECTORY", including those found by following symbolic	links.	Other
       special files in	the directory (such as subdirectories, pipes, or Unix
       sockets)	are ignored.

       When this mode is used, the file	to be served is	chosen by the export
       name passed by the client.  For security, when using directory mode,
       this plugin will	not accept export names	containing slash ("/").

       For example:

	$ ls -l	/var/tmp/exports
	total 0
	-rw-r--r--. 1 rjones rjones 1048576 Dec	14 15:34 disk1
	-rw-r--r--. 1 rjones rjones 2097152 Dec	14 15:34 disk2
	lrwxrwxrwx. 1 rjones rjones	  9 Dec	14 15:35 sda1 -> /dev/sda1
	$ nbdkit file dir=/var/tmp/exports

       will serve three	exports	called "disk1",	"disk2"	and "sda1".  The first
       two are regular files and the last is a block device.  You can add or
       remove files or symbolic	links from the directory while nbdkit is
       running.

       To list exports,	use nbdinfo(1) --list option, for example:

	$ nbdinfo --list nbd://localhost
	protocol: newstyle-fixed without TLS, using structured packets
	export="disk1":
	    export-size: 1048576 (1M)
	    uri: nbd://localhost:10809/disk1
	[etc]

       An NBD client can request a list	of available exports using
       "NBD_OPT_LIST".	For libnbd clients see nbd_opt_list(3).

       A client	that requests the default export ("") will be rejected.
       However,	you can	use nbdkit-exportname-filter(1)	to adjust the default
       export as well as other transformations of export names.	 For example
       to make /var/tmp/exports/disk1 be the default export:

	nbdkit file dir=/var/tmp/exports \
	       --filter=exportname default-export=disk1

   Optimizing for random or sequential access
       If you know in advance that the NBD client will access the file
       randomly	or only	sequentially then you can hint that to the kernel
       using:

	nbdkit file disk.img fadvise=random
	nbdkit file disk.img fadvise=sequential

       As described in the "PARAMETERS"	section	above, on Linux	this disables
       or increases the	amount of read-ahead that the kernel does.

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

   Plugin --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.

       "file_block_size=yes"
	   If set, the plugin has support for getting the minimum and
	   preferred I/O size of block devices.

       "file_blkrotational=yes"
	   If set, the plugin has support for getting the rotational property
	   of block devices.

       "file_blksszget=yes"
       "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.

       "file_blkdiscard=yes"
	   If set, the plugin may be able to efficiently trim ranges of	block
	   devices, where the driver and block device itself supports this.

       "file_extents=yes"
	   If set, the plugin can read file extents.

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

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

       "winfile=yes"
	   If present, this is the Windows version of the file plugin with
	   reduced functionality and some special Windows-only features, as
	   noted in this manual.

   Windows sparse files
       This plugin supports sparse files on Windows (with hole punching).
       However for this	to work	the files must already have the	sparse
       property, the plugin will not make existing files sparse.  Use the
       "fsutil sparse" command to control the sparseness property of files.

   Old "rdelay"	and "wdelay" parameters.
       Before nbdkit supported filters (< 1.2) this plugin had extra
       parameters "rdelay" and "wdelay"	to insert delays.  These parameters
       have been moved to nbdkit-delay-filter(1).  Modify the command line to
       add --filter=delay in order to use these	parameters.

   Concatenating files
       To concatenate and export multiple files, use nbdkit-split-plugin(1).

DEBUG FLAG
       -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.

FILES
       $plugindir/nbdkit-file-plugin.so
	   The plugin.

	   Use "nbdkit --dump-config" to find the location of $plugindir.

VERSION
       "nbdkit-file-plugin" first appeared in nbdkit 1.0.

SEE ALSO
       nbdkit(1), nbdkit-plugin(3), nbdkit-split-plugin(1),
       nbdkit-partitioning-plugin(1), nbdkit-tmpdisk-plugin(1),
       nbdkit-nfs-plugin(1), nbdkit-count-filter(1),
       nbdkit-exportname-filter(1), nbdkit-fua-filter(1),
       nbdkit-luks-filter(1), nbdkit-noextents-filter(1),
       nbdkit-readonly-filter(1), nbdinfo(1).

AUTHORS
       Eric Blake

       Nir Soffer

       Richard W.M. Jones

COPYRIGHT
       Copyright Red Hat

LICENSE
       Redistribution and use in source	and binary forms, with or without
       modification, are permitted provided that the following conditions are
       met:

       •   Redistributions of source code must retain the above	copyright
	   notice, this	list of	conditions and the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright
	   notice, this	list of	conditions and the following disclaimer	in the
	   documentation and/or	other materials	provided with the
	   distribution.

       •   Neither the name of Red Hat nor the names of	its contributors may
	   be used to endorse or promote products derived from this software
	   without specific prior written permission.

       THIS SOFTWARE IS	PROVIDED BY RED	HAT AND	CONTRIBUTORS ''AS IS'' AND ANY
       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
       LIABLE FOR ANY DIRECT, INDIRECT,	INCIDENTAL, SPECIAL, EXEMPLARY,	OR
       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS	OR SERVICES; LOSS OF USE, DATA,	OR PROFITS; OR
       BUSINESS	INTERRUPTION) HOWEVER CAUSED AND ON ANY	THEORY OF LIABILITY,
       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE	USE OF THIS SOFTWARE, EVEN IF
       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

nbdkit-1.46.0			  2026-03-04		 nbdkit-file-plugin(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nbdkit-file-plugin&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>

home | help