1ISCSIADM(8)              Linux Administrator's Manual              ISCSIADM(8)
2
3
4

NAME

6       iscsiadm - open-iscsi administration utility
7

SYNOPSIS

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
13       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
16       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
21       iscsiadm  -m  session  [-hV] [-d debug_level] [-P printlevel] [ -r ses‐
22       sionid|sysfsdir [-R] [-u|-s|-o new] ]
23
24       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
28       iscsiadm -m fw [-d debug_level] [-l]
29
30       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
34       iscsiadm -k priority
35
36

DESCRIPTION

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
42       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
46       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
51
52       Note  that  many  of the node and discovery operations require that the
53       iSCSI daemon (iscsid) be running.
54
55

OPTIONS

57       -a, --ip=ipaddr
58              ipaddr can be IPv4 or IPv6.
59
60              This option is only valid for ping submode.
61
62
63       -A, --portal_type=[ipv4|ipv6]
64              Specify the portal type for the new flash node entry to be  cre‐
65              ated.
66
67              This option is only valid for flashnode submode of host mode and
68              only with new operation.
69
70
71       -b, --packetsize=packetsize
72              Specify the ping packetsize.
73
74              This option is only valid for ping submode.
75
76
77       -c, --count=count
78              count specify number of ping iterations.
79
80              This option is only valid for ping submode.
81
82
83       -C, --submode=op
84              Specify the submode for mode. op must be name of submode.
85
86              Currently iscsiadm support ping as submode for iface. For  exam‐
87              ple,
88
89              iscsiadm  -m  iface -I ifacename -C ping -a ipaddr -b packetsize
90              -c count -i interval
91
92              For host, it supports chap , flashnode and  stats  as  submodes.
93              For example,
94
95              iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation
96
97              iscsiadm  -m  host  -H  hostno  -C flashnode -x flashnode_idx -o
98              operation
99
100              iscsiadm -m host -H hostno -C stats
101
102
103       -d, --debug=debug_level
104              print debugging information. Valid values for debug_level are  0
105              to 8.
106
107
108       -h, --help
109              display help text and exit
110
111
112       -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
117
118       -i, --interval=interval
119              interval specify delay between two ping iterations.
120
121              This option is only valid for ping submode.
122
123
124       -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
136              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
146              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
152              In discovery mode multiple interfaces can be specified by  pass‐
153              ing in multiple -I/--interface instances. For example,
154
155              "iscsiadm  -m  discoverydb  -t st -p ip:port -I iface0 -I iface2
156              --discover"
157
158              Will direct iscsiadm to setup the  node  db  to  create  records
159              which will create sessions through the two intefaces passed in.
160
161              In  node mode, only a single interface is supported in each call
162              to iscsiadm.
163
164              This option is valid for discovery, node and iface mode.
165
166
167       -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
176
177       -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
184              This option is only valid for SendTargets discovery mode.
185
186
187       -l, --login
188              For node and fw mode, login to a specified record. For discovery
189              mode, login to all discovered targets.
190
191              This option is only valid for discovery and node modes.
192
193
194       -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
199              This  option  is  only  valid for node mode (it is valid but not
200              functional for session mode).
201
202
203
204       -m, --mode op
205              specify the mode. op must  be  one  of  discovery,  discoverydb,
206              node, fw, host iface or session.
207
208              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
215
216       -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
220              For use with the update operator.
221
222       -o, --op=op
223              Specifies a database operator op. op must be one of new, delete,
224              update, show or nonpersistent.
225
226              For iface mode, apply and applyall  are also applicable.
227
228              For flashnode submode of host mode, login and  logout  are  also
229              applicable.
230
231              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
235              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
240              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
244              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
252              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
256              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
263              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
268              nonpersistent instructs iscsiadm to not manipulate the node DB.
269
270
271              apply will cause the network settings  to  take  effect  on  the
272              specified iface.
273
274
275              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
279
280              login will log into the specified flash node entry.
281
282
283              logout does the logout from the given flash node entry.
284
285
286       -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
290              IPv6 addresses can be  specified  as  [ddd.ddd.ddd.ddd]:port  or
291              ddd.ddd.ddd.ddd.
292
293              Hostnames can also be used for the ip argument.
294
295
296              This  option is only valid for discovery, or for node operations
297              with the new operator.
298
299              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
304
305       -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
310
311       -T, --targetname=targetname
312              Use target targetname.
313
314              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
319
320       -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
324              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
331              sid | sysfsdir is only required for session mode.
332
333
334       -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
338              In  node mode, rescan a session running through the target, por‐
339              tal, iface tuple passed in.
340
341
342       -s, --stats
343              Display session statistics.  This option  when  used  with  host
344              mode, displays host statistics.
345
346
347       -S, --show
348              When  displaying records, do not hide masked values, such as the
349              CHAP secret (password).
350
351              This option is only valid for node and session mode.
352
353
354       -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
359              This option is only valid for discovery mode.
360
361
362       -u, --logout
363              logout for a specified record.
364
365              This option is only valid for node and session mode.
366
367
368       -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
373              This option is only valid for node mode (it  is  valid  but  not
374              functional for session mode).
375
376
377       -v, --value=value
378              Specify a value for use with the update operator.
379
380              This option is only valid for node mode and flashnode submode of
381              host mode.
382
383
384       -V, --version
385              display version and exit
386
387
388       -x, --index=index
389              Specify the index of the entity to operate on.
390
391              This option is only valid for chap  and  flashnode  submodes  of
392              host mode.
393
394

