Ubuntu Manpage: nbdfuse - mount a network block device in the local filesystem

NAME

       nbdfuse - mount a network block device in the local filesystem

SYNOPSIS

        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

DESCRIPTION

       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.

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:

        $ fusermount3 -u dir
        $ rmdir dir

   Use nbdkit to create a file backed by a temporary RAM disk
       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

   Use qemu-nbd to read and modify a qcow2 file
       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

   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 \
              [ 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.

OPTIONS

--help
Display brief command line help and exit.

-C N
--connections N
If multi-conn is used, use N connections to the server. The default is 4.

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.

-C 1
--connections 1
Disable multi-conn. Only use a single connection to the NBD server. See "THREAD
MODEL" below.

--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 "fusermount3 -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.

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)).

-s Use single-threaded FUSE operations. See "THREAD MODEL" below.

-v
--verbose
-d Enable verbose messages to stderr. This enables libnbd debugging and other messages.
The -d option is an alias, used for compatibility with other FUSE programs.

-V
--version
Display the package name and version and exit.

MODES

Modes are used to select the NBD server. Possible modes are:

nbdfuse MOUNTPOINT URI
This 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

nbdfuse MOUNTPOINT [ CMD [ARGS ...] ]
Run an NBD server as a subprocess. In this mode an NBD server can be run directly
from the command line with nbdfuse communicating with the server over a socket. This
requires that the NBD server supports systemd socket activation. See "EXAMPLES" above
and nbd_connect_systemd_socket_activation(3).

nbdfuse MOUNTPOINT --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 nbd_connect_command(3).

nbdfuse MOUNTPOINT --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).

nbdfuse MOUNTPOINT --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).

nbdfuse MOUNTPOINT --unix SOCKET
Select Unix mode. Connect to an NBD server on a Unix domain socket. See also
nbd_connect_unix(3).

nbdfuse MOUNTPOINT --vsock CID PORT
Select vsock mode. Connect to an NBD server on a "AF_VSOCK" socket. See also
nbd_connect_vsock(3).

THREAD MODEL

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:

• using "[ CMD ... ]" or --command or --fd modes

• using -C 1

• the NBD server does not advertise multi-conn (check using nbdinfo(1))

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.

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).  To copy to and from an NBD server use nbdcopy(1).

COMPARISON TO OTHER TOOLS

   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.

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

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