1nbdfuse(1) LIBNBD nbdfuse(1)
2
6 nbdfuse - mount a network block device in the local filesystem
7
9 nbdfuse [-C N|--connections N] [-d] [-o FUSE-OPTION] [-P PIDFILE]
10 [-r] [-s] [-v|--verbose]
11 MOUNTPOINT[/FILENAME] URI
12 nbdfuse MOUNTPOINT[/FILENAME] [ CMD [ARGS ...] ]
14 nbdfuse MOUNTPOINT[/FILENAME] --command CMD [ARGS ...]
16 nbdfuse MOUNTPOINT[/FILENAME] --fd N
18 nbdfuse MOUNTPOINT[/FILENAME] --tcp HOST PORT
20 nbdfuse MOUNTPOINT[/FILENAME] --unix SOCKET
22 nbdfuse MOUNTPOINT[/FILENAME] --vsock CID PORT
24 To unmount:
26 fusermount3 -u MOUNTPOINT
28 Other options:
30 nbdfuse --help
32 nbdfuse --fuse-help
34 nbdfuse -V|--version
36
38 nbdfuse is used to mount a Network Block Device (NBD) in the local
39 filesystem. The NBD virtual file is mounted at MOUNTPOINT/FILENAME
40 (defaulting to MOUNTPOINT/nbd). Reads and writes to the virtual file
41 are turned into reads and writes to the NBD device.
42 In nbdfuse ≥ 1.6 you can also create a "naked" mountpoint by mounting
44 over any regular file called MOUNTPOINT (the existing contents of the
45 file do not matter).
46 The NBD server itself can be local or remote. The server can be
48 specified as an NBD URI (like "nbd://localhost"), or as an NBD server
49 running as a subprocess of nbdfuse (using "[ ... ]"), or in various
50 other ways (see "MODES").
51 Use "fusermount3 -u MOUNTPOINT" to unmount the filesystem after you
53 have used it.
54
56 Present a remote NBD server as a local file
57 If there is a remote NBD server running on "example.com" at the default
58 NBD port number (10809) then you can turn it into a local file by
59 doing:
60 $ mkdir dir
62 $ nbdfuse dir nbd://example.com &
63 $ ls -l dir/
64 total 0
65 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 nbd
66 The file is called dir/nbd and you can read and write to it as if it is
68 a normal file. Note that writes to the file will write to the remote
69 NBD server. After using it, unmount it:
70 $ fusermount3 -u dir
72 $ rmdir dir
73 Use nbdkit to create a file backed by a temporary RAM disk
75 Using "[ ... ]" you can run an NBD server as a subprocess. In this
76 example nbdkit(1) is used to create a temporary file backed by a RAM
77 disk:
78 $ mkdir dir
80 $ nbdfuse dir/ramdisk [ nbdkit --exit-with-parent memory 1G ] &
81 $ ls -l dir/
82 total 0
83 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 ramdisk
84 $ dd if=/dev/urandom bs=1M count=100 of=mp/ramdisk conv=notrunc,nocreat
85 100+0 records in
86 100+0 records out
87 104857600 bytes (105 MB, 100 MiB) copied, 2.08319 s, 50.3 MB/s
88 When you have finished with the RAM disk, you can unmount it as below
90 which will cause nbdkit to exit and the RAM disk contents to be
91 discarded:
92 $ fusermount3 -u dir
94 $ rmdir dir
95 Use qemu-nbd to read and modify a qcow2 file
97 You can use qemu-nbd(8) as a subprocess to open any file format which
98 qemu understands:
99 $ mkdir dir
101 $ nbdfuse dir/file.raw [ qemu-nbd -f qcow2 file.qcow2 ] &
102 $ ls -l dir/
103 total 0
104 -rw-rw-rw-. 1 nbd nbd 1073741824 Jan 1 10:10 file.raw
105 File dir/file.raw is in raw format, backed by file.qcow2. Any changes
107 made to dir/file.raw are reflected into the qcow2 file. To unmount the
108 file do:
109 $ fusermount3 -u dir
111 $ rmdir dir
112 Use nbdkit to create a local file from a file on a web server
114 nbdkit(1) is able to both access and transparently uncompress remote
115 disk images on web servers, so you can convert them into virtual files:
116 $ mkdir dir
118 $ nbdfuse dir/disk.iso \
119 [ nbdkit --exit-with-parent \
120 curl --filter=xz \
121 http://builder.libguestfs.org/fedora-30.xz ] &
122 $ ls -l dir/
123 total 0
124 -rw-rw-rw-. 1 nbd nbd 6442450944 Jan 1 10:10 disk.iso
125 $ file dir/disk.iso
126 dir/disk.iso: DOS/MBR boot sector
127 $ qemu-system-x86_64 -m 4G \
128 -drive file=dir/disk.iso,format=raw,if=virtio,snapshot=on
129 $ fusermount3 -u dir
130 In this example we have used the virtual file to boot qemu, but qemu
132 can much more efficiently access NBD servers directly so in the real
133 world that would be the preferred method.
134
136 --help
137 Display brief command line help and exit.
138 -C N
140 --connections N
141 If multi-conn is used, use N connections to the server. The
142 default is 4.
143 Multi-conn is enabled by default when possible. Modes which run a
145 subprocess, such as --command are not able to use multi-conn. Mode
146 --fd also cannot use multi-conn. Also the server must advertise
147 multi-conn (use nbdinfo(1) to query what the server supports).
148 See "THREAD MODEL" below.
150 -C 1
152 --connections 1
153 Disable multi-conn. Only use a single connection to the NBD
154 server. See "THREAD MODEL" below.
155 --fuse-help
157 Display FUSE options and exit. See -o below.
158 -o FUSE-OPTION
160 Pass extra options to FUSE. To get a list of all the extra options
161 supported by FUSE, use --fuse-help.
162 Some potentially useful FUSE options:
164 -o allow_other
166 Allow other users to see the filesystem. This option has no
167 effect unless you enable it globally in /etc/fuse.conf.
168 -o kernel_cache
170 Allow the kernel to cache files (reduces the number of reads
171 that have to go through the libnbd(3) API). This is generally
172 a good idea if you can afford the extra memory usage.
173 -o uid=N
175 -o gid=N
176 Use these options to map UIDs and GIDs.
177 -P PIDFILE
179 --pidfile PIDFILE
180 When nbdfuse is ready to serve, write the nbdfuse process ID (PID)
181 to PIDFILE. This can be used in scripts to wait until nbdfuse is
182 ready. Note you mustn't try to kill nbdfuse. Use "fusermount3 -u"
183 to unmount the mountpoint which will cause nbdfuse to exit cleanly.
184 -r
186 --readonly
187 Access the network block device read-only. The virtual file will
188 have read-only permissions, and any writes will return errors.
189 If the remote NBD server is read-only then this flag is added
191 automatically. (Check "is_read_only:" field in the output of
192 nbdinfo(1)).
193 -s Use single-threaded FUSE operations. See "THREAD MODEL" below.
195 -v
197 --verbose
198 -d Enable verbose messages to stderr. This enables libnbd debugging
199 and other messages. The -d option is an alias, used for
200 compatibility with other FUSE programs.
201 -V
203 --version
204 Display the package name and version and exit.
205
207 Modes are used to select the NBD server. Possible modes are:
208 nbdfuse MOUNTPOINT URI
210 This mode uses an NBD URI (see nbd_connect_uri(3) and
211 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md).
212 For example this specifies a TLS-encrypted connection to
213 "example.com" port 10809, with export name "disk":
214 nbdfuse dir nbds://example.com/disk
216 nbdfuse MOUNTPOINT [ CMD [ARGS ...] ]
218 Run an NBD server as a subprocess. In this mode an NBD server can
219 be run directly from the command line with nbdfuse communicating
220 with the server over a socket. This requires that the NBD server
221 supports systemd socket activation. See "EXAMPLES" above and
222 nbd_connect_systemd_socket_activation(3).
223 nbdfuse MOUNTPOINT --command CMD [ARGS ...]
225 Select command mode. In this mode an NBD server can be run
226 directly from the command line with nbdfuse communicating with the
227 server over the server’s stdin/stdout. Normally you would use this
228 with "nbdkit -s". See nbd_connect_command(3).
229 nbdfuse MOUNTPOINT --fd N
231 Select file descriptor mode. In this mode a connected socket is
232 passed to nbdfuse. nbdfuse connects to the socket on the numbered
233 file descriptor. See also nbd_connect_socket(3).
234 nbdfuse MOUNTPOINT --tcp HOST PORT
236 Select TCP mode. Connect to an NBD server on a host and port over
237 an unencrypted TCP socket. See also nbd_connect_tcp(3).
238 nbdfuse MOUNTPOINT --unix SOCKET
240 Select Unix mode. Connect to an NBD server on a Unix domain
241 socket. See also nbd_connect_unix(3).
242 nbdfuse MOUNTPOINT --vsock CID PORT
244 Select vsock mode. Connect to an NBD server on a "AF_VSOCK"
245 socket. See also nbd_connect_vsock(3).
246
248 This section describes how the current version of nbdfuse works.
249 Previous versions worked differently in the past, and future versions
250 may work differently in the future.
251 nbdfuse is always multithreaded.
253 nbdfuse will try to open multiple network connections to the NBD server
255 if possible (called "multi-conn"). This usually improves performance.
256 Some things which disable multi-conn are:
257 • using "[ CMD ... ]" or --command or --fd modes
259 • using -C 1
261 • the NBD server does not advertise multi-conn (check using
263 nbdinfo(1))
264 You can control how many connections are made using the -C flag.
266 nbdfuse runs one thread per connection to service NBD commands (these
268 are called "operation threads"). In addition, FUSE itself creates
269 multiple threads to deal with requests coming from the fuse.ko kernel
270 module. The number of threads that FUSE can create is described in the
271 FUSE documentation, but with many parallel accesses to the virtual file
272 there may be many more FUSE threads created than operation threads, and
273 this should lead to good performance. FUSE requests (like read, write
274 or trim) are multiplexed on to the operation threads (= connections) at
275 random. Each operation thread can handle multiple requests in
276 parallel.
277 Using the -s flag causes FUSE the only run a single thread, but there
279 may still be multiple operation threads.
280
282 Loop mounting
283 It is tempting (and possible) to loop mount the file. However this
284 will be very slow and may sometimes deadlock. Better alternatives are
285 to use nbd-client(8) or qemu-nbd(8), or more securely libguestfs(3),
286 guestfish(1) or guestmount(1) which can all access NBD servers.
287 As a way to access NBD servers
289 You can use this to access NBD servers, but it is usually better (and
290 definitely much faster) to use libnbd(3) directly instead. To access
291 NBD servers from the command line, look at nbdsh(1). To copy to and
292 from an NBD server use nbdcopy(1).
293
295 Compared to "nbd-client"
296 This program is similar in concept to nbd-client(8) (which turns NBD
297 into /dev/nbdX device nodes), except:
298 • nbd-client is faster because it uses a special kernel module
300 • nbd-client requires root, but nbdfuse can be used by any user
302 • nbdfuse virtual files can be mounted anywhere in the filesystem
304 • nbdfuse uses libnbd to talk to the NBD server
306 • nbdfuse requires FUSE support in the kernel
308 Compared to "qemu-nbd"
310 qemu-nbd(8) can also attach itself to /dev/nbdX device nodes. The
311 differences from nbdfuse are similar to the list above.
312
314 libnbd(3), nbdcopy(1), nbddump(1), nbdinfo(1), nbdsh(1),
315 fusermount3(1), mount.fuse3(8), nbd_connect_uri(3),
316 nbd_connect_command(3), nbd_connect_socket(3),
317 nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
318 nbd_connect_unix(3), nbd_connect_vsock(3), libguestfs(3), guestfish(1),
319 guestmount(1), nbdkit(1), nbdkit-loop(1), qemu-nbd(8), nbd-client(8).
320
322 Richard W.M. Jones
323
325 Copyright (C) 2019-2021 Red Hat Inc.
326
328 This library is free software; you can redistribute it and/or modify it
329 under the terms of the GNU Lesser General Public License as published
330 by the Free Software Foundation; either version 2 of the License, or
331 (at your option) any later version.
332 This library is distributed in the hope that it will be useful, but
334 WITHOUT ANY WARRANTY; without even the implied warranty of
335 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
336 Lesser General Public License for more details.
337 You should have received a copy of the GNU Lesser General Public
339 License along with this library; if not, write to the Free Software
340 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
341 02110-1301 USA
342libnbd-1.14.2 2023-01-03 nbdfuse(1)