| nbdfuse(1) | LIBNBD | nbdfuse(1) |
nbdfuse - mount a network block device in the local filesystem
nbdfuse [-C N|--connections N] [-d] [-o FUSE-OPTION] [-P PIDFILE]
[-r] [-s] [-v|--verbose]
MOUNTPOINT[/FILENAME] URI
nbdfuse MOUNTPOINT[/FILENAME] [ CMD [ARGS ...] ]
nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
nbdfuse MOUNTPOINT[/FILENAME] --fd N
nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
To unmount:
fusermount3 -u MOUNTPOINT
Other options:
nbdfuse --help
nbdfuse --fuse-help
nbdfuse -V|--version
nbdfuse is used to mount a Network Block Device (NBD) in the local filesystem. The NBD virtual file is mounted at MOUNTPOINT/FILENAME (defaulting to MOUNTPOINT/nbd). Reads and writes to the virtual file are turned into reads and writes to the NBD device.
In nbdfuse ≥ 1.6 you can also create a "naked" mountpoint by mounting over any regular file called MOUNTPOINT (the existing contents of the file do not matter).
The NBD server itself can be local or remote. The server can be specified as an NBD URI (like "nbd://localhost"), or as an NBD server running as a subprocess of nbdfuse (using "[ ... ]"), or in various other ways (see "MODES").
Use "fusermount3 -u MOUNTPOINT" to unmount the filesystem after you have used it.
If there is a remote NBD server running on "example.com" at the default NBD port number (10809) then you can turn it into a local file by doing:
$ mkdir dir $ nbdfuse dir nbd://example.com & $ ls -l dir/ total 0 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 nbd
The file is called dir/nbd and you can read and write to it as if it is a normal file. Note that writes to the file will write to the remote NBD server. After using it, unmount it:
$ fusermount3 -u dir $ rmdir dir
Using "[ ... ]" you can run an NBD server as a subprocess. In this example nbdkit(1) is used to create a temporary file backed by a RAM disk:
$ mkdir dir $ nbdfuse dir/ramdisk [ nbdkit --exit-with-parent memory 1G ] & $ ls -l dir/ total 0 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 ramdisk $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat 100+0 records in 100+0 records out 104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s
When you have finished with the RAM disk, you can unmount it as below which will cause nbdkit to exit and the RAM disk contents to be discarded:
$ fusermount3 -u dir $ rmdir dir
You can use qemu-nbd(8) as a subprocess to open any file format which qemu understands:
$ mkdir dir $ nbdfuse dir/file.raw [ qemu-nbd -f qcow2 file.qcow2 ] & $ ls -l dir/ total 0 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 file.raw
File dir/file.raw is in raw format, backed by file.qcow2. Any changes made to dir/file.raw are reflected into the qcow2 file. To unmount the file do:
$ fusermount3 -u dir $ rmdir dir
nbdkit(1) is able to both access and transparently uncompress remote disk images on web servers, so you can convert them into virtual files:
$ mkdir dir
$ nbdfuse dir/disk.iso \
[ nbdkit --exit-with-parent \
curl --filter=xz \
http://builder.libguestfs.org/fedora-30.xz ] &
$ ls -l dir/
total 0
-rw-rw-rw-. 1 nbd nbd 6442450944 Jan 1 10:10 disk.iso
$ file dir/disk.iso
dir/disk.iso: DOS/MBR boot sector
$ qemu-system-x86_64 -m 4G \
-drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
$ fusermount3 -u dir
In this example we have used the virtual file to boot qemu, but qemu can much more efficiently access NBD servers directly so in the real world that would be the preferred method.
Multi-conn is enabled by default when possible. Modes which run a subprocess, such as --command are not able to use multi-conn. Mode --fd also cannot use multi-conn. Also the server must advertise multi-conn (use nbdinfo(1) to query what the server supports).
See "THREAD MODEL" below.
Some potentially useful FUSE options:
If the remote NBD server is read-only then this flag is added automatically. (Check "is_read_only:" field in the output of nbdinfo(1)).
Modes are used to select the NBD server. Possible modes are:
nbdfuse dir nbds://example.com/disk
This section describes how the current version of nbdfuse works. Previous versions worked differently in the past, and future versions may work differently in the future.
nbdfuse is always multithreaded.
nbdfuse will try to open multiple network connections to the NBD server if possible (called "multi-conn"). This usually improves performance. Some things which disable multi-conn are:
You can control how many connections are made using the -C flag.
nbdfuse runs one thread per connection to service NBD commands (these are called "operation threads"). In addition, FUSE itself creates multiple threads to deal with requests coming from the fuse.ko kernel module. The number of threads that FUSE can create is described in the FUSE documentation, but with many parallel accesses to the virtual file there may be many more FUSE threads created than operation threads, and this should lead to good performance. FUSE requests (like read, write or trim) are multiplexed on to the operation threads (= connections) at random. Each operation thread can handle multiple requests in parallel.
Using the -s flag causes FUSE the only run a single thread, but there may still be multiple operation threads.
It is tempting (and possible) to loop mount the file. However this will be very slow and may sometimes deadlock. Better alternatives are to use nbd-client(8) or qemu-nbd(8), or more securely libguestfs(3), guestfish(1) or guestmount(1) which can all access NBD servers.
You can use this to access NBD servers, but it is usually better (and definitely much faster) to use libnbd(3) directly instead. To access NBD servers from the command line, look at nbdsh(1). To copy to and from an NBD server use nbdcopy(1).
This program is similar in concept to nbd-client(8) (which turns NBD into /dev/nbdX device nodes), except:
qemu-nbd(8) can also attach itself to /dev/nbdX device nodes. The differences from nbdfuse are similar to the list above.
libnbd(3), nbdcopy(1), nbddump(1), nbdinfo(1), nbdsh(1), fusermount3(1), mount.fuse3(8), nbd_connect_uri(3), nbd_connect_command(3), nbd_connect_socket(3), nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3), nbd_connect_unix(3), nbd_connect_vsock(3), libguestfs(3), guestfish(1), guestmount(1), nbdkit(1), nbdkit-loop(1), qemu-nbd(8), nbd-client(8).
Richard W.M. Jones
Copyright (C) 2019-2021 Red Hat Inc.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
| 2023-01-04 | libnbd-1.14.2 |