nbdkit-file-plugin(1)

1nbdkit-file-plugin(1)               NBDKIT               nbdkit-file-plugin(1)
2
3
4

NAME

6       nbdkit-file-plugin - nbdkit file plugin
7

SYNOPSIS

9        nbdkit file [file=]FILENAME
10                    [cache=default|none] [fadvise=normal|random|sequential]
11
12        nbdkit file dir=DIRECTORY
13
14        nbdkit file fd=FILE_DESCRIPTOR
15
16        nbdkit file dirfd=FILE_DESCRIPTOR
17

DESCRIPTION

19       "nbdkit-file-plugin" is a file serving plugin for nbdkit(1).
20
21       It serves the named "FILENAME" over NBD.  Local block devices (eg.
22       /dev/sda) may also be served.
23
24       If you use the "dir" parameter the plugin works in a different mode
25       where it serves files from the given "DIRECTORY", chosen by the client
26       using the NBD export name.
27
28       If you use the "fd" or "dirfd" parameter then you can pass the file
29       descriptor of a single disk or a directory to the plugin, inherited
30       from the parent process.  This can be useful where special permissions
31       or capabilities are needed to open the file descriptor, or you want to
32       run nbdkit in a sandboxed environment.
33

PARAMETERS

35       Exactly one of file, dir, fd or dirfd must be given.  This controls the
36       mode of the plugin, either serving a single file, the files in a
37       directory, a single file descriptor, or the files in the directory of
38       the file descriptor.
39
40       cache=default
41       cache=none
42           (nbdkit ≥ 1.22, not Windows)
43
44           Using "cache=none" tries to prevent the kernel from keeping parts
45           of the file that have already been read or written in the page
46           cache.
47
48       dir=DIRECTORY
49           (nbdkit ≥ 1.22, not Windows)
50
51           Serve all regular files and block devices located directly inside
52           the directory named "DIRECTORY", including those found by following
53           symbolic links.  Other special files in the directory (such as
54           subdirectories, pipes, or Unix sockets) are ignored.
55
56           When this mode is used, the file to be served is chosen by the
57           export name passed by the client, where the client can request a
58           list of available exports using NBD_OPT_LIST.  A client that
59           requests the default export ("") will be rejected.  However, you
60           can use nbdkit-exportname-filter(1) to adjust what export names the
61           client sees or uses as a default.  For security, when using
62           directory mode, this plugin will not accept export names containing
63           slash ("/").
64
65       dirfd=FILE_DESCRIPTOR
66           (nbdkit ≥ 1.34, not Windows)
67
68           This is like the dir option, but instead of specifying the
69           directory by name, the parent process should open the directory and
70           pass this file descriptor by inheritance to nbdkit.
71
72       fadvise=normal
73       fadvise=random
74       fadvise=sequential
75           (nbdkit ≥ 1.22, not Windows)
76
77           This optional flag hints to the kernel that you will access the
78           file normally, or in a random order, or sequentially.  The exact
79           behaviour depends on your operating system, but for Linux using
80           "normal" causes the kernel to read-ahead, "sequential" causes the
81           kernel to read-ahead twice as much as "normal", and "random" turns
82           off read-ahead.  See also posix_fadvise(2).
83
84           The default is "normal".
85
86       fd=FILE_DESCRIPTOR
87           (nbdkit ≥ 1.34, not Windows)
88
89           The parameter is the number of a file descriptor.  Serve the file
90           or device already open on this file descriptor.  The file
91           descriptor is usually inherited from the parent process.
92
93       [file=]FILENAME
94           Serve the file named "FILENAME".  A local block device name can
95           also be used here.  When this mode is used, the export name
96           requested by the client is ignored.
97
98           "file=" is a magic config key and may be omitted in most cases.
99           See "Magic parameters" in nbdkit(1).
100
101       [file=]\\.\C:
102       [file=]\\.\Volume
103       [file=]\\.\PhysicalDiskN
104       [file=]\\.\CdRomN
105           (Windows only)
106
107           Serve the Windows volume specified by the device name.  See:
108           https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-device-namespaces.
109

NOTES

