filters/extentlist/nbdkit-extentlist-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-extentlist-filter - place extent list over a plugin
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit -r --filter=extentlist plugin extentlist=FILENAME
   8
   9 =head1 DESCRIPTION
  10
  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.
  14
  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)>.
  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
  29 in read-only mode (I<-r> option).
  30
  31 =head1 FILE FORMAT
  32
  33 The list of extents is specified in a text file.  There is one extent
  34 specified per line.  Each line has the format:
  35
  36  offset length type
  37
  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)>).
  43
  44 An example of a valid set of extents covering a C<10M> disk where the
  45 first megabyte only is allocated data:
  46
  47  0  1M
  48  1M 9M  hole,zero
  49
  50 Or you could omit the C<hole,zero> extent since any gaps are assumed
  51 to be holes with that type:
  52
  53  0  1M
  54
  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.
  57
  58 =head1 PARAMETERS
  59
  60 =over 4
  61
  62 =item B<extentlist=>FILENAME
  63
  64 Specify the file containing the extent list, in the format described
  65 in L</FILE FORMAT> above.
  66
  67 =back
  68
  69 =head1 FILES
  70
  71 =over 4
  72
  73 =item F<$filterdir/nbdkit-extentlist-filter.so>
  74
  75 The filter.
  76
  77 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
  78
  79 =back
  80
  81 =head1 VERSION
  82
  83 C<nbdkit-extentlist-filter> first appeared in nbdkit 1.18.
  84
  85 =head1 SEE ALSO
  86
  87 L<nbdkit(1)>,
  88 L<nbdkit-cacheextents-filter(1)>,
  89 L<nbdkit-noextents-filter(1)>,
  90 L<nbdkit-filter(3)>,
  91 L<nbdkit-plugin(3)>.
  92
  93 =head1 AUTHORS
  94
  95 Richard W.M. Jones
  96
  97 =head1 COPYRIGHT
  98
  99 Copyright Red Hat