STAFCTL(1)

📦
version 2.4.1 · 8 versions
, in ubuntu resolute, ubuntu stonking

✨ stafctl(1) — the STorage Appliance Finder (STAF) utility program ✨

okay bestie, pull up a chair, because this is stafctl(1) and she's about to become your new favorite little utility 💅

🎀 SYNOPSIS 🎀

stafctl [OPTIONS...] {COMMAND} [OPTIONS...]

like... options, then a command, then more options. she's flexible like that 🫶

💖 DESCRIPTION 💖

stafctl is a tool that can be used to communicate with the stafd(8) daemon to retrieve operational data.

that's it. that's the whole vibe. you talk, stafd answers, you get the data. the way that this is literally just two programs gossiping. iconic. 💬

🦋 COMMANDS 🦋

The following commands are understood:

  • tron — Trace ON. Enable code tracing, which is to say that lots of debug information will be printed to the syslog (e.g. systemd-journal). not me turning on the firehose 🔥
  • troff — Trace OFF. Disable code tracing. the peace and quiet returns 🌸
  • status — Show runtime status information. the "how u doing" command fr fr
  • ls — Show the list of discovery controllers. This will list all the controllers configured in stafd.conf(5) as well as those discovered with mDNS service discovery. two sources, one list, no cap 🧚
  • dlp — Show discovery log pages. the receipts, but only some of them
  • adlp — Show all discovery log pages. the receipts, ALL of them, periodt 👑

💅 OPTIONS 💅

The following options are understood:

  • -h, --help — Print the help text and exit. she's helpful, she's quick, she leaves ✨
  • --version — Print the version string and exit. main character energy, tiny runtime
  • -d, --detailed — Print additional details. more lore, more context
  • -tTRTYPE, --transport=TRTYPE — NVMe-over-Fabrics fabric type (default: "tcp"). if you don't say anything she's assuming tcp, okay?
  • -aTRADDR, --traddr=TRADDR — Discovery controller's network address. where we're going 📍
  • -sTRSVCID, --trsvcid=TRSVCID — Transport service id (for IP addressing, e.g. tcp, rdma, this field is the port number). lowkey it's just the port when you're doing IP
  • -wTRADDR, --host-traddr=TRADDR — Network source address used on the host to connect to the controller. this is YOUR address, bestie, not theirs 🏠
  • -fIFACE, --host-iface=IFACE — This field specifies the network interface used on the host to connect to the controller. pick your lane (literally, pick the NIC) 🛣️
  • -nNQN, --nqn=NQN — This field specifies the Controller's NVMe Qualified Name.
okay important one: This field is mandatory for I/O Controllers, but is optional for Discovery Controllers (DC). For the latter, the NQN will default to the well-known DC NQN: nqn.2014-08.org.nvmexpress.discovery if left undefined. the way that it just fills itself in... obsessed 😭

🌈 VALUES 🌈

  • TRTYPE — rdma, fc, tcp, loop. four choices, pick one 💫
  • TRADDR — IP or Fibre Channel address. E.g. 10.10.0.100.
  • TRSVCID — E.g., 8009.
  • IFACE — Network interface name. E.g., eth1, enp0s8, wlp0s20f3.
  • NQN — NVMe Qualified Name.

🔥 EXIT STATUS 🔥

On success, 0 is returned; otherwise, a non-zero failure code is returned.

zero is the good ending, anything else means something went sideways 🙈

🌸 EXAMPLES 🌸

Example 1. List all the discovery controllers

$ stafctl ls
[{'device':      'nvme0',
  'host-iface':  '',
  'host-traddr': '',
  'subsysnqn':   'nqn.2014-08.org.nvmexpress.discovery',
  'traddr':      '::1',
  'transport':   'tcp',
  'trsvcid':     '8009'}]

Example 2. Enable tracing

$ stafctl tron

Example 3. Show discovery log pages from a specific discovery controller

$ stafctl dlp --transport tcp --traddr ::1 --trsvcid 8009
[{'adrfam':  'ipv6',
  'asqsz':   '32',
  'cntlid':  '65535',
  'portid':  '1',
  'subnqn':  'nqn.1988-11.com.dell:PowerSANxxx:01:20210225100113-454f73093ceb4847a7bdfc6e34ae8e28',
  'subtype': 'nvme',
  'traddr':  '::1',
  'treq':    'disable sqflow',
  'trsvcid': '8009',
  'trtype':  'tcp'},
 {'adrfam':  'ipv6',
  'asqsz':   '32',
  'cntlid':  '65535',
  'portid':  '1',
  'subnqn':  'nqn.1988-11.com.dell:PowerSANxxx:01:20210225100113-454f73093ceb4847a7bdfc6e34aedead',
  'subtype': 'nvme',
  'traddr':  '::1',
  'treq':    'disable sqflow',
  'trsvcid': '8009',
  'trtype':  'tcp'},
 {'adrfam':  'ipv6',
  'asqsz':   '32',
  'cntlid':  '65535',
  'portid':  '1',
  'subnqn':  'nqn.1988-11.com.dell:PowerSANxxx:01:20210225100113-454f73093ceb4847a7bdfc6e34aebeef',
  'subtype': 'nvme',
  'traddr':  '::1',
  'treq':    'disable sqflow',
  'trsvcid': '8009',
  'trtype':  'tcp'}]

look at those three nearly-identical subnqn entries... the way that they differ by like four characters at the end. the attention to detail. the drama. 💀

🫶 SEE ALSO 🫶

stafd.conf(5), stafd(8) ()

(yes bestie the parentheses at the end are just empty. we don't know either. we're leaving it exactly as we found it, respectfully 🙈)

and that's the whole page!! go forth and talk to your storage appliances, you absolute legend 👑✨

this was nvme-stas version 2.4.1, from the STAFCTL(1) manual — mwah, no notes, bye bestie 💖🦋

📦 where this page comes from