Skip to content
FreeBSDDeep Dive Published Updated 7 min readViews unavailable

FreeBSD iSCSI Initiator Operations: Sessions, LUNs, and Recovery

Connect FreeBSD iSCSI initiators with named sessions, persistent rc configuration, device verification, controlled disconnects, and storage recovery tests.

FreeBSD’s native iSCSI initiator turns a remote target LUN into a local block device. The kernel iscsi(4) component handles the iSCSI full-feature phase and exposes the remote storage through the local device stack; iscsid(8) performs login and SendTargets discovery; iscsictl(8) adds, lists, modifies, and removes sessions. This is block storage, not a mounted filesystem. The initiator sees a raw disk device and must use an explicit storage and filesystem lifecycle above it.

Do not confuse the initiator with a target. An initiator is the client that connects to storage; CTL and ctld(8) are target-side facilities, covered by the separate HAST/CTL guide. This article focuses on one FreeBSD host consuming a LUN from an existing target and the evidence needed to operate that session safely.

Establish the target contract before connecting

Obtain the target portal address and port, exact target IQN, LUN assignment, authentication method, and expected session count from the storage owner. Confirm whether the portal name resolves to the intended address and that the host’s route uses the designated storage interface. If the target is expected to present one LUN, document its expected capacity, SCSI identity, and intended filesystem or application owner before it appears as a device.

Capture the client baseline without attaching or formatting anything:

freebsd-version -kru
netstat -rn
camcontrol devlist
geom disk list
mount -p
swapinfo -h

These commands distinguish current disks and consumers from a new iSCSI device. An iSCSI LUN can become a daN disk, but the unit number depends on discovery and attach order. Never assume that a target is /dev/da0 because a previous boot assigned that number. Identify the device using the session status, CAM inquiry information, capacity, serial or target-provided identity, and GEOM topology together.

Configure a named normal session

The initiator configuration file is /etc/iscsi.conf. A normal session requires a target address and target name. This example uses documentation address space and a placeholder IQN; replace both with values supplied by the target owner:

# /etc/iscsi.conf
archive0 {
    TargetAddress = 192.0.2.40:3260
    TargetName = iqn.2026-10.net.example:archive0
    AuthMethod = None
}

The archive0 token is a local nickname used by iscsictl; it is not the target’s identity. TargetAddress accepts a hostname or address and an optional port, defaulting to TCP 3260. TargetName must match the IQN exported by the target. AuthMethod = None is appropriate only when the target’s connection policy expects no initiator authentication. If it requires CHAP or mutual CHAP, follow iscsi.conf(5) and the target operator’s parameters; do not substitute made-up credentials or infer the method from a successful network connection.

The iscsid daemon does not read iscsi.conf itself. The file is consumed by iscsictl, which provides connection parameters to the kernel initiator. Enable and start the daemon, then add the named session:

sysrc iscsid_enable="YES"
service iscsid start
iscsictl -A -n archive0
iscsictl -L -v -w 30

Adding a session is asynchronous. A successful return from iscsictl -A is not proof that the target login completed; use iscsictl -L to inspect session state or its -w option to wait for establishment. Confirm the reported target name and portal match the approved contract, then correlate the attached daN device with camcontrol devlist and geom disk list.

Make approved sessions persistent across boot

For a host that should connect all named sessions from /etc/iscsi.conf during startup, FreeBSD’s rc.conf(5) documents iscsid_enable, iscsictl_enable, and iscsictl_flags. The default flags for iscsictl startup are -Aa, which add all configured sessions:

sysrc iscsid_enable="YES"
sysrc iscsictl_enable="YES"
sysrc iscsictl_flags="-Aa"

Review whether all file entries should connect automatically before using -Aa. A host may contain disabled or discovery profiles that are intended for operator-controlled use. Enable = Off in an entry can represent an intentionally disabled session; use iscsictl -L after boot to confirm what actually connected. Test the boot-time ordering and network readiness during a planned reboot before using the LUN for a boot-critical service.

