nbd: github.com/Merovius/nbd Index | Files | Directories

package nbd

import "github.com/Merovius/nbd"

Package nbd implements the NBD network protocol.

You can find a full description of the protocol at https://sourceforge.net/p/nbd/code/ci/master/tree/doc/proto.md

This package implements both the client and the server side of the protocol, as well as (on Linux) utilities to hook up the kernel NBD client to use a server as a block device. The protocol is split into two phases: The handshake phase, which allows the client and server to negotiate their respective capabilities and what export to use. And the transmission phase, for actually reading/writing to the block device.

The client side of the handshake is done with the Client type. Its methods can be used to list the exports a server provides and their respective capabilities. Its Go method enters transmission phase. The returned Export can then be passed to Configure (linux only) to hook it up to an NBD device (/dev/nbdX).

The server side combines both handshake and transmission phase into the Serve or ListenAndServe functions. The user is expected to implement the Device interface to serve actual reads/writes. Under linux, the Loopback function serves as a convenient way to use a given Device as a block device.


Package Files

doc.go handshake.go netlink.go transmission.go types.go

func Configure Uses

func Configure(e Export, socks ...*os.File) (uint32, error)

Configure passes the given set of sockets to the kernel to provide them as an NBD device. socks must be connected to the same server (which must support multiple connections) and be in transmission phase. It returns the device-numbers that was chosen by the kernel or any error. You can then use /dev/nbdX as a block device. Use nbdnl.Disconnect to disconnect the device once you're done with it.

This is a Linux-only API.

func ListenAndServe Uses

func ListenAndServe(ctx context.Context, network, addr string, exp ...Export) error

ListenAndServe starts listening on the given network/address and serves the given exports, the first of which will serve as the default. It starts a new goroutine for each connection. ListenAndServe only returns when ctx is cancelled or an unrecoverable error occurs. Either way, it will wait for all connections to terminate first.

func Loopback Uses

func Loopback(ctx context.Context, d Device, size uint64) (idx uint32, wait func() error, err error)

Loopback serves d on a private socket, passing the other end to the kernel to connect to an NBD device. It returns the device-number that the kernel chose. wait should be called to check for errors from serving the device. It blocks until ctx is cancelled or an error occurs (so it behaves like Serve).

This is a Linux-only API.

func Serve Uses

func Serve(ctx context.Context, c net.Conn, exp ...Export) error

Serve serves the given exports on c. The first export is used as a default. Serve returns after ctx is cancelled or an error occurs.

type BlockSizeConstraints Uses

type BlockSizeConstraints struct {
    Min       uint32
    Preferred uint32
    Max       uint32

BlockSizeConstraints optionally specifies possible block sizes for a given export.

type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client performs the client-side of the NBD network protocol handshake and can be used to query information about the exports from a server.

func ClientHandshake Uses

func ClientHandshake(ctx context.Context, c net.Conn) (*Client, error)

ClientHandshake starts the client-side of the NBD handshake over c.

func (*Client) Abort Uses

func (c *Client) Abort() error

Abort aborts the handshake. c should not be used after Abort returns.

func (*Client) Go Uses

func (c *Client) Go(exportName string) (Export, error)

Go terminates the handshake phase of the NBD protocol, opening the export identified by exportName. If exportName is the empty string, the default export will be used. c should not be used after Go returns.

func (*Client) Info Uses

func (c *Client) Info(exportName string) (Export, error)

Info requests information about the export identified by exportName. If exportName is the empty string, the default export will be queried.

func (*Client) List Uses

func (c *Client) List() ([]string, error)

List returns the names of exports the server is providing.

type Device Uses

type Device interface {
    // Sync should block until all previous writes where written to persistent
    // storage and return any errors that occured.
    Sync() error

Device is the interface that should be implemented to expose an NBD device to the network or the kernel. Errors returned should implement Error - otherwise, EIO is assumed as the error number.

type Errno Uses

type Errno uint32

Errno is an error code suitable to be sent over the wire. It mostly corresponds to syscall.Errno, though the constants in this package are specified and so are the only ones to be safe to be sent over the wire and understood by all NBD servers/clients.

const (
    EPERM     Errno = 1
    EIO       Errno = 5
    ENOMEM    Errno = 12
    EINVAL    Errno = 22
    ENOSPC    Errno = 28
    EOVERFLOW Errno = 75
    ESHUTDOWN Errno = 108

See https://manpages.debian.org/stretch/manpages-dev/errno.3.en.html for a description of error numbers.

func (Errno) Errno Uses

func (e Errno) Errno() Errno

Errno returns e.

func (Errno) Error Uses

func (e Errno) Error() string

type Error Uses

type Error interface {
    Error() string
    Errno() Errno

Error combines the normal error interface with an Errno method, that returns an NBD error number. All of Device's methods should return an Error - otherwise, EIO is assumed as the error number.

func Errorf Uses

func Errorf(code Errno, msg string, v ...interface{}) Error

Errorf returns an error implementing Error, returning code from Errno.

type Export Uses

type Export struct {
    Name        string
    Description string
    Size        uint64
    Flags       uint16 // TODO: Determine Flags from Device.
    BlockSizes  *BlockSizeConstraints
    Device      Device

Export specifies the data needed for the NBD network protocol.


BlockSizeConstraints are not yet enforced by the server.

The server does not yet support FUA for direct IO.

StartTLS is not supported yet.

There is no way to declare a preferred block size for Loopback yet.

Server flags are not yet set (or used) correctly.

Structured replies are not yet supported.

CMD_TRIM is not yet supported.

Lame-duck mode (ESHUTDOWN) is not yet implemented.

CMD_WRITE_ZEROES is not yet supported.

Metadata querying is not yet supported.

FLAG_ROTATIONAL is not yet supported.

CMD_CACHE is not yet supported.


nbdnlPackage nbdnl controls the Linux NBD driver via netlink.

Package nbd imports 12 packages (graph). Updated 2019-03-19. Refresh now. Tools for package owners.