1libnbd(3) LIBNBD libnbd(3)
2
6 libnbd - network block device (NBD) client library in userspace
7
9 #include <libnbd.h>
10 struct nbd_handle *nbd;
12 char buf[512];
13 if ((nbd = nbd_create ()) == NULL ||
15 nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1 ||
16 nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1)
17 fprintf (stderr, "%s\n", nbd_get_error ());
18 nbd_close (nbd);
19 exit (EXIT_FAILURE);
20 }
21 nbd_close (nbd);
22 cc prog.c -o prog -lnbd
24 or:
25 cc prog.c -o prog `pkg-config libnbd --cflags --libs`
26
28 Network Block Device (NBD) is a network protocol for accessing block
29 devices over the network. Block devices are hard disks and things that
30 behave like hard disks such as disk images and virtual machines.
31 Libnbd is a client library for the NBD protocol which can access most
33 of the features of NBD while being simple to use and powerful.
34 This manual page gives an overview of libnbd, using C as an example,
36 but the library is available from other programming languages.
37 nbd_create(3), nbd_pread(3), etc.
39 Each manual page covers one function from the C API in detail.
40 There is a full list in section "C API" below.
41 libnbd-ocaml(3)
43 Using the API from OCaml.
44 libnbd-golang(3)
46 Using the API from Go.
47 nbdsh(1)
49 Using the NBD shell (nbdsh) for command line and Python scripting.
50
52 To use the API at all you must first open a handle by calling
53 nbd_create(3) (or its equivalent in other languages):
54 struct nbd_handle *nbd;
56 nbd = nbd_create ();
58 This creates and returns a handle, which is associated with one
60 connection to an NBD server, initially not connected.
61 Each handle is a complex state machine which can be in states such as
63 created, connected to a remote server, handshaking, idle and ready to
64 issue commands, or busy sending or receiving commands.
65 There are two levels of API available. A simple high level synchronous
67 API lets you give the handle high level instructions like “connect to
68 the server”, “read a block”, “write a block”, etc. Each of these
69 functions will run to completion, blocking the current thread before
70 returning. A more complicated low level non-blocking asynchronous API
71 is also available where you can integrate with poll(2) or another main
72 loop.
73 You can freely mix the two APIs on the same handle. You can also call
75 APIs on a single handle from multiple threads. Single API calls on the
76 handle are atomic — they either take a lock on the handle while they
77 run or are careful to access handle fields atomically.
78 Libnbd does not create its own threads.
80
82 This is the simplest way to use the API, with the possible drawback
83 that each libnbd function blocks until it is finished.
84 Create a handle and connect to the server:
86 struct nbd_handle *nbd;
88 nbd = nbd_create ();
90 if (!nbd) {
91 fprintf (stderr, "%s\n", nbd_get_error ());
92 nbd_close (nbd);
93 exit (EXIT_FAILURE);
94 }
95 if (nbd_connect_tcp (nbd, "server.example.com", "nbd") == -1) {
96 fprintf (stderr, "%s\n", nbd_get_error ());
97 nbd_close (nbd);
98 exit (EXIT_FAILURE);
99 }
100 Read the first sector (512 bytes) from the NBD export:
102 char buf[512];
104 if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
106 fprintf (stderr, "%s\n", nbd_get_error ());
107 nbd_close (nbd);
108 exit (EXIT_FAILURE);
109 }
110 Close the handle:
112 nbd_close (nbd);
114 You can call the high level API from multiple threads, but each libnbd
116 API call takes a lock on the handle and so commands will not run in
117 parallel.
118
120 The low level API is useful if you want to use libnbd in non-blocking
121 code; or if you want to issue commands in parallel from multiple
122 threads; or if you need more control especially over having multiple
123 commands in-flight on a single connection.
124 To use the low level API you will need to integrate with poll(2) or
126 another “main loop” such as the GLib main event loop.
127 Issuing asynchronous commands
129 Use the "nbd_aio_*" variants to issue commands asynchronously (without
130 waiting for the command to complete before returning). For example the
131 asynchronous variant of nbd_pread(3) is:
132 int64_t cookie;
134 cookie = nbd_aio_pread (nbd, buf, sizeof buf,
136 NBD_NULL_COMPLETION, 0);
137 if (cookie == -1) {
138 fprintf (stderr, "%s\n", nbd_get_error ());
139 nbd_close (nbd);
140 exit (EXIT_FAILURE);
141 }
142 There are several things to note here:
144 · This only starts the command. The command is still in flight when
146 the call returns.
147 · A buffer ("buf") has been assigned to collect the result of the
149 read, but it is not guaranteed to be filled with data until the
150 command has completed (see examples below). The buffer must not be
151 freed until the command has finished running.
152 · You can issue multiple commands on the same handle at the same
154 time.
155 · A cookie is returned which identifies this command in subsequent
157 calls. The cookie is unique (per libnbd handle) and ≥ 1.
158 · You may register a function which is called when the command
160 completes, see "Completion callbacks" below. In this case we have
161 specified a null completion callback.
162 Socket and direction
164 Each libnbd handle has an associated socket (once it has started
165 connecting). You can read the file descriptor of the socket using:
166 int fd = nbd_aio_get_fd (nbd);
168 The socket is non-blocking. Between calls into libnbd it is in the
170 "would block" condition. You can find out if libnbd is expecting to
171 read or write from the socket next by calling:
172 int dir = nbd_aio_get_direction (nbd);
174 which returns one of "LIBNBD_AIO_DIRECTION_READ",
176 "LIBNBD_AIO_DIRECTION_WRITE" or "LIBNBD_AIO_DIRECTION_BOTH" (=
177 "READ|WRITE"). And so to set up the next call to poll(2) or other main
178 loop you must translate this to "POLLIN", "POLLOUT" or "POLLIN|POLLOUT"
179 (or whatever mechanism your main loop uses).
180 Notifying libnbd when an event happens
182 When you detect (eg. using poll(2)) that a read or write event has
183 happened on the socket, you must then tell libnbd about it. You have
184 to check the direction again (since it may have been changed by another
185 thread), and notify libnbd:
186 int r = 0;
188 dir = nbd_aio_get_direction (nbd);
190 if ((dir & LIBNBD_AIO_DIRECTION_READ) &&
192 a_read_event_occurred ())
193 r = nbd_aio_notify_read (nbd);
194 else if ((dir & LIBNBD_AIO_DIRECTION_WRITE) &&
195 a_write_event_occurred ())
196 r = nbd_aio_notify_write (nbd);
197 if (r == -1) {
199 fprintf (stderr, "%s\n", nbd_get_error ());
200 // ...
201 }
202 The notify calls move the state machine along, reading and writing from
204 the socket possibly multiple times, until the socket would block again,
205 at which point they return control to the caller.
206 Simple implementation with nbd_poll(3)
208 In fact if you want to use poll(2) on a single handle, a simple
209 implementation has already been written called nbd_poll(3). It is also
210 useful to examine how this is implemented (lib/poll.c in the libnbd
211 source code) because that will tell you how to integrate libnbd with
212 more complex main loops.
213 Some examples of using nbd_poll(3) follow.
215 As with the high level API, it all starts by creating a handle:
217 struct nbd_handle *nbd;
219 nbd = nbd_create ();
221 if (nbd == NULL) {
222 fprintf (stderr, "%s\n", nbd_get_error ());
223 nbd_close (nbd);
224 exit (EXIT_FAILURE);
225 }
226 To connect to the server asynchronously, we start the connection using
228 nbd_aio_connect(3) and then enter our main loop to check for events
229 until the connection becomes ready:
230 int fd;
232 struct sockaddr_un addr;
233 socklen_t len;
234 /* some code to set up addr,
236 then ... */
237 if (nbd_aio_connect (nbd, &addr, len) == -1) {
238 fprintf (stderr, "%s\n", nbd_get_error ());
239 nbd_close (nbd);
240 exit (EXIT_FAILURE);
241 }
242 while (! nbd_aio_is_ready (nbd)) {
243 if (nbd_poll (nbd, -1) == -1) {
244 fprintf (stderr, "%s\n", nbd_get_error ());
245 nbd_close (nbd);
246 exit (EXIT_FAILURE);
247 }
248 }
249 To read data asynchronously, start an asynchronous read command, which
251 returns a 64 bit command cookie, and enter the main loop until the
252 command has completed:
253 int64_t cookie;
255 char buf[512];
256 cookie = nbd_aio_pread (nbd, buf, sizeof buf, offset,
258 NBD_NULL_COMPLETION, 0);
259 if (cookie == -1) {
260 fprintf (stderr, "%s\n", nbd_get_error ());
261 nbd_close (nbd);
262 exit (EXIT_FAILURE);
263 }
264 while (! nbd_aio_command_completed (nbd, cookie)) {
265 if (nbd_poll (nbd, -1) == -1) {
266 fprintf (stderr, "%s\n", nbd_get_error ());
267 nbd_close (nbd);
268 exit (EXIT_FAILURE);
269 }
270 }
271 For almost all high level synchronous calls (eg. nbd_pread(3)) there is
273 a low level asynchronous equivalent (eg. nbd_aio_pread(3)) for starting
274 a command.
275 glib2 integration
277 See
278 https://github.com/libguestfs/libnbd/blob/master/examples/glib-main-loop.c
279
281 When any API call returns an error ("-1" or "NULL" depending on the
282 API), an error message and sometimes an errno value are available. You
283 can retrieve the error message and/or errno of the most recently failed
284 call using nbd_get_error(3) and nbd_get_errno(3). For example:
285 if (nbd_connect_tcp (nbd, "remote", "nbd") == -1) {
287 fprintf (stderr,
288 "failed to connect to remote server: %s (errno = %d)\n",
289 nbd_get_error (), nbd_get_errno ());
290 }
291 These functions use thread-local storage to return the most recent
293 error in the current thread. This is why you don't need to pass the
294 handle to these calls. They even work if nbd_create(3) returns "NULL"
295 when there is no handle at all.
296 For this reason you cannot call them from a different thread. You
298 should call them immediately after the failed API call, from the same
299 thread. Furthermore the error string returned by nbd_get_error(3) is
300 only valid until the next libnbd API call in the current thread, so if
301 you need to keep the string you must copy it (eg. using strdup(3)).
302 Errno
304 For some errors, a system call error number (see errno(3)) is
305 available. You can find the error number by calling nbd_get_errno(3).
306 It works the same way as nbd_get_error(3) with respect to threads.
307 Even when a call returns an error, nbd_get_errno(3) might return 0.
309 This does not mean there was no error. It means no additional errno
310 information is available for this error.
311 The error number is often the raw error returned by a system call that
313 failed.
314 It can also be used to indicate special conditions. The most common
316 cases are:
317 "EINVAL"
319 Invalid parameters or state for the current libnbd call.
320 "ENOTSUP"
322 The libnbd call is not available in this build of libnbd (eg. when
323 using a TLS API if the library was compiled without TLS support).
324 "ENOMEM"
326 The library ran out of memory while performing some operation.
327 "ERANGE"
329 A request is too large, for example if you try to read too many
330 bytes in a single nbd_pread(3) call.
331
333 Libnbd can print lots of debugging messages, useful if you have a
334 problem with the library. Either enable debugging after creating the
335 handle:
336 nbd = nbd_create ();
338 nbd_set_debug (nbd, true);
339 or set the "LIBNBD_DEBUG=1" environment variable which will enable
341 debugging by default on all new handles.
342 Debugging messages are sent to stderr by default, but you can redirect
344 them to a logging system using nbd_set_debug_callback(3).
345
347 There are several ways to connect to NBD servers, and you can even run
348 a server from libnbd. Normally you would connect to a server which is
349 already running, over a local Unix domain socket or a remote TCP
350 connection. The high level API calls are:
351 nbd_connect_unix (nbd, "socket");
353 nbd_connect_tcp (nbd, "localhost", "nbd");
354 For nbd_connect_tcp(3) the third parameter is the port name or number,
356 which can either be a name from /etc/services or the port number as a
357 string (eg. "10809").
358 Connecting to an NBD URI
360 libnbd supports the NBD URI specification. The format of URIs is
361 documented in nbd_connect_uri(3).
362 You can connect to a URI as in these examples (using the high level
364 API):
365 nbd_connect_uri (nbd, "nbd://example.com/");
367 nbd_connect_uri (nbd, "nbds+unix:///export?socket=/tmp/nbd.sock");
369 This feature is implemented by calling other libnbd APIs to set up the
371 export name, TLS parameters, and finally connect over a Unix domain
372 socket or TCP.
373 URI support is an optional feature of the library, requiring libxml2 at
375 compile time. The nbd_connect_uri(3) and nbd_aio_connect_uri(3) calls
376 will raise an error (with nbd_get_errno(3) returning "ENOTSUP") if it
377 was not built with this feature, and you can also test for it
378 explicitly using nbd_supports_uri(3).
379 Connecting to a subprocess
381 Some NBD servers — notably nbdkit(1) with the -s parameter, and
382 nbd-server(1) with the port parameter set to 0 — can also accept a
383 single NBD connection on stdin/stdout. You can run these servers as a
384 subprocess of your main program using nbd_connect_command(3). This
385 example creates a 1G writable RAM disk:
386 char *argv[] = { "nbdkit", "-s", "--exit-with-parent",
388 "memory", "1G", NULL };
389 nbd_connect_command (nbd, argv);
390 When the handle is closed the nbdkit subprocess is killed, which in
392 this case means the RAM disk is discarded, so this is useful for
393 testing.
394 Connecting to a subprocess using systemd socket activation
396 Some NBD servers — notably nbdkit(1) and qemu-nbd(1) — support systemd
397 socket activation allowing libnbd to pass a socket to the subprocess.
398 This works very similarly to nbd_connect_command(3) described above,
399 but you must use nbd_connect_systemd_socket_activation(3) instead.
400
402 By default, when beginning a connection, libnbd will handle all
403 negotiation with the server, using only the configuration (eg.
404 nbd_set_export_name(3) or nbd_add_meta_context(3)) that was requested
405 before the connection attempt; this phase continues until
406 nbd_aio_is_connecting(3) no longer returns true, at which point, either
407 data commands are ready to use or else the connection has failed with
408 an error.
409 But there are scenarios in which it is useful to also control the
411 handshaking commands sent during negotiation, such as asking the server
412 for a list of available exports prior to selecting which one to use.
413 This is done by calling nbd_set_opt_mode(3) before connecting; then
414 after requesting a connection, the state machine will pause at
415 nbd_aio_is_negotiating(3) at any point that the user can decide which
416 handshake command to send next. Note that the negotiation state is
417 only reachable from newstyle servers; older servers cannot negotiate
418 and will progress all the way to the ready state.
419 When the negotiating state is reached, you can initiate option commands
421 such as nbd_opt_list(3) or their asynchronous equivalents, as well as
422 alter configuration such as export name that previously had to be set
423 before connection. Since the NBD protocol does not allow parallel
424 negotiating commands, no cookie is involved, and you can track
425 completion of each command when the state is no longer
426 nbd_aio_is_connecting(3). If nbd_opt_go(3) fails but the connection is
427 still live, you will be back in negotiation state, where you can
428 request a different export name and try again. Exiting the negotiation
429 state is only possible with a successful nbd_opt_go(3) which moves to
430 the data phase, or nbd_opt_abort(3) which performs a clean shutdown of
431 the connection by skipping the data phase.
432
434 It is possible for NBD servers to serve different content on different
435 “exports”. For this you must pass the right export name to the server.
436 Call this API before connecting:
437 nbd_set_export_name (nbd, "export");
439 Note that there are some servers (like nbdkit(1) ≤ 1.14) which ignore
441 this, and other servers (like qemu-nbd(8)) which require it to be set
442 correctly but cannot serve different content.
443 These APIs are also available after a successful nbd_opt_info(3) during
445 the negotiation phase, if you used nbd_set_opt_mode(3) prior to
446 connecting.
447 Flag calls
449 After connecting the server will send back a set of flags describing
450 the export, such as whether it is writable and if it can support flush
451 to permanent storage. These flags can be accessed from libnbd using
452 APIs such as:
453 int is_read_only = nbd_is_read_only (nbd);
455 int can_flush = nbd_can_flush (nbd);
456 Flag calls are: nbd_can_cache(3), nbd_can_df(3), nbd_can_fast_zero(3),
458 nbd_can_flush(3), nbd_can_fua(3), nbd_can_meta_context(3),
459 nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
460 nbd_is_read_only(3), nbd_is_rotational(3).
461 Size of the export
463 To get the size of the export in bytes, use nbd_get_size(3):
464 int64_t size = nbd_get_size (nbd);
466
468 You can read and write data from the NBD server using nbd_pread(3) and
469 nbd_pwrite(3) or their asynchronous equivalents.
470 All data commands support a "flags" argument (mandatory in C, but
472 optional in languages where it can default to 0). For convenience, the
473 constant "LIBNBD_CMD_FLAG_MASK" is defined with the set of flags
474 currently recognized by libnbd, where future NBD protocol extensions
475 may result in additional flags being supported; but in general,
476 specific data commands only accept a subset of known flags.
477 Libnbd defaults to performing some client-side sanity checking in each
479 of its data commands; for example, attempts to write to a server that
480 has advertised a read-only connection are rejected. It is possible to
481 override aspects of this checking by using nbd_set_strict_mode(3).
482 Some servers also support:
484 trim/discard
486 If nbd_can_trim(3) returns true, nbd_trim(3) can be used to “punch
487 holes” in the backing storage of the disk on the server. Normally
488 (although not in every case) the holes read back as zeroes but take
489 up no space.
490 zeroing
492 If nbd_can_zero(3) returns true, nbd_zero(3) can be used to
493 efficiently zero parts of the disk without having to send large
494 amounts of zero bytes over the network (as would be necessary if
495 using nbd_pwrite(3)).
496 This is slightly different from trimming because the backing
498 storage is still allocated. For some storage types this can make
499 future writes more efficient and/or less likely to fail because of
500 out of space errors.
501 flushing
503 Some servers can commit data to permanent storage and tell you that
504 this has happened reliably. There are two export flags associated
505 with this: nbd_can_flush(3) and nbd_can_fua(3).
506 The nbd_flush(3) call (available if nbd_can_flush(3) returns true)
508 flushes all pending writes to disk and does not complete until that
509 operation has finished. It is similar to using sync(2) on POSIX
510 systems.
511 A more efficient way to achieve this is to set the flag
513 "LIBNBD_CMD_FLAG_FUA" on write-like calls (like write, trim and
514 zero). This flag means the call will not complete until committed
515 to permanent storage, but it does not involve flushing the entire
516 disk.
517 prefetching
519 Some servers can prefetch data, making subsequent reads faster.
520 The nbd_cache(3) call (available if nbd_can_cache(3) returns true)
521 is used to prefetch.
522 block status
524 Some servers are able to provide information about the various
525 extents within the image, via the notion of one or more meta
526 contexts. The most common meta context is "base:allocation"
527 (available in libnbd.h as "LIBNBD_CONTEXT_BASE_ALLOCATION"), which
528 can be used to learn which portions of a file are allocated or read
529 as zero. Other contexts may be available; for example, qemu-nbd(8)
530 can expose a meta context "qemu:dirty-bitmap:NAME" for tracking
531 which portions of a file are tracked by a qcow2 dirty bitmap.
532 In order to utilize block status, the client must call
534 nbd_add_meta_context(3) prior to connecting, for each meta context
535 in which it is interested, then check nbd_can_meta_context(3) after
536 connection to see which contexts the server actually supports. If
537 a context is supported, the client can then use nbd_block_status(3)
538 with a callback function that will receive an array of 32-bit
539 integer pairs describing consecutive extents within a context. In
540 each pair, the first integer is the length of the extent, the
541 second is a bitmask description of that extent (for the
542 "base:allocation" context, the bitmask may include
543 "LIBNBD_STATE_HOLE" for unallocated portions of the file, and/or
544 "LIBNBD_STATE_ZERO" for portions of the file known to read as
545 zero).
546 There is a full example of requesting meta context and using block
548 status available at
549 https://github.com/libguestfs/libnbd/blob/master/interop/dirty-bitmap.c
550
552 Issuing multiple in-flight requests
553 NBD servers which properly implement the specification can handle
554 multiple data requests in flight over the same connection at the same
555 time. Libnbd supports this when using the low level API.
556 To use it you simply issue more requests as needed (eg. using calls
558 like nbd_aio_pread(3), nbd_aio_pwrite(3)) without waiting for previous
559 commands to complete. You need to be careful that requests in flight
560 do not overlap with disk offsets of other write-like commands in flight
561 — an overlapping read may see indeterminate data, and an overlapping
562 write may even cause disk corruption where the resulting disk contents
563 do not match either of the two writes.
564 Each request is identified by a unique 64 bit cookie (assigned by
566 libnbd), allowing libnbd and callers to match replies to requests.
567 Replies may arrive out of order. A request that is rejected client-
568 side for failing a sanity check (such as attempting to write to a read-
569 only server, see nbd_set_strict_mode(3)) will fail rather than
570 returning a cookie, although closure cleanup is still performed.
571 Although in theory you can have an indefinite number of requests in
573 flight at the same time, in practice it's a good idea to limit them to
574 some number. Libnbd will queue commands in the handle even if it
575 cannot write them to the server, so this limit is largely to prevent a
576 backlog of commands from consuming too much memory. It is suggested to
577 start with a limit of 64 requests in flight (per NBD connection), and
578 measure how adjusting the limit up and down affects performance for
579 your local configuration.
580 There is a full example using multiple in-flight requests available at
582 https://github.com/libguestfs/libnbd/blob/master/examples/threaded-reads-and-writes.c
583 Multi-conn
585 Some NBD servers advertise “multi-conn” which means that it is safe to
586 make multiple connections to the server and load-balance commands
587 across all of the connections.
588 To do this you should open a single connection first and test for this
590 feature using nbd_can_multi_conn(3). Without error handling it would
591 look like this:
592 struct nbd_handle *nbd[4];
594 size_t i;
595 bool supports_multi_conn;
596 nbd[0] = nbd_create ();
598 nbd_connect_tcp (nbd[0], "server", "10809");
599 supports_multi_conn = nbd_can_multi_conn (nbd[0]) > 0;
600 If multi-conn is supported then you can open further connections:
602 if (supports_multi_conn) {
604 for (i = 1; i <= 3; ++i) {
605 nbd[i] = nbd_create ();
606 nbd_connect_tcp (nbd[i], "server", "10809");
607 }
608 }
609 If you are issuing multiple in-flight requests (see above) and limiting
611 the number, then the limit should be applied to each individual NBD
612 connection.
613
615 The NBD protocol and libnbd supports TLS (sometimes incorrectly called
616 “SSL”) for encryption of the data stream and authentication of clients
617 and servers. Libnbd defaults to TLS disabled for maximum
618 interoperability. To enable it on a handle you must call
619 nbd_set_tls(3) before connecting.
620 To allow TLS, but fall back to unencrypted:
622 nbd_set_tls (nbd, LIBNBD_TLS_ALLOW);
624 Use nbd_get_tls_negotiated(3) to find out if TLS negotiation was
626 successful. Avoid "LIBNBD_TLS_ALLOW" if man-in-the-middle attacks are
627 a concern.
628 The most secure mode is to require TLS and fail to connect if the
630 server does not support it:
631 nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE);
633 It may also be necessary to verify that the server’s identity is
635 correct. For some servers it may be necessary to verify to the server
636 that the client is permitted to connect. This can be done using either
637 X.509 certificates, or TLS Pre-Shared Keys (PSK). Certificates are
638 more secure. PSK is far more convenient, but you must have an existing
639 secure channel to distribute the keys.
640 Setting up X.509 using system certificate authorities (CAs)
642 This is the default if you don’t call any other "nbd_set_tls_*"
643 functions. In this case the server must have a public (eg. HTTPS)
644 certificate which can be verified against the CAs registered on your
645 system (eg. under /etc/pki).
646 To disable server name verification — which opens you up to a potential
648 Man-In-The-Middle (MITM) attack — use:
649 nbd_set_tls_verify_peer (nbd, false);
651 Setting up an X.509 certificate authority (CA)
653 You can set up your own CA and register clients and servers with it,
654 issuing client and server certificates which will reliably authenticate
655 your clients and servers to each other.
656 Doing this is described in detail in the nbdkit-tls(1) manual. The
658 only differences for libnbd are:
659 · Non-root certificates must be placed in "$HOME/.pki/libnbd/" or
661 "$HOME/.config/pki/libnbd/"
662 · Libnbd reads client-cert.pem and client-key.pem (instead of
664 server-cert.pem and server-key.pem).
665 Once you have set up the directory containing the certificates, call:
667 nbd_set_tls_certificates (nbd, "/path/to/directory");
669 Setting up Pre-Shared Keys (PSK)
671 TLS Pre-Shared Keys are a much more convenient method of setting up
672 TLS, and more appropriate for NBD, but you should have an existing
673 secure method available to distribute the keys. They are therefore
674 ideal if you want to set up an NBD service as an adjunct to an existing
675 secure REST API.
676 Use psktool(1) to create a file of "username:key" pairs:
678 psktool -u username -p keys.psk
680 and pass this path to libnbd:
682 nbd_set_tls_psk_file (nbd, "keys.psk");
684 If necessary you may need to set the client username (otherwise libnbd
686 will use your login name):
687 nbd_set_tls_username (nbd, "username");
689
691 Some libnbd calls take callbacks (eg. nbd_set_debug_callback(3),
692 nbd_aio_pread(3)). Libnbd can call these functions while processing.
693 In the C API these libnbd calls take a structure which contains the
695 function pointer and an optional opaque "void *user_data" pointer:
696 nbd_aio_pread (nbd, buf, sizeof buf, offset,
698 (nbd_completion_callback) { .callback = my_fn,
699 .user_data = my_data },
700 0);
701 For optional callbacks, if you don't want the callback, either set
703 ".callback" to "NULL" or use the equivalent macros (such as
704 "NBD_NULL_COMPLETION") defined in "libnbd.h":
705 nbd_aio_pread (nbd, buf, sizeof buf, offset,
707 NBD_NULL_COMPLETION, 0);
708 From other languages the structure and opaque pointer are not needed
710 because you can use closures to achieve the same effect.
711 Callback lifetimes
713 You can associate an optional free function with callbacks. Libnbd
714 will call this function when the callback will not be called again by
715 libnbd, including in the case where the API fails.
716 This can be used to free associated "user_data". For example:
718 void *my_data = malloc (...);
720 nbd_aio_pread_structured (nbd, buf, sizeof buf, offset,
722 (nbd_chunk_callback) { .callback = my_fn,
723 .user_data = my_data,
724 .free = free },
725 NBD_NULL_CALLBACK(completion),
726 0);
727 will call free(3) on "my_data" after the last time that the
729 "chunk.callback = my_fn" function is called.
730 The free function is only accessible in the C API as it is not needed
732 in garbage collected programming languages.
733 Callbacks with ".callback=NULL" and ".free!=NULL"
735 It is possible to register a callback like this:
736 ...
738 (nbd_completion_callback) { .callback = NULL,
739 .user_data = my_data,
740 .free = free },
741 ...
742 The meaning of this is that the callback is never called, but the free
744 function is still called after the last time the callback would have
745 been called. This is useful for applying generic freeing actions when
746 asynchronous commands are retired.
747 Callbacks and locking
749 The callbacks are invoked at a point where the libnbd lock is held; as
750 such, it is unsafe for the callback to call any "nbd_*" APIs on the
751 same nbd object, as it would cause deadlock.
752 Completion callbacks
754 All of the low-level commands have a completion callback variant that
755 registers a callback function used right before the command is marked
756 complete.
757 When the completion callback returns 1, the command is automatically
759 retired (there is no need to call nbd_aio_command_completed(3)); for
760 any other return value, the command still needs to be retired.
761 Callbacks with "int *error" parameter
763 Some of the high-level commands (nbd_pread_structured(3),
764 nbd_block_status(3)) involve the use of a callback function invoked by
765 the state machine at appropriate points in the server's reply before
766 the overall command is complete. These callback functions, along with
767 all of the completion callbacks, include a parameter "error" containing
768 the value of any error detected so far; if the callback function fails,
769 it should assign back into "error" and return "-1" to change the
770 resulting error of the overall command. Assignments into "error" are
771 ignored for any other return value; similarly, assigning 0 into "error"
772 does not have an effect.
773
775 On most systems, C programs that use libnbd can be compiled like this:
776 cc prog.c -o prog -lnbd
778 To detect if the libnbd library and header file is installed, the
780 preferred method is to use pkg-config(1) or pkgconf(1):
781 pkg-config libnbd --exists || fail libnbd is required
783 In case the library or header file are not installed in the usual
785 system locations, you can compile your program like this, using pkg-
786 config to detect the proper location of libnbd:
787 cc prog.c -o prog `pkg-config libnbd --cflags --libs`
789 To compile an external project against a built copy of the libnbd
791 source tree which hasn't been installed, see the ./run script.
792 Autoconf projects
794 External projects which use autoconf and need to check if libnbd is
795 installed should use the "PKG_CHECK_MODULES" macro in configure.ac like
796 this:
797 PKG_CHECK_MODULES([LIBNBD], [libnbd])
799 This will define "@LIBNBD_CFLAGS@" and "@LIBNBD_LIBS@" which you will
801 need to add to your Makefile.am.
802 CMake projects
804 For CMake projects use:
805 find_package(PkgConfig REQUIRED)
807 pkg_check_modules(LIBNBD REQUIRED libnbd)
808 target_link_libraries(prog ${LIBNBD_LIBRARIES})
809 target_include_directories(prog PUBLIC ${LIBNBD_INCLUDE_DIRS})
810 target_compile_options(prog PUBLIC ${LIBNBD_CFLAGS_OTHER})
811 Meson projects
813 For meson projects use:
814 nbd_dep = dependency('libnbd')
816 executable('prog', 'prog.c', dependencies : [nbd_dep])
817
819 "HOME"
820 Used in some situations to find TLS certificates. See
821 nbd_set_tls_certificates(3).
822 "LIBNBD_DEBUG"
824 If this is set to the exact string 1 when the handle is created
825 then debugging is enabled. See "DEBUGGING MESSAGES" above.
826 "LOGNAME"
828 The default TLS username. See nbd_set_tls_username(3).
829
831 C API
832 nbd_add_meta_context(3), nbd_aio_block_status(3), nbd_aio_cache(3),
833 nbd_aio_command_completed(3), nbd_aio_connect(3),
834 nbd_aio_connect_command(3), nbd_aio_connect_socket(3),
835 nbd_aio_connect_systemd_socket_activation(3), nbd_aio_connect_tcp(3),
836 nbd_aio_connect_unix(3), nbd_aio_connect_uri(3),
837 nbd_aio_connect_vsock(3), nbd_aio_disconnect(3), nbd_aio_flush(3),
838 nbd_aio_get_direction(3), nbd_aio_get_fd(3), nbd_aio_in_flight(3),
839 nbd_aio_is_closed(3), nbd_aio_is_connecting(3), nbd_aio_is_created(3),
840 nbd_aio_is_dead(3), nbd_aio_is_negotiating(3),
841 nbd_aio_is_processing(3), nbd_aio_is_ready(3), nbd_aio_notify_read(3),
842 nbd_aio_notify_write(3), nbd_aio_opt_abort(3), nbd_aio_opt_go(3),
843 nbd_aio_opt_info(3), nbd_aio_opt_list(3),
844 nbd_aio_opt_list_meta_context(3), nbd_aio_peek_command_completed(3),
845 nbd_aio_pread(3), nbd_aio_pread_structured(3), nbd_aio_pwrite(3),
846 nbd_aio_trim(3), nbd_aio_zero(3), nbd_block_status(3), nbd_cache(3),
847 nbd_can_cache(3), nbd_can_df(3), nbd_can_fast_zero(3),
848 nbd_can_flush(3), nbd_can_fua(3), nbd_can_meta_context(3),
849 nbd_can_multi_conn(3), nbd_can_trim(3), nbd_can_zero(3),
850 nbd_clear_debug_callback(3), nbd_clear_meta_contexts(3), nbd_close(3),
851 nbd_connect_command(3), nbd_connect_socket(3),
852 nbd_connect_systemd_socket_activation(3), nbd_connect_tcp(3),
853 nbd_connect_unix(3), nbd_connect_uri(3), nbd_connect_vsock(3),
854 nbd_connection_state(3), nbd_create(3), nbd_flush(3),
855 nbd_get_block_size(3), nbd_get_canonical_export_name(3),
856 nbd_get_debug(3), nbd_get_errno(3), nbd_get_error(3),
857 nbd_get_export_description(3), nbd_get_export_name(3),
858 nbd_get_full_info(3), nbd_get_handle_name(3),
859 nbd_get_handshake_flags(3), nbd_get_meta_context(3),
860 nbd_get_nr_meta_contexts(3), nbd_get_opt_mode(3),
861 nbd_get_package_name(3), nbd_get_protocol(3),
862 nbd_get_request_structured_replies(3), nbd_get_size(3),
863 nbd_get_strict_mode(3), nbd_get_structured_replies_negotiated(3),
864 nbd_get_tls(3), nbd_get_tls_negotiated(3), nbd_get_tls_username(3),
865 nbd_get_tls_verify_peer(3), nbd_get_version(3), nbd_is_read_only(3),
866 nbd_is_rotational(3), nbd_kill_subprocess(3), nbd_opt_abort(3),
867 nbd_opt_go(3), nbd_opt_info(3), nbd_opt_list(3),
868 nbd_opt_list_meta_context(3), nbd_poll(3), nbd_pread(3),
869 nbd_pread_structured(3), nbd_pwrite(3), nbd_set_debug(3),
870 nbd_set_debug_callback(3), nbd_set_export_name(3),
871 nbd_set_full_info(3), nbd_set_handle_name(3),
872 nbd_set_handshake_flags(3), nbd_set_opt_mode(3),
873 nbd_set_request_structured_replies(3), nbd_set_strict_mode(3),
874 nbd_set_tls(3), nbd_set_tls_certificates(3), nbd_set_tls_psk_file(3),
875 nbd_set_tls_username(3), nbd_set_tls_verify_peer(3),
876 nbd_set_uri_allow_local_file(3), nbd_set_uri_allow_tls(3),
877 nbd_set_uri_allow_transports(3), nbd_shutdown(3), nbd_supports_tls(3),
878 nbd_supports_uri(3), nbd_trim(3), nbd_zero(3).
879 Servers
881 nbdkit(1), nbd-server(1), qemu-nbd(8).
882 Encryption tools
884 certtool(1), nbdkit-tls(1), psktool(1).
885 Standards
887 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/proto.md,
888 https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md.
889 Other
891 libnbd-release-notes-1.6(1), libnbd-release-notes-1.4(1),
892 libnbd-release-notes-1.2(1), libnbd-security(3), nbdcopy(1),
893 nbdfuse(1), nbdinfo(1), nbdsh(1), qemu(1).
894
896 Eric Blake
897 Richard W.M. Jones
899
901 Copyright (C) 2019-2020 Red Hat Inc.
902
904 This library is free software; you can redistribute it and/or modify it
905 under the terms of the GNU Lesser General Public License as published
906 by the Free Software Foundation; either version 2 of the License, or
907 (at your option) any later version.
908 This library is distributed in the hope that it will be useful, but
910 WITHOUT ANY WARRANTY; without even the implied warranty of
911 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
912 Lesser General Public License for more details.
913 You should have received a copy of the GNU Lesser General Public
915 License along with this library; if not, write to the Free Software
916 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
917 02110-1301 USA
918libnbd-1.6.2 2021-03-02 libnbd(3)