1nbdfuse(1) LIBNBD nbdfuse(1)
2
6 nbdfuse - present a network block device in a FUSE filesystem
7
9 nbdfuse [-o FUSE-OPTION] [-P PIDFILE] [-r]
10 MOUNTPOINT[/FILENAME] URI
11 Other modes:
13 nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
15 nbdfuse MOUNTPOINT[/FILENAME] --socket-activation CMD [ARGS ...]
17 nbdfuse MOUNTPOINT[/FILENAME] --fd N
19 nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
21 nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
23 nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
25
27 nbdfuse presents a Network Block Device as a local file inside a FUSE
28 filesystem.
29 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 In nbdfuse ≥ 1.6 you can also create a "naked" mountpoint by mounting
36 over any regular file called MOUNTPOINT (the existing contents of the
37 file do not matter).
38 The NBD server itself can be local or remote. The server can be
40 specified as an NBD URI (like "nbd://localhost") or in various other
41 ways (see "MODES").
42 Use "fusermount -u MOUNTPOINT" to unmount the filesystem after you have
44 used it.
45
47 Present a remote NBD server as a local file
48 If there is a remote NBD server running on "example.com" at the default
49 NBD port number (10809) then you can turn it into a local file by
50 doing:
51 $ mkdir dir
53 $ nbdfuse dir nbd://example.com &
54 $ ls -l dir/
55 total 0
56 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 nbd
57 The file is called dir/nbd and you can read and write to it as if it is
59 a normal file. Note that writes to the file will write to the remote
60 NBD server. After using it, unmount it:
61 $ fusermount -u dir
63 $ rmdir dir
64 Use nbdkit to create a file backed by a temporary RAM disk
66 nbdkit(1) has an -s option allowing it to serve over stdin/stdout. You
67 can combine this with nbdfuse as follows:
68 $ mkdir dir
70 $ nbdfuse dir/ramdisk --command nbdkit -s memory 1G &
71 $ ls -l dir/
72 total 0
73 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 ramdisk
74 $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat
75 100+0 records in
76 100+0 records out
77 104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s
78 When you have finished with the RAM disk, you can unmount it as below
80 which will cause nbdkit to exit and the RAM disk contents to be
81 discarded:
82 $ fusermount -u dir
84 $ rmdir dir
85 Use qemu-nbd to read and modify a qcow2 file
87 qemu-nbd(8) cannot serve over stdin/stdout, but it can use systemd
88 socket activation. You can combine this with nbdfuse and use it to
89 open any file format which qemu understands:
90 $ mkdir dir
92 $ nbdfuse dir/file.raw \
93 --socket-activation qemu-nbd -f qcow2 file.qcow2 &
94 $ ls -l dir/
95 total 0
96 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 file.raw
97 File dir/file.raw is in raw format, backed by file.qcow2. Any changes
99 made to dir/file.raw are reflected into the qcow2 file. To unmount the
100 file do:
101 $ fusermount -u dir
103 $ rmdir dir
104 Use nbdkit to create a local file from a file on a web server
106 nbdkit(1) is able to both access and transparently uncompress remote
107 disk images on web servers, so you can convert them into virtual files:
108 $ mkdir dir
110 $ nbdfuse dir/disk.iso \
111 --command nbdkit -s curl --filter=xz \
112 http://builder.libguestfs.org/fedora-30.xz &
113 $ ls -l dir/
114 total 0
115 -rw-rw-rw-. 1 nbd nbd 6442450944 Jan 1 10:10 disk.iso
116 $ file dir/disk.iso
117 dir/disk.iso: DOS/MBR boot sector
118 $ qemu-system-x86_64 -m 4G \
119 -drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
120 $ fusermount -u dir
121 In this example we have used the virtual file to boot qemu, but qemu
123 can much more efficiently access NBD servers directly so in the real
124 world that would be the preferred method.
125
127 --help
128 Display brief command line help and exit.
129 --fuse-help
131 Display FUSE options and exit. See -o below.
132 -o FUSE-OPTION
134 Pass extra options to FUSE. To get a list of all the extra options
135 supported by FUSE, use --fuse-help.
136 Some potentially useful FUSE options:
138 -o allow_other
140 Allow other users to see the filesystem. This option has no
141 effect unless you enable it globally in /etc/fuse.conf.
142 -o kernel_cache
144 Allow the kernel to cache files (reduces the number of reads
145 that have to go through the libnbd(3) API). This is generally
146 a good idea if you can afford the extra memory usage.
147 -o uid=N
149 -o gid=N
150 Use these options to map UIDs and GIDs.
151 -P PIDFILE
153 --pidfile PIDFILE
154 When nbdfuse is ready to serve, write the nbdfuse process ID (PID)
155 to PIDFILE. This can be used in scripts to wait until nbdfuse is
156 ready. Note you mustn't try to kill nbdfuse. Use "fusermount -u"
157 to unmount the mountpoint which will cause nbdfuse to exit cleanly.
158 -r
160 --readonly
161 Access the network block device read-only. The virtual file will
162 have read-only permissions, and any writes will return errors.
163 -V
165 --version
166 Display the package name and version and exit.
167
169 Modes are used to select the NBD server. The default mode uses an NBD
170 URI (see nbd_connect_uri(3) and
171 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md). For
172 example this specifies a TLS-encrypted connection to "example.com" port
173 10809, with export name "disk":
174 nbdfuse dir nbds://example.com/disk
176 Other modes are:
178 --command CMD [ARGS ...]
180 Select command mode. In this mode an NBD server can be run
181 directly from the command line with nbdfuse communicating with the
182 server over the server’s stdin/stdout. Normally you would use this
183 with "nbdkit -s". See "EXAMPLES" above and nbd_connect_command(3).
184 --fd N
186 Select file descriptor mode. In this mode a connected socket is
187 passed to nbdfuse. nbdfuse connects to the socket on the numbered
188 file descriptor. See also nbd_connect_socket(3).
189 --socket-activation CMD [ARGS ...]
191 Select systemd socket activation mode. This is similar to
192 --command, but is used for servers like qemu-nbd(8) which support
193 systemd socket activation. See "EXAMPLES" above and
194 nbd_connect_systemd_socket_activation(3).
195 --tcp HOST PORT
197 Select TCP mode. Connect to an NBD server on a host and port over
198 an unencrypted TCP socket. See also nbd_connect_tcp(3).
199 --unix SOCKET
201 Select Unix mode. Connect to an NBD server on a Unix domain
202 socket. See also nbd_connect_unix(3).
203 --vsock CID PORT
205 Select vsock mode. Connect to an NBD server on a "AF_VSOCK"
206 socket. See also nbd_connect_vsock(3).
207
209 Loop mounting
210 It is tempting (and possible) to loop mount the file. However this
211 will be very slow and may sometimes deadlock. Better alternatives are
212 to use nbd-client(8) or qemu-nbd(8), or more securely libguestfs(3),
213 guestfish(1) or guestmount(1) which can all access NBD servers.
214 As a way to access NBD servers
216 You can use this to access NBD servers, but it is usually better (and
217 definitely much faster) to use libnbd(3) directly instead. To access
218 NBD servers from the command line, look at nbdsh(1). To copy to and
219 from an NBD server use nbdcopy(1).
220 Compared to "nbd-client"
222 This program is similar in concept to nbd-client(8) (which turns NBD
223 into /dev/nbdX device nodes), except:
224 · nbd-client is faster because it uses a special kernel module
226 · nbd-client requires root, but nbdfuse can be used by any user
228 · nbdfuse virtual files can be mounted anywhere in the filesystem
230 · nbdfuse uses libnbd to talk to the NBD server
232 · nbdfuse requires FUSE support in the kernel
234 Compared to "qemu-nbd"
236 qemu-nbd(8) can also attach itself to /dev/nbdX device nodes. The
237 differences from nbdfuse are similar to the list above.
238
240 libnbd(3), nbdcopy(1), nbdinfo(1), nbdsh(1), fusermount(1),
241 mount.fuse(8), nbd_connect_uri(3), nbd_connect_command(3),
242 nbd_connect_socket(3), nbd_connect_systemd_socket_activation(3),
243 nbd_connect_tcp(3), nbd_connect_unix(3), nbd_connect_vsock(3),
244 libguestfs(3), guestfish(1), guestmount(1), nbdkit(1), nbdkit-loop(1),
245 qemu-nbd(8), nbd-client(8).
246
248 Richard W.M. Jones
249
251 Copyright (C) 2019 Red Hat Inc.
252
254 This library is free software; you can redistribute it and/or modify it
255 under the terms of the GNU Lesser General Public License as published
256 by the Free Software Foundation; either version 2 of the License, or
257 (at your option) any later version.
258 This library is distributed in the hope that it will be useful, but
260 WITHOUT ANY WARRANTY; without even the implied warranty of
261 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
262 Lesser General Public License for more details.
263 You should have received a copy of the GNU Lesser General Public
265 License along with this library; if not, write to the Free Software
266 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
267 02110-1301 USA
268libnbd-1.6.2 2021-03-02 nbdfuse(1)