1nbdfuse(1)                          LIBNBD                          nbdfuse(1)
2
3
4

NAME

6       nbdfuse - mount a network block device in the local filesystem
7

SYNOPSIS

9        nbdfuse [-C N|--connections N] [-d] [-o FUSE-OPTION] [-P PIDFILE]
10                [-r] [-s] [-v|--verbose]
11                MOUNTPOINT[/FILENAME] URI
12
13        nbdfuse MOUNTPOINT[/FILENAME] [ CMD [ARGS ...] ]
14
15        nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
16
17        nbdfuse MOUNTPOINT[/FILENAME] --fd N
18
19        nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
20
21        nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
22
23        nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
24
25       To unmount:
26
27        fusermount3 -u MOUNTPOINT
28
29       Other options:
30
31        nbdfuse --help
32
33        nbdfuse --fuse-help
34
35        nbdfuse -V|--version
36

DESCRIPTION

38       nbdfuse is used to mount a Network Block Device (NBD) in the local
39       filesystem.  The NBD virtual file is mounted at MOUNTPOINT/FILENAME
40       (defaulting to MOUNTPOINT/nbd).  Reads and writes to the virtual file
41       are turned into reads and writes to the NBD device.
42
43       In nbdfuse ≥ 1.6 you can also create a "naked" mountpoint by mounting
44       over any regular file called MOUNTPOINT (the existing contents of the
45       file do not matter).
46
47       The NBD server itself can be local or remote.  The server can be
48       specified as an NBD URI (like "nbd://localhost"), or as an NBD server
49       running as a subprocess of nbdfuse (using "[ ... ]"), or in various
50       other ways (see "MODES").
51
52       Use "fusermount3 -u MOUNTPOINT" to unmount the filesystem after you
53       have used it.
54

EXAMPLES

