FreeBSD Manual Pages
GNBD(8) System Manager's Manual GNBD(8) 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, allow- ing reroot onto the network-backed devices. • Supports using multiple connections to the NBD server to par- allelize 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 con- nection is used if not specified. -n name Connect to the named export. The default ex- port is requested if not specified. -A cacert Verify TLS certificates against the PEM-format- ted CA certificate at the given path. The sys- tem 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 con- nections 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-format- ted CA certificate at the given path. The sys- tem 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. help See geom(8). list See geom(8). load See geom(8). unload 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 informa- tion is printed. If set to 3, the maximum amount of debug in- formation 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). Set- ting 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 connec- tions: # 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 SEE ALSO cxgbe(4), geom(4), ktls(4), loader.conf(5), geom(8) AUTHORS Ryan Moeller FreeBSD ports 15.quarterly June 6, 2025 GNBD(8)
NAME | SYNOPSIS | DESCRIPTION | TLS | SYSCTL TUNABLES | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gnbd&sektion=8&manpath=FreeBSD+Ports+15.0.quarterly>