1nbdkit-extentlist-filter(1)         NBDKIT         nbdkit-extentlist-filter(1)
2
3
4

NAME

6       nbdkit-extentlist-filter - place extent list over a plugin
7

SYNOPSIS

9        nbdkit -r --filter=extentlist plugin extentlist=FILENAME
10

DESCRIPTION

12       "nbdkit-extentlist-filter" is an nbdkit filter that lets you place a
13       static list of extents on top of an existing plugin.  Extents record
14       whether or not specific parts of the disk are allocated or sparse.
15
16       You can use this with plugins which cannot get extent information
17       themselves, but where you can get this information from another source.
18       One place where it is useful is with nbdkit-ssh-plugin(1) because the
19       sftp protocol does not support reading sparseness information, but you
20       may be able to get this information directly from the source disk on
21       the remote server using commands such as xfs_bmap(8).  A similar
22       situation applies to nbdkit-curl-plugin(1).
23
24       Note that the extent list is read-only.  This filter does not monitor
25       writes and trims in order to update the extent list.  What can happen
26       is that you would write to a “hole” in the disk, but would not be able
27       to read it back because the NBD client would still think that part of
28       the disk is a hole.  So it is generally only safe to use this filter in
29       read-only mode (-r option).
30

FILE FORMAT

32       The list of extents is specified in a text file.  There is one extent
33       specified per line.  Each line has the format:
34
35        offset length type
36
37       The "offset" and "length" fields may use any format understood by
38       "nbdkit_parse_size".  The optional "type" field may be an integer,
39       missing (same as 0), or a comma-separated list of the words "hole" and
40       "zero".  (The fields correspond to the inputs of the
41       "nbdkit_add_extent" function, see nbdkit-plugin(3)).
42
43       An example of a valid set of extents covering a "10M" disk where the
44       first megabyte only is allocated data:
45
46        0  1M
47        1M 9M  hole,zero
48
49       Or you could omit the "hole,zero" extent since any gaps are assumed to
50       be holes with that type:
51
52        0  1M
53
54       The extent list need not cover the whole disk, and does not need to be
55       in ascending order, but it must not contain overlapping extents.
56

PARAMETERS

58       extentlist=FILENAME
59           Specify the file containing the extent list, in the format
60           described in "FILE FORMAT" above.
61

FILES

63       $filterdir/nbdkit-extentlist-filter.so
64           The filter.
65
66           Use "nbdkit --dump-config" to find the location of $filterdir.
67

VERSION

69       "nbdkit-extentlist-filter" first appeared in nbdkit 1.18.
70

SEE ALSO

72       nbdkit(1), nbdkit-cacheextents-filter(1), nbdkit-noextents-filter(1),
73       nbdkit-filter(3), nbdkit-plugin(3).
74

AUTHORS

76       Richard W.M. Jones
77

79       Copyright Red Hat
80

LICENSE

82       Redistribution and use in source and binary forms, with or without
83       modification, are permitted provided that the following conditions are
84       met:
85
86       •   Redistributions of source code must retain the above copyright
87           notice, this list of conditions and the following disclaimer.
88
89       •   Redistributions in binary form must reproduce the above copyright
90           notice, this list of conditions and the following disclaimer in the
91           documentation and/or other materials provided with the
92           distribution.
93
94       •   Neither the name of Red Hat nor the names of its contributors may
95           be used to endorse or promote products derived from this software
96           without specific prior written permission.
97
98       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
99       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
100       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
101       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
102       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
103       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
104       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
105       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
106       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
107       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
108       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
109
110
111
112nbdkit-1.36.2                     2023-11-26       nbdkit-extentlist-filter(1)
Impressum