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,onboot] [-U all,manual,automatic,onboot] [-S] [ [-T tar‐
18 getname -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 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
37 The iscsiadm utility is a command-line tool allowing discovery and
38 login 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
91 operation
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), or qla4xxx
126 (Qlogic 4XXXX HBAs). The hwaddress is the MAC address or for
127 software iSCSI it may be the special value "default" which
128 directs the initiator to not bind the session to a specific
129 hardware resource and instead allow the network or InfiniBand
130 layer to decide what to do. There is no need to create an iface
131 config with the default behavior. If you do not specify an
132 iface, then the default behavior is used.
133 As mentioned above there is a special iface name default. There
135 are three others -- cxgb3i, bnx2i and iser, which does not bind
136 the session to a specific card, but will bind the session to the
137 cxgb3i, bnx2i or iser transport. These are experimental and the
138 use is not supported as a stable interface yet.
139 In discovery mode multiple interfaces can be specified by pass‐
141 ing in multiple -I/--interface instances. For example:
142 "iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2
144 --discover"
145 Will direct iscsiadm to setup the node db to create records
147 which will create sessions through the two intefaces passed in.
148 In node mode, only a single interface is supported in each call
150 to iscsiadm.
151 This option is valid for discovery, node and iface mode.
153 -k, --killiscsid=[priority]
155 Currently priority must be zero. This will immediately stop all
156 iscsid operations and shutdown iscsid. It does not logout any
157 sessions. Running this command is the same as doing "killall
158 iscsid". Neither should normally be used, because if iscsid is
159 doing error recovery or if there is an error while iscsid is not
160 running, the system may not be able to recover. This command
161 and iscsid's SIGTERM handling are experimental.
162 -D, --discover
164 Discover targets using the discovery record with the recid
165 matching the the discovery type and portal passed in. If there
166 is no matching record, it will be created using the iscsid.conf
167 discovery settings. This must be passed in discoverydb mode to
168 instruct iscsiadm to perform discovery.
169 This option is only valid for SendTargets discovery mode.
171 -l, --login
173 For node and fw mode, login to a specified record. For discovery
174 mode, login to all discovered targets.
175 This option is only valid for discovery and node modes.
177 -L, --loginall=[all|manual|automatic|onboot]
179 For node mode, login all sessions with the node or conn startup
180 values passed in or all running session, except ones marked
181 onboot, if all is passed in.
182 This option is only valid for node mode (it is valid but not
184 functional for session mode).
185 -m, --mode op
187 specify the mode. op must be one of discovery, discoverydb,
188 node, fw, host iface or session.
189 If no other options are specified: for discovery, discoverydb
191 and node, all of their respective records are displayed; for
192 session, all active sessions and connections are displayed; for
193 fw, all boot firmware values are displayed; for host, all iSCSI
194 hosts are displayed; and for iface, all ifaces setup in
195 /var/lib/iscsi/ifaces are displayed.
196 -n, --name=name
198 In node mode, specify a field name in a record. In flashnode
199 submode of host mode, specify name of the flash node parameter.
200 For use with the update operator.
202 -o, --op=op
204 Specifies a database operator op. op must be one of new, delete,
205 update, show or nonpersistent.
206 For iface mode, apply and applyall are also applicable.
208 For flashnode submode of host mode, login and logout are also
210 applicable.
211 This option is valid for all modes except fw. Delete should not
213 be used on a running session. If it is iscsiadm will stop the
214 session and then delete the record.
215 new creates a new database record for a given object. In node
217 mode, the recid is the target name and portal (IP:port). In
218 iface mode, the recid is the iface name. In discovery mode, the
219 recid is the portal and discovery type.
220 In session mode, the new operation logs in a new session using
222 the same node database and iface information as the specified
223 session.
224 In discovery mode, if the recid and new operation is passed in,
226 but the --discover argument is not, then iscsiadm will only cre‐
227 ate a discovery record (it will not perform discovery). If the
228 --discover argument is passed in with the portal and discovery
229 type, then iscsiadm will create the discovery record if needed,
230 and it will create records for portals returned by the target
231 that do not yet have a node DB record.
232 delete deletes a specified recid. In discovery mode, if iscsiadm
234 is performing discovery it will delete records for portals that
235 are no longer returned.
236 update will update the recid with name to the specified value.
238 In discovery mode, if iscsiadm is performing discovery the
239 recid, name and value arguments are not needed. The update
240 operation will operate on the portals returned by the target,
241 and will update the node records with info from the config file
242 and command line.
243 show is the default behaviour for node, discovery and iface
245 mode. It is also used when there are no commands passed into
246 session mode and a running sid is passed in. name and value are
247 currently ignored when used with show.
248 nonpersistent instructs iscsiadm to not manipulate the node DB.
250 apply will cause the network settings to take effect on the
252 specified iface.
253 applyall will cause the network settings to take effect on all
255 the ifaces whose MAC address or host number matches that of the
256 specific host.
257 login will log into the specified flash node entry.
259 logout does the logout from the given flash node entry.
261 -p, --portal=ip[:port]
263 Use target portal with ip-address ip and port. If port is not
264 passed in the default port value is 3260.
265 IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or
267 ddd.ddd.ddd.ddd.
268 Hostnames can also be used for the ip argument.
270 This option is only valid for discovery, or for node operations
272 with the new operator.
273 This should be used along with --target in node mode, to specify
275 what the open-iscsi docs refer to as a node or node record.
276 Note: open-iscsi's use of the word node, does not match the
277 iSCSI RFC's iSCSI Node term.
278 -P, --print=printlevel
280 If in node mode print nodes in tree format. If in session mode
281 print sessions in tree format. If in discovery mode print the
282 nodes in tree format.
283 -T, --targetname=targetname
285 Use target targetname.
286 This should be used along with --portal in node mode, to specify
288 what the open-iscsi docs refer to as a node or node record.
289 Note: open-iscsi's use of the word node, does not match the
290 iSCSI RFC's iSCSI Node term.
291 -r, --sid=sid | sysfsdir
293 Use session ID sid. The sid of a session can be found from run‐
294 ning iscsiadm in session mode with the --info argument.
295 Instead of sid, a sysfs path containing the session can be used.
297 For example using one of the following: /sys/devices/plat‐
298 form/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/plat‐
299 form/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
300 form/hostH/sessionS, for the sysfsdir argument would result in
301 the session with sid S to be used.
302 sid | sysfsdir is only required for session mode.
304 -R, --rescan
306 In session mode, if sid is also passed in rescan the session. If
307 no sid has been passed in rescan all running sessions.
308 In node mode, rescan a session running through the target, por‐
310 tal, iface tuple passed in.
311 -s, --stats
313 Display session statistics. This option when used with host
314 mode, displays host statistics.
315 -S, --show
317 When displaying records, do not hide masked values, such as the
318 CHAP secret (password).
319 This option is only valid for node and session mode.
321 -t, --type=type
323 type must be sendtargets (or abbreviated as st), slp, isns or
324 fw. Currently only sendtargets, fw, and iSNS is supported, see
325 the DISCOVERY TYPES section.
326 This option is only valid for discovery mode.
328 -u, --logout
330 logout for a specified record.
331 This option is only valid for node and session mode.
333 -U, --logoutall=[all,manual,automatic|onboot]
335 logout all sessions with the node or conn startup values passed
336 in or all running session, except ones marked onboot, if all is
337 passed in.
338 This option is only valid for node mode (it is valid but not
340 functional for session mode).
341 -v, --value=value
343 Specify a value for use with the update operator.
344 This option is only valid for node mode and flashnode submode of
346 host mode.
347 -V, --version
349 display version and exit
350 -x, --index=index
352 Specify the index of the entity to operate on.
353 This option is only valid for chap and flashnode submodes of
355 host mode.
356
358 iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
359 SendTargets
361 A native iSCSI protocol which allows each iSCSI target to send a
362 list of available targets to the initiator.
363 SLP Optionally an iSCSI target can use the Service Location Protocol
365 (SLP) to announce the available targets. The initiator can
366 either implement SLP queries directly or can use a separate tool
367 to acquire the information about available targets.
368 iSNS iSNS (Internet Storage Name Service) records information about
370 storage volumes within a larger network. To utilize iSNS, pass
371 the address and optionally the port of the iSNS server to do
372 discovery to.
373 fw Several NICs and systems contain a mini iSCSI initiator which
375 can be used for boot. To get the values used for boot the fw
376 option can be used. Doing fw discovery, does not store persis‐
377 tent records in the node or discovery DB, because the values are
378 stored in the system's or NIC's resource.
379 Performing fw discovery will print the portals, like with other
381 discovery methods. To see other settings like CHAP values and
382 initiator settings, like you would in node mode, run "iscsiadm
383 -m fw".
384 fw support in open-iscsi is experimental. The settings and isc‐
386 siadm syntax and output format may change.
387 iscsiadm supports the iSNS (isns) or SendTargets (st) discovery type.
389 An SLP implementation is under development.
390
392 On success 0 is returned. On error one of the return codes below will
393 be returned.
394 Commands that operate on multiple objects (sessions, records, etc),
396 iscsiadm/iscsistart will return the first error that is encountered.
397 iscsiadm/iscsistart will attempt to execute the operation on the
398 objects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is
399 returned.
400 0 ISCSI_SUCCESS - command executed successfully.
402 1 ISCSI_ERR - generic error code.
404 2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
406 3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
408 4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
410 5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
412 6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
414 7 ISCSI_ERR_INVAL - invalid argument.
416 8 ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying
418 to connect.
419 9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
421 10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
423 11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
425 12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
427 kernel or iscsid.
428 13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
430 iscsid or execute iscsiadm command.
431 14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
433 tion.
434 15 ISCSI_ERR_SESS_EXISTS - session is logged in.
436 16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
438 17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
440 18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
442 19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
444 20 ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
446 21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
448 found to execute operation on.
449 22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
451 23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
453 24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
455 failure.
456 25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
458 26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
460 failed.
461
463 Discover targets at a given IP address:
464 iscsiadm --mode discoverydb --type sendtargets --portal
466 192.168.1.10 --discover
467 Login, must use a node record id found by the discovery:
469 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
471 --portal 192.168.1.1:3260 --login
472 Logout:
474 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
476 --portal 192.168.1.1:3260 --logout
477 List node records:
479 iscsiadm --mode node
481 Display all data for a given node record:
483 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
485 --portal 192.168.1.1:3260
486
488 /etc/iscsi/iscsid.conf
489 The configuration file read by iscsid and iscsiadm on startup.
490 /etc/iscsi/initiatorname.iscsi
492 The file containing the iSCSI InitiatorName and InitiatorAlias
493 read by iscsid and iscsiadm on startup.
494 /var/lib/iscsi/nodes/
496 This directory contains the nodes with their targets.
497 /var/lib/iscsi/send_targets
499 This directory contains the portals.
500
502 iscsid(8)
503
505 Open-iSCSI project <http://www.open-iscsi.com/>
506 Alex Aizman <itn780@yahoo.com>
507 Dmitry Yusupov <dmitry_yus@yahoo.com>
508 Sep 2006 ISCSIADM(8)