ISCSIADM(8)

📦
version 2.1.13 · 7 versions
, in alpine 3.24, arch rolling, opensuse-leap 16.0

💅 iscsiadm(8) — open-iscsi administration utility 🫶

okay so this is the iscsiadm(8) page from the Linux Administrator's Manual, and it’s literally the open-iscsi administration utility. If you’re doing iSCSI discovery, login, or touching the open-iscsi database, this is your girl. ✨

✨ NAME ✨

iscsiadm — open-iscsi administration utility. no cap, that’s the whole name. 🎀

🦋 SYNOPSIS 🦋

Here’s the whole synopsis energy, copied exactly so you can trust it:

iscsiadm -m discoverydb [-hV] [-d debug_level] [-P printlevel] [-I iface
-t type -p ip:port [-lD] ] | [ [-p ip:port -t type] [-o operation] [-n
name] [-v value] [-lD] ]

iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [-I iface]
[-t type] [-p ip:port] [-l]

iscsiadm -m node [-hV] [-d debug_level] [-P printlevel] [-L
all,manual,automatic,onboot] [-W] [-U all,manual,automatic,onboot] [-S]
[ [-T targetname -p ip:port -I iface] [-l|-u|-R|-s] ] [ [-o operation]
[-n name] [-v value] [-p ip:port] ]

iscsiadm -m session [-hV] [-d debug_level] [-P printlevel] [-r
sessionid|sysfsdir [-R] [-u|-s|-o new] ]

iscsiadm -m iface [-hV] [-d debug_level] [-P printlevel] [-I ifacename |
-H hostno|MAC] [ [-o operation] [-n name] [-v value] ] [ -C ping [-a ip]
[-b packetsize] [-c count] [-i interval] ]

iscsiadm -m fw [-d debug_level] [-l] [-W] [-n name] [-v value]

iscsiadm -m host [-P printlevel] [-H hostno|MAC] [ [-C chap [-x
chap_tbl_idx] ] | [-C flashnode [-A portal_type] [-x flashnode_idx] ] |
[-C stats] ] [ [-o operation] [-n name] [-v value] ]

iscsiadm -k priority

💖 DESCRIPTION 💖

okay so the iscsiadm utility is a command-line tool that lets you do discovery and login to iSCSI targets, plus access and manage the open-iscsi database. 💅

Important vibe check: open-iscsi does not use the term node the way the iSCSI RFC does. In the RFC, a node is a single iSCSI initiator or target. Open-iscsi uses node to mean a portal on a target. yes bestie, terminology slay. 🌸

For session mode, a session id (sid) is used. You can find the sid of a session by running iscsiadm -m session -P 1. The session id and sysfs path are not currently persistent and are partially determined by when the session is setup. okay that’s the tea. 😭

🌈 NOTES 🌈

Many of the node and discovery operations require that the iSCSI daemon (iscsid) be running. If you’re on a system that uses systemd, the daemon may start up automatically, if enabled, when needed. 🫶

Open-iscsi has two groups of files it needs to store or get access to while running: the HOMEDIR and the DBROOT. Here’s the breakdown:

🏠 Home Directory 🏠

The home directory for open-iscsi is /etc/iscsi. This is where it keeps its configuration file (iscsid.conf) and its initiator name file (initiatorname.iscsi). literally the home base. 💅

🗄️ Database Root Directory 🗄️

The database root directory for open-iscsi is /var/lib/iscsi. This is where it keeps its flat database files, such as its list of nodes (see below). 🎀

🔥 OPTIONS 🔥

  • -a, --ip=ipaddr — ipaddr can be IPv4 or IPv6. This option is only valid for ping submode. 🫶
  • -A, --portal_type=[ipv4|ipv6] — Specify the portal type for the new flash node entry to be created. This option is only valid for flashnode submode of host mode and only with new operation. ✨
  • -b, --packetsize=packetsize — Specify the ping packetsize. This option is only valid for ping submode. 📦
  • -c, --count=count — count specifies the number of ping iterations. This option is only valid for ping submode. 🔁
  • -C, --submode=op — Specify the submode for mode. op must be name of submode. Currently iscsiadm supports ping as a submode for iface. For example:
iscsiadm -m iface -I ifacename -C ping -a ipaddr -b packetsize -c count -i interval

For host, it supports chap, flashnode and stats as submodes. For example:

iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation

iscsiadm -m host -H hostno -C flashnode -x flashnode_idx -o operation

