.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.20.0 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdfuse 1"
.TH nbdfuse 1 2024-05-31 libnbd-1.20.0 LIBNBD
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdfuse \- mount a network block device in the local filesystem
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& nbdfuse [\-C N|\-\-connections N] [\-d] [\-o FUSE\-OPTION] [\-P PIDFILE]
\&         [\-r] [\-s] [\-v|\-\-verbose]
\&         MOUNTPOINT[/FILENAME] URI
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] [ CMD [ARGS ...] ]
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] \-\-command CMD [ARGS ...]
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] \-\-fd N
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] \-\-tcp HOST PORT
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] \-\-unix SOCKET
.Ve
.PP
.Vb 1
\& nbdfuse MOUNTPOINT[/FILENAME] \-\-vsock CID PORT
.Ve
.PP
To unmount:
.PP
.Vb 1
\& fusermount3 \-u MOUNTPOINT
.Ve
.PP
Other options:
.PP
.Vb 1
\& nbdfuse \-\-help
.Ve
.PP
.Vb 1
\& nbdfuse \-\-fuse\-help
.Ve
.PP
.Vb 1
\& nbdfuse \-V|\-\-version
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
nbdfuse is used to mount a Network Block Device (NBD) in the local
filesystem.  The NBD virtual file is mounted at \fIMOUNTPOINT/FILENAME\fR
(defaulting to \fIMOUNTPOINT/nbd\fR).  Reads and writes to the virtual
file are turned into reads and writes to the NBD device.
.PP
In nbdfuse ≥ 1.6 you can also create a "naked" mountpoint by
mounting over any regular file called \fIMOUNTPOINT\fR (the existing
contents of the file do not matter).
.PP
The NBD server itself can be local or remote.  The server can be
specified as an NBD URI (like \f(CW\*(C`nbd://localhost\*(C'\fR), or as an NBD server
running as a subprocess of nbdfuse (using \f(CW\*(C`[\ ...\ ]\*(C'\fR), or in
various other ways (see "MODES").
.PP
Use \f(CW\*(C`fusermount3 \-u MOUNTPOINT\*(C'\fR to unmount the filesystem after you
have used it.
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "Present a remote NBD server as a local file"
.IX Subsection "Present a remote NBD server as a local file"
If there is a remote NBD server running on \f(CW\*(C`example.com\*(C'\fR at the
default NBD port number (10809) then you can turn it into a local file
by doing:
.PP
.Vb 5
\& $ mkdir dir
\& $ nbdfuse dir nbd://example.com &
\& $ ls \-l dir/
\& total 0
\& \-rw\-rw\-rw\-. 1 nbd nbd 1073741824 Jan  1 10:10 nbd
.Ve
.PP
The file is called \fIdir/nbd\fR 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:
.PP
.Vb 2
\& $ fusermount3 \-u dir
\& $ rmdir dir
.Ve
.SS "Use nbdkit to create a file backed by a temporary RAM disk"
.IX Subsection "Use nbdkit to create a file backed by a temporary RAM disk"
Using \f(CW\*(C`[\ ...\ ]\*(C'\fR you can run an NBD server as a subprocess.  In
this example \fBnbdkit\fR\|(1) is used to create a temporary file backed by
a RAM disk:
.PP
.Vb 9
\& $ 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
.Ve
.PP
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:
.PP
.Vb 2
\& $ fusermount3 \-u dir
\& $ rmdir dir
.Ve
.SS "Use qemu-nbd to read and modify a qcow2 file"
.IX Subsection "Use qemu-nbd to read and modify a qcow2 file"
You can use \fBqemu\-nbd\fR\|(8) as a subprocess to open any file format
which qemu understands:
.PP
.Vb 5
\& $ 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
.Ve
.PP
File \fIdir/file.raw\fR is in raw format, backed by \fIfile.qcow2\fR.  Any
changes made to \fIdir/file.raw\fR are reflected into the qcow2 file.  To
unmount the file do:
.PP
.Vb 2
\& $ fusermount3 \-u dir
\& $ rmdir dir
.Ve
.SS "Use nbdkit to create a local file from a file on a web server"
.IX Subsection "Use nbdkit to create a local file from a file on a web server"
\&\fBnbdkit\fR\|(1) is able to both access and transparently uncompress
remote disk images on web servers, so you can convert them into
virtual files:
.PP
.Vb 10
\& $ mkdir dir
\& $ nbdfuse dir/disk.iso \e
\&       [ nbdkit \-\-exit\-with\-parent \e
\&                curl \-\-filter=xz \e
\&                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 \e
\&       \-drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
\& $ fusermount3 \-u dir
.Ve
.PP
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.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-help\fR 4
.IX Item "--help"
Display brief command line help and exit.
.IP "\fB\-C\fR N" 4
.IX Item "-C N"
.PD 0
.IP "\fB\-\-connections\fR N" 4
.IX Item "--connections N"
.PD
If multi-conn is used, use N connections to the server.  The default
is 4.
.Sp
Multi-conn is enabled by default when possible.  Modes which run a
subprocess, such as \fI\-\-command\fR are not able to use multi-conn.  Mode
\&\fI\-\-fd\fR also cannot use multi-conn.  Also the server must advertise
multi-conn (use \fBnbdinfo\fR\|(1) to query what the server supports).
.Sp
See "THREAD MODEL" below.
.IP "\fB\-C 1\fR" 4
.IX Item "-C 1"
.PD 0
.IP "\fB\-\-connections 1\fR" 4
.IX Item "--connections 1"
.PD
Disable multi-conn.  Only use a single connection to the NBD server.
See "THREAD MODEL" below.
.IP \fB\-\-fuse\-help\fR 4
.IX Item "--fuse-help"
Display FUSE options and exit.  See \fI\-o\fR below.
.IP "\fB\-o\fR FUSE-OPTION" 4
.IX Item "-o FUSE-OPTION"
Pass extra options to FUSE.  To get a list of all the extra options
supported by FUSE, use \fI\-\-fuse\-help\fR.
.Sp
Some potentially useful FUSE options:
.RS 4
.IP "\fB\-o\fR \fBallow_other\fR" 4
.IX Item "-o allow_other"
Allow other users to see the filesystem.  This option has no effect
unless you enable it globally in \fI/etc/fuse.conf\fR.
.IP "\fB\-o\fR \fBkernel_cache\fR" 4
.IX Item "-o kernel_cache"
Allow the kernel to cache files (reduces the number of reads that have
to go through the \fBlibnbd\fR\|(3) API).  This is generally a good idea if
you can afford the extra memory usage.
.IP "\fB\-o\fR \fBuid=\fRN" 4
.IX Item "-o uid=N"
.PD 0
.IP "\fB\-o\fR \fBgid=\fRN" 4
.IX Item "-o gid=N"
.PD
Use these options to map UIDs and GIDs.
.RE
.RS 4
.RE
.IP "\fB\-P\fR PIDFILE" 4
.IX Item "-P PIDFILE"
.PD 0
.IP "\fB\-\-pidfile\fR PIDFILE" 4
.IX Item "--pidfile PIDFILE"
.PD
When nbdfuse is ready to serve, write the nbdfuse process ID (PID) to
\&\fIPIDFILE\fR.  This can be used in scripts to wait until nbdfuse is
ready.  Note you mustn't try to kill nbdfuse.  Use \f(CW\*(C`fusermount3 \-u\*(C'\fR
to unmount the mountpoint which will cause nbdfuse to exit cleanly.
.IP \fB\-r\fR 4
.IX Item "-r"
.PD 0
.IP \fB\-\-readonly\fR 4
.IX Item "--readonly"
.PD
Access the network block device read-only.  The virtual file will have
read-only permissions, and any writes will return errors.
.Sp
If the remote NBD server is read-only then this flag is added
automatically.  (Check \f(CW\*(C`is_read_only:\*(C'\fR field in the output of
\&\fBnbdinfo\fR\|(1)).
.IP \fB\-s\fR 4
.IX Item "-s"
Use single-threaded FUSE operations.
See "THREAD MODEL" below.
.IP \fB\-v\fR 4
.IX Item "-v"
.PD 0
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
.IP \fB\-d\fR 4
.IX Item "-d"
.PD
Enable verbose messages to stderr.  This enables libnbd debugging and
other messages.  The \fI\-d\fR option is an alias, used for compatibility
with other FUSE programs.
.IP \fB\-V\fR 4
.IX Item "-V"
.PD 0
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD
Display the package name and version and exit.
.SH MODES
.IX Header "MODES"
Modes are used to select the NBD server.  Possible modes are:
.IP "nbdfuse MOUNTPOINT URI" 4
.IX Item "nbdfuse MOUNTPOINT URI"
This mode uses an NBD URI (see \fBnbd_connect_uri\fR\|(3) and
https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).
For example this specifies a TLS-encrypted connection to
\&\f(CW\*(C`example.com\*(C'\fR port \f(CW10809\fR, with export name \f(CW\*(C`disk\*(C'\fR:
.Sp
.Vb 1
\& nbdfuse dir nbds://example.com/disk
.Ve
.IP "nbdfuse MOUNTPOINT \fB[\fR CMD [ARGS ...] \fB]\fR" 4
.IX Item "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
\&\fBnbd_connect_systemd_socket_activation\fR\|(3).
.IP "nbdfuse MOUNTPOINT \fB\-\-command\fR CMD [ARGS ...]" 4
.IX Item "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
\&\f(CW\*(C`nbdkit \-s\*(C'\fR.  See \fBnbd_connect_command\fR\|(3).
.IP "nbdfuse MOUNTPOINT \fB\-\-fd\fR N" 4
.IX Item "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 \fBnbd_connect_socket\fR\|(3).
.IP "nbdfuse MOUNTPOINT \fB\-\-tcp\fR HOST PORT" 4
.IX Item "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 \fBnbd_connect_tcp\fR\|(3).
.IP "nbdfuse MOUNTPOINT \fB\-\-unix\fR SOCKET" 4
.IX Item "nbdfuse MOUNTPOINT --unix SOCKET"
Select Unix mode.  Connect to an NBD server on a Unix domain socket.
See also \fBnbd_connect_unix\fR\|(3).
.IP "nbdfuse MOUNTPOINT \fB\-\-vsock\fR CID PORT" 4
.IX Item "nbdfuse MOUNTPOINT --vsock CID PORT"
Select vsock mode.  Connect to an NBD server on a \f(CW\*(C`AF_VSOCK\*(C'\fR socket.
See also \fBnbd_connect_vsock\fR\|(3).
.SH "THREAD MODEL"
.IX Header "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.
.PP
nbdfuse is always multithreaded.
.PP
nbdfuse will try to open multiple network connections to the NBD
server if possible (called "multi-conn").  This usually improves
performance.  Some things which \fIdisable\fR multi-conn are:
.IP \(bu 4
using \f(CW\*(C`[ CMD ... ]\*(C'\fR or \fI\-\-command\fR or \fI\-\-fd\fR modes
.IP \(bu 4
using \fI\-C 1\fR
.IP \(bu 4
the NBD server does not advertise multi-conn
(check using \fBnbdinfo\fR\|(1))
.PP
You can control how many connections are made using the \fI\-C\fR flag.
.PP
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 \fIfuse.ko\fR
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.
.PP
Using the \fI\-s\fR flag causes FUSE the only run a single thread, but
there may still be multiple operation threads.
.SH NOTES
.IX Header "NOTES"
.SS "Loop mounting"
.IX Subsection "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 \fBnbd\-client\fR\|(8) or \fBqemu\-nbd\fR\|(8), or more securely
\&\fBlibguestfs\fR\|(3), \fBguestfish\fR\|(1) or \fBguestmount\fR\|(1) which can all
access NBD servers.
.SS "As a way to access NBD servers"
.IX Subsection "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 \fBlibnbd\fR\|(3) directly instead.  To
access NBD servers from the command line, look at \fBnbdsh\fR\|(1).  To
copy to and from an NBD server use \fBnbdcopy\fR\|(1).
.SH "COMPARISON TO OTHER TOOLS"
.IX Header "COMPARISON TO OTHER TOOLS"
.ie n .SS "Compared to ""nbd\-client"""
.el .SS "Compared to \f(CWnbd\-client\fP"
.IX Subsection "Compared to nbd-client"
This program is similar in concept to \fBnbd\-client\fR\|(8) (which turns
NBD into \fI/dev/nbdX\fR device nodes), except:
.IP \(bu 4
nbd-client is faster because it uses a special kernel module
.IP \(bu 4
nbd-client requires root, but nbdfuse can be used by any user
.IP \(bu 4
nbdfuse virtual files can be mounted anywhere in the filesystem
.IP \(bu 4
nbdfuse uses libnbd to talk to the NBD server
.IP \(bu 4
nbdfuse requires FUSE support in the kernel
.ie n .SS "Compared to ""qemu\-nbd"""
.el .SS "Compared to \f(CWqemu\-nbd\fP"
.IX Subsection "Compared to qemu-nbd"
\&\fBqemu\-nbd\fR\|(8) can also attach itself to \fI/dev/nbdX\fR device nodes.
The differences from nbdfuse are similar to the list above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBlibnbd\fR\|(3),
\&\fBnbdcopy\fR\|(1),
\&\fBnbddump\fR\|(1),
\&\fBnbdinfo\fR\|(1),
\&\fBnbdsh\fR\|(1),
\&\fBnbdublk\fR\|(1),
\&\fBfusermount3\fR\|(1),
\&\fBmount.fuse3\fR\|(8),
\&\fBnbd_connect_uri\fR\|(3),
\&\fBnbd_connect_command\fR\|(3),
\&\fBnbd_connect_socket\fR\|(3),
\&\fBnbd_connect_systemd_socket_activation\fR\|(3),
\&\fBnbd_connect_tcp\fR\|(3),
\&\fBnbd_connect_unix\fR\|(3),
\&\fBnbd_connect_vsock\fR\|(3),
\&\fBlibguestfs\fR\|(3),
\&\fBguestfish\fR\|(1),
\&\fBguestmount\fR\|(1),
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-loop\fR\|(1),
\&\fBqemu\-nbd\fR\|(8),
\&\fBnbd\-client\fR\|(8).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "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.
.PP
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.
.PP
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