Do not store a second, contradictory session definition in a hand-maintained startup script. Keep one authoritative configuration path and verify the effective flags with sysrc iscsid_enable iscsictl_enable iscsictl_flags. iscsid and iscsictl have separate roles: the daemon services kernel login and reconnect requests, while the control utility configures the session set.

Treat disconnect as a storage change

An iSCSI disconnect is not just closing a socket. It removes access to a remote block device that may back a mounted filesystem, swap, virtual machine disk, database, or GEOM provider. Before disconnecting, find every consumer and quiesce its writes through the owning application. Unmount filesystems cleanly, disable only the exact swap provider if applicable, stop guests, and verify GEOM no longer shows an active consumer.

Then remove only the intended session nickname and verify status:

iscsictl -L -v
iscsictl -R -n archive0
iscsictl -L -v

-R removes a session; it does not repair a filesystem or ensure that an application has flushed data. Do not use iscsictl -R -a on a production client unless the planned operation explicitly requires removal of every active iSCSI session. A forceful disconnect while I/O is outstanding can turn a network maintenance action into an application or filesystem recovery incident.

If a connection is already unavailable, inspect the mounted filesystems, device state, process I/O, application logs, and target-side sessions before restarting anything. The kernel initiator’s kern.iscsi.fail_on_disconnection policy controls whether disconnected device nodes remain while I/O waits for reconnection or are destroyed and recreated after reconnect. Read the installed release’s iscsi(4) manual before changing this behavior; applications and device discovery scripts must tolerate the selected model.

Diagnose login, discovery, and I/O symptoms separately

Target not found or no session. Confirm the portal address, TCP port, target IQN, route, target service, and any server-side initiator allow-list. SendTargets discovery is separate from logging into a known normal target; do not use a discovery nickname as if it were the final LUN identity.

Authentication failed. Compare the target’s configured method, initiator identity, and credentials with the exact client entry. The target may allow TCP connection and still reject login. Avoid putting secrets on a command line because command history and process inspection may expose them; use the configuration mechanism prescribed by the installed manuals and the site’s credential-handling policy.

Session connected but no expected disk appears. Recheck the target’s LUN mapping and the initiator’s session output, then inspect CAM and GEOM. A session can authenticate successfully while exporting no LUN or a different LUN. Do not initialize a newly visible block device until its identity and owner are confirmed.

I/O stalls during a network interruption. The initiator’s reconnect policy may suspend operations pending reconnection. This can look like an application hang rather than an immediate error. Correlate client timestamps, iscsictl -L -v, kernel messages, interface errors, path failover state, and target logs. A TCP connection report does not prove stable storage latency or durable application writes.

Throughput or tail latency degrades. Measure target and initiator interface errors, retransmissions, link rate, negotiated session behavior, storage queueing, and application latency over the same interval. Do not raise outstanding I/O, timeouts, or queue values before identifying which layer is limiting progress. A fast ping to the portal says little about storage response time under load.

Validate the complete block-device contract

On a nonproduction target and client, test initial login, expected LUN identity, controlled I/O, target restart, network loss, recovery, and clean logout. Confirm the device reappears or remains according to the selected disconnect policy, and verify the filesystem or application can recover using its documented procedure. Never use a production data LUN as a disposable newfs test target.

For a production change, record the session nickname, target IQN, portal, authentication policy, LUN inventory, device identity, client FreeBSD build, interface path, filesystem or application owner, restart order, and rollback. Monitor session state, device presence, I/O latency, network errors, target-side LUN health, and application errors independently. Retest after target firmware, FreeBSD, driver, network topology, or rc configuration changes.

The core safety rule is to preserve the distinction between a healthy network session, an attached block device, a consistent filesystem, and a healthy application. Each layer needs independent evidence. iscsictl -L confirms session state; CAM and GEOM identify device presentation and consumers; filesystem checks and application tests establish whether that storage is usable for its actual workload.

Related:

Sources:

Comments