NAME

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

SYNOPSIS

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

DESCRIPTION

       "nbdkit-extentlist-filter" is an nbdkit filter that lets you place a static list of
       extents on top of an existing plugin.  Extents record whether or not specific parts of the
       disk are allocated or sparse.

       You can use this with plugins which cannot get extent information themselves, but where
       you can get this information from another source.  One place where it is useful is with
       nbdkit-ssh-plugin(1) because the sftp protocol does not support reading sparseness
       information, but you may be able to get this information directly from the source disk on
       the remote server using commands such as xfs_bmap(8).  A similar situation applies to
       nbdkit-curl-plugin(1).

       Note that the extent list is read-only.  This filter does not monitor writes and trims in
       order to update the extent list.  What can happen is that you would write to a “hole” in
       the disk, but would not be able to read it back because the NBD client would still think
       that part of the disk is a hole.  So it is generally only safe to use this filter in read-
       only mode (-r option).

FILE FORMAT

       The list of extents is specified in a text file.  There is one extent specified per line.
       Each line has the format:

        offset length type

       The "offset" and "length" fields may use any format understood by "nbdkit_parse_size".
       The optional "type" field may be an integer, missing (same as 0), or a comma-separated
       list of the words "hole" and "zero".  (The fields correspond to the inputs of the
       "nbdkit_add_extent" function, see nbdkit-plugin(3)).

       An example of a valid set of extents covering a "10M" disk where the first megabyte only
       is allocated data:

        0  1M
        1M 9M  hole,zero

       Or you could omit the "hole,zero" extent since any gaps are assumed to be holes with that
       type:

        0  1M

       The extent list need not cover the whole disk, and does not need to be in ascending order,
       but it must not contain overlapping extents.

PARAMETERS

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

FILES

       $filterdir/nbdkit-extentlist-filter.so
           The filter.

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

VERSION

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

SEE ALSO

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

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright (C) 2020 Red Hat Inc.

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.