forked from open-iscsi/open-iscsi
-
Notifications
You must be signed in to change notification settings - Fork 5
/
README
1946 lines (1339 loc) · 65.4 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=================================================================
Linux* Open-iSCSI
=================================================================
Jun 6, 2022
Contents
========
- 1. In This Release
- 2. Introduction
- 3. Installation
- 4. Open-iSCSI daemon
- 5. Open-iSCSI Configuration Utility
- 6. Configuration
- 7. Getting Started
- 8. Advanced Configuration
- 9. iSCSI System Info
1. In This Release
==================
This file describes the Linux* Open-iSCSI Initiator. The software was
tested on AMD Opteron (TM) and Intel Xeon (TM).
The latest development release is available at:
https://github.com/open-iscsi/open-iscsi
For questions, comments, contributions post an issue on github, or
send e-mail to:
open-iscsi@googlegroups.com
You can also raise an issue on the github page.
1.1. Features
=============
- highly optimized and very small-footprint data path
- persistent configuration database
- SendTargets discovery
- CHAP
- PDU header Digest
- multiple sessions
1.2 Licensing
==============
The daemon and other top-level commands are licensed as GPLv3, while the
libopeniscsiusr library used by some of those commmands is licensed as LGPLv3.
2. Introduction
===============
The Open-iSCSI project is a high-performance, transport independent,
multi-platform implementation of RFC3720 iSCSI.
Open-iSCSI is partitioned into user and kernel parts.
The kernel portion of Open-iSCSI was originally part of this project
repository, but now is built into the linux kernel itself. It
includes loadable modules: scsi_transport_iscsi.ko, libiscsi.ko and
scsi_tcp.ko. The kernel code handles the "fast" path, i.e. data flow.
User space contains the entire control plane: configuration
manager, iSCSI Discovery, Login and Logout processing,
connection-level error processing, Nop-In and Nop-Out handling,
and (perhaps in the future:) Text processing, iSNS, SLP, Radius, etc.
The user space Open-iSCSI consists of a daemon process called
iscsid, and a management utility iscsiadm. There are also helper
programs, and iscsiuio, which is used for certain iSCSI adapters.
3. Installation
===============
NOTE: You will need to be root to install the Open-iSCSI code, and
you will also need to be root to run it.
As of today, the Open-iSCSI Initiator requires a host running the
Linux operating system with kernel.
The userspace components iscsid, iscsiadm and iscsistart require the
open-isns library, unless open-isns use is diabled when building (see
below).
If this package is not available for your distribution, you can download
and install it yourself. To install the open-isns headers and library
required for Open-iSCSI, download the current release from:
https://github.com/open-iscsi/open-isns
Then, from the top-level directory, run:
./configure [<OPTIONS>]
make
make install
For the open-iscsi project and iscsiuio, the original build
system used make and autoconf the build the project. These
build systems are being depcreated in favor of meson (and ninja).
See below for how to build using make and autoconf, but
migrating as soon as possible to meson would be a good idea.
Building open-iscsi/iscsiuio using meson
----------------------------------------
For Open-iSCSI and iscsiuio, the system is built using meson and ninja
(see https://github.com/mesonbuild/meson). If these packages aren't
available to you on your Linux distribution, you can download
the latest release from: https://github.com/mesonbuild/meson/releases).
The README.md file describes in detail how to build it yourself, including
how to get ninja.
To build the open-iscsi project, including iscsiuio, first run meson
to configure the build, from the top-level open-iscsi directory, e.g.:
rm -rf builddir
mkdir builddir
meson [<MESON-OPTIONS>] builddir
Then, to build the code:
ninja -C builddir
If you change any code and want to rebuild, you simply run ninja again.
When you are ready to install:
[DESTDIR=<SOME-DIR>] ninja -C builddir install
This will install the iSCSI tools, configuration files, interfaces, and
documentation. If you do not set DESTDIR, it defaults to "/".
MESON-OPTIONS:
--------------
One can override several default values when building with meson:
Option Description
===================== =====================================================
--libdir=<LIBDIR> Where library files go [/lib64]
--sbindir=<DIR> Meson 0.63 or newer: Where binaries go [/usr/sbin]
-Dc_flags="<C-FLAGS>" Add in addition flags to the C compiler
-Dno_systemd=<BOOL> Enables systemd usage [false]
(set to "true" to disable systemd)
-Dsystemddir=<DIR> Set systemd unit directory [/usr/lib/systemd]
-Dhomedir=<DIR> Set config file directory [/etc/iscsi]
-Ddbroot=<DIR> Set Database directory [/etciscsi]
-Dlockdir=<DIR> Set Lock directory [/run/lock/iscsi]
-Drulesdir=<DIR> Set udev rules directory [/usr/lib/udev/rules.d]
-Discsi_sbindir=<DIR> Where binaries go [/usr/sbin]
(for use when sbindir can't be set, in older versions
of meson)
-Disns_supported=<BOOL> Enable/disable iSNS support [true]
(set to "false" to disable use of open-isns)
Building open-iscsi/iscsiuio using make/autoconf (Deprecated)
-------------------------------------------------------------
If you wish to build using the older deprecated system, you can
simply run:
make [<MAKE-OPTIONS>]
make [DESTDIR=<SOME-DIR>] install
Where MAKE-OPTIONS are from:
* SBINDIR=<some-dir> [/usr/bin] for executables
* DBROOT=<some-dir> [/etc/iscsi] for iscsi database files
* HOMEDIR=<some-dir> [/etc/iscsi] for iscsi config files
4. Open-iSCSI daemon
====================
The iscsid daemon implements control path of iSCSI protocol, plus some
anagement facilities. For example, the daemon could be configured to
utomatically re-start discovery at startup, based on the contents of
ersistent iSCSI database (see next section).
For help, run:
iscsid --help
The output will be similar to the following (assuming a default install):
Usage: iscsid [OPTION]
-c, --config=[path] Execute in the config file (/etc/iscsi/iscsid.conf).
-i, --initiatorname=[path] read initiatorname from file (/etc/iscsi/initiatorname.iscsi).
-f, --foreground run iscsid in the foreground
-d, --debug debuglevel print debugging information
-u, --uid=uid run as uid, default is current user
-g, --gid=gid run as gid, default is current user group
-n, --no-pid-file do not use a pid file
-p, --pid=pidfile use pid file (default /run/iscsid.pid).
-h, --help display this help and exit
-v, --version display version and exit
5. Open-iSCSI Configuration and Administration Utility
======================================================
Open-iSCSI persistent configuration is stored in a number of
directories under a configuration root directory, using a flat-file
format. This configuration root directory is /etc/iscsi by default,
but may also commonly be in /var/lib/iscsi (see "dbroot" in the meson
options discussed earlier).
Configuration is contained in directories for:
- nodes
- isns
- static
- fw
- send_targets
- ifaces
The iscsiadm utility is a command-line tool to manage (update, delete,
insert, query) the persistent database, as well manage discovery,
session establishment (login), and ending sessions (logout).
This utility presents set of operations that a user can perform
on iSCSI node, session, connection, and discovery records.
Open-iSCSI does not use the term node as defined by the iSCSI RFC,
where a node is a single iSCSI initiator or target. Open-iSCSI uses the
term node to refer to a portal on a target, so tools like iscsiadm
require that the '--targetname' and '--portal' arguments be used when
in node mode.
For session mode, a session id (sid) is used. The sid of a session can be
found by running:
iscsiadm -m session -P 1
The session id is not currently persistent and is partially determined by
when the session is setup.
Note that some of the iSCSI Node and iSCSI Discovery operations
do not require iSCSI daemon (iscsid) loaded.
For help on the command, run:
iscsiadm --help
The output will be similar to the following.
iscsiadm -m discoverydb [-hV] [-d debug_level] [-P printlevel] [-t type -p ip:port -I ifaceN ... [-Dl]] | [[-p ip:port -t type] [-o operation] [-n name] [-v value] [-lD]]
iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [-t type -p ip:port -I ifaceN ... [-l]] | [[-p ip:port] [-l | -D]] [-W]
iscsiadm -m node [-hV] [-d debug_level] [-P printlevel] [-L all,manual,automatic,onboot] [-W] [-U all,manual,automatic,onboot] [-S] [[-T targetname -p ip:port -I ifaceN] [-l | -u | -R | -s]] [[-o operation ] [-n name] [-v value]]
iscsiadm -m session [-hV] [-d debug_level] [-P printlevel] [-r sessionid | sysfsdir [-R | -u | -s] [-o operation] [-n name] [-v value]]
iscsiadm -m iface [-hV] [-d debug_level] [-P printlevel] [-I ifacename | -H hostno|MAC] [[-o operation ] [-n name] [-v value]] [-C ping [-a ip] [-b packetsize] [-c count] [-i interval]]
iscsiadm -m fw [-d debug_level] [-l] [-W] [[-n name] [-v value]]
iscsiadm -m host [-P printlevel] [-H hostno|MAC] [[-C chap [-x chap_tbl_idx]] | [-C flashnode [-A portal_type] [-x flashnode_idx]] | [-C stats]] [[-o operation] [-n name] [-v value]]
iscsiadm -k priority
The first parameter specifies the mode to operate in:
-m, --mode <op> specify operational mode op =
<discoverydb|discovery|node|session|iface|fw|host>
Mode "discoverydb"
------------------
-m discoverydb --type=[type] --interface=[iface…] --portal=[ip:port] \
--print=[N] \
--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \
--discover
This command will use the discovery record settings
matching the record with type=type and
portal=ip:port]. If a record does not exist, it will
create a record using the iscsid.conf discovery
settings.
By default, it will then remove records for
portals no longer returned. And,
if a portal is returned by the target, then the
discovery command will create a new record or modify
an existing one with values from iscsi.conf and the
command line.
[op] can be passed in multiple times to this
command, and it will alter the node DB manipulation.
If [op] is passed in and the value is
"new", iscsiadm will add records for portals that do
not yet have records in the db.
If [op] is passed in and the value is
"update", iscsiadm will update node records using
info from iscsi.conf and the command line for portals
that are returned during discovery and have
a record in the db.
If [op] is passed in and the value is "delete",
iscsiadm will delete records for portals that
were not returned during discovery.
If [op] is passed in and the value is
"nonpersistent", iscsiadm will not store
the portals found in the node DB. This is
only useful with the --login command.
See the example section for more info.
See below for how to setup iSCSI ifaces for
software iSCSI or override the system defaults.
Multiple ifaces can be passed in during discovery.
For the above commands, "print" is optional. If
used, N can be 0 or 1.
0 = The old flat style of output is used.
1 = The tree style with the inteface info is used.
If print is not used, the old flat style is used.
-m discoverydb --interface=[iface...] --type=[type] --portal=[ip:port] \
--print=[N] \
--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT] \
--discover --login
This works like the previous discoverydb command
with the --login argument passed in will also
log into the portals that are found.
-m discoverydb --portal=[ip:port] --type=[type] \
--op=[op] [--name=[name] --value=[value]]
Perform specific DB operation [op] for
discovery portal. It could be one of:
[new], [delete], [update] or [show]. In case of
[update], you have to provide [name] and [value]
you wish to update
Setting op=NEW will create a new discovery record
using the iscsid.conf discovery settings. If it
already exists, it will be overwritten using
iscsid.conf discovery settings.
Setting op=DELETE will delete the discovery record
and records for the targets found through
Phat discovery source.
Setting op=SHOW will display the discovery record
values. The --show argument can be used to
force the CHAP passwords to be displayed.
Mode "discovery"
----------------
-m discovery --type=[type] --interface=iscsi_ifacename \
--portal=[ip:port] --login --print=[N] \
--op=[op]=[NEW | UPDATE | DELETE | NONPERSISTENT]
Perform [type] discovery for target portal with
ip-address [ip] and port [port].
This command will not use the discovery record
settings. It will use the iscsid.conf discovery
settings and it will overwrite the discovery
record with iscsid.conf discovery settings if it
exists. By default, it will then remove records for
portals no longer returned. And,
if a portal is returned by the target, then the
discovery command will create a new record or modify
an existing one with values from iscsi.conf and the
command line.
[op] can be passed in multiple times to this
command, and it will alter the DB manipulation.
If [op] is passed in and the value is
"new", iscsiadm will add records for portals that do
not yet have records in the db.
If [op] is passed in and the value is
"update", iscsiadm will update node records using
info from iscsi.conf and the command line for portals
that are returned during discovery and have
a record in the db.
If [op] is passed in and the value is "delete",
iscsiadm will delete records for portals that
were not returned during discovery.
If [op] is passed in and the value is
"nonpersistent", iscsiadm will not store
the portals found in the node DB.
See the example section for more info.
See below for how to setup iSCSI ifaces for
software iSCSI or override the system defaults.
Multiple ifaces can be passed in during discovery.
-m discovery --print=[N]
Display all discovery records from internal
persistent discovery database.
Mode "node"
-----------
-m node display all discovered nodes from internal
persistent discovery database
-m node --targetname=[name] --portal=[ip:port] \
--interface=iscsi_ifacename] \
[--login|--logout|--rescan|--stats] [-W]
-m node --targetname=[name] --portal=[ip:port]
--interface=[driver,HWaddress] \
--op=[op] [--name=[name] --value=[value]]
-m node --targetname=[name] --portal=[ip:port]
--interface=iscsi_ifacename] \
--print=[level]
Perform specific DB operation [op] for specific
interface on host that will connect to portal on
target. targetname, portal and interface are optional.
See below for how to setup iSCSI ifaces for
software iSCSI or override the system defaults.
The op could be one of [new], [delete], [update] or
[show]. In case of [update], you have to provide
[name] and [value] you wish to update.
For [delete], note that if a session is using the
node record, the session will be logged out then
the record will be deleted.
Using --rescan will perform a SCSI layer scan of the
session to find new LUNs.
Using --stats prints the iSCSI stats for the session.
Using --login normally sends a login request to the
specified target and normally waits for the results.
If -W/--no_wait is supplied return success if we are
able to send the login request, and do not wait
for the response. The user will have to poll for
success
Print level can be 0 to 1.
-m node --logoutall=[all|manual|automatic]
Logout "all" the running sessions or just the ones
with a node startup value manual or automatic.
Nodes marked as ONBOOT are skipped.
-m node --loginall=[all|manual|automatic] [-W]
Login "all" the running sessions or just the ones
with a node startup value manual or automatic.
Nodes marked as ONBOOT are skipped.
If -W is supplied then do not wait for the login
response for the target, returning success if we
are able to just send the request. The client
will have to poll for success.
Mode "session"
--------------
-m session display all active sessions and connections
-m session --sid=[sid] [ --print=level | --rescan | --logout ]
--op=[op] [--name=[name] --value=[value]]
Perform operation for specific session with
session id sid. If no sid is given, the operation
will be performed on all running sessions if possible.
--logout and --op work like they do in node mode,
but in session mode targetname and portal info
is not passed in.
Print level can be 0 to 2.
1 = Print basic session info like node we are
connected to and whether we are connected.
2 = Print iSCSI params used.
3 = Print SCSI info like LUNs, device state.
If no sid and no operation is given print out the
running sessions.
Mode "iface"
------------
-m iface --interface=iscsi_ifacename --op=[op] [--name=[name] --value=[value]]
--print=level
Perform operation on given interface with name
iscsi_ifacename.
See below for examples.
-m iface --interface=iscsi_ifacename -C ping --ip=[ipaddr] --packetsize=[size]
--count=[count] --interval=[interval]
Mode "host"
-----------
-m host [--host=hostno|MAC] --print=level -C chap --op=[SHOW]
Display information for a specific host. The host
can be passed in by host number or by MAC address.
If a host is not passed in, then info
for all hosts is printed.
Print level can be 0 to 4.
1 = Print info for how like its state, MAC, and
netinfo if possible.
2 = Print basic session info for nodes the host
is connected to.
3 = Print iSCSI params used.
4 = Print SCSI info like LUNs, device state.
-m host --host=hostno|MAC -C chap --op=[DELETE] --index=[chap_tbl_idx]
Delete chap entry at the given index from chap table.
-m host --host=hostno|MAC -C chap --op=[NEW | UPDATE] --index=[chap_tbl_idx] \
--name=[name] --value=[value]
Add new or update existing chap entry at the given
index with given username and password pair. If index
is not passed then entry is added at the first free
index in chap table.
-m host --host=hostno|MAC -C flashnode
Display list of all the targets in adapter's
flash (flash node), for the specified host,
with ip, port, tpgt and iqn.
-m host --host=hostno|MAC -C flashnode --op=[NEW] --portal_type=[ipv4|ipv6]
Create new flash node entry for the given host of the
specified portal_type. This returns the index of the
newly created entry on success.
-m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \
--op=[UPDATE] --name=[name] --value=[value]
Update the params of the specified flash node.
The [name] and [value] pairs must be provided for the
params that need to be updated. Multiple params can
be updated using a single command.
-m host --host=hostno|MAC -C flashnode --index=[flashnode_index] \
--op=[SHOW | DELETE | LOGIN | LOGOUT]
Setting op=DELETE|LOGIN|LOGOUT will perform
deletion/login/ logout operation on the specified
flash node.
Setting op=SHOW will list all params with the values
for the specified flash node. This is the default
operation.
See the iscsiadm example section below for more info.
Other arguments
---------------
-d, --debug debuglevel print debugging information
-V, --version display version and exit
-h, --help display this help and exit
5.1 iSCSI iface setup
=====================
The next sections describe how to setup iSCSI ifaces so you can bind
a session to a NIC port when using software iSCSI (section 5.1.1), and
it describes how to setup ifaces for use with offload cards from Chelsio
and Broadcom (section 5.1.2).
5.1.1 How to setup iSCSI interfaces (iface) for binding
=======================================================
If you wish to allow the network susbsystem to figure out
the best path/NIC to use, then you can skip this section. For example
if you have setup your portals and NICs on different subnets, then
the following is not needed for software iSCSI.
Warning!!!!!!
This feature is experimental. The interface may change. When reporting
bugs, if you cannot do a "ping -I ethX target_portal", then check your
network settings first. Make sure the rp_filter setting is set to 0 or 2
(see Prep section below for more info). If you cannot ping the portal,
then you will not be able to bind a session to a NIC.
What is a scsi_host and iface for software, hardware and partial
offload iSCSI?
Software iSCSI, like iscsi_tcp and iser, allocates a scsi_host per session
and does a single connection per session. As a result
/sys/class_scsi_host and /proc/scsi will report a scsi_host for
each connection/session you have logged into. Offload iSCSI, like
Chelsio cxgb3i, allocates a scsi_host for each PCI device (each
port on a HBA will show up as a different PCI device so you get
a scsi_host per HBA port).
To manage both types of initiator stacks, iscsiadm uses the interface (iface)
structure. For each HBA port or for software iSCSI for each network
device (ethX) or NIC, that you wish to bind sessions to you must create
a iface config /etc/iscsi/ifaces.
Prep
----
The iface binding feature requires the sysctl setting
net.ipv4.conf.default.rp_filter to be set to 0 or 2.
This can be set in /etc/sysctl.conf by having the line:
net.ipv4.conf.default.rp_filter = N
where N is 0 or 2. Note that when setting this you may have to reboot
for the value to take effect.
rp_filter information from Documentation/networking/ip-sysctl.txt:
rp_filter - INTEGER
0 - No source validation.
1 - Strict mode as defined in RFC3704 Strict Reverse Path
Each incoming packet is tested against the FIB and if the interface
is not the best reverse path the packet check will fail.
By default failed packets are discarded.
2 - Loose mode as defined in RFC3704 Loose Reverse Path
Each incoming packet's source address is also tested against the FIB
and if the source address is not reachable via any interface
the packet check will fail.
Running
-------
The command:
iscsiadm -m iface
will report iface configurations that are setup in /etc/iscsi/ifaces:
iface0 qla4xxx,00:c0:dd:08:63:e8,20.15.0.7,default,iqn.2005-06.com.redhat:madmax
iface1 qla4xxx,00:c0:dd:08:63:ea,20.15.0.9,default,iqn.2005-06.com.redhat:madmax
The format is:
iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname
For software iSCSI, you can create the iface configs by hand, but it is
recommended that you use iscsiadm's iface mode. There is an iface.example in
/etc/iscsi/ifaces which can be used as a template for the daring.
For each network object you wish to bind a session to, you must create
a separate iface config in /etc/iscsi/ifaces and each iface config file
must have a unique name which is less than or equal to 64 characters.
Example
-------
If you have NIC1 with MAC address 00:0F:1F:92:6B:BF and NIC2 with
MAC address 00:C0:DD:08:63:E7, and you wanted to do software iSCSI over
TCP/IP, then in /etc/iscsi/ifaces/iface0 you would enter:
iface.transport_name = tcp
iface.hwaddress = 00:0F:1F:92:6B:BF
and in /etc/iscsi/ifaces/iface1 you would enter:
iface.transport_name = tcp
iface.hwaddress = 00:C0:DD:08:63:E7
Warning: Do not name an iface config file "default" or "iser".
They are special values/files that are used by the iSCSI tools for
backward compatibility. If you name an iface default or iser, then
the behavior is not defined.
To use iscsiadm to create an iface0 similar to the above example, run:
iscsiadm -m iface -I iface0 --op=new
(This will create a new empty iface config. If there was already an iface
with the name "iface0", this command will overwrite it.)
Next, set the hwaddress:
iscsiadm -m iface -I iface0 --op=update \
-n iface.hwaddress -v 00:0F:1F:92:6B:BF
If you had sessions logged in, iscsiadm will not update or overwrite
an iface. You must log out first. If you have an iface bound to a node/portal
but you have not logged in, then iscsiadm will update the config and
all existing bindings.
You should now skip to 5.1.3 to see how to log in using the iface, and for
some helpful management commands.
5.1.2 Setting up an iface for an iSCSI offload card
===================================================
This section describes how to setup ifaces for use with Chelsio, Broadcom and
QLogic cards.
By default, iscsiadm will create an iface for each Broadcom, QLogic and Chelsio
port. The iface name will be of the form:
$transport/driver_name.$MAC_ADDRESS
Running the following command:
iscsiadm -m iface
will report iface configurations that are setup in /etc/iscsi/ifaces:
default tcp,<empty>,<empty>,<empty>,<empty>
iser iser,<empty>,<empty>,<empty>,<empty>
cxgb3i.00:07:43:05:97:07 cxgb3i,00:07:43:05:97:07,<empty>,<empty>,<empty>
qla4xxx.00:0e:1e:04:8b:2e qla4xxx,00:0e:1e:04:8b:2e,<empty>,<empty>,<empty>
The format is:
iface_name transport_name,hwaddress,ipaddress,net_ifacename,initiatorname
where: iface_name: name of iface
transport_name: name of driver
hwaddress: MAC address
ipaddress: IP address to use for this port
net_iface_name: will be <empty> because change between reboots.
It is used for software iSCSI's vlan or alias binding.
initiatorname: Initiatorname to be used if you want to override the
default one in /etc/iscsi/initiatorname.iscsi.
To display these values in a more friendly way, run:
iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07
Example output:
# BEGIN RECORD 2.0-871
iface.iscsi_ifacename = cxgb3i.00:07:43:05:97:07
iface.net_ifacename = <empty>
iface.ipaddress = <empty>
iface.hwaddress = 00:07:43:05:97:07
iface.transport_name = cxgb3i
iface.initiatorname = <empty>
# END RECORD
Before you can use the iface, you must set the IP address for the port.
We determine the corresponding variable name that we want to update from
the output above, which is "iface.ipaddress".
Then we fill this empty variable with the value we desire, with this command:
iscsiadm -m iface -I cxgb3i.00:07:43:05:97:07 -o update \
-n iface.ipaddress -v 20.15.0.66
Note for QLogic ports: After updating the iface record, you must apply or
applyall the settings for the changes to take effect:
iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2e -o apply
iscsiadm -m iface -H 00:0e:1e:04:8b:2e -o applyall
With "apply", the network settings for the specified iface will take effect.
With "applyall", the network settings for all ifaces on a specific host will
take effect. The host can be specified using the -H/--host argument by either
the MAC address of the host or the host number.
Here is an example of setting multiple IPv6 addresses on a single iSCSI
interface port.
First interface (no need to set iface_num, it is 0 by default):
iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
-n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9392
Create the second interface if it does not exist (iface_num is mandatory here):
iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a.1 -op=new
iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
-n iface.iface_num -v 1
iscsiadm -m iface -I qla4xxx.00:0e:1e:04:8b:2a -o update \
-n iface.ipaddress -v fec0:ce00:7014:0041:1111:2222:1e04:9393
iscsiadm -m iface -H 00:0e:1e:04:8b:2a --op=applyall
Note: If there are common settings for multiple interfaces then the
settings from 0th iface would be considered valid.
Now, we can use this iface to login into targets, which is described in the
next section.
5.1.3 Discovering iSCSI targets/portals
========================================
Be aware that iscsiadm will use the default route to do discovery. It will
not use the iface specified. So if you are using an offload card, you will
need a separate network connection to the target for discovery purposes.
*This should be fixed in the some future version of Open-iSCSI*
For compatibility reasons, when you run iscsiadm to do discovery, it
will check for interfaces in /etc/iscsi/iscsi/ifaces that are using
tcp for the iface.transport, and it will bind the portals that are discovered
so that they will be logged in through those ifaces. This behavior can also
be overridden by passing in the interfaces you want to use. For the case
of offload, like with cxgb3i and bnx2i, this is required because the transport
will not be tcp.
For example if you had defined two interfaces but only wanted to use one,
you can use the --interface/-I argument:
iscsiadm -m discoverydb -t st -p ip:port -I iface1 --discover -P 1
If you had defined interfaces but wanted the old behavior, where we do not
bind a session to an iface, then you can use the special iface "default":
iscsiadm -m discoverydb -t st -p ip:port -I default --discover -P 1
And if you did not define any interfaces in /etc/iscsi/ifaces and do
not pass anything into iscsiadm, running iscsiadm will do the default
behavior, allowing the network subsystem to decide which device to use.
If you later want to remove the bindings for a specific target and
iface, then you can run:
iscsiadm -m node -T my_target -I iface0 --op=delete
To do this for a specific portal on a target, run:
iscsiadm -m node -T my_target -p ip:port -I iface0 --op=delete
If you wanted to delete all bindinds for iface0, then you can run:
iscsiadm -m node -I iface0 --op=delete
And for equalogic targets it is sometimes useful to remove just by portal:
iscsiadm -m node -p ip:port -I iface0 --op=delete
Now logging into targets is the same as with software iSCSI. See section 7
for how to get started.
5.2 iscsiadm examples
=====================
Usage examples using the one-letter options (see iscsiadm man page
for long options):
Discovery mode
--------------
- SendTargets iSCSI Discovery using the default driver and interface and
using the discovery settings for the discovery record with the
ID [192.168.1.1:3260]:
iscsiadm -m discoverydb -t st -p 192.168.1.1:3260 --discover
This will search /etc/iscsi/send_targets for a record with the
ID [portal = 192.168.1.1:3260 and type = sendtargets. If found it
will perform discovery using the settings stored in the record.
If a record does not exist, it will be created using the iscsid.conf
discovery settings.
The argument to -p may also be a hostname instead of an address:
iscsiadm -m discoverydb -t st -p somehost --discover
For the ifaces, iscsiadm will first search /etc/iscsi/ifaces for
interfaces using software iSCSI. If any are found then nodes found
during discovery will be setup so that they can logged in through
those interfaces. To specify a specific iface, pass the
-I argument for each iface.
- SendTargets iSCSI Discovery updating existing target records:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o update --discover
If there is a record for targetX, and portalY exists in the DB, and
is returned during discovery, it will be updated with the info from
the iscsi.conf. No new portals will be added and stale portals
will not be removed.
- SendTargets iSCSI Discovery deleting existing target records:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o delete --discover
If there is a record for targetX, and portalY exists in the DB, but
is not returned during discovery, it will be removed from the DB.
No new portals will be added and existing portal records will not
be changed.
Note: If a session is logged into portal we are going to delete
a record for, it will be logged out then the record will be
deleted.
- SendTargets iSCSI Discovery adding new records:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o new --discover
If there is targetX, and portalY is returned during discovery, and does
not have a record, it will be added. Existing records are not modified.
- SendTargets iSCSI Discovery using multiple ops:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o new -o delete --discover
This command will add new portals and delete records for portals
no longer returned. It will not change the record information for
existing portals.
- SendTargets iSCSI Discovery in nonpersistent mode:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o nonpersistent --discover
This command will perform discovery, but not manipulate the node DB.
- SendTargets iSCSI Discovery with a specific interface. If you wish
to only use a subset of the interfaces in
/etc/iscsi/ifaces, then you can pass them in during discovery:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
--interface=iface0 --interface=iface1 --discover
Note that for software iSCSI, we let the network layer select
which NIC to use for discovery, but for later logins iscsiadm
will use the NIC defined in the iface configuration.
qla4xxx support is very basic and experimental. It does not store
the record info in the card's FLASH or the node DB, so you must
rerun discovery every time the driver is reloaded.
- Manipulate SendTargets DB: Create new SendTargets discovery record or
overwrite an existing discovery record with iscsid.conf
discovery settings:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o new
- Manipulate SendTargets DB: Display discovery settings:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o show
- Manipulate SendTargets DB: Display hidden discovery settings like
CHAP passwords:
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o show --show
- Manipulate SendTargets DB: Set discovery setting.
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 \
-o update -n name -v value
- Manipulate SendTargets DB: Delete discovery record. This will also delete
the records for the targets found through the discovery source.
iscsiadm -m discoverydb -t sendtargets -p 192.168.1.1:3260 -o delete
- Show all records in discovery database:
iscsiadm -m discovery
- Show all records in discovery database and show the targets that were
discovered from each record:
iscsiadm -m discovery -P 1
Node mode
---------
In node mode you can specify which records you want to log
into by specifying the targetname, ip address, port or interface
(if specifying the interface it must already be setup in the node db).
iscsiadm will search the node db for records which match the values
you pass in, so if you pass in the targetname and interface, iscsiadm
will search for records with those values and operate on only them.
Passing in none of them will result in all node records being operated on.
- iSCSI Login to all portals on every node/starget through each interface