56   Present a remote NBD server as a local file
57       If there is a remote NBD server running on "example.com" at the default
58       NBD port number (10809) then you can turn it into a local file by
59       doing:
60
61        $ mkdir dir
62        $ nbdfuse dir nbd://example.com &
63        $ ls -l dir/
64        total 0
65        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 nbd
66
67       The file is called dir/nbd and you can read and write to it as if it is
68       a normal file.  Note that writes to the file will write to the remote
69       NBD server.  After using it, unmount it:
70
71        $ fusermount3 -u dir
72        $ rmdir dir
73
74   Use nbdkit to create a file backed by a temporary RAM disk
75       Using "[ ... ]" you can run an NBD server as a subprocess.  In this
76       example nbdkit(1) is used to create a temporary file backed by a RAM
77       disk:
78
79        $ mkdir dir
80        $ nbdfuse dir/ramdisk [ nbdkit --exit-with-parent memory 1G ] &
81        $ ls -l dir/
82        total 0
83        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 ramdisk
84        $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat
85        100+0 records in
86        100+0 records out
87        104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s
88
89       When you have finished with the RAM disk, you can unmount it as below
90       which will cause nbdkit to exit and the RAM disk contents to be
91       discarded:
92
93        $ fusermount3 -u dir
94        $ rmdir dir
95
96   Use qemu-nbd to read and modify a qcow2 file
97       You can use qemu-nbd(8) as a subprocess to open any file format which
98       qemu understands:
99
100        $ mkdir dir
101        $ nbdfuse dir/file.raw [ qemu-nbd -f qcow2 file.qcow2 ] &
102        $ ls -l dir/
103        total 0
104        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 file.raw
105
106       File dir/file.raw is in raw format, backed by file.qcow2.  Any changes
107       made to dir/file.raw are reflected into the qcow2 file.  To unmount the
108       file do:
109
110        $ fusermount3 -u dir
111        $ rmdir dir
112
113   Use nbdkit to create a local file from a file on a web server
114       nbdkit(1) is able to both access and transparently uncompress remote
115       disk images on web servers, so you can convert them into virtual files:
116
117        $ mkdir dir
118        $ nbdfuse dir/disk.iso \
119              [ nbdkit --exit-with-parent \
120                       curl --filter=xz \
121                       http://builder.libguestfs.org/fedora-30.xz ] &
122        $ ls -l dir/
123        total 0
124        -rw-rw-rw-. 1 nbd nbd 6442450944 Jan  1 10:10 disk.iso
125        $ file dir/disk.iso
126        dir/disk.iso: DOS/MBR boot sector
127        $ qemu-system-x86_64 -m 4G \
128              -drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
129        $ fusermount3 -u dir
130
131       In this example we have used the virtual file to boot qemu, but qemu
132       can much more efficiently access NBD servers directly so in the real
133       world that would be the preferred method.
134

OPTIONS

136       --help
137           Display brief command line help and exit.
138
139       -C N
140       --connections N
141           If multi-conn is used, use N connections to the server.  The
142           default is 4.
143
144           Multi-conn is enabled by default when possible.  Modes which run a
145           subprocess, such as --command are not able to use multi-conn.  Mode
146           --fd also cannot use multi-conn.  Also the server must advertise
147           multi-conn (use nbdinfo(1) to query what the server supports).
148
149           See "THREAD MODEL" below.
150
151       -C 1
152       --connections 1
153           Disable multi-conn.  Only use a single connection to the NBD
154           server.  See "THREAD MODEL" below.
155
156       --fuse-help
157           Display FUSE options and exit.  See -o below.
158
159       -o FUSE-OPTION
160           Pass extra options to FUSE.  To get a list of all the extra options
161           supported by FUSE, use --fuse-help.
162
163           Some potentially useful FUSE options:
164
165           -o allow_other
166               Allow other users to see the filesystem.  This option has no
167               effect unless you enable it globally in /etc/fuse.conf.
168
169           -o kernel_cache
170               Allow the kernel to cache files (reduces the number of reads
171               that have to go through the libnbd(3) API).  This is generally
172               a good idea if you can afford the extra memory usage.
173
174           -o uid=N
175           -o gid=N
176               Use these options to map UIDs and GIDs.
177
178       -P PIDFILE
179       --pidfile PIDFILE
180           When nbdfuse is ready to serve, write the nbdfuse process ID (PID)
181           to PIDFILE.  This can be used in scripts to wait until nbdfuse is
182           ready.  Note you mustn't try to kill nbdfuse.  Use "fusermount3 -u"
183           to unmount the mountpoint which will cause nbdfuse to exit cleanly.
184
185       -r
186       --readonly
187           Access the network block device read-only.  The virtual file will
188           have read-only permissions, and any writes will return errors.
189
190           If the remote NBD server is read-only then this flag is added
191           automatically.  (Check "is_read_only:" field in the output of
192           nbdinfo(1)).
193
194       -s  Use single-threaded FUSE operations.  See "THREAD MODEL" below.
195
196       -v
197       --verbose
198       -d  Enable verbose messages to stderr.  This enables libnbd debugging
199           and other messages.  The -d option is an alias, used for
200           compatibility with other FUSE programs.
201
202       -V
203       --version
204           Display the package name and version and exit.
205

MODES

207       Modes are used to select the NBD server.  Possible modes are:
208
209       nbdfuse MOUNTPOINT URI
210           This mode uses an NBD URI (see nbd_connect_uri(3) and
211           https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).
212           For example this specifies a TLS-encrypted connection to
213           "example.com" port 10809, with export name "disk":
214
215            nbdfuse dir nbds://example.com/disk
216
217       nbdfuse MOUNTPOINT [ CMD [ARGS ...] ]
218           Run an NBD server as a subprocess.  In this mode an NBD server can
219           be run directly from the command line with nbdfuse communicating
220           with the server over a socket.  This requires that the NBD server
221           supports systemd socket activation.  See "EXAMPLES" above and
222           nbd_connect_systemd_socket_activation(3).
223
224       nbdfuse MOUNTPOINT --command CMD [ARGS ...]
225           Select command mode.  In this mode an NBD server can be run
226           directly from the command line with nbdfuse communicating with the
227           server over the server’s stdin/stdout.  Normally you would use this
228           with "nbdkit -s".  See nbd_connect_command(3).
229
230       nbdfuse MOUNTPOINT --fd N
231           Select file descriptor mode.  In this mode a connected socket is
232           passed to nbdfuse.  nbdfuse connects to the socket on the numbered
233           file descriptor.  See also nbd_connect_socket(3).
234
235       nbdfuse MOUNTPOINT --tcp HOST PORT
236           Select TCP mode.  Connect to an NBD server on a host and port over
237           an unencrypted TCP socket.  See also nbd_connect_tcp(3).
238
239       nbdfuse MOUNTPOINT --unix SOCKET
240           Select Unix mode.  Connect to an NBD server on a Unix domain
241           socket.  See also nbd_connect_unix(3).
242
243       nbdfuse MOUNTPOINT --vsock CID PORT
244           Select vsock mode.  Connect to an NBD server on a "AF_VSOCK"
245           socket.  See also nbd_connect_vsock(3).
246

THREAD MODEL

248       This section describes how the current version of nbdfuse works.
249       Previous versions worked differently in the past, and future versions
250       may work differently in the future.
251
252       nbdfuse is always multithreaded.
253
254       nbdfuse will try to open multiple network connections to the NBD server
255       if possible (called "multi-conn").  This usually improves performance.
256       Some things which disable multi-conn are:
257
258       •   using "[ CMD ... ]" or --command or --fd modes
259
260       •   using -C 1
261
262       •   the NBD server does not advertise multi-conn (check using
263           nbdinfo(1))
264
265       You can control how many connections are made using the -C flag.
266
267       nbdfuse runs one thread per connection to service NBD commands (these
268       are called "operation threads").  In addition, FUSE itself creates
269       multiple threads to deal with requests coming from the fuse.ko kernel
270       module.  The number of threads that FUSE can create is described in the
271       FUSE documentation, but with many parallel accesses to the virtual file
272       there may be many more FUSE threads created than operation threads, and
273       this should lead to good performance.  FUSE requests (like read, write
274       or trim) are multiplexed on to the operation threads (= connections) at
275       random.  Each operation thread can handle multiple requests in
276       parallel.
277
278       Using the -s flag causes FUSE the only run a single thread, but there
279       may still be multiple operation threads.
280

NOTES

282   Loop mounting
283       It is tempting (and possible) to loop mount the file.  However this
284       will be very slow and may sometimes deadlock.  Better alternatives are
285       to use nbd-client(8) or qemu-nbd(8), or more securely libguestfs(3),
286       guestfish(1) or guestmount(1) which can all access NBD servers.
287
288   As a way to access NBD servers
289       You can use this to access NBD servers, but it is usually better (and
290       definitely much faster) to use libnbd(3) directly instead.  To access
291       NBD servers from the command line, look at nbdsh(1).  To copy to and
292       from an NBD server use nbdcopy(1).
293

COMPARISON TO OTHER TOOLS

295   Compared to "nbd-client"
296       This program is similar in concept to nbd-client(8) (which turns NBD
297       into /dev/nbdX device nodes), except:
298
299       •   nbd-client is faster because it uses a special kernel module
300
301       •   nbd-client requires root, but nbdfuse can be used by any user
302
303       •   nbdfuse virtual files can be mounted anywhere in the filesystem
304
305       •   nbdfuse uses libnbd to talk to the NBD server
306
307       •   nbdfuse requires FUSE support in the kernel
308
309   Compared to "qemu-nbd"
310       qemu-nbd(8) can also attach itself to /dev/nbdX device nodes.  The
311       differences from nbdfuse are similar to the list above.
312

SEE ALSO

314       libnbd(3), nbdcopy(1), nbddump(1), nbdinfo(1), nbdsh(1),
315       fusermount3(1), mount.fuse3(8), nbd_connect_uri(3),
316       nbd_connect_command(3), nbd_connect_socket(3),
317       nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
318       nbd_connect_unix(3), nbd_connect_vsock(3), libguestfs(3), guestfish(1),
319       guestmount(1), nbdkit(1), nbdkit-loop(1), qemu-nbd(8), nbd-client(8).
320

AUTHORS

322       Richard W.M. Jones
323
325       Copyright (C) 2019-2021 Red Hat Inc.
326

LICENSE

328       This library is free software; you can redistribute it and/or modify it
329       under the terms of the GNU Lesser General Public License as published
330       by the Free Software Foundation; either version 2 of the License, or
331       (at your option) any later version.
332
333       This library is distributed in the hope that it will be useful, but
334       WITHOUT ANY WARRANTY; without even the implied warranty of
335       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
336       Lesser General Public License for more details.
337
338       You should have received a copy of the GNU Lesser General Public
339       License along with this library; if not, write to the Free Software
340       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
341       02110-1301 USA
342
343
344
345libnbd-1.14.2                     2023-01-03                        nbdfuse(1)
Impressum