Richard W.M. Jones
2023-Sep-09 13:57 UTC
[Libguestfs] [PATCH nbdkit 10/10] XXX docs: Remove references to -U - when it is implicit
XXX NOTE XXX
I would not apply this patch immediately, since online documentation
will get updated as soon as I do that. Best to wait until after 1.36
is released at least.
XXX END NOTE XXX
---
docs/nbdkit-captive.pod | 6 +++---
filters/cacheextents/nbdkit-cacheextents-filter.pod | 2 +-
filters/checkwrite/nbdkit-checkwrite-filter.pod | 6 +++---
filters/pause/nbdkit-pause-filter.pod | 2 +-
filters/retry/nbdkit-retry-filter.pod | 2 +-
plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod | 4 ++--
plugins/nbd/nbdkit-nbd-plugin.pod | 2 +-
plugins/random/nbdkit-random-plugin.pod | 2 +-
plugins/sparse-random/nbdkit-sparse-random-plugin.pod | 2 +-
plugins/torrent/nbdkit-torrent-plugin.pod | 6 +++---
plugins/vddk/nbdkit-vddk-plugin.pod | 4 ++--
BENCHMARKING | 4 ++--
12 files changed, 21 insertions(+), 21 deletions(-)
diff --git a/docs/nbdkit-captive.pod b/docs/nbdkit-captive.pod
index 248f9df28..4f9740bc9 100644
--- a/docs/nbdkit-captive.pod
+++ b/docs/nbdkit-captive.pod
@@ -46,7 +46,7 @@ When guestfish exits, nbdkit is killed.
Running nbdkit captive under nbdsh for unit testing:
- nbdkit -U - memory 1 --run 'nbdsh -u "$uri" -c
"print(h.pread(1, 0))"'
+ nbdkit memory 1 --run 'nbdsh -u "$uri" -c "print(h.pread(1,
0))"'
The following shell variables are available in the I<--run> argument:
@@ -104,7 +104,7 @@ Captive nbdkit + L<qemu-img(1)> can be used to copy
data into and out
of nbdkit plugins. For example L<nbdkit-example1-plugin(1)> contains
an embedded disk image. To copy it out:
- nbdkit -U - example1 --run 'qemu-img convert $nbd disk.img'
+ nbdkit example1 --run 'qemu-img convert $nbd disk.img'
If the source suffers from temporary network failures
L<nbdkit-retry-filter(1)> or L<nbdkit-retry-request-filter(1)> may
@@ -114,7 +114,7 @@ To overwrite a file inside an uncompressed tar file (the
file being
overwritten must be the same size), use L<nbdkit-tar-filter(1)> like
this:
- nbdkit -U - file data.tar --filter=tar tar-entry=disk.img \
+ nbdkit file data.tar --filter=tar tar-entry=disk.img \
--run 'qemu-img convert -n disk.img $nbd'
=head1 EXIT WITH PARENT
diff --git a/filters/cacheextents/nbdkit-cacheextents-filter.pod
b/filters/cacheextents/nbdkit-cacheextents-filter.pod
index 77dc680c8..a2b2aa519 100644
--- a/filters/cacheextents/nbdkit-cacheextents-filter.pod
+++ b/filters/cacheextents/nbdkit-cacheextents-filter.pod
@@ -17,7 +17,7 @@ only one extent at a time (such as S<C<qemu-img
convert>>), but where
the plugin can provide multiple extents for the same high latency as a
single extent (such as L<nbdkit-vddk-plugin(1)>). For example:
- nbdkit -U - --filter=cacheextents --run 'qemu-img map $nbd' vddk ...
+ nbdkit --filter=cacheextents --run 'qemu-img map $nbd' vddk ...
For files with big extents (when it is unlikely for one extents() call
to return multiple different extents) this does not slow down the
diff --git a/filters/checkwrite/nbdkit-checkwrite-filter.pod
b/filters/checkwrite/nbdkit-checkwrite-filter.pod
index 67a466f87..6855d7988 100644
--- a/filters/checkwrite/nbdkit-checkwrite-filter.pod
+++ b/filters/checkwrite/nbdkit-checkwrite-filter.pod
@@ -28,17 +28,17 @@ You can check that a copying tool is copying data correctly
by
creating an nbdkit instance containing some test data, overlaying this
filter, and copying from and to nbdkit at the same time:
- nbdkit -U - --filter=checkwrite data "@32768 1" \
+ nbdkit --filter=checkwrite data "@32768 1" \
--run 'nbdcopy "$uri" "$uri"'
=for paragraph
- nbdkit -U - --filter=checkwrite file disk.img \
+ nbdkit --filter=checkwrite file disk.img \
--run 'nbdcopy "$uri" "$uri"'
=for paragraph
- nbdkit -U - --filter=checkwrite linuxdisk testdir/ \
+ nbdkit --filter=checkwrite linuxdisk testdir/ \
--run 'qemu-img convert -n "$uri" "$uri"'
If the copying program is buggy then you will see EIO errors and (if
diff --git a/filters/pause/nbdkit-pause-filter.pod
b/filters/pause/nbdkit-pause-filter.pod
index 1bc083ddc..708e0b3ea 100644
--- a/filters/pause/nbdkit-pause-filter.pod
+++ b/filters/pause/nbdkit-pause-filter.pod
@@ -39,7 +39,7 @@ Any unknown commands are ignored. The filter responds with
C<'X'>.
Pick a large file, disk image or ISO, serve it over NBD, and start
copying it:
- nbdkit -U - --filter=pause --filter=rate \
+ nbdkit --filter=pause --filter=rate \
file BIG_FILE.ISO rate=10M pause-control=sock \
--run 'qemu-img convert -p $nbd /var/tmp/out'
diff --git a/filters/retry/nbdkit-retry-filter.pod
b/filters/retry/nbdkit-retry-filter.pod
index 6eba3d4ff..6179a507d 100644
--- a/filters/retry/nbdkit-retry-filter.pod
+++ b/filters/retry/nbdkit-retry-filter.pod
@@ -50,7 +50,7 @@ waiting in total about 1 minute before we give up.
In this example we copy and convert a large file using
L<nbdkit-ssh-plugin(1)>, L<qemu-img(1)> and
L<nbdkit-captive(1)>.
- nbdkit -U - \
+ nbdkit \
ssh host=remote.example.com /var/tmp/test.iso \
--filter=retry \
--run 'qemu-img convert -p -f raw $nbd -O qcow2 test.qcow2'
diff --git a/plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod
b/plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod
index 179923518..9f78367ad 100644
--- a/plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod
+++ b/plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod
@@ -57,7 +57,7 @@ Instead of serving a partitioned disk image, serve just the
"naked"
filesystem (ie. the first partition, see
L<nbdkit-partition-filter(1)>).
-=item nbdkit -U - linuxdisk /path/to/directory
+=item nbdkit linuxdisk /path/to/directory
--run 'nbdcopy "$uri" ext2fs.img'
This serves nothing. Instead it turns a directory into a disk image,
@@ -77,7 +77,7 @@ have that.
ln root/sbin/busybox root/sbin/init
ln root/sbin/busybox root/bin/ls
ln root/sbin/busybox root/bin/sh
- nbdkit -U - linuxdisk root --run '
+ nbdkit linuxdisk root --run '
qemu-kvm -display none -kernel /boot/vmlinuz -drive
file=nbd:unix:$unixsocket,snapshot=on -append "console=ttyS0 root=/dev/sda1
rw" -serial stdio
'
diff --git a/plugins/nbd/nbdkit-nbd-plugin.pod
b/plugins/nbd/nbdkit-nbd-plugin.pod
index fc89b9c56..96d2f289d 100644
--- a/plugins/nbd/nbdkit-nbd-plugin.pod
+++ b/plugins/nbd/nbdkit-nbd-plugin.pod
@@ -298,7 +298,7 @@ style. Use I<--run> to clean up nbdkit at the time
the client exits.
In general, note that it is best to keep the plaintext connection
limited to a Unix socket on the local machine.
- nbdkit -U - -o --tls=off nbd hostname=example.com export=foo tls=require \
+ nbdkit -o --tls=off nbd hostname=example.com export=foo tls=require \
--run '/path/to/oldclient --socket=$unixsocket'
=for paragraph
diff --git a/plugins/random/nbdkit-random-plugin.pod
b/plugins/random/nbdkit-random-plugin.pod
index 0d6da8d5f..cd0a37df7 100644
--- a/plugins/random/nbdkit-random-plugin.pod
+++ b/plugins/random/nbdkit-random-plugin.pod
@@ -27,7 +27,7 @@ same offset (if not, it returns EIO error). You can use this
to test
copying programs by making the source and destination NBD URIs be the
same:
- nbdkit -U - random size=100M --run 'nbdcopy "$uri"
"$uri"'
+ nbdkit random size=100M --run 'nbdcopy "$uri"
"$uri"'
C<qemu-img convert> could be used in place of nbdcopy.
See also L<nbdkit-checkwrite-filter(1)>.
diff --git a/plugins/sparse-random/nbdkit-sparse-random-plugin.pod
b/plugins/sparse-random/nbdkit-sparse-random-plugin.pod
index 5636e76c4..8a6fbf42a 100644
--- a/plugins/sparse-random/nbdkit-sparse-random-plugin.pod
+++ b/plugins/sparse-random/nbdkit-sparse-random-plugin.pod
@@ -42,7 +42,7 @@ Writes to the disk verify that the data written is the same as
the
data read (if not, returning EIO). Thus when testing copies you can
use a single instance of this plugin for both read and write:
- nbdkit -U - sparse-random size=1T --run 'nbdcopy "$uri"
"$uri"'
+ nbdkit sparse-random size=1T --run 'nbdcopy "$uri"
"$uri"'
C<qemu-img convert> could be used in place of nbdcopy.
See also L<nbdkit-checkwrite-filter(1)>.
diff --git a/plugins/torrent/nbdkit-torrent-plugin.pod
b/plugins/torrent/nbdkit-torrent-plugin.pod
index b29990f51..744db124d 100644
--- a/plugins/torrent/nbdkit-torrent-plugin.pod
+++ b/plugins/torrent/nbdkit-torrent-plugin.pod
@@ -47,7 +47,7 @@ Choose the right URL from
L<https://torrent.fedoraproject.org/>:
url=https://torrent.fedoraproject.org/torrents/Fedora-Server-dvd-x86_64-32.torrent
wget $url
- nbdkit -U - torrent Fedora-Server-*.torrent \
+ nbdkit torrent Fedora-Server-*.torrent \
--run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
=head2 Boot the Debian installer
@@ -56,7 +56,7 @@ Choose the right URL from
L<https://www.debian.org/CD/torrent-cd/>:
url=https://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-10.4.0-amd64-DVD-1.iso.torrent
wget $url
- nbdkit -U - torrent debian-*.torrent \
+ nbdkit torrent debian-*.torrent \
--run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
=head1 PARAMETERS
@@ -99,7 +99,7 @@ torrent, so if the torrent contains subdirectories you may
need to use
a path like C<file=SUBDIR/DISK>. To list all the files within the
torrent try running:
- $ nbdkit -fv -U - torrent file.torrent
+ $ nbdkit -fv torrent file.torrent
and examining the debug output. As an alternative you can use
standard BitTorrent tools, eg:
diff --git a/plugins/vddk/nbdkit-vddk-plugin.pod
b/plugins/vddk/nbdkit-vddk-plugin.pod
index 704ff63c7..49010db2d 100644
--- a/plugins/vddk/nbdkit-vddk-plugin.pod
+++ b/plugins/vddk/nbdkit-vddk-plugin.pod
@@ -53,7 +53,7 @@ of a disk image. Note the C<create-size> parameter is
the virtual
size of the final VMDK disk image and must be at least as large as the
input disk:
- nbdkit -U - vddk \
+ nbdkit vddk \
/absolute/path/to/output.vmdk \
create=true create-size=100M \
--run 'qemu-img convert input.qcow2 $uri'
@@ -456,7 +456,7 @@ using this command:
Another way to get the thumbprint of a server is to connect to the
server using a bogus thumbprint with debugging enabled:
- nbdkit -U - -fv vddk server=esxi.example.com [...] thumbprint=12 \
+ nbdkit -fv vddk server=esxi.example.com [...] thumbprint=12 \
--run 'qemu-img info "$uri"'
The nbdkit process will try to connect (and fail because the
diff --git a/BENCHMARKING b/BENCHMARKING
index 462266642..195cd732b 100644
--- a/BENCHMARKING
+++ b/BENCHMARKING
@@ -128,9 +128,9 @@ the qemu client support sparseness detection and efficient
zeroing.
To test copying speed you can use ?qemu-img convert?, to or from
nbdkit:
- nbdkit -U - memory 1G --run 'qemu-img convert file.qcow2 -O raw $nbd'
+ nbdkit memory 1G --run 'qemu-img convert file.qcow2 -O raw $nbd'
- nbdkit -U - memory 1G --run 'qemu-img convert $nbd -O qcow2
file.qcow2'
+ nbdkit memory 1G --run 'qemu-img convert $nbd -O qcow2 file.qcow2'
Notes:
--
2.41.0
Eric Blake
2023-Sep-11 14:34 UTC
[Libguestfs] [PATCH nbdkit 10/10] XXX docs: Remove references to -U - when it is implicit
On Sat, Sep 09, 2023 at 02:57:58PM +0100, Richard W.M. Jones wrote:> XXX NOTE XXX > > I would not apply this patch immediately, since online documentation > will get updated as soon as I do that. Best to wait until after 1.36 > is released at least.At the earliest, on the day that we are ready to cut 1.36 (I don't see a problem with the docs being updated once the tarball will be ready, rather than having to wait yet longer to 1.36.1). But I agree that we aren't quite ready for the stable release yet.> > XXX END NOTE XXX > --- > docs/nbdkit-captive.pod | 6 +++--- > filters/cacheextents/nbdkit-cacheextents-filter.pod | 2 +- > filters/checkwrite/nbdkit-checkwrite-filter.pod | 6 +++--- > filters/pause/nbdkit-pause-filter.pod | 2 +- > filters/retry/nbdkit-retry-filter.pod | 2 +- > plugins/linuxdisk/nbdkit-linuxdisk-plugin.pod | 4 ++-- > plugins/nbd/nbdkit-nbd-plugin.pod | 2 +- > plugins/random/nbdkit-random-plugin.pod | 2 +- > plugins/sparse-random/nbdkit-sparse-random-plugin.pod | 2 +- > plugins/torrent/nbdkit-torrent-plugin.pod | 6 +++--- > plugins/vddk/nbdkit-vddk-plugin.pod | 4 ++-- > BENCHMARKING | 4 ++--Unless I'm mistaken, BENCHMARKING is the only file in this list that is not live on the website, and therefore which could be hoisted into 9/10 if desired. But I see no harm in leaving it here. Obviously, we'd better not forget to apply this at the correct later date, and you'll have to touch up the commit message at that point. But once we are ready, feel free to add Reviewed-by: Eric Blake <eblake at redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org