.\" Automatically generated by Podwrapper::Man 1.2.3 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "2020-05-04" "libnbd-1.2.3" "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 \- present a network block device in a FUSE filesystem
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& nbdfuse [\-o FUSE\-OPTION] [\-P PIDFILE] [\-r]
\&         MOUNTPOINT[/FILENAME] URI
.Ve
.PP
Other modes:
.PP
.Vb 1
\& 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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
nbdfuse presents a Network Block Device as a local file inside a \s-1FUSE\s0
filesystem.
.PP
The \s-1FUSE\s0 filesystem is mounted at \fI\s-1MOUNTPOINT\s0\fR and contains a single
virtual file called \fI\s-1FILENAME\s0\fR (defaulting to \fInbd\fR).  Reads and
writes to the virtual file or device are turned into reads and writes
to the \s-1NBD\s0 device.
.PP
The \s-1NBD\s0 server itself can be local or remote.  The server can be
specified as an \s-1NBD URI\s0 (like \f(CW\*(C`nbd://localhost\*(C'\fR) or in various other
ways (see \*(L"\s-1MODES\*(R"\s0).
.PP
Use \f(CW\*(C`fusermount \-u MOUNTPOINT\*(C'\fR to unmount the filesystem after you
have used it.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Present a remote \s-1NBD\s0 server as a local file"
.IX Subsection "Present a remote NBD server as a local file"
If there is a remote \s-1NBD\s0 server running on \f(CW\*(C`example.com\*(C'\fR at the
default \s-1NBD\s0 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 \s-1NBD\s0 server.  After using it, unmount it:
.PP
.Vb 2
\& $ fusermount \-u dir
\& $ rmdir dir
.Ve
.SS "Use nbdkit to create a file backed by a temporary \s-1RAM\s0 disk"
.IX Subsection "Use nbdkit to create a file backed by a temporary RAM disk"
\&\fBnbdkit\fR\|(1) has an \fI\-s\fR option allowing it to serve over
stdin/stdout.  You can combine this with nbdfuse as follows:
.PP
.Vb 9
\& $ 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
.Ve
.PP
When you have finished with the \s-1RAM\s0 disk, you can unmount it as below
which will cause nbdkit to exit and the \s-1RAM\s0 disk contents to be
discarded:
.PP
.Vb 2
\& $ fusermount \-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"
\&\fBqemu\-nbd\fR\|(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:
.PP
.Vb 6
\& $ mkdir dir
\& $ nbdfuse dir/file.raw \e
\&           \-\-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
.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
\& $ fusermount \-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 12
\& $ mkdir dir
\& $ nbdfuse dir/disk.iso \e
\&       \-\-command nbdkit \-s 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
\& $ fusermount \-u dir
.Ve
.PP
In this example we have used the virtual file to boot qemu, but qemu
can much more efficiently access \s-1NBD\s0 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\-\-fuse\-help\fR" 4
.IX Item "--fuse-help"
Display \s-1FUSE\s0 options and exit.  See \fI\-o\fR below.
.IP "\fB\-o\fR FUSE-OPTION" 4
.IX Item "-o FUSE-OPTION"
Pass extra options to \s-1FUSE.\s0  To get a list of all the extra options
supported by \s-1FUSE,\s0 use \fI\-\-fuse\-help\fR.
.Sp
Some potentially useful \s-1FUSE\s0 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) \s-1API\s0).  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 \s-1PIDFILE\s0" 4
.IX Item "-P PIDFILE"
.PD 0
.IP "\fB\-\-pidfile\fR \s-1PIDFILE\s0" 4
.IX Item "--pidfile PIDFILE"
.PD
When nbdfuse is ready to serve, write the nbdfuse process \s-1ID\s0 (\s-1PID\s0) to
\&\fI\s-1PIDFILE\s0\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`fusermount \-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.
.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 \s-1NBD\s0 server.  The default mode uses an \s-1NBD
URI\s0 (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:
.PP
.Vb 1
\& nbdfuse dir nbds://example.com/disk
.Ve
.PP
Other modes are:
.IP "\fB\-\-command\fR \s-1CMD\s0 [\s-1ARGS ...\s0]" 4
.IX Item "--command CMD [ARGS ...]"
Select command mode.  In this mode an \s-1NBD\s0 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 \*(L"\s-1EXAMPLES\*(R"\s0 above and \fBnbd_connect_command\fR\|(3).
.IP "\fB\-\-fd\fR N" 4
.IX Item "--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 "\fB\-\-socket\-activation\fR \s-1CMD\s0 [\s-1ARGS ...\s0]" 4
.IX Item "--socket-activation CMD [ARGS ...]"
Select systemd socket activation mode.  This is similar to
\&\fI\-\-command\fR, but is used for servers like \fBqemu\-nbd\fR\|(8) which
support systemd socket activation.  See \*(L"\s-1EXAMPLES\*(R"\s0 above and
\&\fBnbd_connect_systemd_socket_activation\fR\|(3).
.IP "\fB\-\-tcp\fR \s-1HOST PORT\s0" 4
.IX Item "--tcp HOST PORT"
Select \s-1TCP\s0 mode.  Connect to an \s-1NBD\s0 server on a host and port over an
unencrypted \s-1TCP\s0 socket.  See also \fBnbd_connect_tcp\fR\|(3).
.IP "\fB\-\-unix\fR \s-1SOCKET\s0" 4
.IX Item "--unix SOCKET"
Select Unix mode.  Connect to an \s-1NBD\s0 server on a Unix domain socket.
See also \fBnbd_connect_unix\fR\|(3).
.IP "\fB\-\-vsock\fR \s-1CID PORT\s0" 4
.IX Item "--vsock CID PORT"
Select vsock mode.  Connect to an \s-1NBD\s0 server on a \f(CW\*(C`AF_VSOCK\*(C'\fR socket.
See also \fBnbd_connect_vsock\fR\|(3).
.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 \s-1NBD\s0 servers.
.SS "As a way to access \s-1NBD\s0 servers"
.IX Subsection "As a way to access NBD servers"
You can use this to access \s-1NBD\s0 servers, but it is usually better (and
definitely much faster) to use \fBlibnbd\fR\|(3) directly instead.  To
access \s-1NBD\s0 servers from the command line, look at \fBnbdsh\fR\|(1).
.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
\&\s-1NBD\s0 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 \s-1NBD\s0 server
.IP "\(bu" 4
nbdfuse requires \s-1FUSE\s0 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),
\&\fBnbdsh\fR\|(1),
\&\fBfusermount\fR\|(1),
\&\fBmount.fuse\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 (C) 2019 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or
modify it under the terms of the \s-1GNU\s0 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 \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0
Lesser General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA 02110\-1301 USA\s0