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 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 Use "fusermount -u MOUNTPOINT" to unmount the filesystem after you have
40 used it.
41
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 $ 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 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 $ fusermount -u dir
59 $ rmdir dir
60 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 $ 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 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 $ fusermount -u dir
80 $ rmdir dir
81 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 $ 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 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 $ fusermount -u dir
99 $ rmdir dir
100 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 $ 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 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
123 --help
124 Display brief command line help and exit.
125 --fuse-help
127 Display FUSE options and exit. See -o below.
128 -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 Some potentially useful FUSE options:
134 -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 -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 -o uid=N
145 -o gid=N
146 Use these options to map UIDs and GIDs.
147 -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 -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 -V
161 --version
162 Display the package name and version and exit.
163
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 nbdfuse dir nbds://example.com/disk
172 Other modes are:
174 --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 --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 --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 --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 --unix SOCKET
197 Select Unix mode. Connect to an NBD server on a Unix domain
198 socket. See also nbd_connect_unix(3).
199 --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
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 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 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 · nbd-client is faster because it uses a special kernel module
221 · nbd-client requires root, but nbdfuse can be used by any user
223 · nbdfuse virtual files can be mounted anywhere in the filesystem
225 · nbdfuse uses libnbd to talk to the NBD server
227 · nbdfuse requires FUSE support in the kernel
229 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
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
242 Richard W.M. Jones
243
245 Copyright (C) 2019 Red Hat Inc.
246
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 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 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
262libnbd-1.2.1 2019-11-14 nbdfuse(1)