MAN page from OpenSuSE open-iscsi-2.1.6-150400.37.6.x86_64.rpm


Section: Linux Administrator's Manual (8)
Updated: Mar 2022


iscsiadm - open-iscsi administration utility 


iscsiadm-m discoverydb[-hV][-ddebug_level][-Pprintlevel][-Iiface-t type -p ip:port[-lD]] | [[-pip:port-ttype][-ooperation][-nname][-vvalue][-lD]]

iscsiadm-m discovery[-hV][-ddebug_level][-Pprintlevel][-Iiface][-ttype][-pip:port][-l]

iscsiadm-m node[-hV][-ddebug_level][-Pprintlevel][-Lall,manual,automatic,onboot][-W][-Uall,manual,automatic,onboot][-S][[-Ttargetname -p ip:port -Iiface][-l|-u|-R|-s]][[-ooperation][-nname][-vvalue][-pip:port]]

iscsiadm-m session[-hV][-ddebug_level][-Pprintlevel][-rsessionid|sysfsdir[-R][-u|-s|-onew]]

iscsiadm-m iface[-hV][-ddebug_level][-Pprintlevel][-Iifacename |-Hhostno|MAC][[-ooperation][-nname][-vvalue]][-C ping[-aip][-bpacketsize][-ccount][-iinterval]]

iscsiadm-m fw[-ddebug_level][-l][-W][-nname][-vvalue]

iscsiadm-m host[-Pprintlevel][-Hhostno|MAC][[-Cchap[-xchap_tbl_idx]] |[-Cflashnode[-Aportal_type][-xflashnode_idx]] |[-Cstats]][[-ooperation][-nname][-vvalue]]

iscsiadm-k priority 


The iscsiadm utility is a command-line tool allowing discovery and loginto iSCSI targets, as well as access and management of the open-iscsidatabase.

Open-iscsi does not use the term node as defined by the iSCSI RFC,where a node is a single iSCSI initiator or target. Open-iscsi uses theterm node to refer to a portal on a target.

For session mode, a session id (sid) is used. The sid of a session can befound by running iscsiadm -m session -P 1. The session id and sysfspath are not currently persistent and is partially determined by when thesession is setup. 


Many of the node and discovery operations require that the iSCSIdaemon (iscsid) be running. If running 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. The followingdescribes them:

Home Directory
The home directory for open-iscsi is /etc/iscsi. This iswhere it keeps it's configuration file (iscsid.conf) and it'sinitiator name file (initiatorname.iscsi).
Database Root Directory
The database root directory for open-iscsi is /etc/iscsi. Thisis where it keeps its flat database files, such as it's list of nodes(see below).


