NAME

gnbd — control utility for the network block device GEOM class

SYNOPSIS

To load the GEOM_NBD module at boot time, add the following line to your loader.conf(5):

geom_nbd_load="YES"

Usage of the gnbd utility:

gnbd connect [-c num] [-n name] [-p port] host

gnbd connect [-c num] [-n name] [-p port] [-A cacert] -C cert -K key host

gnbd reconnect [-r seconds] host

gnbd reconnect [-r seconds] [-A cacert] -C cert -K key prov

gnbd scale -c num prov

gnbd scale -c num [-A cacert] -C cert -K key prov

gnbd disconnect prov

gnbd exports [-p port] host

gnbd exports [-p port] [-A cacert] -C cert -K key host

gnbd help

gnbd list [-a] [prov ...]

gnbd status [-ags] [prov ...]

gnbd load [-v]

gnbd unload [-v]

DESCRIPTION

The gnbd utility is used to configure network block device (NBD) GEOM providers.

The following is a list of the most important features:

Established connections are handed off to the kernel, allowing reroot onto the network-backed devices.
Supports using multiple connections to the NBD server to parallelize commands.
Supports optional TLS encryption using ktls(4).
Zero copies are performed for writes where possible. Work is needed to support cxgbe(4) TCP-offload module DDP for zero-copy reads.

The first argument to gnbd indicates an action to be performed:

connect

Connect to an NBD server.

-c connections: Use this many parallel connections. One connection is used if not specified.
-n name: Connect to the named export. The default export is requested if not specified.
-A cacert: Verify TLS certificates against the PEM-formatted CA certificate at the given path. The system root CAs are used if not specified.
-C cert: Make a TLS connection using the PEM-formatted client certificate at the given path.
-K key: Make a TLS connection using the PEM-formatted client key at the given path.

To make TLS connections, both a certificate and key must be given.

The path of a UNIX-domain socket may be specified in place of a host. UNIX-domain sockets are not expected to perform well or be useful with TLS.

reconnect

Re-establish failed connections.

-r seconds: Retry until connections are re-established, waiting this many seconds between successive retries. This is useful for a devd action in response to the GEOM NBD DISCONNECTED event.

When all connections for a device have failed, the provider will persist and can resume normal operation when new connections are established. The number of connections set by connect or scale is restored.

scale

Scale the number of connections for an existing device up or down.

-c connections: Use this many parallel connections.
-A cacert: Verify TLS certificates against the PEM-formatted CA certificate at the given path. The system root CAs are used if not specified.
-C cert: Make a TLS connection using the PEM-formatted client certificate at the given path.
-K key: Make a TLS connection using the PEM-formatted client key at the given path.

To make TLS connections, both a certificate and key must be given.

disconnect

Disconnect and remove the given provider.

exports

List exports of an NBD server.

See geom(8).

See geom(8).

See geom(8).

See geom(8).

TLS

All TLS certificates and keys must be in PEM format. TLS certificates may be a certificate chain to include intermediary certificates in the chain of trust.

SYSCTL TUNABLES

The following sysctl(8) tunables can be used to control the behavior of the NBD GEOM class. The default value is shown next to each variable.

kern.geom.nbd.debug: 0

Debug level of the NBD GEOM class. This can be set to a number between 0 and 3 inclusive. If set to 0, minimal debug information is printed. If set to 3, the maximum amount of debug information is printed.

kern.geom.nbd.maxpayload: 33554432 (32 MiB)

Upper limit on the size in bytes of a single transfer over the network.

kern.geom.nbd.sendspace: 1572864 (1536 kiB)

Size of socket send buffer reservation per connection.

Note: connections may also be limited by standard socket buffer limits.

kern.geom.nbd.recvspace: 1572864 (1536 kiB)

Size of socket receive buffer reservation per connection.

Note: connections may also be limited by standard socket buffer limits.

kern.geom.nbd.identfmt: 0

Format of the GEOM::ident attribute.

Setting to 0 uses the format "host:port/name". Setting to 1 uses "name" if the export has a name, falling back to "host:port/name" when the name is empty (default export). Setting to 2 always uses "name", even if the name is empty.

Formats 1 and 2 can be useful when the export names are serial numbers.

EXIT STATUS

Exit status is 0 on success, and 1 if the command fails.

EXAMPLES

Connect to an NBD server with 4 connections:

# gnbd connect -c 4 servername
nbd0

Connect to an NBD server using TLS with an internal CA and 2 connections:

# gnbd connect -c 2 -A cacert.pem -C cert.pem -K key.pem servername
nbd1

Scale the second provider up to 8 connections:

# gnbd scale -c 8 -A cacert.pem -C cert.pem -K key.pem nbd1

Disconnect the previous examples:

# gnbd disconnect nbd0
# gnbd disconnect nbd1

AUTHORS

Ryan Moeller