nbd-client v1.0.5
node-nbd-client
Linux NBD client and library for Node.js. Built to automate block storage systems.
Features
- Fast:
node-nbd-client
can attach an NBD device in ~10ms and does all I/O in parallel.nbd-client
does all I/O serially. Transmission is handled by the kernel so it performs exactly the same. - Persistent connections: will always reconnect, even if
nbd-client -disconnect
is used.nbd-client
will stop if the server crashes, even with-persist
. - Built for containers:
ioctl
interface by default.nbd-client
defaults to thenetlink
interface which requires--network=host
on Docker.node-nbd-client
uses threads and never callsfork()
, which keep sockets in the calling PID.nbd-client
will fork even with-nofork
(it is intended per the man page), causing a kernel deadlock ifSIGKILL
is sent to a container: main process waits for file descriptors to close, which cannot close because the forked process is opened, but the forked process won't quit until the Docker init process quits, which is blocked by the main process, making Docker show a zoombie process error, requiring a machine restart to unlock resources.
Usage
CLI
$ npm install nbd-client --global
$ node-nbd-client --help
Usage: node-nbd-client [options] <device>
<device>
Full path to the block device the client should use, example:
/dev/nbd5
.
-H, --host <host>
Server hostname or IP address, defaults to
localhost
.
-P, --port <port>
Server port, defaults to
10809
, the IANA-assigned port number for the NBD protocol.
-u, --unix <path>
UNIX domain socket path, overrides TCP options.
-b, --block-size <size>
Block-size in bytes, defaults to
1024
; allowed values are either512
,1024
,2048
or4096
.
-C, --connections <number>
Number of connections to the server, increasing throughput and reducing latency at the cost of higher resource usage. Requires Linux 4.9+.
-N, --name <name>
Configure the export name, defaults to
default
.
-p, --persist
Configure if the client should always reconnect if the connection is unexpectedly dropped.
-c, --check
Configure if the client should quit with an exit code of
0
if the NBD device is attached or1
if the NBD device is not attached.
-h, --help
Display help.
Library
Install using
npm install nbd-client
import { NBD } from 'nbd-client'
const device = '/dev/nbd0'
if (await NBD.check(device)) {
throw new Error(`${device} is already attached`)
}
const client = new NBD({
device,
name: 'my-disk', // same as nbd-client --name
socket: { path: 'nbd-server.sock' }, // same options as net.createConnection()
persist: true, // same as nbd-client --persist
connections: 4, // same as nbd-client --connections
connected() {
console.log('Client connected')
},
})
// Stop the client after 5 seconds
setTimeout(() => client.stop(), 5000)
console.log('Connecting to NBD..')
// Start the client
await client.start()
console.log('Client stopped')
Not implemented
netlink
interface- Old-style negotiation
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago