From 2a3e909e9e1ccb608bde75b76524acd753b33889 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sat, 25 Jan 2020 11:38:14 +0000
Subject: [PATCH 12/19] extentlist: Documentation and test fixes.

Updates commit 3e770b6d6620a62546849a2863638041c0b00640.

(cherry picked from commit c16709ef663a5ed9fd9ddef4e379f316d84c9a07)
---
 TODO                                          | 12 +++++++----
 .../extentlist/nbdkit-extentlist-filter.pod   | 21 +++++++++++++------
 plugins/curl/nbdkit-curl-plugin.pod           |  1 +
 plugins/ssh/nbdkit-ssh-plugin.pod             |  1 +
 tests/test-extentlist.sh                      |  2 +-
 5 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/TODO b/TODO
index 2a3e89dc..e1ac71cd 100644
--- a/TODO
+++ b/TODO
@@ -187,10 +187,6 @@ Suggestions for filters
   MBs of extra data)
   https://github.com/facebook/zstd/issues/395#issuecomment-535875379
 
-* nbdkit-extentlist-filter could read the extents generated by
-  qemu-img map, allowing extents to be ported from a qemu block
-  device.
-
 nbdkit-rate-filter:
 
 * allow other kinds of traffic shaping such as VBR
@@ -216,6 +212,14 @@ nbdkit-retry-filter:
 
 * subsecond times
 
+nbdkit-extentlist-filter:
+
+* read the extents generated by qemu-img map, allowing extents to be
+  ported from a qemu block device
+
+* make non-read-only access safe by updating the extent list when the
+  filter sees writes and trims
+
 Filters for security
 --------------------
 
diff --git a/filters/extentlist/nbdkit-extentlist-filter.pod b/filters/extentlist/nbdkit-extentlist-filter.pod
index adfb4ad8..5d1a38ae 100644
--- a/filters/extentlist/nbdkit-extentlist-filter.pod
+++ b/filters/extentlist/nbdkit-extentlist-filter.pod
@@ -4,7 +4,7 @@ nbdkit-extentlist-filter - place extent list over a plugin
 
 =head1 SYNOPSIS
 
- nbdkit --filter=extentlist plugin extentlist=FILENAME
+ nbdkit -r --filter=extentlist plugin extentlist=FILENAME
 
 =head1 DESCRIPTION
 
@@ -13,11 +13,20 @@ 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 you can get this information from another source.  One
-place where it is useful is with L<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.
+themselves, but where you can get this information from another
+source.  One place where it is useful is with L<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
+L<xfs_bmap(8)>.  A similar situation applies to
+L<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 (I<-r> option).
 
 =head1 FILE FORMAT
 
diff --git a/plugins/curl/nbdkit-curl-plugin.pod b/plugins/curl/nbdkit-curl-plugin.pod
index 827e0bd1..d3c85248 100644
--- a/plugins/curl/nbdkit-curl-plugin.pod
+++ b/plugins/curl/nbdkit-curl-plugin.pod
@@ -182,6 +182,7 @@ L<libcurl(3)>,
 L<CURLOPT_COOKIE(3)>
 L<CURLOPT_VERBOSE(3)>,
 L<nbdkit(1)>,
+L<nbdkit-extentlist-filter(1)>,
 L<nbdkit-readahead-filter(1)>,
 L<nbdkit-retry-filter(1)>,
 L<nbdkit-ssh-plugin(1)>,
diff --git a/plugins/ssh/nbdkit-ssh-plugin.pod b/plugins/ssh/nbdkit-ssh-plugin.pod
index 0a0421d5..3fc3146a 100644
--- a/plugins/ssh/nbdkit-ssh-plugin.pod
+++ b/plugins/ssh/nbdkit-ssh-plugin.pod
@@ -316,6 +316,7 @@ C<nbdkit-ssh-plugin> first appeared in nbdkit 1.12.
 
 L<nbdkit(1)>,
 L<nbdkit-curl-plugin(1)>,
+L<nbdkit-extentlist-filter(1)>,
 L<nbdkit-readahead-filter(1)>,
 L<nbdkit-retry-filter(1)>,
 L<nbdkit-plugin(3)>,
diff --git a/tests/test-extentlist.sh b/tests/test-extentlist.sh
index 7d05de4f..73ce3ca6 100755
--- a/tests/test-extentlist.sh
+++ b/tests/test-extentlist.sh
@@ -50,7 +50,7 @@ cleanup_fn rm $files
 test ()
 {
     nbdkit -v -D extentlist.lookup=1 \
-           -U - \
+           -r -U - \
            --filter=extentlist \
            null size=$1 extentlist=$input \
            --run 'qemu-img map -f raw --output=json $nbd' |
-- 
2.18.2