.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "nbdkit-protocol 1"
.TH nbdkit-protocol 1 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" 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"
nbdkit \- which parts of the NBD protocol nbdkit supports
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit [\-n|\-\-newstyle] [\-o|\-\-oldstyle] [\-e|\-\-exportname EXPORTNAME]
\&        [...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This page documents the level of support in nbdkit for various parts
of the \s-1NBD\s0 protocol.
.SH "NEW STYLE VS OLD STYLE PROTOCOL"
.IX Header "NEW STYLE VS OLD STYLE PROTOCOL"
The \s-1NBD\s0 protocol comes in two incompatible forms that we call
\&\*(L"oldstyle\*(R" and \*(L"newstyle\*(R".  Unfortunately which protocol you should
use depends on the client and cannot be known in advance, nor can it
be negotiated from the server side.
.PP
nbdkit defaults to the newstyle protocol since nbdkit ≥ 1.3.  The
newstyle protocol is better in every respect than the oldstyle
protocol and you should prefer it if possible.
.PP
Use the \fI\-e\fR or \fI\-\-exportname\fR flag to set the optional exportname
for the newstyle protocol.
.PP
Use the \fI\-o\fR or \fI\-\-oldstyle\fR flag to force the oldstyle protocol.
.SS "Common clients and the protocol they require"
.IX Subsection "Common clients and the protocol they require"
.Vb 9
\& Client                          Protocol
\& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\& qemu <= 2.5 without exportname  oldstyle
\& qemu <= 2.5 with exportname     newstyle
\& qemu >= 2.6                     client can talk either protocol
\& nbd\-client < 3.10               client can talk either protocol
\& nbd\-client >= 3.10              newstyle
\& any TLS (encrypted) client      newstyle
\& nbdkit nbd plugin               client can talk either protocol
.Ve
.SS "Errors seen if using the wrong protocol"
.IX Subsection "Errors seen if using the wrong protocol"
If you use qemu ≤ 2.5 without the exportname field against a
newstyle server, it will give the error:
.PP
.Vb 1
\& Server requires an export name
.Ve
.PP
If you use qemu ≤ 2.5 with the exportname field against an
oldstyle server, it will give the error:
.PP
.Vb 1
\& Server does not support export names
.Ve
.PP
If you use the oldstyle protocol with nbd-client ≥ 3.10, it will
give the error:
.PP
.Vb 1
\& Error: It looks like you\*(Aqre trying to connect to an oldstyle server.
.Ve
.SS "\s-1NBD\s0 protocol and port number"
.IX Subsection "NBD protocol and port number"
Port 10809/tcp is reserved by \s-1IANA\s0 for the \s-1NBD\s0 protocol, but you can
use nbdkit on any port or on Unix domain sockets.
.PP
The \s-1NBD\s0 protocol specification claims that you should always use
newstyle when using port 10809, and use oldstyle on all other ports,
but this claim is not based on the reality of what \s-1NBD\s0 servers do, and
nbdkit does not require or encourage this.
.SH "NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT"
.IX Header "NBD PROTOCOL FEATURES SUPPORTED BY NBDKIT"
.IP "newstyle protocol" 4
.IX Item "newstyle protocol"
Supported in nbdkit ≥ 1.1.12, and the default in nbdkit ≥ 1.3.
.IP "export names" 4
.IX Item "export names"
Supported in nbdkit ≥ 1.1.12.
.Sp
nbdkit can advertise an export name, but ignores any export name sent
by the client.  nbdkit does \fInot\fR support serving different data on
different export names.
.ie n .IP """NBD_FLAG_NO_ZEROES""" 4
.el .IP "\f(CWNBD_FLAG_NO_ZEROES\fR" 4
.IX Item "NBD_FLAG_NO_ZEROES"
Supported in nbdkit ≥ 1.1.13.
.Sp
This protocol optimization avoids sending a useless block of zero
bytes during protocol negotiation.
.ie n .IP """NBD_CMD_WRITE_ZEROES""" 4
.el .IP "\f(CWNBD_CMD_WRITE_ZEROES\fR" 4
.IX Item "NBD_CMD_WRITE_ZEROES"
Supported in nbdkit ≥ 1.1.13.
.IP "\s-1TLS\s0 with X.509 certificates" 4
.IX Item "TLS with X.509 certificates"
Supported in nbdkit ≥ 1.1.15.
.IP "\s-1TLS\s0 with Pre-Shared Keys (\s-1PSK\s0)" 4
.IX Item "TLS with Pre-Shared Keys (PSK)"
Supported in nbdkit ≥ 1.4.0.
.ie n .IP """NBD_OPT_GO""" 4
.el .IP "\f(CWNBD_OPT_GO\fR" 4
.IX Item "NBD_OPT_GO"
Supported in nbdkit ≥ 1.5.3.
.Sp
This protocol enhancement allows the server to return errors when
negotiating the export name.
.ie n .IP """NBD_OPT_INFO""" 4
.el .IP "\f(CWNBD_OPT_INFO\fR" 4
.IX Item "NBD_OPT_INFO"
Supported in nbdkit ≥ 1.9.3.
.Sp
This protocol enhancement allows a client to inspect details about
the export without actually connecting.
.ie n .IP """NBD_FLAG_CAN_MULTI_CONN""" 4
.el .IP "\f(CWNBD_FLAG_CAN_MULTI_CONN\fR" 4
.IX Item "NBD_FLAG_CAN_MULTI_CONN"
Supported in nbdkit ≥ 1.9.9.
.IP "Structured Replies" 4
.IX Item "Structured Replies"
\&\fINot supported\fR.
.IP "Block Status" 4
.IX Item "Block Status"
\&\fINot supported\fR.
.IP "Resize Extension" 4
.IX Item "Resize Extension"
\&\fINot supported\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
https://nbd.sourceforge.io/.
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.PP
Richard W.M. Jones
.PP
Pino Toscano
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2013\-2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
.IP "\(bu" 4
Neither the name of Red Hat nor the names of its contributors may be
used to endorse or promote products derived from this software without
specific prior written permission.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0