ISCSI(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 ISCSI(4) — the iSCSI initiator, but make it make sense 💖

Hey bestie, welcome to the iscsi man page, which is literally your guide to the FreeBSD iSCSI initiator. So iscsi — yeah, that's the thing speaking iSCSI, no cap. It's a kernel interface manual, and this page lowkey explains the kernel side of the whole initiator setup. Anyway, the vibe check for this page comes from the Debian manual, dated May 28, 2017 — we'll get to the cute sign-off at the end, promise. 🫶

✨ NAME ✨

iscsi — iSCSI initiator. That's the whole name, and it's iconic.

🎀 SYNOPSIS 🎀

Okay so if you wanna compile this driver into the kernel (main character energy, very permanent), you put this line in the kernel configuration file:

device iscsi

Alternatively — and honestly, slay — you can load the driver as a module at boot time. For that, put this line in loader.conf(5):

iscsi_load="YES"

🦋 DESCRIPTION 🦋

So here's the tea: the iscsi subsystem provides the kernel component of an iSCSI initiator, and it's responsible for implementing the Full Feature Phase of the iSCSI protocol. No shortcuts, bestie, full feature phase only. 💅

The initiator is the iSCSI client. It connects to an iSCSI target, and that connection gives you local access to a remote block device. Basically you're using a disk that's not physically in your box, iykyk.

The userland component is provided by iscsid(8) — that's the other half of the operation. And both the kernel side and the userland side are configured using iscsictl(8). So iscsictl(8) is your one-stop shop for config. 🌈

🌸 SYSCTL VARIABLES 🌸

The following variables are available as both sysctl(8) variables and loader(8) tunables. So yes, you can set them at runtime, you can set them at boot, whatever fits your vibe. ✨

  • kern.iscsi.debug — Verbosity level for log messages from the iscsi driver. Set it to 0 to disable logging, or 1 to warn about potential problems. Larger values enable debugging output. Defaults to 1. So if you're like "why is my log silent," check this first. 🕵️‍♀️
  • kern.iscsi.ping_timeout — The number of seconds to wait for the target to respond to a NOP-Out PDU. If there's no response within that time, the session gets forcibly restarted. Set to 0 to disable sending NOP-Out PDUs. Defaults to 5. So it's a patience meter for your target, basically. ⏳
  • kern.iscsi.iscsid_timeout — The number of seconds to wait for iscsid(8) to establish a session. After that time, iscsi will abort and retry. Defaults to 60. That's a whole minute of waiting, bestie, don't leave it hanging. 😭
  • kern.iscsi.login_timeout — The number of seconds to wait for a login attempt to succeed. After that time, iscsi will abort and retry. Defaults to 60. Again, a full minute. Consistent queen. 👑
  • kern.iscsi.maxtags — The maximum number of outstanding IO requests. Defaults to 255. So that's how many requests can be in flight at once. Don't exceed the limit, fr fr. 🔥
  • kern.iscsi.fail_on_disconnection — Controls the behavior after an iSCSI connection has been dropped due to network problems. When set to 1, a dropped connection causes the iSCSI device nodes to be destroyed. After reconnecting, they will be created again. By default, the device nodes are left intact. While the connection is down, all input/output operations are suspended, to be retried after the connection is reestablished. So basically: either they get destroyed and come back, or they stay and the IO just holds its breath until the network stops being flaky. Either way, no data loss, just vibes. 🫧
Real talk: if the network drops, don't panic — the default behavior keeps the device nodes alive, and all your IO is just paused, waiting to be retried. That's a slay safety net. 💅

👑 SEE ALSO 👑

Go read those too, bestie, they complete the picture. 🦋

⭐ HISTORY ⭐

The iscsi subsystem first appeared in FreeBSD 10.0. So it's been around, it's not new-new, but it's still iconic. 🔥

🌈 AUTHORS 🌈

The iscsi subsystem was developed by Edward Tomasz Napierala <trasz@FreeBSD.org> under sponsorship from the FreeBSD Foundation. Respect the author, no cap. 💖

Cute sign-off: this was the Debian manual page for ISCSI(4), dated May 28, 2017 — and now you know the whole vibe. Go forth and configure your iSCSI, bestie, you're literally the main character. 🎀✨💅
📦 where this page comes from