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=DIRNAME
13

DESCRIPTION

15       "nbdkit-file-plugin" is a file serving plugin for nbdkit(1).
16
17       It serves the named "FILENAME" over NBD.  Local block devices (eg.
18       /dev/sda) may also be served.  It may also be used to serve any file
19       within a given "DIRECTORY", according to which export name the guest
20       requests.
21

PARAMETERS

23       One of file or dir must be given to determine which mode the server
24       will use.
25
26       cache=default
27       cache=none
28           (nbdkit ≥ 1.22, not Windows)
29
30           Using "cache=none" tries to prevent the kernel from keeping parts
31           of the file that have already been read or written in the page
32           cache.
33
34       fadvise=normal
35       fadvise=random
36       fadvise=sequential
37           (nbdkit ≥ 1.22, not Windows)
38
39           This optional flag hints to the kernel that you will access the
40           file normally, or in a random order, or sequentially.  The exact
41           behaviour depends on your operating system, but for Linux using
42           "normal" causes the kernel to read-ahead, "sequential" causes the
43           kernel to read-ahead twice as much as "normal", and "random" turns
44           off read-ahead.  See also posix_fadvise(2).
45
46           The default is "normal".
47
48       [file=]FILENAME
49           Serve the file named "FILENAME".  A local block device name can
50           also be used here.  When this mode is used, the export name
51           requested by the client is ignored.
52
53           "file=" is a magic config key and may be omitted in most cases.
54           See "Magic parameters" in nbdkit(1).
55
56       [file=]\\.\C:
57       [file=]\\.\Volume
58       [file=]\\.\PhysicalDiskN
59       [file=]\\.\CdRomN
60           (Windows only)
61
62           Serve the Windows volume specified by the device name.  See:
63           https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file#win32-device-namespaces.
64
65       dir=DIRNAME
66           (nbdkit ≥ 1.22, not Windows)
67
68           Serve all regular files and block devices located directly within
69           the directory named "DIRNAME", including those found by following
70           symbolic links.  Other special files in the directory (such as
71           subdirectories, fifos, or Unix sockets) are ignored.  When this
72           mode is used, the file to be served is chosen by the export name
73           passed by the client, where the client can request a list of
74           available exports using NBD_OPT_LIST.  A client that requests the
75           default export ("") will be rejected.  However, you can use
76           nbdkit-exportname-filter(1) to adjust what export names the client
77           sees or uses as a default.  For security, when using directory
78           mode, this plugin will not accept export names containing slash
79           ("/").
80

NOTES

82   Optimizing for random or sequential access
83       If you know in advance that the NBD client will access the file
84       randomly or only sequentially then you can hint that to the kernel
85       using:
86
87        nbdkit file disk.img fadvise=random
88        nbdkit file disk.img fadvise=sequential
89
90       As described in the "PARAMETERS" section above, on Linux this disables
91       or increases the amount of read-ahead that the kernel does.
92
93   Reducing evictions from the page cache
94       If the file is very large and you know the client will only read/write
95       the file sequentially one time (eg for making a single copy or backup)
96       then this will stop other processes from being evicted from the page
97       cache:
98
99        nbdkit file disk.img fadvise=sequential cache=none
100
101   Files on tmpfs
102       If you want to expose a file that resides on a file system known to
103       have poor lseek(2) performance when searching for holes ("tmpfs" is
104       known to be one such file system), you can use
105       nbdkit-noextents-filter(1) to avoid the penalty of probing for holes.
106
107   Plugin --dump-plugin output
108       You can obtain extra information about how the file plugin was compiled
109       by doing:
110
111        nbdkit file --dump-plugin
112
113       Some of the fields which may appear are listed below.  Note these are
114       for information only and may be changed or removed at any time in the
115       future.
116
117       "file_blksszget=yes"
118       "file_blkzeroout=yes"
119           If both set, the plugin may be able to efficiently zero ranges of
120           block devices, where the driver and block device itself supports
121           this.
122
123       "file_falloc_fl_punch_hole=yes"
124           If set, the plugin may be able to punch holes (make sparse) files
125           and block devices.
126
127       "file_falloc_fl_zero_range=yes"
128           If set, the plugin may be able to efficiently zero ranges of files
129           and block devices.
130
131       "winfile=yes"
132           If present, this is the Windows version of the file plugin which
133           lacks certain features as noted in this manual.
134
135   Windows sparse files
136       This plugin supports sparse files on Windows (with hole punching).
137       However for this to work the files must already have the sparse
138       property, the plugin will not make existing files sparse.  Use the
139       "fsutil sparse" command to control the sparseness property of files.
140
141   Old "rdelay" and "wdelay" parameters.
142       Before nbdkit supported filters (< 1.2) this plugin had extra
143       parameters "rdelay" and "wdelay" to insert delays.  These parameters
144       have been moved to nbdkit-delay-filter(1).  Modify the command line to
145       add --filter=delay in order to use these parameters.
146
147   Concatenating files
148       To concatenate and export multiple files, use nbdkit-split-plugin(1).
149

DEBUG FLAG

151       -D file.zero=1
152           This enables very verbose debugging of the NBD zero request.  This
153           can be used to tell if the file plugin is able to zero ranges in
154           the file or block device efficiently or not.
155

FILES

157       $plugindir/nbdkit-file-plugin.so
158           The plugin.
159
160           Use "nbdkit --dump-config" to find the location of $plugindir.
161

VERSION

163       "nbdkit-file-plugin" first appeared in nbdkit 1.0.
164

AUTHORS

172       Eric Blake
173
174       Nir Soffer
175
176       Richard W.M. Jones
177

COPYRIGHT

179       Copyright (C) 2013-2020 Red Hat Inc.
180

LICENSE

182       Redistribution and use in source and binary forms, with or without
183       modification, are permitted provided that the following conditions are
184       met:
185
186       ·   Redistributions of source code must retain the above copyright
187           notice, this list of conditions and the following disclaimer.
188
189       ·   Redistributions in binary form must reproduce the above copyright
190           notice, this list of conditions and the following disclaimer in the
191           documentation and/or other materials provided with the
192           distribution.
193
194       ·   Neither the name of Red Hat nor the names of its contributors may
195           be used to endorse or promote products derived from this software
196           without specific prior written permission.
197
198       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
199       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
200       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
201       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
202       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
203       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
204       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
205       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
206       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
207       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
208       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
209
210
211
212nbdkit-1.24.2                     2021-03-02             nbdkit-file-plugin(1)