.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.36.3 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-extentlist-filter 1"
.TH nbdkit-extentlist-filter 1 2024-01-17 nbdkit-1.36.3 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-extentlist\-filter \- place extent list over a plugin
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit \-r \-\-filter=extentlist plugin extentlist=FILENAME
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-extentlist\-filter\*(C'\fR 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.
.PP
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 \fBnbdkit\-ssh\-plugin\fR\|(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
\&\fBxfs_bmap\fR\|(8).  A similar situation applies to
\&\fBnbdkit\-curl\-plugin\fR\|(1).
.PP
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 (\fI\-r\fR option).
.SH "FILE FORMAT"
.IX Header "FILE FORMAT"
The list of extents is specified in a text file.  There is one extent
specified per line.  Each line has the format:
.PP
.Vb 1
\& offset length type
.Ve
.PP
The \f(CW\*(C`offset\*(C'\fR and \f(CW\*(C`length\*(C'\fR fields may use any format understood by
\&\f(CW\*(C`nbdkit_parse_size\*(C'\fR.  The optional \f(CW\*(C`type\*(C'\fR field may be an integer,
missing (same as 0), or a comma-separated list of the words \f(CW\*(C`hole\*(C'\fR
and \f(CW\*(C`zero\*(C'\fR.  (The fields correspond to the inputs of the
\&\f(CW\*(C`nbdkit_add_extent\*(C'\fR function, see \fBnbdkit\-plugin\fR\|(3)).
.PP
An example of a valid set of extents covering a \f(CW\*(C`10M\*(C'\fR disk where the
first megabyte only is allocated data:
.PP
.Vb 2
\& 0  1M
\& 1M 9M  hole,zero
.Ve
.PP
Or you could omit the \f(CW\*(C`hole,zero\*(C'\fR extent since any gaps are assumed
to be holes with that type:
.PP
.Vb 1
\& 0  1M
.Ve
.PP
The extent list need not cover the whole disk, and does not need to be
in ascending order, but it must \fInot\fR contain overlapping extents.
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP \fBextentlist=\fRFILENAME 4
.IX Item "extentlist=FILENAME"
Specify the file containing the extent list, in the format described
in "FILE FORMAT" above.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$filterdir\fR\fI/nbdkit\-extentlist\-filter.so\fR 4
.el .IP \fR\f(CI$filterdir\fR\fI/nbdkit\-extentlist\-filter.so\fR 4
.IX Item "$filterdir/nbdkit-extentlist-filter.so"
The filter.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$filterdir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-extentlist\-filter\*(C'\fR first appeared in nbdkit 1.18.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-cacheextents\-filter\fR\|(1),
\&\fBnbdkit\-noextents\-filter\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3),
\&\fBnbdkit\-plugin\fR\|(3).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.