1nbdfuse(1)                          LIBNBD                          nbdfuse(1)
2
3
4

NAME

6       nbdfuse - present a network block device in a FUSE filesystem
7

SYNOPSIS

9        nbdfuse [-o FUSE-OPTION] [-P PIDFILE] [-r]
10                MOUNTPOINT[/FILENAME] URI
11
12       Other modes:
13
14        nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
15
16        nbdfuse MOUNTPOINT[/FILENAME] --socket-activation CMD [ARGS ...]
17
18        nbdfuse MOUNTPOINT[/FILENAME] --fd N
19
20        nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
21
22        nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
23
24        nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
25

DESCRIPTION

27       nbdfuse presents a Network Block Device as a local file inside a FUSE
28       filesystem.
29
30       The FUSE filesystem is mounted at MOUNTPOINT and contains a single
31       virtual file called FILENAME (defaulting to nbd).  Reads and writes to
32       the virtual file or device are turned into reads and writes to the NBD
33       device.
34
35       The NBD server itself can be local or remote.  The server can be
36       specified as an NBD URI (like "nbd://localhost") or in various other
37       ways (see "MODES").
38
39       Use "fusermount -u MOUNTPOINT" to unmount the filesystem after you have
40       used it.
41

EXAMPLES

43   Present a remote NBD server as a local file
44       If there is a remote NBD server running on "example.com" at the default
45       NBD port number (10809) then you can turn it into a local file by
46       doing:
47
48        $ mkdir dir
49        $ nbdfuse dir nbd://example.com &
50        $ ls -l dir/
51        total 0
52        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 nbd
53
54       The file is called dir/nbd and you can read and write to it as if it is
55       a normal file.  Note that writes to the file will write to the remote
56       NBD server.  After using it, unmount it:
57
58        $ fusermount -u dir
59        $ rmdir dir
60
61   Use nbdkit to create a file backed by a temporary RAM disk
62       nbdkit(1) has an -s option allowing it to serve over stdin/stdout.  You
63       can combine this with nbdfuse as follows:
64
65        $ mkdir dir
66        $ nbdfuse dir/ramdisk --command nbdkit -s memory 1G &
67        $ ls -l dir/
68        total 0
69        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 ramdisk
70        $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat
71        100+0 records in
72        100+0 records out
73        104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s
74
75       When you have finished with the RAM disk, you can unmount it as below
76       which will cause nbdkit to exit and the RAM disk contents to be
77       discarded:
78
79        $ fusermount -u dir
80        $ rmdir dir
81
82   Use qemu-nbd to read and modify a qcow2 file
83       qemu-nbd(8) cannot serve over stdin/stdout, but it can use systemd
84       socket activation.  You can combine this with nbdfuse and use it to
85       open any file format which qemu understands:
86
87        $ mkdir dir
88        $ nbdfuse dir/file.raw \
89                  --socket-activation qemu-nbd -f qcow2 file.qcow2 &
90        $ ls -l dir/
91        total 0
92        -rw-rw-rw-. 1 nbd nbd 1073741824 Jan  1 10:10 file.raw
93
94       File dir/file.raw is in raw format, backed by file.qcow2.  Any changes
95       made to dir/file.raw are reflected into the qcow2 file.  To unmount the
96       file do:
97
98        $ fusermount -u dir
99        $ rmdir dir
100
101   Use nbdkit to create a local file from a file on a web server
102       nbdkit(1) is able to both access and transparently uncompress remote
103       disk images on web servers, so you can convert them into virtual files:
104
105        $ mkdir dir
106        $ nbdfuse dir/disk.iso \
107              --command nbdkit -s curl --filter=xz \
108                               http://builder.libguestfs.org/fedora-30.xz &
109        $ ls -l dir/
110        total 0
111        -rw-rw-rw-. 1 nbd nbd 6442450944 Jan  1 10:10 disk.iso
112        $ file dir/disk.iso
113        dir/disk.iso: DOS/MBR boot sector
114        $ qemu-system-x86_64 -m 4G \
115              -drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
116        $ fusermount -u dir
117
118       In this example we have used the virtual file to boot qemu, but qemu
119       can much more efficiently access NBD servers directly so in the real
120       world that would be the preferred method.
121

OPTIONS

