.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.20.1 (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 "libnbd-release-notes-1.18 1"
.TH libnbd-release-notes-1.18 1 2024-05-08 libnbd-1.20.1 LIBNBD
.\" 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
libnbd\-release\-notes\-1.18 \- release notes for libnbd 1.18
.SH DESCRIPTION
.IX Header "DESCRIPTION"
These are the release notes for libnbd stable release 1.18.
This describes the major changes since 1.16.
.PP
libnbd 1.18.0 was released on \fB27 September 2023\fR.
.SS Security
.IX Subsection "Security"
Eric Blake found a case where a server could cause libnbd to crash,
although not in the normal libnbd configuration.  For more information
see the announcement here:
https://listman.redhat.com/archives/libguestfs/2023\-July/032035.html
.PP
Eric Blake found an issue with \fBnbd_get_size\fR\|(3) where a server that
returns a size > (uint64_t)INT64_MAX and < (uint64_t)\-1
would cause nbd_get_size to return a negative number (which is not
\&\f(CW\-1\fR and so callers may or may not treat it as an error).  While no
client code in libnbd itself is affected by this, it could affect
external clients.  libnbd ≥ 1.16.5 now returns an error (\f(CW\-1\fR)
and sets nbd_get_errno to \f(CW\*(C`EOVERFLOW\*(C'\fR in this case.  This was
assigned CVE\-2023\-5215 (low severity).  See the announcement here:
https://listman.redhat.com/archives/libguestfs/2023\-September/032711.html
.PP
During routine fuzzing we found several security problems which had
been introduced during this development cycle and have subsequently
been fixed.  Stable (even numbered) releases of libnbd should not be
vulnerable; do not use the development (odd numbered) releases in
production.
.PP
If you find a security issue, please read \fISECURITY\fR in the source
(online here:
https://gitlab.com/nbdkit/libnbd/blob/master/SECURITY).  To
find out about previous security issues in libnbd, see
\&\fBlibnbd\-security\fR\|(3).
.SS "New APIs"
.IX Subsection "New APIs"
.IP \fBnbd_block_status_64\fR\|(3) 4
.IX Item "nbd_block_status_64"
.PD 0
.IP \fBnbd_aio_block_status_64\fR\|(3) 4
.IX Item "nbd_aio_block_status_64"
.PD
Make a 64 bit block status request, see "Protocol" below (Eric Blake).
.IP \fBnbd_block_status_filter\fR\|(3) 4
.IX Item "nbd_block_status_filter"
.PD 0
.IP \fBnbd_aio_block_status_filter\fR\|(3) 4
.IX Item "nbd_aio_block_status_filter"
.PD
Send filtered block status command, see "Protocol" below (Eric
Blake).
.IP \fBnbd_can_block_status_payload\fR\|(3) 4
.IX Item "nbd_can_block_status_payload"
Find out if the server supports filtered block status command
(Eric Blake).
.IP \fBnbd_set_request_extended_headers\fR\|(3) 4
.IX Item "nbd_set_request_extended_headers"
.PD 0
.IP \fBnbd_get_request_extended_headers\fR\|(3) 4
.IX Item "nbd_get_request_extended_headers"
.IP \fBnbd_get_extended_headers_negotiated\fR\|(3) 4
.IX Item "nbd_get_extended_headers_negotiated"
.IP \fBnbd_opt_extended_headers\fR\|(3) 4
.IX Item "nbd_opt_extended_headers"
.IP \fBnbd_aio_opt_extended_headers\fR\|(3) 4
.IX Item "nbd_aio_opt_extended_headers"
.PD
Set/get whether we request extended headers from the server, and find
out if we negotiated extended headers, see "Protocol" below (Eric
Blake).
.SS "Enhancements to existing APIs"
.IX Subsection "Enhancements to existing APIs"
\&\f(CW"qemu:"\fR meta-context constants (eg. \f(CW"qemu:dirty\-bitmap"\fR as
\&\f(CW\*(C`LIBNBD_CONTEXT_QEMU_DIRTY_BITMAP\*(C'\fR) are now available through the C,
Golang, OCaml and Python language bindings (Eric Blake).
.PP
\&\fBnbd_shutdown\fR\|(3) now works correctly when in opt mode (Eric Blake).
.PP
\&\fBnbd_set_strict_mode\fR\|(3) adds \f(CW\*(C`LIBNBD_STRICT_AUTO_FLAG\*(C'\fR which allows
the client to test how servers behave when the payload length flag is
adjusted (Eric Blake).
.SS Protocol
.IX Subsection "Protocol"
libnbd now supports NBD 64 bit "extended headers" and extent sizes.
In practice this allows certain requests such as zeroing very large
sections of the disk to be implemented much more efficiently, with
servers that support this (Eric Blake).
.PP
libnbd now supports filtered block status requests (Eric Blake).
.SS Tools
.IX Subsection "Tools"
\&\fBnbdcopy\fR\|(1), \fBnbdinfo\fR\|(1) and \fBnbddump\fR\|(1) have been expanded to
use and report NBD 64 bit / extended header support when the server
supports it (Eric Blake).
.PP
nbdinfo \fI\-\-has\fR can be used as an alias for \fI\-\-can\fR, eg.
\&\f(CW\*(C`nbdinfo\ \-\-has\ structured\-reply\ URI\*(C'\fR (Eric Blake).
.PP
nbdinfo makes the export size output optional, for servers which send
an oversized one (Eric Blake).
.PP
nbdcopy now supports "human sizes" for some parameters, eg.
\&\f(CW\*(C`nbdcopy\ \-\-request\-size=1M\ ...\*(C'\fR.
.SS "Language bindings"
.IX Subsection "Language bindings"
New Rust bindings.  There is a basic API for ordinary use, and an
asynch API implemented using Tokio.  Rust\ ≥\ 1.69 is required.
(Tage Johansson, supported by sponsorship from Google Summer of Code
2023, additional review and fixes by Eric Blake).
.PP
OCaml 5 is now supported.
.PP
Golang 1.21 is now supported.  The minimum version is now 1.17 (Eric
Blake).
.PP
Use \f(CW\*(C`gofmt\*(C'\fR to format Golang bindings (Eric Blake).
.PP
Use \f(CW\*(C`unsafe.Slice\*(C'\fR when converting C arrays to Golang slices (Eric Blake).
.PP
All language bindings support NBD 64 bit / extended headers, and
examples of how to use this feature are available (Eric Blake).
.SS Tests
.IX Subsection "Tests"
Fix a couple of race conditions in tests where we did not fully
consume stdin in \fBnbdkit\-sh\-plugin\fR\|(3) pwrite method (Eric Blake).
.PP
Fuzzing now disables client-side strictness checks, enabling a wider
range of inputs to be fuzzed (Eric Blake).
.SS "Other improvements and bug fixes"
.IX Subsection "Other improvements and bug fixes"
Consistently wrap source code at 80 columns (Laszlo Ersek).
.PP
Debug messages no longer print the very verbose state transitions
inside the state machine as these are not usually useful.  You can
reenable this by defining \f(CW\*(C`\-DLIBNBD_STATE_VERBOSE=1\*(C'\fR at compile time.
.PP
Completion \f(CW\*(C`.callback\*(C'\fR methods are now always called exactly once,
and documentation is clearer on when this happens (Eric Blake).
.SS Documentation
.IX Subsection "Documentation"
\&\f(CW\*(C`podwrapper\*(C'\fR has a new \fI\-\-replace\fR parameter which makes it easier
to use \f(CW\*(C`AC_SUBST\*(C'\fR\-substitutions in documentation.
.SS Build
.IX Subsection "Build"
Automake's \f(CW\*(C`subdir\-objects\*(C'\fR option is now used (Eric Blake).
.PP
Multiple, ongoing fixes to the CI tests (Eric Blake).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlibnbd\fR\|(3).
.SH AUTHORS
.IX Header "AUTHORS"
.IP "Eric Blake" 4
.IX Item "Eric Blake"
.PD 0
.IP "Laszlo Ersek" 4
.IX Item "Laszlo Ersek"
.IP "Richard W.M. Jones" 4
.IX Item "Richard W.M. Jones"
.IP "Tage Johansson" 4
.IX Item "Tage Johansson"
.PD
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
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.
.PP
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.
.PP
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