[Libguestfs] [PATCH nbdinfo v2] info: Add a --map option for displaying allocation metadata.

[Eric Blake]

On 9/26/20 11:36 AM, Richard W.M. Jones wrote:
> ---
>  info/Makefile.am                      |   4 +
>  info/info-map-base-allocation-json.sh |  52 ++++++++++
>  info/info-map-base-allocation.sh      |  49 ++++++++++
>  info/nbdinfo.c                        | 134 ++++++++++++++++++++++++--
>  info/nbdinfo.pod                      |  39 +++++++-
>  5 files changed, 271 insertions(+), 7 deletions(-)

An interesting followup might be adding options for --start and --length
to map out only a subset of the file.  That was recently added to
qemu-img map, because there are cases where a file is fragmented enough
that getting the entire map can be time-consuming, in relation to
mapping out just a subset of the image.

> +++ b/info/info-map-base-allocation-json.sh
> @@ -0,0 +1,52 @@
> +#!/usr/bin/env bash
> +# nbd client library in userspace
> +# Copyright (C) 2020 Red Hat Inc.
> +#
> +# This library is free software; you can redistribute it and/or
> +# modify it under the terms of the GNU Lesser General Public
> +# License as published by the Free Software Foundation; either
> +# version 2 of the License, or (at your option) any later version.
> +#
> +# This library is distributed in the hope that it will be useful,
> +# but WITHOUT ANY WARRANTY; without even the implied warranty of
> +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +# Lesser General Public License for more details.
> +#
> +# You should have received a copy of the GNU Lesser General Public
> +# License along with this library; if not, write to the Free Software
> +# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
> +
> +. ../tests/functions.sh
> +
> +set -e
> +set -x
> +
> +requires nbdkit --version
> +requires nbdsh --version

Why are we requiring nbdsh in the libnbd testsuite? :)  Is there a
configure option where you can have nbdinfo but not nbdsh?

On the other hand, we _do_ require URI support (libxml2); maybe it's
worth porting 'requires_nbdsh_uri' from nbdkit back to libnbd's
functions.sh, and using that...

> +requires jq --version
> +
> +out=info-base-allocation-json.out
> +cleanup_fn rm -f $out
> +rm -f $out
> +
> +# Note the memory plugin uses a 32K page size, and extents
> +# are always aligned with this.
> +nbdkit -U - memory 1M --run '
> +    nbdsh -u "$uri" \

...since you are depending on it.


> +/* Callback handling --map. */
> +static const char *
> +extent_description (const char *metacontext, uint32_t type)
> +{
> +  if (strcmp (metacontext, "base:allocation") == 0) {

Should we favor the use of LIBNBD_CONTEXT_BASE_ALLOCATION instead of
open-coding this?

> +    switch (type) {
> +    case 0: return "allocated";
> +    case 1: return "zero";
> +    case 2: return "hole";
> +    case 3: return "hole,zero";
> +    }
> +  }
> +  else if (strcmp (metacontext, "qemu:dirty-bitmap") == 0) {

I see you've figured out since that this is not the context name
actually returned by qemu.

> +    switch (type) {
> +    case 0: return "clean";
> +    case 1: return "dirty";
> +    }
> +  }
> +
> +  return "unknown";
> +}
> +

> +++ b/info/nbdinfo.pod
> @@ -4,7 +4,7 @@ nbdinfo - display information and metadata about NBD servers and exports
>  
>  =head1 SYNOPSIS
>  
> - nbdinfo [--json] [--size] NBD-URI
> + nbdinfo [--json] [--map] [--size] NBD-URI
>  
>   nbdinfo -L|--list NBD-URI
>  
> @@ -20,6 +20,8 @@ nbdinfo - display information and metadata about NBD servers and exports
>  
>   nbdinfo --size nbd://example.com
>  
> + nbdinfo --map nbd://example.com
> +
>   nbdinfo --json nbd://example.com
>  
>   nbdinfo --list nbd://example.com
> @@ -84,6 +86,32 @@ the I<--json> parameter:
>     ]
>   }
>  
> +=head3 Map
> +
> +To show a map which areas of the disk are allocated and sparse, use
> +the I<--map> option:
> +
> + $ nbdinfo --map nbd://localhost/
> + 0        1048576  0  allocated
> + 1048576  1048576  3  hole,zero
> +
> +The fields are: start size type description.
> +
> +The type field is an integer showing the raw value from the NBD
> +protocol.  For some maps nbdinfo knows how to translate the type into
> +a printable description.
> +
> +By default this shows the C<"base:allocation"> map, but you can show
> +other maps too:
> +
> + $ nbdinfo --map=qemu:dirty-bitmap nbd://localhost/
> + 0  1048576  1  dirty
> +
> +For more information on NBD maps, see I<Metadata querying> in the NBD
> +protocol.  I<--json> can also be used here for parsable JSON output.
> +
> +=head3 List of exports
> +
>  To list all the exports available on an NBD server use the I<--list>
>  (I<-L>) option.

Looks like I have more to add here once nbd_opt_info_meta_context lands
for displaying available contexts during --list, and auto-selecting
contexts with --map.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20201001/0fb8e7b5/attachment.sig>