1ISCSIADM(8) Linux Administrator's Manual ISCSIADM(8)
2
6 iscsiadm - open-iscsi administration utility
7
9 iscsiadm -m discoverydb [-hV] [-d debug_level] [-P printlevel] [-I
10 iface -t type -p ip:port [-lD] ] | [ [-p ip:port -t type] [-o opera‐
11 tion] [-n name] [-v value] [-lD] ]
12 iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [-I iface]
14 [-t type] [-p ip:port] [-l]
15 iscsiadm -m node [-hV] [-d debug_level] [-P printlevel] [-L all,man‐
17 ual,automatic,onboot] [-W] [-U all,manual,automatic,onboot] [-S] [ [-T
18 targetname -p ip:port -I iface] [-l|-u|-R|-s] ] [ [-o operation] [-n
19 name] [-v value] [-p ip:port] ]
20 iscsiadm -m session [-hV] [-d debug_level] [-P printlevel] [-r ses‐
22 sionid|sysfsdir [-R] [-u|-s|-o new] ]
23 iscsiadm -m iface [-hV] [-d debug_level] [-P printlevel] [-I iface‐
25 name | -H hostno|MAC] [ [-o operation] [-n name] [-v value] ] [ -C ping
26 [-a ip] [-b packetsize] [-c count] [-i interval] ]
27 iscsiadm -m fw [-d debug_level] [-l] [-W] [-n name] [-v value]
29 iscsiadm -m host [-P printlevel] [-H hostno|MAC] [ [-C chap [-x
31 chap_tbl_idx] ] | [-C flashnode [-A portal_type] [-x flashnode_idx] ] |
32 [-C stats] ] [ [-o operation] [-n name] [-v value] ]
33 iscsiadm -k priority
35
37 The iscsiadm utility is a command-line tool allowing discovery and lo‐
38 gin to iSCSI targets, as well as access and management of the open-
39 iscsi database.
40 Open-iscsi does not use the term node as defined by the iSCSI RFC,
42 where a node is a single iSCSI initiator or target. Open-iscsi uses the
43 term node to refer to a portal on a target.
44 For session mode, a session id (sid) is used. The sid of a session can
46 be found by running iscsiadm -m session -P 1. The session id and sysfs
47 path are not currently persistent and is partially determined by when
48 the session is setup.
49
51 Many of the node and discovery operations require that the iSCSI daemon
52 (iscsid) be running. If running on a system that uses systemd, the dae‐
53 mon may start up automatically, if enabled, when needed.
54 Open-iscsi has two groups of files it needs to store or get access to,
56 while running: the HOMEDIR and the DBROOT. The following describes
57 them:
58 Home Directory
60 The home directory for open-iscsi is /etc/iscsi. This is where
61 it keeps it's configuration file (iscsid.conf) and it's initia‐
62 tor name file (initiatorname.iscsi).
63 Database Root Directory
65 The database root directory for open-iscsi is /var/lib/iscsi.
66 This is where it keeps its flat database files, such as it's
67 list of nodes (see below).
68
70 -a, --ip=ipaddr
71 ipaddr can be IPv4 or IPv6.
72 This option is only valid for ping submode.
74 -A, --portal_type=[ipv4|ipv6]
76 Specify the portal type for the new flash node entry to be cre‐
77 ated.
78 This option is only valid for flashnode submode of host mode and
80 only with new operation.
81 -b, --packetsize=packetsize
83 Specify the ping packetsize.
84 This option is only valid for ping submode.
86 -c, --count=count
88 count specifies the number of ping iterations.
89 This option is only valid for ping submode.
91 -C, --submode=op
93 Specify the submode for mode. op must be name of submode.
94 Currently iscsiadm supports ping as a submode for iface. For ex‐
96 ample:
97 iscsiadm -m iface -I ifacename -C ping -a ipaddr -b packetsize
99 -c count -i interval
100 For host, it supports chap, flashnode and stats as submodes. For
102 example:
103 iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation
105 iscsiadm -m host -H hostno -C flashnode -x flashnode_idx -o op‐
107 eration
108 iscsiadm -m host -H hostno -C stats
110 -d, --debug=debug_level
112 print debugging information. Valid values for debug_level are 0
113 to 8.
114 -h, --help
116 display help text and exit
117 -H, --host=[hostno|MAC]
119 The host argument specifies the SCSI host to use for the opera‐
120 tion. It can be the scsi host number assigned to the host by the
121 kernel's scsi layer, or the MAC address of a scsi host.
122 -i, --interval=interval
124 interval specifies the delay between two ping iterations.
125 This option is only valid for ping submode.
127 -I, --interface=[iface]
129 The interface argument specifies the iSCSI interface to use for
130 the operation. iSCSI interfaces (iface) are defined in
131 /var/lib/iscsi/ifaces. For hardware iSCSI (e.g. qla4xxx) the
132 iface configuration must have the hardware address (iface.hwad‐
133 dress = port's MAC address) and the driver/transport_name
134 (iface.transport_name). The iface's name is then the filename of
135 the iface configuration. For software iSCSI, the iface configu‐
136 ration must have either the hardware address (iface.hwaddress),
137 or the network layer's interface name (iface.net_ifacename), and
138 it must have the driver/transport_name.
139 The available drivers/iscsi_transports are tcp (software iSCSI
141 over TCP/IP), iser (software iSCSI over InfiniBand), qla4xxx
142 (Qlogic 4XXXX and 82XXX HBAs), cxgb3i and cxgb4i (Chelsio T3 and
143 T4 adapters), bnx2i (QLogic Netextreme II adapters), be2iscsi
144 (Emulex 10G adapter), qedi (QLogic QEDI 25/40/100Gb adapter),
145 and ocs (Emulex One Connect storage). Some of these are consid‐
146 ered experimental, as they are not fully tested.
147 The hwaddress is the MAC address or for software iSCSI it may be
149 the special value default which directs the initiator to not
150 bind the session to a specific hardware resource and instead al‐
151 low the network or InfiniBand layer to decide what to do. There
152 is no need to create an iface configuration with the default be‐
153 havior. If you do not specify an iface, then the default behav‐
154 ior is used.
155 As mentioned above there is a special iface name default. There
157 are others which do not bind the session to a specific card, but
158 instead bind the session to the transport: iser, cxgb3i, cxgb4i,
159 and bnx2i.
160 In discovery mode multiple interfaces can be specified by pass‐
162 ing in multiple -I/--interface instances. For example:
163 sh# iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2
165 --discover
166 Will direct iscsiadm to setup the node db to create records
168 which will create sessions through the two interfaces passed in.
169 In node mode, only a single interface is supported in each call
171 to iscsiadm.
172 This option is valid for discovery, node and iface modes.
174 -k, --killiscsid=[priority]
176 Currently priority must be zero. This will immediately stop all
177 iscsid operations and shutdown iscsid. It does not logout any
178 sessions. Running this command is the same as doing killall isc‐
179 sid. Neither should normally be used, because if iscsid is doing
180 error recovery or if there is an error while iscsid is not run‐
181 ning, the system may not be able to recover. This command and
182 iscsid's SIGTERM handling are experimental.
183 -D, --discover
185 Discover targets using the discovery record with the recid
186 matching the the discovery type and portal passed in. If there
187 is no matching record, it will be created using the iscsid.conf
188 discovery settings. This must be passed in to discoverydb mode
189 to instruct iscsiadm to perform discovery.
190 This option is only valid for SendTargets discovery mode.
192 -l, --login
194 For node and fw modes, login to a specified record. For discov‐
195 ery mode, login to all discovered targets.
196 This option is only valid for discovery, node, and fw modes.
198 For fw mode only, name and value pairs can optionally be passed
199 in, so that those values get used for the sessions created. In
200 this case, no op is needed, since update is assumed.
201 -L, --loginall=[all|manual|automatic|onboot]
203 For node mode, login to all sessions with the node or conn
204 startup values passed in or all running session, except ones
205 marked onboot, if all is passed in.
206 This option is only valid for node mode (it is valid but not
208 functional for session mode).
209 -W, ---no_wait
211 In node, discovery, or fw (firmware) mode, do not wait for a re‐
212 sponse from the target(s). This means that success will be re‐
213 turned if the command is able to send the login requests,
214 whether or not they succeed. In this case, it will be up to the
215 caller to poll for success (i.e. session creation).
216 -m, --mode op
218 specify the mode. op must be one of discovery, discoverydb,
219 node, fw, host, iface or session.
220 If no other options are specified: for discovery, discoverydb
222 and node mode, all of their respective records are displayed;
223 for session mode, all active sessions and connections are dis‐
224 played; for fw mode, all boot firmware values are displayed; for
225 host mode, all iSCSI hosts are displayed; and for iface mode,
226 all interfaces setup in /var/lib/iscsi/ifaces are displayed.
227 -n, --name=name
229 In node mode, specify a field name in a record. In flashnode
230 submode of host mode, specify name of the flash node parameter.
231 For use with the update operator.
233 -o, --op=op
235 Specifies a database operator op. op must be one of new, delete,
236 update, show or nonpersistent.
237 For iface mode, apply and applyall are also applicable.
239 For flashnode submode of host mode, login and logout are also
241 applicable.
242 This option is valid for all modes except fw. Delete should not
244 be used on a running session. If it is iscsiadm will stop the
245 session and then delete the record.
246 An op of new creates a new database record for a given object.
248 In node mode, the recid is the target name and portal (IP:port).
249 In iface mode, the recid is the iface name. In discovery mode,
250 the recid is the portal and discovery type.
251 In session mode, the new operation logs in a new session using
253 the same node database and iface information as the specified
254 session.
255 In discovery mode, if the recid and new operation is passed in,
257 but the --discover argument is not passed in, then iscsiadm will
258 only create a discovery record (it will not perform discovery).
259 If the --discover argument is passed in with the portal and dis‐
260 covery type, then iscsiadm will create the discovery record if
261 needed, and it will create records for portals returned by the
262 target that do not yet have a node DB record.
263 Setting op to delete deletes the specified recid. In discovery
265 mode, if iscsiadm is performing discovery, it will delete
266 records for portals that are no longer returned.
267 Setting op to update will update the recid with name to the
269 specified value. In discovery mode, if iscsiadm is performing
270 discovery the recid, name and value arguments are not needed.
271 The update operation will operate on the portals returned by the
272 target, and will update the node records with information from
273 the configuration file and command line.
274 The op value of show is the default behaviour for node, discov‐
276 ery and iface mode. It is also used when there are no commands
277 passed into session mode and a running sid is passed in. If
278 name and value are passed in, they are currently ignored in show
279 mode.
280 An op value of nonpersistent instructs iscsiadm to not manipu‐
282 late the node DB.
283 An op value of apply will cause the network settings to take ef‐
285 fect on the specified iface.
286 An op value of applyall will cause the network settings to take
288 effect on all the ifaces whose MAC address or host number
289 matches that of the specific host.
290 An op value of login will log into the specified flash node en‐
292 try.
293 An op value of logout does the logout from the given flash node
295 entry.
296 -p, --portal=ip[:port]
298 Use target portal with IP address ip and port port. If port is
299 not passed in the default value of 3260 is used.
300 IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or
302 ddd.ddd.ddd.ddd.
303 Hostnames can also be used for the ip argument.
305 This option is only valid for discovery, or for node operations
307 with the new operator.
308 This should be used along with --target in node mode, to specify
310 what the open-iscsi documents refer to as a node or node record.
311 Note: open-iscsi's use of the word node, does not match the
312 iSCSI RFC's iSCSI Node term.
313 -P, --print=printlevel
315 If in node mode print nodes in tree format. If in session mode
316 print sessions in tree format. If in discovery mode print the
317 nodes in tree format.
318 -T, --targetname=targetname
320 Use target targetname.
321 This should be used along with --portal in node mode, to specify
323 what the open-iscsi documents refer to as a node or node record.
324 Note: open-iscsi's use of the word node, does not match the
325 iSCSI RFC's iSCSI Node term.
326 -r, --sid=sid | sysfsdir
328 Use session ID sid. The session ID of a session can be found
329 from running iscsiadm in session mode with the --info argument.
330 Instead of a session ID, a sysfs path containing the session can
332 be used. For example using one of the following: /sys/de‐
333 vices/platform/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/de‐
334 vices/platform/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
335 form/hostH/sessionS, for the sysfsdir argument would result in
336 the session with session ID S to be used.
337 sid | sysfsdir is only required for session mode.
339 -R, --rescan
341 In session mode, if sid is also passed in, rescan the session.
342 If no sid has been passed in rescan all running sessions.
343 In node mode, rescan a session running through the target, por‐
345 tal, iface tuple passed in.
346 -s, --stats
348 Display session statistics. This option when used with host
349 mode, displays host statistics.
350 -S, --show
352 When displaying records, do not hide masked values, such as the
353 CHAP secret (password).
354 This option is only valid for node and session mode.
356 -t, --type=type
358 type must be sendtargets (or abbreviated as st), isns (if en‐
359 abled), or fw. See the DISCOVERY TYPES section.
360 This option is only valid for discovery mode.
362 -u, --logout
364 Logout for the specified record.
365 This option is only valid for node and session mode.
367 -U, --logoutall=[all,manual,automatic|onboot]
369 Logout of all sessions with the node or conn startup values
370 passed in or all running sessions, except ones marked onboot, if
371 all is passed in.
372 This option is only valid for node mode (it is valid but not
374 functional for session mode).
375 -v, --value=value
377 Specify a value for use with the update operator, or for
378 firmware login mode.
379 This option is only valid for node mode and flashnode submode of
381 host mode.
382 -V, --version
384 Display version and exit.
385 -x, --index=index
387 Specify the index of the entity to operate on.
388 This option is only valid for chap and flashnode submodes of
390 host mode.
391
393 iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS. SLP is
394 not widely supported, and not supported by this pacakge. SNS supported
395 depends on build options, but is enabled by default.
396 A special discovery type called fw (for firmware) is also supported,
398 for discovering firmware interfaces, and populating the interface data‐
399 base in the process.
400 SendTargets
402 A native iSCSI protocol which allows each iSCSI target to send a
403 list of available targets to the initiator.
404 iSNS iSNS (Internet Storage Name Service) records information about
406 storage volumes within a larger network. To utilize iSNS, pass
407 the address and optionally the port of the iSNS server to do
408 discovery to.
409 fw Firmware mode. Several NICs and systems contain a mini iSCSI
411 initiator which can be used for boot. To get the values used for
412 boot the fw option can be used. Doing fw discovery does not
413 store persistent records in the node or discovery DB, because
414 the values are stored in the system's or NIC's resource.
415 Performing fw discovery will print the portals, like with other
417 discovery methods. To see other settings like CHAP values and
418 initiator settings, like you would in node mode, run iscsiadm -m
419 fw.
420
422 On success 0 is returned. On error one of the return codes below will
423 be returned.
424 Commands that operate on multiple objects (sessions, records, etc),
426 iscsiadm/iscsistart will return the first error that is encountered.
427 iscsiadm/iscsistart will attempt to execute the operation on the ob‐
428 jects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is re‐
429 turned.
430 0 ISCSI_SUCCESS - command executed successfully.
432 1 ISCSI_ERR - generic error code.
434 2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
436 3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
438 4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
440 5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
442 6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
444 7 ISCSI_ERR_INVAL - invalid argument.
446 8 ISCSI_ERR_TRANS_TIMEOUT - connection timer expired while trying
448 to connect.
449 9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
451 10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
453 11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timed out.
455 12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
457 kernel or iscsid.
458 13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
460 iscsid or execute iscsiadm command.
461 14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
463 tion.
464 15 ISCSI_ERR_SESS_EXISTS - session is logged in.
466 16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
468 17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
470 18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
472 19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
474 20 ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
476 21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
478 found to execute operation on.
479 22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
481 23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
483 24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
485 failure.
486 25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
488 26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
490 failed.
491 27 ISCSI_ERR_OP_NOT_SUPP - operation not support
493 28 ISCSI_ERR_BUSY - device or resource in use
495 29 ISCSI_ERR_AGAIN - operation failed, but retrying later may suc‐
497 ceed
498 30 ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type
500 31 ISCSI_ERR_CHILD_TERMINATED - child process terminated
502 32 ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected
504
506 Discover targets at a given IP address:
507 sh# iscsiadm --mode discoverydb --type sendtargets --portal
509 192.168.1.10 --discover
510 Login, must use a node record id found by the discovery:
512 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
514 --portal 192.168.1.1:3260 --login
515 Logout:
517 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
519 --portal 192.168.1.1:3260 --logout
520 List node records:
522 sh# iscsiadm --mode node
524 Display all data for a given node record:
526 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
528 --portal 192.168.1.1:3260
529 List all sessions:
531 sh# iscsiadm --mode session
533 List all sessions in tree format:
535 sh# iscsiadm --mode session --print
537
539 /etc/iscsi/iscsid.conf
540 The configuration file read by iscsid and iscsiadm on startup.
541 /etc/iscsi/initiatorname.iscsi
543 The file containing the iSCSI InitiatorName and InitiatorAlias
544 read by iscsid and iscsiadm on startup.
545 /var/lib/iscsi/nodes/
547 This directory contains the nodes with their targets.
548 /var/lib/iscsi/send_targets
550 This directory contains the portals.
551
553 iscsid(8)
554
556 Open-iSCSI project <http://www.open-iscsi.com/>
557 Alex Aizman <itn780@yahoo.com>
558 Dmitry Yusupov <dmitry_yus@yahoo.com>
559 Mar 2022 ISCSIADM(8)