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
14 iface -t type -p ip:port [-l] ] | [ [-p ip:port] [-l|-D] ]
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]
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 Note that many of the node and discovery operations require that the
51 iSCSI daemon (iscsid) be running.
52
54 -a, --ip=ipaddr
55 ipaddr can be IPv4 or IPv6.
56 This option is only valid for ping submode.
58 -A, --portal_type=[ipv4|ipv6]
60 Specify the portal type for the new flash node entry to be cre‐
61 ated.
62 This option is only valid for flashnode submode of host mode and
64 only with new operation.
65 -b, --packetsize=packetsize
67 Specify the ping packetsize.
68 This option is only valid for ping submode.
70 -c, --count=count
72 count specify number of ping iterations.
73 This option is only valid for ping submode.
75 -C, --submode=op
77 Specify the submode for mode. op must be name of submode.
78 Currently iscsiadm support ping as submode for iface. For exam‐
80 ple:
81 iscsiadm -m iface -I ifacename -C ping -a ipaddr -b packetsize
83 -c count -i interval
84 For host, it supports chap , flashnode and stats as submodes.
86 For example:
87 iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation
89 iscsiadm -m host -H hostno -C flashnode -x flashnode_idx -o op‐
91 eration
92 iscsiadm -m host -H hostno -C stats
94 -d, --debug=debug_level
96 print debugging information. Valid values for debug_level are 0
97 to 8.
98 -h, --help
100 display help text and exit
101 -H, --host=[hostno|MAC]
103 The host argument specifies the SCSI host to use for the opera‐
104 tion. It can be the scsi host number assigned to the host by the
105 kernel's scsi layer, or the MAC address of a scsi host.
106 -i, --interval=interval
108 interval specify delay between two ping iterations.
109 This option is only valid for ping submode.
111 -I, --interface=[iface]
113 The interface argument specifies the iSCSI interface to use for
114 the operation. iSCSI interfaces (iface) are defined in
115 /var/lib/iscsi/ifaces. For hardware iSCSI (qla4xxx) the iface
116 config must have the hardware address (iface.hwaddress = port's
117 MAC address) and the driver/transport_name (iface.trans‐
118 port_name). The iface's name is then the filename of the iface
119 config. For software iSCSI, the iface config must have either
120 the hardware address (iface.hwaddress), or the network layer's
121 interface name (iface.net_ifacename), and it must have the
122 driver/transport_name
123 The available drivers/iscsi_transports are tcp (software iSCSI
125 over TCP/IP), iser (software iSCSI over InfiniBand), qla4xxx
126 (Qlogic 4XXXX and 82XXX HBAs), cxgb3i and cxgb4i (Chelsio T3 and
127 T4 adapters), bnx2i (QLogic Netextreme II adapters), be2iscsi
128 (Emulex 10G adapter), qedi (QLogic QEDI 25/40/100Gb adapter),
129 and ocs (Emulex One Connect storage). Some of these are consid‐
130 ered experimental, as they are not fully tested.
131 The hwaddress is the MAC address or for software iSCSI it may be
133 the special value default which directs the initiator to not
134 bind the session to a specific hardware resource and instead al‐
135 low the network or InfiniBand layer to decide what to do. There
136 is no need to create an iface config with the default behavior.
137 If you do not specify an iface, then the default behavior is
138 used.
139 As mentioned above there is a special iface name default. There
141 are others which do not bind the session to a specific card, but
142 instead bind the session to the transport: iser, cxgb3i, cxgb4i,
143 and bnx2i.
144 In discovery mode multiple interfaces can be specified by pass‐
146 ing in multiple -I/--interface instances. For example:
147 sh# iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2
149 --discover
150 Will direct iscsiadm to setup the node db to create records
152 which will create sessions through the two intefaces passed in.
153 In node mode, only a single interface is supported in each call
155 to iscsiadm.
156 This option is valid for discovery, node and iface mode.
158 -k, --killiscsid=[priority]
160 Currently priority must be zero. This will immediately stop all
161 iscsid operations and shutdown iscsid. It does not logout any
162 sessions. Running this command is the same as doing killall isc‐
163 sid. Neither should normally be used, because if iscsid is doing
164 error recovery or if there is an error while iscsid is not run‐
165 ning, the system may not be able to recover. This command and
166 iscsid's SIGTERM handling are experimental.
167 -D, --discover
169 Discover targets using the discovery record with the recid
170 matching the the discovery type and portal passed in. If there
171 is no matching record, it will be created using the iscsid.conf
172 discovery settings. This must be passed in discoverydb mode to
173 instruct iscsiadm to perform discovery.
174 This option is only valid for SendTargets discovery mode.
176 -l, --login
178 For node and fw mode, login to a specified record. For discovery
179 mode, login to all discovered targets.
180 This option is only valid for discovery and node modes.
182 -L, --loginall=[all|manual|automatic|onboot]
184 For node mode, login all sessions with the node or conn startup
185 values passed in or all running session, except ones marked on‐
186 boot, if all is passed in.
187 This option is only valid for node mode (it is valid but not
189 functional for session mode).
190 -W, ---no_wait
192 In node mode, do not wait for a response from the targets. This
193 means that success will be returned if the command is able to
194 send the login requests, whether or not they succeed. In this
195 case, it will be up to the caller to poll for success (i.e. ses‐
196 sion creation).
197 -m, --mode op
199 specify the mode. op must be one of discovery, discoverydb,
200 node, fw, host iface or session.
201 If no other options are specified: for discovery, discoverydb
203 and node, all of their respective records are displayed; for
204 session, all active sessions and connections are displayed; for
205 fw, all boot firmware values are displayed; for host, all iSCSI
206 hosts are displayed; and for iface, all ifaces setup in
207 /var/lib/iscsi/ifaces are displayed.
208 -n, --name=name
210 In node mode, specify a field name in a record. In flashnode
211 submode of host mode, specify name of the flash node parameter.
212 For use with the update operator.
214 -o, --op=op
216 Specifies a database operator op. op must be one of new, delete,
217 update, show or nonpersistent.
218 For iface mode, apply and applyall are also applicable.
220 For flashnode submode of host mode, login and logout are also
222 applicable.
223 This option is valid for all modes except fw. Delete should not
225 be used on a running session. If it is iscsiadm will stop the
226 session and then delete the record.
227 new creates a new database record for a given object. In node
229 mode, the recid is the target name and portal (IP:port). In
230 iface mode, the recid is the iface name. In discovery mode, the
231 recid is the portal and discovery type.
232 In session mode, the new operation logs in a new session using
234 the same node database and iface information as the specified
235 session.
236 In discovery mode, if the recid and new operation is passed in,
238 but the --discover argument is not, then iscsiadm will only cre‐
239 ate a discovery record (it will not perform discovery). If the
240 --discover argument is passed in with the portal and discovery
241 type, then iscsiadm will create the discovery record if needed,
242 and it will create records for portals returned by the target
243 that do not yet have a node DB record.
244 delete deletes a specified recid. In discovery mode, if iscsiadm
246 is performing discovery it will delete records for portals that
247 are no longer returned.
248 update will update the recid with name to the specified value.
250 In discovery mode, if iscsiadm is performing discovery the re‐
251 cid, name and value arguments are not needed. The update opera‐
252 tion will operate on the portals returned by the target, and
253 will update the node records with info from the config file and
254 command line.
255 show is the default behaviour for node, discovery and iface
257 mode. It is also used when there are no commands passed into
258 session mode and a running sid is passed in. name and value are
259 currently ignored when used with show.
260 nonpersistent instructs iscsiadm to not manipulate the node DB.
262 apply will cause the network settings to take effect on the
264 specified iface.
265 applyall will cause the network settings to take effect on all
267 the ifaces whose MAC address or host number matches that of the
268 specific host.
269 login will log into the specified flash node entry.
271 logout does the logout from the given flash node entry.
273 -p, --portal=ip[:port]
275 Use target portal with ip-address ip and port. If port is not
276 passed in the default port value is 3260.
277 IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or
279 ddd.ddd.ddd.ddd.
280 Hostnames can also be used for the ip argument.
282 This option is only valid for discovery, or for node operations
284 with the new operator.
285 This should be used along with --target in node mode, to specify
287 what the open-iscsi docs refer to as a node or node record.
288 Note: open-iscsi's use of the word node, does not match the
289 iSCSI RFC's iSCSI Node term.
290 -P, --print=printlevel
292 If in node mode print nodes in tree format. If in session mode
293 print sessions in tree format. If in discovery mode print the
294 nodes in tree format.
295 -T, --targetname=targetname
297 Use target targetname.
298 This should be used along with --portal in node mode, to specify
300 what the open-iscsi docs refer to as a node or node record.
301 Note: open-iscsi's use of the word node, does not match the
302 iSCSI RFC's iSCSI Node term.
303 -r, --sid=sid | sysfsdir
305 Use session ID sid. The sid of a session can be found from run‐
306 ning iscsiadm in session mode with the --info argument.
307 Instead of sid, a sysfs path containing the session can be used.
309 For example using one of the following: /sys/devices/plat‐
310 form/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/plat‐
311 form/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
312 form/hostH/sessionS, for the sysfsdir argument would result in
313 the session with sid S to be used.
314 sid | sysfsdir is only required for session mode.
316 -R, --rescan
318 In session mode, if sid is also passed in rescan the session. If
319 no sid has been passed in rescan all running sessions.
320 In node mode, rescan a session running through the target, por‐
322 tal, iface tuple passed in.
323 -s, --stats
325 Display session statistics. This option when used with host
326 mode, displays host statistics.
327 -S, --show
329 When displaying records, do not hide masked values, such as the
330 CHAP secret (password).
331 This option is only valid for node and session mode.
333 -t, --type=type
335 type must be sendtargets (or abbreviated as st), slp, isns or
336 fw. Currently only sendtargets, fw, and iSNS is supported, see
337 the DISCOVERY TYPES section.
338 This option is only valid for discovery mode.
340 -u, --logout
342 logout for a specified record.
343 This option is only valid for node and session mode.
345 -U, --logoutall=[all,manual,automatic|onboot]
347 logout all sessions with the node or conn startup values passed
348 in or all running session, except ones marked onboot, if all is
349 passed in.
350 This option is only valid for node mode (it is valid but not
352 functional for session mode).
353 -v, --value=value
355 Specify a value for use with the update operator.
356 This option is only valid for node mode and flashnode submode of
358 host mode.
359 -V, --version
361 display version and exit
362 -x, --index=index
364 Specify the index of the entity to operate on.
365 This option is only valid for chap and flashnode submodes of
367 host mode.
368
370 iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
371 SendTargets
373 A native iSCSI protocol which allows each iSCSI target to send a
374 list of available targets to the initiator.
375 SLP Optionally an iSCSI target can use the Service Location Protocol
377 (SLP) to announce the available targets. The initiator can ei‐
378 ther implement SLP queries directly or can use a separate tool
379 to acquire the information about available targets.
380 iSNS iSNS (Internet Storage Name Service) records information about
382 storage volumes within a larger network. To utilize iSNS, pass
383 the address and optionally the port of the iSNS server to do
384 discovery to.
385 fw Several NICs and systems contain a mini iSCSI initiator which
387 can be used for boot. To get the values used for boot the fw op‐
388 tion can be used. Doing fw discovery, does not store persistent
389 records in the node or discovery DB, because the values are
390 stored in the system's or NIC's resource.
391 Performing fw discovery will print the portals, like with other
393 discovery methods. To see other settings like CHAP values and
394 initiator settings, like you would in node mode, run iscsiadm -m
395 fw.
396 fw support in open-iscsi is experimental. The settings and isc‐
398 siadm syntax and output format may change.
399 iscsiadm supports the iSNS (isns) or SendTargets (st) discovery type.
401 An SLP implementation is under development.
402
404 On success 0 is returned. On error one of the return codes below will
405 be returned.
406 Commands that operate on multiple objects (sessions, records, etc),
408 iscsiadm/iscsistart will return the first error that is encountered.
409 iscsiadm/iscsistart will attempt to execute the operation on the ob‐
410 jects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is re‐
411 turned.
412 0 ISCSI_SUCCESS - command executed successfully.
414 1 ISCSI_ERR - generic error code.
416 2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
418 3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
420 4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
422 5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
424 6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
426 7 ISCSI_ERR_INVAL - invalid argument.
428 8 ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying
430 to connect.
431 9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
433 10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
435 11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
437 12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
439 kernel or iscsid.
440 13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
442 iscsid or execute iscsiadm command.
443 14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
445 tion.
446 15 ISCSI_ERR_SESS_EXISTS - session is logged in.
448 16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
450 17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
452 18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
454 19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
456 20 ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
458 21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
460 found to execute operation on.
461 22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
463 23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
465 24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
467 failure.
468 25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
470 26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
472 failed.
473 27 ISCSI_ERR_OP_NOT_SUPP - operation not support
475 28 ISCSI_ERR_BUSY - device or resource in use
477 29 ISCSI_ERR_AGAIN - operation failed, but retrying later may suc‐
479 ceed
480 30 ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type
482 31 ISCSI_ERR_CHILD_TERMINATED - child process terminated
484 32 ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected
486
488 Discover targets at a given IP address:
489 sh# iscsiadm --mode discoverydb --type sendtargets --portal
491 192.168.1.10 --discover
492 Login, must use a node record id found by the discovery:
494 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
496 --portal 192.168.1.1:3260 --login
497 Logout:
499 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
501 --portal 192.168.1.1:3260 --logout
502 List node records:
504 sh# iscsiadm --mode node
506 Display all data for a given node record:
508 sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
510 --portal 192.168.1.1:3260
511
513 /etc/iscsi/iscsid.conf
514 The configuration file read by iscsid and iscsiadm on startup.
515 /etc/iscsi/initiatorname.iscsi
517 The file containing the iSCSI InitiatorName and InitiatorAlias
518 read by iscsid and iscsiadm on startup.
519 /var/lib/iscsi/nodes/
521 This directory contains the nodes with their targets.
522 /var/lib/iscsi/send_targets
524 This directory contains the portals.
525
527 iscsid(8)
528
530 Open-iSCSI project <http://www.open-iscsi.com/>
531 Alex Aizman <itn780@yahoo.com>
532 Dmitry Yusupov <dmitry_yus@yahoo.com>
533 Nov 2020 ISCSIADM(8)