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.

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 in various other ways (see "MODES").

Use "fusermount -u MOUNTPOINT" to unmount the filesystem after you have used it.

EXAMPLES¶

 $ mkdir dir
 $ nbdfuse dir nbd://example.com &
 $ ls -l dir/
 total 0
 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 nbd

 $ fusermount -u dir
 $ rmdir dir

 $ 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

 $ fusermount -u dir
 $ rmdir dir

 $ 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

 $ fusermount -u dir
 $ rmdir dir

 $ 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

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:

-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¶

SEE ALSO¶

libnbd(3), nbdcopy(1), nbdinfo(1), 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