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] [-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 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 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), 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 di‐
128 rects the initiator to not bind the session to a specific hard‐
129 ware resource and instead allow the network or InfiniBand layer
130 to decide what to do. There is no need to create an iface config
131 with the default behavior. If you do not specify an iface, then
132 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 on‐
181 boot, 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 -W, ---no_wait
187 In node mode, do not wait for a response from the targets. This
188 means that success will be returned if the command is able to
189 send the login requests, whether or not they succeed. In this
190 case, it will be up to the caller to poll for success (i.e. ses‐
191 sion creation).
192 -m, --mode op
194 specify the mode. op must be one of discovery, discoverydb,
195 node, fw, host iface or session.
196 If no other options are specified: for discovery, discoverydb
198 and node, all of their respective records are displayed; for
199 session, all active sessions and connections are displayed; for
200 fw, all boot firmware values are displayed; for host, all iSCSI
201 hosts are displayed; and for iface, all ifaces setup in
202 /var/lib/iscsi/ifaces are displayed.
203 -n, --name=name
205 In node mode, specify a field name in a record. In flashnode
206 submode of host mode, specify name of the flash node parameter.
207 For use with the update operator.
209 -o, --op=op
211 Specifies a database operator op. op must be one of new, delete,
212 update, show or nonpersistent.
213 For iface mode, apply and applyall are also applicable.
215 For flashnode submode of host mode, login and logout are also
217 applicable.
218 This option is valid for all modes except fw. Delete should not
220 be used on a running session. If it is iscsiadm will stop the
221 session and then delete the record.
222 new creates a new database record for a given object. In node
224 mode, the recid is the target name and portal (IP:port). In
225 iface mode, the recid is the iface name. In discovery mode, the
226 recid is the portal and discovery type.
227 In session mode, the new operation logs in a new session using
229 the same node database and iface information as the specified
230 session.
231 In discovery mode, if the recid and new operation is passed in,
233 but the --discover argument is not, then iscsiadm will only cre‐
234 ate a discovery record (it will not perform discovery). If the
235 --discover argument is passed in with the portal and discovery
236 type, then iscsiadm will create the discovery record if needed,
237 and it will create records for portals returned by the target
238 that do not yet have a node DB record.
239 delete deletes a specified recid. In discovery mode, if iscsiadm
241 is performing discovery it will delete records for portals that
242 are no longer returned.
243 update will update the recid with name to the specified value.
245 In discovery mode, if iscsiadm is performing discovery the re‐
246 cid, name and value arguments are not needed. The update opera‐
247 tion will operate on the portals returned by the target, and
248 will update the node records with info from the config file and
249 command line.
250 show is the default behaviour for node, discovery and iface
252 mode. It is also used when there are no commands passed into
253 session mode and a running sid is passed in. name and value are
254 currently ignored when used with show.
255 nonpersistent instructs iscsiadm to not manipulate the node DB.
257 apply will cause the network settings to take effect on the
259 specified iface.
260 applyall will cause the network settings to take effect on all
262 the ifaces whose MAC address or host number matches that of the
263 specific host.
264 login will log into the specified flash node entry.
266 logout does the logout from the given flash node entry.
268 -p, --portal=ip[:port]
270 Use target portal with ip-address ip and port. If port is not
271 passed in the default port value is 3260.
272 IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or
274 ddd.ddd.ddd.ddd.
275 Hostnames can also be used for the ip argument.
277 This option is only valid for discovery, or for node operations
279 with the new operator.
280 This should be used along with --target in node mode, to specify
282 what the open-iscsi docs refer to as a node or node record.
283 Note: open-iscsi's use of the word node, does not match the
284 iSCSI RFC's iSCSI Node term.
285 -P, --print=printlevel
287 If in node mode print nodes in tree format. If in session mode
288 print sessions in tree format. If in discovery mode print the
289 nodes in tree format.
290 -T, --targetname=targetname
292 Use target targetname.
293 This should be used along with --portal in node mode, to specify
295 what the open-iscsi docs refer to as a node or node record.
296 Note: open-iscsi's use of the word node, does not match the
297 iSCSI RFC's iSCSI Node term.
298 -r, --sid=sid | sysfsdir
300 Use session ID sid. The sid of a session can be found from run‐
301 ning iscsiadm in session mode with the --info argument.
302 Instead of sid, a sysfs path containing the session can be used.
304 For example using one of the following: /sys/devices/plat‐
305 form/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/plat‐
306 form/hostH/sessionS/targetH:B:I, or /sys/devices/plat‐
307 form/hostH/sessionS, for the sysfsdir argument would result in
308 the session with sid S to be used.
309 sid | sysfsdir is only required for session mode.
311 -R, --rescan
313 In session mode, if sid is also passed in rescan the session. If
314 no sid has been passed in rescan all running sessions.
315 In node mode, rescan a session running through the target, por‐
317 tal, iface tuple passed in.
318 -s, --stats
320 Display session statistics. This option when used with host
321 mode, displays host statistics.
322 -S, --show
324 When displaying records, do not hide masked values, such as the
325 CHAP secret (password).
326 This option is only valid for node and session mode.
328 -t, --type=type
330 type must be sendtargets (or abbreviated as st), slp, isns or
331 fw. Currently only sendtargets, fw, and iSNS is supported, see
332 the DISCOVERY TYPES section.
333 This option is only valid for discovery mode.
335 -u, --logout
337 logout for a specified record.
338 This option is only valid for node and session mode.
340 -U, --logoutall=[all,manual,automatic|onboot]
342 logout all sessions with the node or conn startup values passed
343 in or all running session, except ones marked onboot, if all is
344 passed in.
345 This option is only valid for node mode (it is valid but not
347 functional for session mode).
348 -v, --value=value
350 Specify a value for use with the update operator.
351 This option is only valid for node mode and flashnode submode of
353 host mode.
354 -V, --version
356 display version and exit
357 -x, --index=index
359 Specify the index of the entity to operate on.
360 This option is only valid for chap and flashnode submodes of
362 host mode.
363
365 iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
366 SendTargets
368 A native iSCSI protocol which allows each iSCSI target to send a
369 list of available targets to the initiator.
370 SLP Optionally an iSCSI target can use the Service Location Protocol
372 (SLP) to announce the available targets. The initiator can ei‐
373 ther implement SLP queries directly or can use a separate tool
374 to acquire the information about available targets.
375 iSNS iSNS (Internet Storage Name Service) records information about
377 storage volumes within a larger network. To utilize iSNS, pass
378 the address and optionally the port of the iSNS server to do
379 discovery to.
380 fw Several NICs and systems contain a mini iSCSI initiator which
382 can be used for boot. To get the values used for boot the fw op‐
383 tion can be used. Doing fw discovery, does not store persistent
384 records in the node or discovery DB, because the values are
385 stored in the system's or NIC's resource.
386 Performing fw discovery will print the portals, like with other
388 discovery methods. To see other settings like CHAP values and
389 initiator settings, like you would in node mode, run "iscsiadm
390 -m fw".
391 fw support in open-iscsi is experimental. The settings and isc‐
393 siadm syntax and output format may change.
394 iscsiadm supports the iSNS (isns) or SendTargets (st) discovery type.
396 An SLP implementation is under development.
397
399 On success 0 is returned. On error one of the return codes below will
400 be returned.
401 Commands that operate on multiple objects (sessions, records, etc),
403 iscsiadm/iscsistart will return the first error that is encountered.
404 iscsiadm/iscsistart will attempt to execute the operation on the ob‐
405 jects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is re‐
406 turned.
407 0 ISCSI_SUCCESS - command executed successfully.
409 1 ISCSI_ERR - generic error code.
411 2 ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
413 3 ISCSI_ERR_NOMEM - could not allocate resource for operation.
415 4 ISCSI_ERR_TRANS - connect problem caused operation to fail.
417 5 ISCSI_ERR_LOGIN - generic iSCSI login failure.
419 6 ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
421 7 ISCSI_ERR_INVAL - invalid argument.
423 8 ISCSI_ERR_TRANS_TIMEOUT - connection timer exired while trying
425 to connect.
426 9 ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
428 10 ISCSI_ERR_LOGOUT - iSCSI logout failed.
430 11 ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
432 12 ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
434 kernel or iscsid.
435 13 ISCSI_ERR_ACCESS - did not have proper OS permissions to access
437 iscsid or execute iscsiadm command.
438 14 ISCSI_ERR_TRANS_CAPS - transport module did not support opera‐
440 tion.
441 15 ISCSI_ERR_SESS_EXISTS - session is logged in.
443 16 ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
445 17 ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
447 18 ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
449 19 ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
451 20 ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
453 21 ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals
455 found to execute operation on.
456 22 ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
458 23 ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
460 24 ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization
462 failure.
463 25 ISCSI_ERR_ISNS_QUERY - iSNS query failure.
465 26 ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration
467 failed.
468
470 Discover targets at a given IP address:
471 iscsiadm --mode discoverydb --type sendtargets --portal
473 192.168.1.10 --discover
474 Login, must use a node record id found by the discovery:
476 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
478 --portal 192.168.1.1:3260 --login
479 Logout:
481 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
483 --portal 192.168.1.1:3260 --logout
484 List node records:
486 iscsiadm --mode node
488 Display all data for a given node record:
490 iscsiadm --mode node --targetname iqn.2001-05.com.doe:test
492 --portal 192.168.1.1:3260
493
495 /etc/iscsi/iscsid.conf
496 The configuration file read by iscsid and iscsiadm on startup.
497 /etc/iscsi/initiatorname.iscsi
499 The file containing the iSCSI InitiatorName and InitiatorAlias
500 read by iscsid and iscsiadm on startup.
501 /var/lib/iscsi/nodes/
503 This directory contains the nodes with their targets.
504 /var/lib/iscsi/send_targets
506 This directory contains the portals.
507
509 iscsid(8)
510
512 Open-iSCSI project <http://www.open-iscsi.com/>
513 Alex Aizman <itn780@yahoo.com>
514 Dmitry Yusupov <dmitry_yus@yahoo.com>
515 Sep 2006 ISCSIADM(8)