nbd_opt_starttls(3)

💅 nbd_opt_starttls(3) — the libnbd girlies' guide

okay so bestie, you're reading a page from the LIBNBD manual and today's main character is nbd_opt_starttls(3). sit down, grab a strawberry drink 🍓, and let's get into it.

✨ NAME ✨

nbd_opt_starttls — literally just ask the server to start TLS for you 🔐

🌸 SYNOPSIS 🌸

#include <libnbd.h>

int nbd_opt_starttls (
      struct nbd_handle *h
    );

🦋 DESCRIPTION 🦋

So the vibe here is: you're requesting that the server initiate a secure TLS connection, and you do that by sending "NBD_OPT_STARTTLS". Iconic. But there are receipts, okay?

• This can only be used if nbd_set_opt_mode(3) enabled option mode. No option mode, no starttls, periodt.
• furthermore, if you use nbd_set_tls(3) to request anything other than the default of "LIBNBD_TLS_DISABLE", then libnbd will have already attempted a TLS connection prior to allowing you control over option negotiation. like, it already did the thing before you got the aux cord 🎧
• This command is disabled if nbd_supports_tls(3) reports false.

Here's the tea though, and I need you to actually listen 🫶: this function is mainly useful for integration testing of corner cases in server handling. In particular, misuse of this function when coupled with a server that is not careful about resetting stateful commands such as nbd_opt_structured_reply(3) could result in a security hole (see CVE-2021-3716 against nbdkit, for example) 😭. So when security is a concern, you should instead prefer to use nbd_set_tls(3) with "LIBNBD_TLS_REQUIRE" and let libnbd negotiate TLS automatically. let the professionals handle it, bestie, no cap.

Okay so what does it actually return? This function returns true if the server replies with success, false if the server replies with an error, and fails only if the server does not reply (such as for a loss of connection, which can include when the server rejects credentials supplied during the TLS handshake). Not me getting ghosted by a socket 💀

Also important: note that the NBD protocol documents that requesting TLS after it is already enabled is a client error. most servers will gracefully fail a second request, but that does not downgrade a TLS session that has already been established, as reported by nbd_get_tls_negotiated(3). so no, you can't demote an established session with a second ask — the TLS stays slaying 👑

🌈 RETURN VALUE 🌈

This call returns a boolean value. true-ish or false-ish, that's the whole menu 💖

💀 ERRORS 💀

On error -1 is returned.

Refer to "ERROR HANDLING" in libnbd(3) for how to get further details of the error.

The following parameters must not be NULL: "h". For more information see "Non-NULL parameters" in libnbd(3). like, pls don't hand it a null handle, that's not the move 🙈

👑 HANDLE STATE 👑

nbd_opt_starttls can be called when the handle is in the following state — think of it as a vibe check for your handle ✨:

• Handle created, before connecting — ❌ error
• Connecting — ❌ error
• Connecting & handshaking (opt_mode) — ✅ allowed
• Connected to the server — ❌ error
• Connection shut down — ❌ error
• Handle dead — ❌ error

so basically the only window is while you're connecting and handshaking in opt_mode. timing is everything, bestie 🎀

⭐ VERSION ⭐

This function first appeared in libnbd 1.16.

If you need to test if this function is available at compile time check if the following macro is defined:

#define LIBNBD_HAVE_NBD_OPT_STARTTLS 1

🧚 SEE ALSO 🧚

• nbd_aio_opt_starttls(3)
• nbd_create(3)
• nbd_get_tls_negotiated(3)
• nbd_opt_structured_reply(3)
• nbd_set_opt_mode(3)
• nbd_set_tls(3)
• nbd_supports_tls(3)
• libnbd(3)

💜 AUTHORS 💜

Eric Blake

Richard W.M. Jones

(genuinely obsessed with them for writing this down, fr fr 🫶)

🎀 COPYRIGHT 🎀

Copyright Red Hat

📜 LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

---

and that's the whole page, bestie 💅✨ this was libnbd-1.25.8, dated 2026-10-13 — mwah, go forth and negotiate safely 🦋🌸