Provided by: nbdfuse_1.2.2-1ubuntu2_amd64 
NAME
nbdfuse - present a network block device in a FUSE filesystem
SYNOPSIS
nbdfuse [-o FUSE-OPTION] [-P PIDFILE] [-r]
MOUNTPOINT[/FILENAME] URI
Other modes:
nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
nbdfuse MOUNTPOINT[/FILENAME] --socket-activation CMD [ARGS ...]
nbdfuse MOUNTPOINT[/FILENAME] --fd N
nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
DESCRIPTION
nbdfuse presents a Network Block Device as a local file inside a FUSE filesystem.
The FUSE filesystem is mounted at MOUNTPOINT and contains a single virtual file called
FILENAME (defaulting to nbd). Reads and writes to the virtual file or device are turned
into reads and writes to the NBD device.
The NBD server itself can be local or remote. The server can be specified as an NBD URI
(like "nbd://localhost") or in various other ways (see "MODES").
Use "fusermount -u MOUNTPOINT" to unmount the filesystem after you have used it.
EXAMPLES
Present a remote NBD server as a local file
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:
$ fusermount -u dir
$ rmdir dir
Use nbdkit to create a file backed by a temporary RAM disk
nbdkit(1) has an -s option allowing it to serve over stdin/stdout. You can combine this
with nbdfuse as follows:
$ mkdir dir
$ nbdfuse dir/ramdisk --command nbdkit -s 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:
$ fusermount -u dir
$ rmdir dir
Use qemu-nbd to read and modify a qcow2 file
qemu-nbd(8) cannot serve over stdin/stdout, but it can use systemd socket activation. You
can combine this with nbdfuse and use it to open any file format which qemu understands:
$ mkdir dir
$ nbdfuse dir/file.raw \
--socket-activation 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:
$ fusermount -u dir
$ rmdir dir
Use nbdkit to create a local file from a file on a web server
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 \
--command nbdkit -s 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
$ fusermount -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.
OPTIONS
--help
Display brief command line help and exit.
--fuse-help
Display FUSE options and exit. See -o below.
-o FUSE-OPTION
Pass extra options to FUSE. To get a list of all the extra options supported by FUSE,
use --fuse-help.
Some potentially useful FUSE options:
-o allow_other
Allow other users to see the filesystem. This option has no effect unless you
enable it globally in /etc/fuse.conf.
-o kernel_cache
Allow the kernel to cache files (reduces the number of reads that have to go
through the libnbd(3) API). This is generally a good idea if you can afford the
extra memory usage.
-o uid=N
-o gid=N
Use these options to map UIDs and GIDs.
-P PIDFILE
--pidfile PIDFILE
When nbdfuse is ready to serve, write the nbdfuse process ID (PID) to PIDFILE. This
can be used in scripts to wait until nbdfuse is ready. Note you mustn't try to kill
nbdfuse. Use "fusermount -u" to unmount the mountpoint which will cause nbdfuse to
exit cleanly.
-r
--readonly
Access the network block device read-only. The virtual file will have read-only
permissions, and any writes will return errors.
-V
--version
Display the package name and version and exit.
MODES
Modes are used to select the NBD server. The default mode uses an NBD URI (see
nbd_connect_uri(3) and https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).
For example this specifies a TLS-encrypted connection to "example.com" port 10809, with
export name "disk":
nbdfuse dir nbds://example.com/disk
Other modes are:
--command CMD [ARGS ...]
Select command mode. In this mode an NBD server can be run directly from the command
line with nbdfuse communicating with the server over the server’s stdin/stdout.
Normally you would use this with "nbdkit -s". See "EXAMPLES" above and
nbd_connect_command(3).
--fd N
Select file descriptor mode. In this mode a connected socket is passed to nbdfuse.
nbdfuse connects to the socket on the numbered file descriptor. See also
nbd_connect_socket(3).
--socket-activation CMD [ARGS ...]
Select systemd socket activation mode. This is similar to --command, but is used for
servers like qemu-nbd(8) which support systemd socket activation. See "EXAMPLES"
above and nbd_connect_systemd_socket_activation(3).
--tcp HOST PORT
Select TCP mode. Connect to an NBD server on a host and port over an unencrypted TCP
socket. See also nbd_connect_tcp(3).
--unix SOCKET
Select Unix mode. Connect to an NBD server on a Unix domain socket. See also
nbd_connect_unix(3).
--vsock CID PORT
Select vsock mode. Connect to an NBD server on a "AF_VSOCK" socket. See also
nbd_connect_vsock(3).
NOTES
Loop mounting
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.
As a way to 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).
Compared to "nbd-client"
This program is similar in concept to nbd-client(8) (which turns NBD into /dev/nbdX device
nodes), except:
• nbd-client is faster because it uses a special kernel module
• nbd-client requires root, but nbdfuse can be used by any user
• nbdfuse virtual files can be mounted anywhere in the filesystem
• nbdfuse uses libnbd to talk to the NBD server
• nbdfuse requires FUSE support in the kernel
Compared to "qemu-nbd"
qemu-nbd(8) can also attach itself to /dev/nbdX device nodes. The differences from
nbdfuse are similar to the list above.
SEE ALSO
libnbd(3), nbdsh(1), fusermount(1), mount.fuse(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).
AUTHORS
Richard W.M. Jones
COPYRIGHT
Copyright (C) 2019 Red Hat Inc.
LICENSE
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