nbd_set_tls_username(3)

📦
version 1.25.8 · 18 versions
, in centos-stream 10

💅 nbd_set_tls_username(3) — libnbd, bestie edition

okay so this is a page from the libnbd manual, section 3, and it's all about one tiny little function that sets your TLS username. it's giving "small but mighty" honestly. let's get into it 🫶

✨ NAME ✨

nbd_set_tls_username — set the TLS username. that's it, that's the whole vibe. it sets the username, for TLS. 💖

🌸 SYNOPSIS 🌸

like, here's the actual code shape of it, no cap:

#include <libnbd.h>

int nbd_set_tls_username (
      struct nbd_handle *h, const char *username
    );

two args: the handle h and your username. that's the whole signature, periodt.

🎀 DESCRIPTION 🎀

so what does it do? it sets the TLS client username. this is the username that gets used when you're authenticating with PSK over TLS. and if you don't set it? no worries bestie, it just uses the local username instead. effortless. ✨

now the important part — this function may be called regardless of whether TLS is supported. but listen: it will have no effect unless nbd_set_tls(3) is also used to request or require TLS. so like, it's not doing anything on its own, it's a team player. it needs its bestie nbd_set_tls(3) to actually show up. 💀

⭐ RETURN VALUE ⭐

if the call succeeds, the function returns 0. iconic. that's the good number. 🥳

💀 ERRORS 💀

on error, -1 is returned. that's the sad number. 😭

for how to get further details of the error, refer to "ERROR HANDLING" in libnbd(3) — that's where all the detective work happens.

also heads up, this is a real rule, not a suggestion: the following parameters must not be NULL: h, username. for more info see "Non-NULL parameters" in libnbd(3). don't try it, don't pass NULL, it's not the move. 🙈

🔥 HANDLE STATE 🔥

nbd_set_tls_username can be called when the handle is in the following state — here's your vibe check:

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

so basically: before you connect, or nothing. once you're connecting it's too late, the door is closed, sorry bestie. 🚪✨

🦋 VERSION 🦋

this function first appeared in libnbd 1.0. she's an OG, she's been here since the beginning. 👑

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

#define LIBNBD_HAVE_NBD_SET_TLS_USERNAME 1

iykyk 🧚

🌈 EXAMPLE 🌈

this example is also available as examples/encryption.c in the libnbd source code. it's a whole little program, and honestly it ate. here it is verbatim:

/* An example showing how to connect to a server which is
 * using TLS encryption.
 *
 * This requires nbdkit, and psktool from gnutls.
 *
 * Both libnbd and nbdkit support TLS-PSK which is a
 * simpler-to-deploy form of encryption.  (Of course
 * certificate-based encryption is also supported, but
 * it’s harder to make a self-contained example).
 */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>

#include <libnbd.h>

#define TMPDIR "/tmp/XXXXXX"
#define KEYS "keys.psk"
#define USERNAME "alice"

static char dir[] = TMPDIR;
static char keys[] = TMPDIR "/" KEYS;
static char cmd[] =
  "psktool -u " USERNAME " -p " TMPDIR "/" KEYS;

/* Remove the temporary keys file when the program
 * exits.
 */
static void
cleanup_keys (void)
{
  unlink (keys);
  rmdir (dir);
}

/* Create the temporary keys file to share with the
 * server.
 */
static void
create_keys (void)
{
  size_t i;

  if (mkdtemp (dir) == NULL) {
    perror ("mkdtemp");
    exit (EXIT_FAILURE);
  }
  i = strlen (cmd) - strlen (TMPDIR) - strlen (KEYS) - 1;
  memcpy (&cmd[i], dir, strlen (TMPDIR));
  memcpy (keys, dir, strlen (TMPDIR));

  if (system (cmd) != 0) {
    fprintf (stderr, "psktool command failed\n");
    exit (EXIT_FAILURE);
  }

  atexit (cleanup_keys);
}

int
main (int argc, char *argv[])
{
  struct nbd_handle *nbd;
  char buf[512];

  create_keys ();

  /* Create the libnbd handle. */
  nbd = nbd_create ();
  if (nbd == NULL) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Enable TLS in the client. */
  if (nbd_set_tls (nbd, LIBNBD_TLS_REQUIRE) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Enable TLS-PSK and pass the keys filename. */
  if (nbd_set_tls_psk_file (nbd, keys) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Set the local username for authentication. */
  if (nbd_set_tls_username (nbd, USERNAME) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Run nbdkit as a subprocess, enabling and requiring
   * TLS-PSK encryption.
   */
  char *args[] = {
    "nbdkit", "-s", "--exit-with-parent",
    "--tls", "require", "--tls-psk", keys,
    "pattern", "size=1M", NULL
  };
  if (nbd_connect_command (nbd, args) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Read the first sector. */
  if (nbd_pread (nbd, buf, sizeof buf, 0, 0) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* TLS connections must be shut down. */
  if (nbd_shutdown (nbd, 0) == -1) {
    fprintf (stderr, "%s\n", nbd_get_error ());
    exit (EXIT_FAILURE);
  }

  /* Close the libnbd handle. */
  nbd_close (nbd);

  exit (EXIT_SUCCESS);
}

notice the #define USERNAME "alice" — yes she gave herself a name and it's alice. main character energy fr fr. 👑

also real talk: /* TLS connections must be shut down. */ — that's in the original and it's a real requirement, so don't skip your nbd_shutdown. 💅

💜 SEE ALSO 💜

go read these next, they're all connected:

🌸 AUTHORS 🌸

  • Eric Blake
  • Richard W.M. Jones

giving credit where credit is due, we love them for this. 🫶

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, section 3, nbd_set_tls_username(3) — mwah, slay, go set some usernames responsibly ✨🦋🎀

📦 where this page comes from