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] [.BI -I
10 iface -t type -p ip:port [-lD] ] | [ [-p ip:port -t type] [-o oper‐
11 ation] [-n name] [-v value] [-lD] ]
12 iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [.BI -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] [-U all,manual,automatic] [-S] [ [-T target‐
18 name -p ip:port -I iface ] [-l|-u|-R|-s] ] [ [-o operation] [-n name]
19 [-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 ifacename
25 | -H hostno|MAC ] [ [-o operation] [-n name] [-v value] ] [ -C ping [-a
26 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
38 The iscsiadm utility is a command-line tool allowing discovery and
39 login to iSCSI targets, as well as access and management of the open-
40 iscsi database.
41 Open-iscsi does not use the term node as defined by the iSCSI RFC,
43 where a node is a single iSCSI initiator or target. Open-iscsi uses the
44 term node to refer to a portal on a target.
45 For session mode, a session id (sid) is used. The sid of a session can
47 be found by running iscsiadm -m session -P 1. The session id and sysfs
48 path are not currently persistent and is partially determined by when
49 the session is setup.
50 Note that many of the node and discovery operations require that the
53 iSCSI daemon (iscsid) be running.
54
57 -a, --ip=ipaddr
58 ipaddr can be IPv4 or IPv6.
59 This option is only valid for ping submode.
61 -A, --portal_type=[ipv4|ipv6]
64 Specify the portal type for the new flash node entry to be cre‐
65 ated.
66 This option is only valid for flashnode submode of host mode and
68 only with new operation.
69 -b, --packetsize=packetsize
72 Specify the ping packetsize.
73 This option is only valid for ping submode.
75 -c, --count=count
78 count specify number of ping iterations.
79 This option is only valid for ping submode.
81 -C, --submode=op
84 Specify the submode for mode. op must be name of submode.
85 Currently iscsiadm support ping as submode for iface. For exam‐
87 ple,
88 iscsiadm -m iface -I ifacename -C ping -a ipaddr -b packetsize
90 -c count -i interval
91 For host, it supports chap , flashnode and stats as submodes.
93 For example,
94 iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation
96 iscsiadm -m host -H hostno -C flashnode -x flashnode_idx -o
98 operation
99 iscsiadm -m host -H hostno -C stats
101 -d, --debug=debug_level
104 print debugging information. Valid values for debug_level are 0
105 to 8.
106 -h, --help
109 display help text and exit
110 -H, --host=[hostno|MAC]
113 The host argument specifies the SCSI host to use for the opera‐
114 tion. It can be the scsi host number assigned to the host by the
115 kernel's scsi layer, or the MAC address of a scsi host.
116 -i, --interval=interval
119 interval specify delay between two ping iterations.
120 This option is only valid for ping submode.
122 -I, --interface=[iface]
125 The interface argument specifies the iSCSI interface to use for
126 the operation. iSCSI interfaces (iface) are defined in
127 /var/lib/iscsi/ifaces. For hardware iSCSI (qla4xxx) the iface
128 config must have the hardware address (iface.hwaddress = port's
129 MAC address) and the driver/transport_name (iface.trans‐
130 port_name). The iface's name is then the filename of the iface
131 config. For software iSCSI, the iface config must have either
132 the hardware address (iface.hwaddress), or the network layer's
133 interface name (iface.net_ifacename), and it must have the
134 driver/transport_name
135 The available drivers/iscsi_transports are tcp (software iSCSI
137 over TCP/IP), iser (software iSCSI over InfiniBand), or qla4xxx
138 (Qlogic 4XXXX HBAs). The hwaddress is the MAC address or for
139 software iSCSI it may be the special value "default" which
140 directs the initiator to not bind the session to a specific
141 hardware resource and instead allow the network or InfiniBand
142 layer to decide what to do. There is no need to create an iface
143 config with the default behavior. If you do not specify an
144 iface, then the default behavior is used.
145 As mentioned above there is a special iface name default. There
147 are three others -- cxgb3i, bnx2i and iser, which does not bind
148 the session to a specific card, but will bind the session to the
149 cxgb3i, bnx2i or iser transport. These are experimental and the
150 use is not supported as a stable interface yet.
151 In discovery mode multiple interfaces can be specified by pass‐
153 ing in multiple -I/--interface instances. For example,
154 "iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2
156 --discover"
157 Will direct iscsiadm to setup the node db to create records
159 which will create sessions through the two intefaces passed in.
160 In node mode, only a single interface is supported in each call
162 to iscsiadm.
163 This option is valid for discovery, node and iface mode.
165 -k, --killiscsid=[priority]
168 Currently priority must be zero. This will immediately stop all
169 iscsid operations and shutdown iscsid. It does not logout any
170 sessions. Running this command is the same as doing "killall
171 iscsid". Neither should normally be used, because if iscsid is
172 doing error recovery or if there is an error while iscsid is not
173 running, the system may not be able to recover. This command
174 and iscsid's SIGTERM handling are experimental.
175 -D, --discover
178 Discover targets using the discovery record with the recid
179 matching the the discovery type and portal passed in. If there
180 is no matching record, it will be created using the iscsid.conf
181 discovery settings. This must be passed in discoverydb mode to
182 instruct iscsiadm to perform discovery.
183 This option is only valid for SendTargets discovery mode.
185 -l, --login
188 For node and fw mode, login to a specified record. For discovery
189 mode, login to all discovered targets.
190 This option is only valid for discovery and node modes.
192 -L, --loginall=[all|manual|automatic]
195 For node mode, login all sessions with the node or conn startup
196 values passed in or all running session, except ones marked
197 onboot, if all is passed in.
198 This option is only valid for node mode (it is valid but not
200 functional for session mode).
201 -m, --mode op
205 specify the mode. op must be one of discovery, discoverydb,
206 node, fw, host iface or session.
207 If no other options are specified: for discovery, discoverydb
209 and node, all of their respective records are displayed; for
210 session, all active sessions and connections are displayed; for
211 fw, all boot firmware values are displayed; for host, all iSCSI
212 hosts are displayed; and for iface, all ifaces setup in
213 /var/lib/iscsi/ifaces are displayed.
214 -n, --name=name
217 In node mode, specify a field name in a record. In flashnode
218 submode of host mode, specify name of the flash node parameter.
219 For use with the update operator.
221 -o, --op=op
223 Specifies a database operator op. op must be one of new, delete,
224 update, show or nonpersistent.
225 For iface mode, apply and applyall are also applicable.
227 For flashnode submode of host mode, login and logout are also
229 applicable.
230 This option is valid for all modes except fw. Delete should not
232 be used on a running session. If it is iscsiadm will stop the
233 session and then delete the record.
234 new creates a new database record for a given object. In node
236 mode, the recid is the target name and portal (IP:port). In
237 iface mode, the recid is the iface name. In discovery mode, the
238 recid is the portal and discovery type.
239 In session mode, the new operation logs in a new session using
241 the same node database and iface information as the specified
242 session.
243 In discovery mode, if the recid and new operation is passed in,
245 but the --discover argument is not, then iscsiadm will only cre‐
246 ate a discovery record (it will not perform discovery). If the
247 --discover argument is passed in with the portal and discovery
248 type, then iscsiadm will create the discovery record if needed,
249 and it will create records for portals returned by the target
250 that do not yet have a node DB record.
251 delete deletes a specified recid. In discovery mode, if iscsiadm
253 is performing discovery it will delete records for portals that
254 are no longer returned.
255 update will update the recid with name to the specified value.
257 In discovery mode, if iscsiadm is performing discovery the
258 recid, name and value arguments are not needed. The update
259 operation will operate on the portals returned by the target,
260 and will update the node records with info from the config file
261 and command line.
262 show is the default behaviour for node, discovery and iface
264 mode. It is also used when there are no commands passed into
265 session mode and a running sid is passed in. name and value are
266 currently ignored when used with show.
267 nonpersistent instructs iscsiadm to not manipulate the node DB.
269 apply will cause the network settings to take effect on the
272 specified iface.
273 applyall will cause the network settings to take effect on all
276 the ifaces whose MAC address or host number matches that of the
277 specific host.
278 login will log into the specified flash node entry.
281 logout does the logout from the given flash node entry.
284 -p, --portal=ip[:port]
287 Use target portal with ip-address ip and port. If port is not
288 passed in the default port value is 3260.
289 IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or
291 ddd.ddd.ddd.ddd.
292 Hostnames can also be used for the ip argument.
294 This option is only valid for discovery, or for node operations
297 with the new operator.
298 This should be used along with --target 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 -P, --print=printlevel
306 If in node mode print nodes in tree format. If in session mode
307 print sessions in tree format. If in discovery mode print the
308 nodes in tree format.
309 -T, --targetname=targetname
312 Use target targetname.
313 This should be used along with --portal in node mode, to specify
315 what the open-iscsi docs refer to as a node or node record.
316 Note: open-iscsi's use of the word node, does not match the
317 iSCSI RFC's iSCSI Node term.
318 -r, --sid=sid | sysfsdir
321 Use session ID sid. The sid of a session can be found from run‐
322 ning iscsiadm in session mode with the --info argument.
323 Instead of sid, a sysfs path containing the session can be used.
325 For example using one of the following: /sys/devices/plat‐
326 form/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/plat‐
327 form/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
328 form/hostH/sessionS, for the sysfsdir argument would result in
329 the session with sid S to be used.
330 sid | sysfsdir is only required for session mode.
332 -R, --rescan
335 In session mode, if sid is also passed in rescan the session. If
336 no sid has been passed in rescan all running sessions.
337 In node mode, rescan a session running through the target, por‐
339 tal, iface tuple passed in.
340 -s, --stats
343 Display session statistics. This option when used with host
344 mode, displays host statistics.
345 -S, --show
348 When displaying records, do not hide masked values, such as the
349 CHAP secret (password).
350 This option is only valid for node and session mode.
352 -t, --type=type
355 type must be sendtargets (or abbreviated as st), slp, isns or
356 fw. Currently only sendtargets, fw, and iSNS is supported, see
357 the DISCOVERY TYPES section.
358 This option is only valid for discovery mode.
360 -u, --logout
363 logout for a specified record.
364 This option is only valid for node and session mode.
366 -U, --logoutall=[all,manual,automatic]
369 logout all sessions with the node or conn startup values passed
370 in or all running session, except ones marked onboot, if all is
371 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
378 Specify a value for use with the update operator.
379 This option is only valid for node mode and flashnode submode of
381 host mode.
382 -V, --version
385 display version and exit
386 -x, --index=index
389 Specify the index of the entity to operate on.
390 This option is only valid for chap and flashnode submodes of
392 host mode.
393
396 iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
397 SendTargets
400 A native iSCSI protocol which allows each iSCSI target to send a
401 list of available targets to the initiator.
402 SLP Optionally an iSCSI target can use the Service Location Protocol
405 (SLP) to announce the available targets. The initiator can
406 either implement SLP queries directly or can use a separate tool
407 to acquire the information about available targets.
408 iSNS iSNS (Internet Storage Name Service) records information about
411 storage volumes within a larger network. To utilize iSNS, pass
412 the address and optionally the port of the iSNS server to do
413 discovery to.
414 fw Several NICs and systems contain a mini iSCSI initiator which
417 can be used for boot. To get the values used for boot the fw
418 option can be used. Doing fw discovery, does not store persis‐
419 tent records in the node or discovery DB, because the values are
420 stored in the system's or NIC's resource.
421 Performing fw discovery will print the portals, like with other
423 discovery methods. To see other settings like CHAP values and
424 initiator settings, like you would in node mode, run "iscsiadm
425 -m fw".
426 fw support in open-iscsi is experimental. The settings and isc‐
428 siadm syntax and output format may change.
429 iscsiadm supports the iSNS (isns) or SendTargets (st) discovery type.
432 An SLP implementation is under development.
433
436 On success 0 is returned. On error one of the return codes below will
437 be returned.
438 Commands that operate on multiple objects (sessions, records, etc),
440 iscsiadm/iscsistart will return the first error that is encountered.
441 iscsiadm/iscsistart will attempt to execute the operation on the
442 objects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is
443 returned.
444 0 ISCSI_SUCCESS - command executed successfully.
448 1 ISCSI_ERR - generic error code.
451 2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
454 3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
457 4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
459 5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
462 6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
465 7 ISCSI_ERR_INVAL - invalid argument.
468 8 ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying
471 to connect.
472 9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
475 10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
478 11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
481 12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
484 kernel or iscsid.
485 13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
488 iscsid or execute iscsiadm command.
489 14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
492 tion.
493 15 ISCSI_ERR_SESS_EXISTS - session is logged in.
496 16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
499 17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
502 18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
505 19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
508 20 ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
511 21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
514 found to execute operation on.
515 22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
518 23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
521 24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
524 failure.
525 25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
528 26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
531 failed.
532
536 Discover targets at a given IP address:
537 iscsiadm --mode discoverydb --type sendtargets --portal 192.168.1.10 --discover
539 Login, must use a node record id found by the discovery:
541 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login
543 Logout:
545 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout
547 List node records:
549 iscsiadm --mode node
551 Display all data for a given node record:
554 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260
556
559 /etc/iscsi/iscsid.conf
560 The configuration file read by iscsid and iscsiadm on startup.
561 /etc/iscsi/initiatorname.iscsi
563 The file containing the iSCSI InitiatorName and InitiatorAlias
564 read by iscsid and iscsiadm on startup.
565 /var/lib/iscsi/nodes/
567 This directory contains the nodes with their targets.
568 /var/lib/iscsi/send_targets
570 This directory contains the portals.
571
574 iscsid(8)
575
578 Open-iSCSI project <http://www.open-iscsi.com/>
579 Alex Aizman <itn780@yahoo.com>
580 Dmitry Yusupov <dmitry_yus@yahoo.com>
581 Sep 2006 ISCSIADM(8)