123       --help
124           Display brief command line help and exit.
125
126       --fuse-help
127           Display FUSE options and exit.  See -o below.
128
129       -o FUSE-OPTION
130           Pass extra options to FUSE.  To get a list of all the extra options
131           supported by FUSE, use --fuse-help.
132
133           Some potentially useful FUSE options:
134
135           -o allow_other
136               Allow other users to see the filesystem.  This option has no
137               effect unless you enable it globally in /etc/fuse.conf.
138
139           -o kernel_cache
140               Allow the kernel to cache files (reduces the number of reads
141               that have to go through the libnbd(3) API).  This is generally
142               a good idea if you can afford the extra memory usage.
143
144           -o uid=N
145           -o gid=N
146               Use these options to map UIDs and GIDs.
147
148       -P PIDFILE
149       --pidfile PIDFILE
150           When nbdfuse is ready to serve, write the nbdfuse process ID (PID)
151           to PIDFILE.  This can be used in scripts to wait until nbdfuse is
152           ready.  Note you mustn't try to kill nbdfuse.  Use "fusermount -u"
153           to unmount the mountpoint which will cause nbdfuse to exit cleanly.
154
155       -r
156       --readonly
157           Access the network block device read-only.  The virtual file will
158           have read-only permissions, and any writes will return errors.
159
160       -V
161       --version
162           Display the package name and version and exit.
163

MODES

165       Modes are used to select the NBD server.  The default mode uses an NBD
166       URI (see nbd_connect_uri(3) and
167       https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).  For
168       example this specifies a TLS-encrypted connection to "example.com" port
169       10809, with export name "disk":
170
171        nbdfuse dir nbds://example.com/disk
172
173       Other modes are:
174
175       --command CMD [ARGS ...]
176           Select command mode.  In this mode an NBD server can be run
177           directly from the command line with nbdfuse communicating with the
178           server over the server’s stdin/stdout.  Normally you would use this
179           with "nbdkit -s".  See "EXAMPLES" above and nbd_connect_command(3).
180
181       --fd N
182           Select file descriptor mode.  In this mode a connected socket is
183           passed to nbdfuse.  nbdfuse connects to the socket on the numbered
184           file descriptor.  See also nbd_connect_socket(3).
185
186       --socket-activation CMD [ARGS ...]
187           Select systemd socket activation mode.  This is similar to
188           --command, but is used for servers like qemu-nbd(8) which support
189           systemd socket activation.  See "EXAMPLES" above and
190           nbd_connect_systemd_socket_activation(3).
191
192       --tcp HOST PORT
193           Select TCP mode.  Connect to an NBD server on a host and port over
194           an unencrypted TCP socket.  See also nbd_connect_tcp(3).
195
196       --unix SOCKET
197           Select Unix mode.  Connect to an NBD server on a Unix domain
198           socket.  See also nbd_connect_unix(3).
199
200       --vsock CID PORT
201           Select vsock mode.  Connect to an NBD server on a "AF_VSOCK"
202           socket.  See also nbd_connect_vsock(3).
203

NOTES

205   Loop mounting
206       It is tempting (and possible) to loop mount the file.  However this
207       will be very slow and may sometimes deadlock.  Better alternatives are
208       to use nbd-client(8) or qemu-nbd(8), or more securely libguestfs(3),
209       guestfish(1) or guestmount(1) which can all access NBD servers.
210
211   As a way to access NBD servers
212       You can use this to access NBD servers, but it is usually better (and
213       definitely much faster) to use libnbd(3) directly instead.  To access
214       NBD servers from the command line, look at nbdsh(1).
215
216   Compared to "nbd-client"
217       This program is similar in concept to nbd-client(8) (which turns NBD
218       into /dev/nbdX device nodes), except:
219
220       ·   nbd-client is faster because it uses a special kernel module
221
222       ·   nbd-client requires root, but nbdfuse can be used by any user
223
224       ·   nbdfuse virtual files can be mounted anywhere in the filesystem
225
226       ·   nbdfuse uses libnbd to talk to the NBD server
227
228       ·   nbdfuse requires FUSE support in the kernel
229
230   Compared to "qemu-nbd"
231       qemu-nbd(8) can also attach itself to /dev/nbdX device nodes.  The
232       differences from nbdfuse are similar to the list above.
233

SEE ALSO

235       libnbd(3), nbdsh(1), fusermount(1), mount.fuse(8), nbd_connect_uri(3),
236       nbd_connect_command(3), nbd_connect_socket(3),
237       nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
238       nbd_connect_unix(3), nbd_connect_vsock(3), libguestfs(3), guestfish(1),
239       guestmount(1), nbdkit(1), nbdkit-loop(1), qemu-nbd(8), nbd-client(8).
240

AUTHORS

242       Richard W.M. Jones
243
245       Copyright (C) 2019 Red Hat Inc.
246

LICENSE

248       This library is free software; you can redistribute it and/or modify it
249       under the terms of the GNU Lesser General Public License as published
250       by the Free Software Foundation; either version 2 of the License, or
251       (at your option) any later version.
252
253       This library is distributed in the hope that it will be useful, but
254       WITHOUT ANY WARRANTY; without even the implied warranty of
255       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
256       Lesser General Public License for more details.
257
258       You should have received a copy of the GNU Lesser General Public
259       License along with this library; if not, write to the Free Software
260       Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
261       02110-1301 USA
262
263
264
265libnbd-1.2.1                      2019-11-14                        nbdfuse(1)
Impressum