111   Optimizing for random or sequential access
112       If you know in advance that the NBD client will access the file
113       randomly or only sequentially then you can hint that to the kernel
114       using:
115
116        nbdkit file disk.img fadvise=random
117        nbdkit file disk.img fadvise=sequential
118
119       As described in the "PARAMETERS" section above, on Linux this disables
120       or increases the amount of read-ahead that the kernel does.
121
122   Reducing evictions from the page cache
123       If the file is very large and you know the client will only read/write
124       the file sequentially one time (eg for making a single copy or backup)
125       then this will stop other processes from being evicted from the page
126       cache:
127
128        nbdkit file disk.img fadvise=sequential cache=none
129
130       Only use fadvise=sequential if reading, and the reads are mainly
131       sequential.
132
133   Files on tmpfs
134       If you want to expose a file that resides on a file system known to
135       have poor lseek(2) performance when searching for holes ("tmpfs" is
136       known to be one such file system), you can use
137       nbdkit-noextents-filter(1) to avoid the penalty of probing for holes.
138
139   Plugin --dump-plugin output
140       You can obtain extra information about how the file plugin was compiled
141       by doing:
142
143        nbdkit file --dump-plugin
144
145       Some of the fields which may appear are listed below.  Note these are
146       for information only and may be changed or removed at any time in the
147       future.
148
149       "file_blksszget=yes"
150       "file_blkzeroout=yes"
151           If both set, the plugin may be able to efficiently zero ranges of
152           block devices, where the driver and block device itself supports
153           this.
154
155       "file_extents=yes"
156           If set, the plugin can read file extents.
157
158       "file_falloc_fl_punch_hole=yes"
159           If set, the plugin may be able to punch holes (make sparse) files
160           and block devices.
161
162       "file_falloc_fl_zero_range=yes"
163           If set, the plugin may be able to efficiently zero ranges of files
164           and block devices.
165
166       "winfile=yes"
167           If present, this is the Windows version of the file plugin with
168           reduced functionality and some special Windows-only features, as
169           noted in this manual.
170
171   Windows sparse files
172       This plugin supports sparse files on Windows (with hole punching).
173       However for this to work the files must already have the sparse
174       property, the plugin will not make existing files sparse.  Use the
175       "fsutil sparse" command to control the sparseness property of files.
176
177   Old "rdelay" and "wdelay" parameters.
178       Before nbdkit supported filters (< 1.2) this plugin had extra
179       parameters "rdelay" and "wdelay" to insert delays.  These parameters
180       have been moved to nbdkit-delay-filter(1).  Modify the command line to
181       add --filter=delay in order to use these parameters.
182
183   Concatenating files
184       To concatenate and export multiple files, use nbdkit-split-plugin(1).
185

DEBUG FLAG

187       -D file.zero=1
188           This enables very verbose debugging of the NBD zero request.  This
189           can be used to tell if the file plugin is able to zero ranges in
190           the file or block device efficiently or not.
191

FILES

193       $plugindir/nbdkit-file-plugin.so
194           The plugin.
195
196           Use "nbdkit --dump-config" to find the location of $plugindir.
197

VERSION

199       "nbdkit-file-plugin" first appeared in nbdkit 1.0.
200

AUTHORS

208       Eric Blake
209
210       Nir Soffer
211
212       Richard W.M. Jones
213

COPYRIGHT

215       Copyright Red Hat
216

LICENSE

218       Redistribution and use in source and binary forms, with or without
219       modification, are permitted provided that the following conditions are
220       met:
221
222       •   Redistributions of source code must retain the above copyright
223           notice, this list of conditions and the following disclaimer.
224
225       •   Redistributions in binary form must reproduce the above copyright
226           notice, this list of conditions and the following disclaimer in the
227           documentation and/or other materials provided with the
228           distribution.
229
230       •   Neither the name of Red Hat nor the names of its contributors may
231           be used to endorse or promote products derived from this software
232           without specific prior written permission.
233
234       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
235       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
236       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
237       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
238       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
239       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
240       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
241       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
242       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
243       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
244       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
245
246
247
248nbdkit-1.34.4                     2023-09-26             nbdkit-file-plugin(1)