nbdublk(1)

1nbdublk(1)                          LIBNBD                          nbdublk(1)
2
3
4

NAME

6       nbdublk - connect network block device to a local device
7

SYNOPSIS

9        nbdublk [-C N|--connections N] [-r] [-v|--verbose] /dev/ublkb<N> URI
10
11        nbdublk [-C N|--connections N] [-r] [-v|--verbose] <N> URI
12
13        nbdublk [-C N|--connections N] [-r] [-v|--verbose] - URI
14
15        nbdublk /dev/ublkb<N> [ CMD [ARGS ...] ]
16
17        nbdublk /dev/ublkb<N> --command CMD [ARGS ...]
18
19        nbdublk /dev/ublkb<N> --fd N
20
21        nbdublk /dev/ublkb<N> --tcp HOST PORT
22
23        nbdublk /dev/ublkb<N> --unix SOCKET
24
25        nbdublk /dev/ublkb<N> --vsock CID PORT
26
27       To list devices:
28
29        ublk list
30
31       To unmount:
32
33        ublk del -n <N>
34
35       Other commands:
36
37        nbdublk --help
38
39        nbdublk -V|--version
40
41        modprobe ublk_drv
42

DESCRIPTION

44       nbdublk is used to create a Linux device /dev/ublkb<N> from a network
45       block device server.  Reads and writes to the virtual device are turned
46       into reads and writes to the NBD server.
47
48       The first parameter is the Linux device name of the form /dev/ublkb<N>
49       (for some number <N>), for example /dev/ublkb0, /dev/ublkb1, &c.  You
50       can just use the number on its own, or use "-" to get ublk to allocate
51       an unused device.
52
53       The second and following parameters refer to the NBD server, which can
54       be local or remote.  The server can be specified as an NBD URI (like
55       "nbd://localhost"), or as an NBD server running as a subprocess of
56       nbdublk (using "[ ... ]"), or in various other ways (see "MODES").
57
58       Use ublk(8) to list and delete devices.
59
60   Requires Linux and root
61       This program requires Linux ≥ 6.0 and the "ublk_drv.ko" kernel module.
62       You may need to load the kernel module and you usually have to run
63       nbdublk as root.
64

EXAMPLE

66       Create an NBD ublk device connected to a remote NBD server:
67
68        # nbdublk /dev/ublkb0 nbd://server
69
70       List the device:
71
72        # ublk list
73        dev id 0: nr_hw_queues 4 queue_depth 64 block size 1 dev_capacity 0
74                max rq size 67108864 daemon pid 32382 flags 0x0 state LIVE
75
76       You can then use "/dev/ublkb0" as a regular device.  To disconnect the
77       device use:
78
79        # ublk del -n 0
80

OPTIONS

82       --help
83           Display brief command line help and exit.
84
85       -C N
86       --connections N
87           If multi-conn is used, use N connections to the server.  The
88           default is 4.
89
90           Multi-conn is enabled by default when possible.  Modes which run a
91           subprocess, such as --command are not able to use multi-conn.  Mode
92           --fd also cannot use multi-conn.  Also the server must advertise
93           multi-conn (use nbdinfo(1) to query what the server supports).
94
95       -C 1
96       --connections 1
97           Disable multi-conn.  Only use a single connection to the NBD
98           server.  See "THREAD MODEL" below.
99
100       -r
101       --readonly
102           Access the network block device read-only.  The virtual file will
103           have read-only permissions, and any writes will return errors.
104
105           If the remote NBD server is read-only then this flag is added
106           automatically.  (Check "is_read_only:" field in the output of
107           nbdinfo(1)).
108
109       -v
110       --verbose
111           Enable verbose messages to stderr.  This enables libnbd debugging
112           and other messages.
113
114       -V
115       --version
116           Display the package name and version and exit.
117

MODES

119       Modes are used to select the NBD server.  Possible modes are:
120
121       nbdublk DEVICE URI
122           This mode uses an NBD URI (see nbd_connect_uri(3) and
123           https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).
124           For example this specifies a TLS-encrypted connection to
125           "example.com" port 10809, with export name "disk":
126
127            nbdublk /dev/ublkb0 nbds://example.com/disk
128
129       nbdublk DEVICE [ CMD [ARGS ...] ]
130           Run an NBD server as a subprocess.  In this mode an NBD server can
131           be run directly from the command line with nbdublk communicating
132           with the server over a socket.  This requires that the NBD server
133           supports systemd socket activation.  See "EXAMPLES" above and
134           nbd_connect_systemd_socket_activation(3).
135
136       nbdublk DEVICE --command CMD [ARGS ...]
137           Select command mode.  In this mode an NBD server can be run
138           directly from the command line with nbdublk communicating with the
139           server over the server’s stdin/stdout.  Normally you would use this
140           with "nbdkit -s".  See nbd_connect_command(3).
141
142       nbdublk DEVICE --fd N
143           Select file descriptor mode.  In this mode a connected socket is
144           passed to nbdublk.  nbdublk connects to the socket on the numbered
145           file descriptor.  See also nbd_connect_socket(3).
146
147       nbdublk DEVICE --tcp HOST PORT
148           Select TCP mode.  Connect to an NBD server on a host and port over
149           an unencrypted TCP socket.  See also nbd_connect_tcp(3).
150
151       nbdublk DEVICE --unix SOCKET
152           Select Unix mode.  Connect to an NBD server on a Unix domain
153           socket.  See also nbd_connect_unix(3).
154
155       nbdublk DEVICE --vsock CID PORT
156           Select vsock mode.  Connect to an NBD server on a "AF_VSOCK"
157           socket.  See also nbd_connect_vsock(3).
158

AUTHORS

167       Richard W.M. Jones
168
169       Ming Lei
170

COPYRIGHT

172       Copyright Red Hat
173

LICENSE

175       This library is free software; you can redistribute it and/or modify it
176       under the terms of the GNU Lesser General Public License as published
177       by the Free Software Foundation; either version 2 of the License, or
178       (at your option) any later version.
179
180       This library is distributed in the hope that it will be useful, but
181       WITHOUT ANY WARRANTY; without even the implied warranty of
182       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
183       Lesser General Public License for more details.
184
185       You should have received a copy of the GNU Lesser General Public
186       License along with this library; if not, write to the Free Software
187       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
188       02110-1301 USA
189
190
191
192libnbd-1.18.1                     2023-10-31                        nbdublk(1)