iscsiadm -m host -H hostno -C stats
  • -d, --debug=debug_level — print debugging information. Valid values for debug_level are 0 to 8. 🐛
  • -h, --help — display help text and exit. bestie behavior honestly. 🫡
  • -H, --host=[hostno|MAC] — The host argument specifies the SCSI host to use for the operation. It can be the scsi host number assigned to the host by the kernel’s scsi layer, or the MAC address of a scsi host. 🖥️
  • -i, --interval=interval — interval specifies the delay between two ping iterations. This option is only valid for ping submode. ⏳
  • -I, --interface=[iface] — The interface argument specifies the iSCSI interface to use for the operation. iSCSI interfaces (iface) are defined in /var/lib/iscsi/ifaces. For hardware iSCSI (e.g. qla4xxx) the iface configuration must have the hardware address (iface.hwaddress = port's MAC address) and the driver/transport_name (iface.transport_name). The iface’s name is then the filename of the iface configuration. For software iSCSI, the iface configuration must have either the hardware address (iface.hwaddress), or the network layer’s interface name (iface.net_ifacename), and it must have the driver/transport_name.

The available drivers/iscsi_transports are:

  • tcp — software iSCSI over TCP/IP
  • iser — software iSCSI over InfiniBand
  • qla4xxx — Qlogic 4XXXX and 82XXX HBAs
  • cxgb3i and cxgb4i — Chelsio T3 and T4 adapters
  • bnx2i — QLogic Netextreme II adapters
  • be2iscsi — Emulex 10G adapter
  • qedi — QLogic QEDI 25/40/100Gb adapter
  • ocs — Emulex One Connect storage

Some of these are considered experimental, as they are not fully tested. 👀

The hwaddress is the MAC address or for software iSCSI it may be the special value default which directs the initiator to not bind the session to a specific hardware resource and instead allow the network or InfiniBand layer to decide what to do. There is no need to create an iface configuration with the default behavior. If you do not specify an iface, then the default behavior is used. 🌸

As mentioned above there is a special iface name default. There are others which do not bind the session to a specific card, but instead bind the session to the transport: iser, cxgb3i, cxgb4i, and bnx2i.

In discovery mode multiple interfaces can be specified by passing in multiple -I/--interface instances. For example:

sh# iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2 --discover

Will direct iscsiadm to setup the node db to create records which will create sessions through the two interfaces passed in. 🦋

In node mode, only a single interface is supported in each call to iscsiadm.

This option is valid for discovery, node and iface modes. 💅

  • -k, --killiscsid=[priority] — Currently priority must be zero. This will immediately stop all iscsid operations and shutdown iscsid. It does not logout any sessions. Running this command is the same as doing killall iscsid. Neither should normally be used, because if iscsid is doing error recovery or if there is an error while iscsid is not running, the system may not be able to recover. This command and iscsid’s SIGTERM handling are experimental. 💀
  • -D, --discover — Discover targets using the discovery record with the recid matching the the discovery type and portal passed in. If there is no matching record, it will be created using the iscsid.conf discovery settings. This must be passed in to discoverydb mode to instruct iscsiadm to perform discovery. This option is only valid for SendTargets discovery mode. 🔍
  • -l, --login — For node and fw modes, login to a specified record. For discovery mode, login to all discovered targets. This option is only valid for discovery, node, and fw modes. For fw mode only, name and value pairs can optionally be passed in, so that those values get used for the sessions created. In this case, no op is needed, since update is assumed. 🚪✨
  • -L, --loginall=[all|manual|automatic|onboot] — For node mode, login to all sessions with the node or conn startup values passed in or all running session, except ones marked onboot, if all is passed in. This option is only valid for node mode (it is valid but not functional for session mode). 👑
  • -W, ---no_wait — In node, discovery, or fw (firmware) mode, do not wait for a response from the target(s). This means that success will be returned if the command is able to send the login requests, whether or not they succeed. In this case, it will be up to the caller to poll for success (i.e. session creation). ⚡
  • -m, --mode op — specify the mode. op must be one of discovery, discoverydb, node, fw, host, iface or session. If no other options are specified: for discovery, discoverydb and node mode, all of their respective records are displayed; for session mode, all active sessions and connections are displayed; for fw mode, all boot firmware values are displayed; for host mode, all iSCSI hosts are displayed; and for iface mode, all interfaces setup in /var/lib/iscsi/ifaces are displayed. 🎛️
  • -n, --name=name — In node mode, specify a field name in a record. In flashnode submode of host mode, specify name of the flash node parameter. For use with the update operator. 🏷️
  • -o, --op=op — Specifies a database operator op. op must be one of new, delete, update, show or nonpersistent. For iface mode, apply and applyall are also applicable. For flashnode submode of host mode, login and logout are also applicable. This option is valid for all modes except fw. Delete should not be used on a running session. If it is iscsiadm will stop the session and then delete the record. An op of new creates a new database record for a given object. In node mode, the recid is the target name and portal (IP:port). In iface mode, the recid is the iface name. In discovery mode, the recid is the portal and discovery type. In session mode, the new operation logs in a new session using the same node database and iface information as the specified session. In discovery mode, if the recid and new operation is passed in, but the --discover argument is not passed in, then iscsiadm will only create a discovery record (it will not perform discovery). If the --discover argument is passed in with the portal and discovery type, then iscsiadm will create the discovery record if needed, and it will create records for portals returned by the target that do not yet have a node DB record. 🫶

Setting op to delete deletes the specified recid. In discovery mode, if iscsiadm is doing discovery, it deletes records for portals that are no longer returned. 💅

Setting op to update updates the recid with name to the specified value. In discovery mode, if iscsiadm is performing discovery, the recid, name and value arguments are not needed — the update operation just operates on the portals returned by the target, and updates the node records with info from the config file and command line. ✨

The op value of show is the default behaviour for node, discovery and iface mode. It's also what gets used when no commands are passed into session mode and a running sid is passed in. If name and value are passed in, they are currently ignored in show mode (yeah, iykyk, it just do be like that 🙈).

An op value of nonpersistent tells iscsiadm to not touch the node DB.

An op value of apply makes the network settings actually take effect on the specified iface. 🫶

An op value of applyall makes the network settings take effect on all the ifaces whose MAC address or host number matches that of the specific host.

An op value of login logs into the specified flash node entry.

An op value of logout does the logout from the given flash node entry.

  • -p, --portal=ip[:port] — use target portal with IP address ip and port port. No port? Default 3260 steps in, no cap. IPv6 addresses can be written as [ddd.ddd.ddd.ddd]:port or ddd.ddd.ddd.ddd. Hostnames work for the ip argument too. This option is only valid for discovery, or for node operations with the new operator. Use it alongside --target in node mode to specify what the open-iscsi docs call a node or node record. ⚠️ Note: open-iscsi's use of the word node does not match the iSCSI RFC's iSCSI Node term — don't get it twisted bestie.
  • -P, --print=printlevel — if you're in node mode, print nodes in tree format 🌳. In session mode, print sessions in tree format. In discovery mode, print the nodes in tree format. Tree format everywhere, honestly iconic.
  • -T, --targetname=targetname — use target targetname. Use this alongside --portal in node mode to specify what the open-iscsi docs call a node or node record. ⚠️ Again: open-iscsi's node ≠ the iSCSI RFC's iSCSI Node term.
  • -r, --sid=sid | sysfsdir — use session ID sid. You can find a session's ID by running iscsiadm in session mode. Instead of a session ID you can hand over a sysfs path containing the session — for example using one of these as the sysfsdir argument:
/sys/devices/platform/hostH/sessionS/targetH:B:I/H:B:I:L
/sys/devices/platform/hostH/sessionS/targetH:B:I
/sys/devices/platform/hostH/sessionS

would result in the session with session ID S being used. sid | sysfsdir is only required for session mode.

  • -R, --rescan — in session mode, if sid is also passed in, rescan that session. No sid? It rescans all running sessions 👑. In node mode, it rescans a session running through the target, portal, iface tuple you passed in.
  • -s, --stats — display session statistics. Used with host mode, it displays host statistics instead. 📊
  • -S, --show — when displaying records, don't hide masked values like the CHAP secret (password). 👀 Only valid for node and session mode.
  • -t, --type=type — type must be sendtargets (or the abbreviation st), isns (if enabled), or fw. See the DISCOVERY TYPES section. Only valid for discovery mode.
  • -u, --logout — logout for the specified record. Only valid for node and session mode.
  • -U, --logoutall=[all,manual,automatic|onboot] — logout of all sessions with the node or conn startup values passed in, or all running sessions — except the ones marked onboot, if all is passed in. Only valid for node mode (it's valid but not functional for session mode, so like… don't 💀).
  • -v, --value=value — specify a value for use with the update operator, or for firmware login mode. Only valid for node mode and the flashnode submode of host mode.
  • -V, --version — display version and exit. Short and sweet, we stan.
  • -x, --index=index — specify the index of the entity to operate on. Only valid for the chap and flashnode submodes of host mode.

🦋 DISCOVERY TYPES 🦋

iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS. SLP is not widely supported, and isn't supported by this package (rip, not invited to the party 😭). iSNS support depends on build options, but it's enabled by default. ✨

There's also a special discovery type called fw (for firmware), which discovers firmware interfaces and populates the interface database in the process. Main character energy.

SendTargets

A native iSCSI protocol which lets each iSCSI target send a list of available targets to the initiator. 🎀

iSNS

iSNS (Internet Storage Name Service) records information about storage volumes within a larger network. To use iSNS, pass the address and optionally the port of the iSNS server to do discovery to.

fw

Firmware mode. Several NICs and systems contain a mini iSCSI initiator that can be used for boot. To get the values used for boot, the fw option can be used. Doing fw discovery does not store persistent records in the node or discovery DB, because the values live in the system's or NIC's resource. 🔥

Performing fw discovery prints the portals, just like with other discovery methods. To see other settings like CHAP values and initiator settings — like you would in node mode — run iscsiadm -m fw.

💖 EXIT STATUS 💖

On success 0 is returned. On error, one of the return codes below is returned.

Commands that operate on multiple objects (sessions, records, etc): iscsiadm/iscsistart returns the first error it encounters. iscsiadm/iscsistart will attempt to execute the operation on the objects it can. If no objects are found, ISCSI_ERR_NO_OBJS_FOUND is returned. 🫠

  • 0 — ISCSI_SUCCESS — command executed successfully. slay!
  • 1 — ISCSI_ERR — generic error code.
  • 2 — ISCSI_ERR_SESS_NOT_FOUND — session could not be found.
  • 3 — ISCSI_ERR_NOMEM — could not allocate resource for operation.
  • 4 — ISCSI_ERR_TRANS — connect problem caused operation to fail.
  • 5 — ISCSI_ERR_LOGIN — generic iSCSI login failure.
  • 6 — ISCSI_ERR_IDBM — error accessing/managing iSCSI DB.
  • 7 — ISCSI_ERR_INVAL — invalid argument.
  • 8 — ISCSI_ERR_TRANS_TIMEOUT — connection timer expired while trying to connect.
  • 9 — ISCSI_ERR_INTERNAL — generic internal iscsid/kernel failure.
  • 10 — ISCSI_ERR_LOGOUT — iSCSI logout failed.
  • 11 — ISCSI_ERR_PDU_TIMEOUT — iSCSI PDU timed out.
  • 12 — ISCSI_ERR_TRANS_NOT_FOUND — iSCSI transport module not loaded in kernel or iscsid.
  • 13 — ISCSI_ERR_ACCESS — did not have proper OS permissions to access iscsid or execute the iscsiadm command.
  • 14 — ISCSI_ERR_TRANS_CAPS — transport module did not support the operation.
  • 15 — ISCSI_ERR_SESS_EXISTS — session is logged in.
  • 16 — ISCSI_ERR_INVALID_MGMT_REQ — invalid IPC MGMT request.
  • 17 — ISCSI_ERR_ISNS_UNAVAILABLE — iSNS service is not supported.
  • 18 — ISCSI_ERR_ISCSID_COMM_ERR — a read/write to iscsid failed.
  • 19 — ISCSI_ERR_FATAL_LOGIN — fatal iSCSI login error.
  • 20 — ISCSI_ERR_ISCSID_NOTCONN — could not connect to iscsid.
  • 21 — ISCSI_ERR_NO_OBJS_FOUND — no records/targets/sessions/portals found to execute operation on.
  • 22 — ISCSI_ERR_SYSFS_LOOKUP — could not lookup object in sysfs.
  • 23 — ISCSI_ERR_HOST_NOT_FOUND — could not lookup host.
  • 24 — ISCSI_ERR_LOGIN_AUTH_FAILED — login failed due to authorization failure.
  • 25 — ISCSI_ERR_ISNS_QUERY — iSNS query failure.
  • 26 — ISCSI_ERR_ISNS_REG_FAILED — iSNS registration/deregistration failed.
  • 27 — ISCSI_ERR_OP_NOT_SUPP — operation not support
  • 28 — ISCSI_ERR_BUSY — device or resource in use
  • 29 — ISCSI_ERR_AGAIN — operation failed, but retrying later may succeed
  • 30 — ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE — unknown discovery type
  • 31 — ISCSI_ERR_CHILD_TERMINATED — child process terminated
  • 32 — ISCSI_ERR_SESSION_NOT_CONNECTED — session likely not connected

🌸 EXAMPLES 🌸

Discover targets at a given IP address:

sh# iscsiadm --mode discoverydb --type sendtargets --portal 192.168.1.10 --discover

Login — you must use a node record id found by the discovery:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login

Logout:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout

List node records:

sh# iscsiadm --mode node

Display all data for a given node record:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260

List all sessions:

sh# iscsiadm --mode session

List all sessions in tree format:

sh# iscsiadm --mode session  --print

🎀 FILES 🎀

  • /etc/iscsi/iscsid.conf — the configuration file read by iscsid and iscsiadm on startup.
  • /etc/iscsi/initiatorname.iscsi — the file containing the iSCSI InitiatorName and InitiatorAlias, read by iscsid and iscsiadm on startup.
  • /var/lib/iscsi/nodes/ — this directory contains the nodes with their targets.
  • /var/lib/iscsi/send_targets — this directory contains the portals.

👑 SEE ALSO 👑

iscsid(8)

💜 AUTHORS 💜

And that's the whole page bestie, you ate it up 💅✨ This little masterpiece is the ISCSIADM(8) man page, dated Mar 2022 — go forth and discover targets, and remember: not all nodes are iSCSI Nodes 😌🦋💖

📦 where this page comes from