-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
-H, --host=[hostno|MAC]
The host argument specifies the SCSI host to use for the operation. It can bethe scsi host number assigned to the host by the kernel's scsi layer, or theMAC 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 /etc/iscsi/ifaces. For hardwareiSCSI (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 isthen the filename of the iface configuration. For software iSCSI, the iface configurationmust have either the hardware address (iface.hwaddress), or the networklayer's interface name (iface.net_ifacename), and it must have thedriver/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), andocs (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 specialvalue default which directs the initiator to not bind the session to aspecific hardware resource and instead allow the network or InfiniBand layerto decide what to do. There is no need to create an iface configuration with the defaultbehavior. If you do not specify an iface, then the default behavior is used.
As mentioned above there is a special iface name default. There areothers which do not bind the session to a specific card, but instead bindthe session to the transport:iser,cxgb3i,cxgb4i, andbnx2i.
In discovery mode multiple interfaces can be specified by passing inmultiple -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 createsessions 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 iscsidoperations and shutdown iscsid. It does not logout any sessions. Runningthis command is the same as doing killall iscsid. Neither shouldnormally be used, because if iscsid is doing error recovery or if thereis 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 matchingthe 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 performdiscovery.
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 opis 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 passedin 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 functionalfor 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 tosend the login requests, whether or not they succeed. In this case, it willbe up to the caller to poll for success (i.e. session creation).
-m, --mode op
specify the mode. opmust be one of discovery, discoverydb, node, fw,host, iface or session.
If no other options are specified: for discovery, discoverydb andnode mode, all of their respective records are displayed; for session mode,all active sessions and connections are displayed; for fw mode, all bootfirmware values are displayed; for host mode, all iSCSI hosts are displayed;and for iface mode, all interfaces setup in /etc/iscsi/ifaces are displayed.
-n, --name=name
In node mode, specify a field name in a record. In flashnode submodeof 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 ofnew, 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 usedon a running session. If it is iscsiadm will stop the session and then delete therecord.
An op of new creates a new database record for a given object. In node mode, therecid is the target name and portal (IP:port). In iface mode, the recidis the iface name. In discovery mode, the recid is the portal anddiscovery type.
In session mode, the new operation logs in a new session usingthe 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 adiscovery record (it will not perform discovery). If the --discoverargument is passed in with the portal and discovery type, then iscsiadmwill create the discovery record if needed, and it will create recordsfor 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, ifiscsiadm is performing discovery, it will delete records for portals thatare no longer returned.
Setting op to update will update the recid with name to the specifiedvalue. In discovery mode, if iscsiadm is performing discovery therecid, name and value arguments are not needed. Theupdate operation will operate on the portals returned by the target,and will update the node records with information from the configuration file andcommand line.
The op value of show is the default behaviour for node,discovery and iface mode. It isalso used when there are no commands passed into session mode and arunning sid is passed in.If name and value are passed in, they are currently ignored in show mode.
An op value of nonpersistent instructs iscsiadm to not manipulate the node DB.
An op value of apply will cause the network settings to take effect on the specified iface.
An op value of applyall will cause the network settings to take effect on all theifaces whose MAC address or host number matches that of the specific host.
An op value of login will log 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. If port is not passedin the default value of 3260 is used.
IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or ddd.ddd.ddd.ddd.
Hostnames can also be used for the ip argument.
This option is only valid for discovery, or for node operations withthe new operator.
This should be used along with --target in node mode, to specify whatthe open-iscsi documents refer to as a node or node record. Note: open-iscsi'suse of the word node, does not match the iSCSI RFC's iSCSI Node term.
-P, --print=printlevel
If in node mode print nodes in tree format. If in session mode printsessions in tree format. If in discovery mode print the nodes intree format.
-T, --targetname=targetname
Use target targetname.
This should be used along with --portal in node mode, to specify whatthe open-iscsi documents refer to as a node or node record. Note: open-iscsi'suse of the word node, does not match the iSCSI RFC's iSCSI Node term.
-r, --sid=sid | sysfsdir
Use session ID sid. The session ID of a session can be found from runningiscsiadm in session mode with the --info argument.
Instead of a session ID, a sysfs path containing the session can be used.For example using one of the following:/sys/devices/platform/hostH/sessionS/targetH:B:I/H:B:I:L,/sys/devices/platform/hostH/sessionS/targetH:B:I, or/sys/devices/platform/hostH/sessionS, for the sysfsdir argument wouldresult in the session with session ID S to be used.
sid | sysfsdir is only required for session mode.
-R, --rescan
In session mode, if sid is also passed in, rescan the session.If no sid has been passed in rescan all running sessions.
In node mode, rescan a session running through the target, portal, ifacetuple passed in.
-s, --stats
Display session statistics.This option when used with host mode, displays host statistics.
-S, --show
When displaying records, do not hide masked values, such as the CHAPsecret (password).
This option is only valid for node and session mode.
-t, --type=type
type must be sendtargets (or abbreviated as st),slp, isns or fw. Currently only sendtargets, fw, andiSNS are supported, see the DISCOVERY TYPES section.
This option is only valid for discovery mode.
-u, --logout
Logout for the specified record.
This option is 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 allrunning sessions, except ones marked onboot, if all is passed in.
This option is only valid for node mode (it is valid but not functionalfor session mode).
-v, --value=value
Specify a value for use with the update operator, or for firmware login mode.
This option is only valid for node mode and flashnode submode of host mode.
-V, --version
Display version and exit.
-x, --index=index
Specify the index of the entity to operate on.
This option is only valid for chap and flashnode submodes of host mode.


iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.

A special discovery type calledfw(for firmware) is also supported, for discovering firmware interfaces,and populating the interface database in the process.

A native iSCSI protocol which allows each iSCSItarget to send a list of available targets to the initiator.
Optionally an iSCSI target can use the Service Location Protocol (SLP)to announce the available targets. The initiator can either implementSLP queries directly or can use a separate tool to acquire theinformation about available targets.
iSNS (Internet Storage Name Service) records information about storagevolumes within a larger network. To utilize iSNS, pass the address andoptionally the port of the iSNS server to do discovery to.
Firmware mode.Several NICs and systems contain a mini iSCSI initiator which can be usedfor 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 ordiscovery DB, because the values are stored in the system's or NIC'sresource.
Performing fw discovery will print the portals, like with other discoverymethods. To see other settings like CHAP values and initiator settings,like you would in node mode, run iscsiadm -m fw.Note that the SLP implementation is under development and currentlyis not supported.


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

Commands that operate on multiple objects (sessions, records, etc),iscsiadm/iscsistart will return the first error that is encountered.iscsiadm/iscsistart will attempt to execute the operation on the objects itcan. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is returned.

ISCSI_SUCCESS - command executed successfully.
ISCSI_ERR - generic error code.
ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
ISCSI_ERR_NOMEM - could not allocate resource for operation.
ISCSI_ERR_TRANS - connect problem caused operation to fail.
ISCSI_ERR_LOGIN - generic iSCSI login failure.
ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
ISCSI_ERR_INVAL - invalid argument.
ISCSI_ERR_TRANS_TIMEOUT - connection timer expired while trying to connect.
ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
ISCSI_ERR_LOGOUT - iSCSI logout failed.
ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in kernel or iscsid.
ISCSI_ERR_ACCESS - did not have proper OS permissions to access iscsid or execute iscsiadm command.
ISCSI_ERR_TRANS_CAPS - transport module did not support operation.
ISCSI_ERR_SESS_EXISTS - session is logged in.
ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals found to execute operation on.
ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization failure.
ISCSI_ERR_ISNS_QUERY - iSNS query failure.
ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration failed.
ISCSI_ERR_OP_NOT_SUPP - operation not support
ISCSI_ERR_BUSY - device or resource in use
ISCSI_ERR_AGAIN - operation failed, but retrying later may succeed
ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type
ISCSI_ERR_CHILD_TERMINATED - child process terminated
ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected


Discover targets at a given IP address:
sh# iscsiadm --mode discoverydb --type sendtargets --portal --discover

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

sh# iscsiadm --mode node --targetname --portal --login


sh# iscsiadm --mode node --targetname --portal --logout

List node records:

sh# iscsiadm --mode node

Display all data for a given node record:

sh# iscsiadm --mode node --targetname --portal


The configuration file read by iscsid and iscsiadm on startup.
The file containing the iSCSI InitiatorName and InitiatorAlias read byiscsid and iscsiadm on startup.
This directory contains the nodes with their targets.
This directory contains the portals.




Open-iSCSI project <>
Alex Aizman <>
Dmitry Yusupov <>




This document was created byman2html,using the manual pages.