Go implementation of the Linux Network Block Device protocol
This repository contains Go implementations of
- The NBD network protocol (both client and server).
- The Netlink API for NBD, to configure the in-kernel NBD client.
- A basic CLI tool that uses these implementations.
It's currently in beta and thus there are a bunch of known (and unknown) issues. Check the "beta" label for known problems. It is particularly interesting if you require features that are not yet supported. Please comment/vote on the corresponding issue.
Currently, this is pre-release, so the only way to install is from source. To do that, use
go get -u github.com/Merovius/nbd
Using the library
There are two packages:
- nbd, containing the client and server implementations of the network protocol, as well as some convenience functions for nbdnl. The network protocol is used as a handshake between client and server, to negotiate optional features and other options. Under Linux, there are also a couple of functions provided to easily hook up a
Deviceimplementation and use it as a block device.
- nbdnl, containing an implementation of the NBD generic netlink family, based on Matt Layher's genetlink package. This package can only be used on Linux; you should guard any usage with corresponding build tags.
The main usecase of this library is fuzzing code that tries to provide durable filesystem-operations. It allows you to implement aribtrary failure modes of a block device and then create any filesystem you'd like to test on it. For example, to fuzz for crash-resistence, you can have the block device return errors on any write-operations after an arbitrary point in time and then repeatedly mount a filesystem, run a bunch of application code, simulate a crash and then check invariants (after re-mounting). This can provide some confidence (though no guarantees) that your code works with actual filesystem-implementations.
Note, that any code that wants to configure the in-kernel NBD client has to be privileged (the process needs to have
This repo contains basic CLI tool to configure/serve/connect to NBD devices. You can install it via
go get -u github.com/Merovius/nbd/cmd/nbd
To see what it can do, use
nbd help. Note, that most of the useful commands require root (or, more specifically,
CAP_SYS_ADMIN) to work.
One of the most useful subcommands is
lo, which can be used to use a file as a block device (similarly to
losetup). It also supports toggling write-only mode of the device via a unix signal, though, which can be used to test the durability of software not written in Go. Refer to
nbd help lo for details.
Copyright 2018 Axel Wagner Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.