DISCOVERY TYPES

396       iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS.
397
398
399       SendTargets
400              A native iSCSI protocol which allows each iSCSI target to send a
401              list of available targets to the initiator.
402
403
404       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
409
410       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
415
416       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
422              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
427              fw  support in open-iscsi is experimental. The settings and isc‐
428              siadm syntax and output format may change.
429
430
431       iscsiadm supports the iSNS (isns) or SendTargets (st)  discovery  type.
432       An SLP implementation is under development.
433
434

EXIT STATUS

436       On  success  0 is returned. On error one of the return codes below will
437       be returned.
438
439       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
445
446
447       0      ISCSI_SUCCESS - command executed successfully.
448
449
450       1      ISCSI_ERR - generic error code.
451
452
453       2      ISCSI_ERR_SESS_NOT_FOUND - session could not be found.
454
455
456       3      ISCSI_ERR_NOMEM - could not allocate resource for operation.
457
458       4      ISCSI_ERR_TRANS - connect problem caused operation to fail.
459
460
461       5      ISCSI_ERR_LOGIN - generic iSCSI login failure.
462
463
464       6      ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.
465
466
467       7      ISCSI_ERR_INVAL - invalid argument.
468
469
470       8      ISCSI_ERR_TRANS_TIMEOUT - connection timer exired  while  trying
471              to connect.
472
473
474       9      ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.
475
476
477       10     ISCSI_ERR_LOGOUT - iSCSI logout failed.
478
479
480       11     ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timedout.
481
482
483       12     ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in
484              kernel or iscsid.
485
486
487       13     ISCSI_ERR_ACCESS - did not have proper OS permissions to  access
488              iscsid or execute iscsiadm command.
489
490
491       14     ISCSI_ERR_TRANS_CAPS  -  transport module did not support opera‐
492              tion.
493
494
495       15     ISCSI_ERR_SESS_EXISTS - session is logged in.
496
497
498       16     ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.
499
500
501       17     ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.
502
503
504       18     ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.
505
506
507       19     ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.
508
509
510       20     ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.
511
512
513       21     ISCSI_ERR_NO_OBJS_FOUND  -  no  records/targets/sessions/portals
514              found to execute operation on.
515
516
517       22     ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.
518
519
520       23     ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.
521
522
523       24     ISCSI_ERR_LOGIN_AUTH_FAILED  - login failed due to authorization
524              failure.
525
526
527       25     ISCSI_ERR_ISNS_QUERY - iSNS query failure.
528
529
530       26     ISCSI_ERR_ISNS_REG_FAILED  -  iSNS   registration/deregistration
531              failed.
532
533
534

EXAMPLES

536       Discover targets at a given IP address:
537
538            iscsiadm --mode discoverydb --type sendtargets --portal 192.168.1.10 --discover
539
540       Login, must use a node record id found by the discovery:
541
542            iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login
543
544       Logout:
545
546            iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout
547
548       List node records:
549
550            iscsiadm --mode node
551
552
553       Display all data for a given node record:
554
555            iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260
556
557

FILES

559       /etc/iscsi/iscsid.conf
560              The configuration file read by iscsid and iscsiadm on startup.
561
562       /etc/iscsi/initiatorname.iscsi
563              The  file  containing the iSCSI InitiatorName and InitiatorAlias
564              read by iscsid and iscsiadm on startup.
565
566       /var/lib/iscsi/nodes/
567              This directory contains the nodes with their targets.
568
569       /var/lib/iscsi/send_targets
570              This directory contains the portals.
571
572

SEE ALSO

574       iscsid(8)
575
576

AUTHORS

578       Open-iSCSI project <http://www.open-iscsi.com/>
579       Alex Aizman <itn780@yahoo.com>
580       Dmitry Yusupov <dmitry_yus@yahoo.com>
581
582
583
584                                   Sep 2006                        ISCSIADM(8)
Impressum