nbdkit-extentlist-filter1

Usage

Overview

"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(3). 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.