3 nbdkit-extentlist-filter - place extent list over a plugin
7 nbdkit -r --filter=extentlist plugin extentlist=FILENAME
11 C<nbdkit-extentlist-filter> is an nbdkit filter that lets you place a
12 static list of extents on top of an existing plugin. Extents record
13 whether or not specific parts of the disk are allocated or sparse.
15 You can use this with plugins which cannot get extent information
16 themselves, but where you can get this information from another
17 source. One place where it is useful is with L<nbdkit-ssh-plugin(1)>
18 because the sftp protocol does not support reading sparseness
19 information, but you may be able to get this information directly from
20 the source disk on the remote server using commands such as
21 L<xfs_bmap(8)>. A similar situation applies to
22 L<nbdkit-curl-plugin(1)>.
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
29 in read-only mode (I<-r> option).
33 The list of extents is specified in a text file. There is one extent
34 specified per line. Each line has the format:
38 The C<offset> and C<length> fields may use any format understood by
39 C<nbdkit_parse_size>. The optional C<type> field may be an integer,
40 missing (same as 0), or a comma-separated list of the words C<hole>
41 and C<zero>. (The fields correspond to the inputs of the
42 C<nbdkit_add_extent> function, see L<nbdkit-plugin(3)>).
44 An example of a valid set of extents covering a C<10M> disk where the
45 first megabyte only is allocated data:
50 Or you could omit the C<hole,zero> extent since any gaps are assumed
51 to be holes with that type:
55 The extent list need not cover the whole disk, and does not need to be
56 in ascending order, but it must I<not> contain overlapping extents.
62 =item B<extentlist=>FILENAME
64 Specify the file containing the extent list, in the format described
65 in L</FILE FORMAT> above.
73 =item F<$filterdir/nbdkit-extentlist-filter.so>
77 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
83 C<nbdkit-extentlist-filter> first appeared in nbdkit 1.18.
88 L<nbdkit-cacheextents-filter(1)>,
89 L<nbdkit-noextents-filter(1)>,