idnits 2.17.1 draft-ietf-ips-iscsi-20.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == The page length should not exceed 58 lines per page, but there was 238 longer pages, the longest (page 140) being 119 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC3347], [SEC-IPS], [NDT], [BOOT]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 3 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. == There are 1 instance of lines with non-RFC3849-compliant IPv6 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1483 has weird spacing: '... or the timin...' == Line 1528 has weird spacing: '... of worldwi...' == Line 2323 has weird spacing: '...fer Tag that ...' == Line 3407 has weird spacing: '...ks must optio...' == Line 4361 has weird spacing: '...nection a "c...' == (9 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: In reassigning connection allegiance for a command, the targets SHOULD continue the command from its current state. For example, when reassigning read commands, the target SHOULD take advantage of the ExpDataSN field provided by the Task Management function request (which must be set to zero if there was no data transfer) and bring the read command to completion by sending the remaining data and sending (or resending) the status. ExpDataSN acknowledges all data sent up to, but not including, the Data-In PDU and or R2T with DataSN (or R2TSN) equal to ExpDataSN. However, targets may choose to send/receive all unacknowledged data or all of the data on a reassignment of connection allegiance if unable to recover or maintain accurate an state. Initiators MUST not subsequently request data retransmission through Data SNACK for PDUs numbered less than ExpDataSN (i.e., prior to the acknowledged sequence number). For all types of commands, a reassignment request implies that the task is still considered in progress by the initiator and the target must conclude the task appropriately if the target returns the "Function Complete" response to the reassignment request. This might possibly involve retransmission of data/R2T/ status PDUs as necessary, but MUST involve the (re)transmission of the status PDU. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: DataSegmentLength MUST not exceed MaxRecvDataSegmentLength for the direction it is sent and the total of all the DataSegmentLength of all PDUs in a sequence MUST not exceed MaxBurstLength (or FirstBurstLength for unsolicited data). However the number of individual PDUs in a sequence (or in total) may be higher than the MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength ratio (as PDUs may be limited in length by the sender capabilities). Using DataSegmentLength of 0 may increase beyond what is reasonable for the number of PDUs and should therefore be avoided. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The target specifies how many bytes it wants the initiator to send because of this R2T PDU. The target may request the data from the initiator in several chunks, not necessarily in the original order of the data. The target, therefore, also specifies a Buffer Offset that indicates the point at which the data transfer should begin, relative to the beginning of the total data transfer. The Desired Data Transfer Length MUST NOT be 0 and MUST not exceed MaxBurstLength. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: KRB_AP_REQ and KRB_AP_REP are binary-values and their binary length (not the length of the character string that represents them in encoded form) MUST not exceed 65536 bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: All the SPKM-* tokens are binary-values and their binary length (not the length of the character string that represents them in encoded form) MUST not exceed 65536 bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] (using the SHA1 hash function, such as SRP-SHA1) and G,Gn (Gn stands for G1,G2...) are identifiers of SRP groups specified in [SEC-IPS]. G, Gn, and U are text strings, s,A,B,M, and H(A | M | K) are binary-values. The length of s,A,B,M and H(A | M | K) in binary form (not the length of the character string that represents them in encoded form) MUST not exceed 1024 bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, Algorithm, Identifier, Challenge, and Response as defined in [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C and R are binary-values and their binary length (not the length of the character string that represents them in encoded form) MUST not exceed 1024 bytes. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: TargetName MUST not be redeclared within the login phase. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: InitiatorName MUST not be redeclared within the login phase. == Unrecognized Status in '', assuming Proposed Standard (Expected one of 'Standards Track', 'Full Standard', 'Draft Standard', 'Proposed Standard', 'Best Current Practice', 'Informational', 'Experimental', 'Informational', 'Historic'.) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'SPC3' is mentioned on line 12181, but not defined -- Looks like a reference, but probably isn't: '7' on line 5774 -- Looks like a reference, but probably isn't: '0' on line 5773 == Missing Reference: 'MaxMissingDPDU' is mentioned on line 11232, but not defined == Missing Reference: 'MaxOutStandingR2T' is mentioned on line 11240, but not defined == Missing Reference: 'MaxMissingSPDU' is mentioned on line 11259, but not defined == Missing Reference: 'MaxSupportedConns' is mentioned on line 11269, but not defined == Unused Reference: 'CAM' is defined on line 9988, but no explicit reference was found in the text == Unused Reference: 'RFC790' is defined on line 9993, but no explicit reference was found in the text == Unused Reference: 'RFC791' is defined on line 9994, but no explicit reference was found in the text == Unused Reference: 'RFC793' is defined on line 9996, but no explicit reference was found in the text == Unused Reference: 'RFC1035' is defined on line 9998, but no explicit reference was found in the text == Unused Reference: 'RFC1122' is defined on line 10000, but no explicit reference was found in the text == Unused Reference: 'RFC1766' is defined on line 10006, but no explicit reference was found in the text == Unused Reference: 'RFC1964' is defined on line 10008, but no explicit reference was found in the text == Unused Reference: 'RFC2026' is defined on line 10016, but no explicit reference was found in the text == Unused Reference: 'RFC2044' is defined on line 10018, but no explicit reference was found in the text == Unused Reference: 'RFC2119' is defined on line 10024, but no explicit reference was found in the text == Unused Reference: 'RFC2234' is defined on line 10026, but no explicit reference was found in the text == Unused Reference: 'RFC2246' is defined on line 10028, but no explicit reference was found in the text == Unused Reference: 'RFC2373' is defined on line 10029, but no explicit reference was found in the text == Unused Reference: 'RFC2396' is defined on line 10031, but no explicit reference was found in the text == Unused Reference: 'RFC2434' is defined on line 10048, but no explicit reference was found in the text == Unused Reference: 'CRC' is defined on line 10083, but no explicit reference was found in the text == Unused Reference: 'RFC3385' is defined on line 10089, but no explicit reference was found in the text == Unused Reference: 'Schneier' is defined on line 10096, but no explicit reference was found in the text == Outdated reference: A later version (-04) exists of draft-ietf-ipsec-ciph-aes-cbc-03 == Outdated reference: A later version (-05) exists of draft-ietf-ipsec-ciph-aes-ctr-00 -- Possible downref: Non-RFC (?) normative reference: ref. 'CAM' -- Possible downref: Non-RFC (?) normative reference: ref. 'EUI' -- Possible downref: Non-RFC (?) normative reference: ref. 'OUI' ** Obsolete normative reference: RFC 790 (Obsoleted by RFC 820) ** Obsolete normative reference: RFC 793 (Obsoleted by RFC 9293) ** Obsolete normative reference: RFC 1510 (Obsoleted by RFC 4120, RFC 6649) ** Downref: Normative reference to an Informational RFC: RFC 1737 ** Obsolete normative reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2044 (Obsoleted by RFC 2279) ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2373 (Obsoleted by RFC 3513) ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2401 (Obsoleted by RFC 4301) ** Obsolete normative reference: RFC 2406 (Obsoleted by RFC 4303, RFC 4305) ** Obsolete normative reference: RFC 2407 (Obsoleted by RFC 4306) ** Obsolete normative reference: RFC 2409 (Obsoleted by RFC 4306) ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 2732 (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'SAM' -- Possible downref: Non-RFC (?) normative reference: ref. 'SAM2' -- Possible downref: Non-RFC (?) normative reference: ref. 'SBC' == Outdated reference: A later version (-10) exists of draft-ietf-ipsec-esp-v3-03 == Outdated reference: A later version (-19) exists of draft-ietf-ips-security-16 == Outdated reference: A later version (-06) exists of draft-ietf-ips-iscsi-string-prep-03 -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' == Outdated reference: A later version (-12) exists of draft-ietf-ips-iscsi-boot-03 -- Possible downref: Non-RFC (?) normative reference: ref. 'Castagnoli93' -- Possible downref: Non-RFC (?) normative reference: ref. 'CRC' == Outdated reference: A later version (-10) exists of draft-ietf-ips-iscsi-name-disc-07 ** Downref: Normative reference to an Informational draft: draft-ietf-ips-iscsi-name-disc (ref. 'NDT') ** Downref: Normative reference to an Informational RFC: RFC 3385 -- Possible downref: Non-RFC (?) normative reference: ref. 'Schneier' Summary: 24 errors (**), 0 flaws (~~), 50 warnings (==), 15 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 iSCSI 19-January-03 3 IP Storage Working Group Julian Satran 4 Internet Draft Kalman Meth 5 draft-ietf-ips-iscsi-20.txt IBM 6 Category: standards-track 7 Costa Sapuntzakis 8 Cisco Systems 10 Mallikarjun Chadalapaka 11 Hewlett-Packard Co. 13 Efri Zeidner 14 SANGate 16 iSCSI 18 Julian Satran Expires August 2003 1 19 iSCSI 19-January-03 21 Status of this Memo 23 This document is an Internet-Draft and fully conforms to all 24 provisions of Section 10 of RFC2026. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 Drafts. Internet-Drafts are draft documents valid for at most six 30 months and may be updated, replaced, or made obsolete by other 31 documents at any time. It is inappropriate to use Internet- Drafts 32 as reference material or to cite them except as "work in progress." 33 The list of Internet-Drafts can be accessed at http://www.ietf.org/ 34 ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 Abstract 40 The Small Computer Systems Interface (SCSI) is a popular family of 41 protocols that enable systems to communicate with I/O devices, 42 especially storage devices. SCSI protocols are request/response 43 application protocols with a common standardized architecture model 44 and basic command set as well as standardized command sets for 45 different device classes (disks, tapes, media-changers etc.). 47 As system interconnects move from the classical bus structure to a 48 network structure SCSI has to be mapped to network transport 49 protocols. IP networks now meet the performance requirements of 50 fast system interconnects and as such are good candidates to "carry" 51 SCSI. 53 This document describes a transport protocol for SCSI that works on 54 top of TCP. The iSCSI protocol aims to be fully compliant with the 55 standardized SCSI architectural model. 57 Acknowledgements 59 This protocol was developed by a design team that, in addition to 60 the authors, included Daniel Smith, Ofer Biran, Jim Hafner and John 61 Hufferd (IBM), Mark Bakke (Cisco), Randy Haagens (HP), Matt Wakeley 62 (Agilent, now Sierra Logic), Luciano Dalle Ore (Quantum), and Paul 63 Von Stamwitz (Adaptec, now TrueSAN Networks). 65 Furthermore, a large group of people contributed to this work 66 through their review, comments, and valuable insights. We are 67 grateful to all of them. We especially thank those people who found 68 the time and patience to take part in our weekly phone conferences 69 and intermediate meetings in Almaden and Haifa, which helped shape 70 this document: Prasenjit Sarkar, Meir Toledano, John Dowdy, Steve 71 Legg, Alain Azagury (IBM), Dave Nagle (CMU), David Black (EMC), John 72 Matze (Veritas - now Okapi Software), Steve DeGroote, Mark Schrandt 73 (Cisco), Gabi Hecht (Gadzoox), Robert Snively and Brian Forbes 74 (Brocade), Nelson Nachum (StorAge), and Uri Elzur (Broadcom). Many 75 others helped edit and improve this document within the IPS working 77 Julian Satran Expires August 2003 2 78 iSCSI 19-January-03 80 group. We are especially grateful to David Robinson and Raghavendra 81 Rao (Sun), Charles Monia, Joshua Tseng (Nishan), Somesh Gupta 82 (Silverback), Michael Krause, Pierre Labat, Santosh Rao, Matthew 83 Burbridge, Bob Barry, Robert Elliott, Nick Martin (HP), Stephen 84 Bailey (Sandburst), Steve Senum, Ayman Ghanem, Dave Peterson 85 (Cisco), Barry Reinhold (Trebia Networks), Bob Russell (UNH), Eddy 86 Quicksall (iVivity, Inc.), Bill Lynn and Michael Fischer (Adaptec), 87 Vince Cavanna, Pat Thaler (Agilent), Jonathan Stone (Stanford), 88 Luben Tuikov (Splentec), Paul Koning (EqualLogic), Michael Krueger 89 (Windriver), Martins Krikis (Intel), Doug Otis (Sanlight), John 90 Marberg (IBM), Robert Griswold and Bill Moody (Crossroads), Bill 91 Studenmund (Wasabi Systems), Elizabeth Rodriguez (Brocade) and Yaron 92 Klein (Sanrad). The recovery chapter was enhanced with the help of 93 Stephen Bailey (Sandburst), Somesh Gupta (Silverback), and Venkat 94 Rangan (Rhapsody Networks). Eddy Quicksall contributed some examples 95 and began the Definitions section. Michael Fischer and Bob Barry 96 started the Acronyms section. Last, but not least, we thank Ralph 97 Weber for keeping us in line with T10 (SCSI) standardization. 99 We would like to thank Steve Hetzler for his unwavering support and 100 for coming up with such a good name for the protocol, and Micky 101 Rodeh, Jai Menon, Clod Barrera, and Andy Bechtolsheim for helping 102 make this work happen. 104 In addition to this document, we recommend you acquaint yourself 105 with the following in order to get a full understanding of the iSCSI 106 specification: "iSCSI Naming & Discovery"[NDT], "Bootstrapping 107 Clients using the iSCSI Protocol" [BOOT], "Securing Block Storage 108 Protocols over IP"[SEC-IPS] documents, and "iSCSI Requirements and 109 Design Considerations" [RFC3347]. 111 The "iSCSI Naming & Discovery" document is authored by: 113 Mark Bakke (Cisco), Jim Hafner, John Hufferd, Kaladhar Voruganti 114 (IBM), and Marjorie Krueger (HP). 116 The "Bootstrapping Clients using the iSCSI Protocol" document is 117 authored by: 119 Prasenjit Sarkar (IBM), Duncan Missimer (HP), and Costa 120 Sapuntzakis (Cisco). 122 The "Securing Block Storage Protocols over IP" document is authored 123 by: 125 Bernard Aboba (Microsoft), Joshua Tseng (Nishan), Jesse Walker 126 (Intel), Venkat Rangan (Rhapsody Networks), and Franco 127 Travostino (Nortel Networks). 129 The "iSCSI Requirements and Design Considerations" document is 130 authored by: 132 Marjorie Krueger, Randy Haagens (HP), Costa Sapuntzakis, and 133 Mark Bakke (Cisco). 135 Julian Satran Expires August 2003 3 136 iSCSI 19-January-03 138 We are grateful to all of them for their good work and for helping 139 us correlate this document with the ones they produced. 141 Julian Satran Expires August 2003 4 142 iSCSI 19-January-03 144 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 2 145 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 146 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 2 147 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 13 148 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . . 14 149 2.1 Definitions . . . . . . . . . . . . . . . . . . . . . . . . 14 150 2.2 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . 18 151 2.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . 19 152 2.3.1 Word Rule . . . . . . . . . . . . . . . . . . . . . . . 20 153 2.3.2 Half-Word Rule . . . . . . . . . . . . . . . . . . . . . 20 154 2.3.3 Byte Rule . . . . . . . . . . . . . . . . . . . . . . . 20 155 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 156 3.1 SCSI Concepts . . . . . . . . . . . . . . . . . . . . . . . 21 157 3.2 iSCSI Concepts and Functional Overview . . . . . . . . . . . 21 158 3.2.1 Layers and Sessions . . . . . . . . . . . . . . . . . . 22 159 3.2.2 Ordering and iSCSI Numbering . . . . . . . . . . . . . . 23 160 3.2.2.1 Command Numbering and Acknowledging . . . . . . . . 23 161 3.2.2.2 Response/Status Numbering and Acknowledging . . . . 26 162 3.2.2.3 Data Sequencing . . . . . . . . . . . . . . . . . . 26 163 3.2.3 iSCSI Login . . . . . . . . . . . . . . . . . . . . . . 27 164 3.2.4 iSCSI Full Feature Phase . . . . . . . . . . . . . . . . 28 165 3.2.4.1 Command Connection Allegiance . . . . . . . . . . . 28 166 3.2.4.2 Data Transfer Overview . . . . . . . . . . . . . . . 29 167 3.2.4.3 Tags and Integrity Checks . . . . . . . . . . . . . 30 168 3.2.4.4 Task Management . . . . . . . . . . . . . . . . . . 30 169 3.2.5 iSCSI Connection Termination . . . . . . . . . . . . . . 31 170 3.2.6 iSCSI Names . . . . . . . . . . . . . . . . . . . . . . 31 171 3.2.6.1 iSCSI Name Properties . . . . . . . . . . . . . . . 31 172 3.2.6.2 iSCSI Name Encoding . . . . . . . . . . . . . . . . 33 173 3.2.6.3 iSCSI Name Structure . . . . . . . . . . . . . . . . 33 174 3.2.6.3.1 Type "iqn." (iSCSI Qualified Name) . . . . . . . 34 175 3.2.6.3.2 Type "eui." (IEEE EUI-64 format) . . . . . . . . 35 176 3.2.7 Persistent State . . . . . . . . . . . . . . . . . . . . 35 177 3.2.8 Message Synchronization and Steering . . . . . . . . . . 36 178 3.2.8.1 Sync/Steering and iSCSI PDU Length . . . . . . . . . 37 179 3.3 iSCSI Session Types . . . . . . . . . . . . . . . . . . . . 37 180 3.4 SCSI to iSCSI Concepts Mapping Model . . . . . . . . . . . . 37 181 3.4.1 iSCSI Architecture Model . . . . . . . . . . . . . . . . 38 182 3.4.2 SCSI Architecture Model . . . . . . . . . . . . . . . . 40 183 3.4.3 Consequences of the Model . . . . . . . . . . . . . . . 42 184 3.4.3.1 I_T Nexus State . . . . . . . . . . . . . . . . . . 43 185 3.5 Request/Response Summary . . . . . . . . . . . . . . . . . . 43 186 3.5.1 Request/Response Types Carrying SCSI Payload . . . . . . 43 187 3.5.1.1 SCSI-Command . . . . . . . . . . . . . . . . . . . . 43 188 3.5.1.2 SCSI-Response . . . . . . . . . . . . . . . . . . . 43 189 3.5.1.3 Task Management Function Request . . . . . . . . . . 44 190 3.5.1.4 Task Management Function Response . . . . . . . . . 44 191 3.5.1.5 SCSI Data-out and SCSI Data-in . . . . . . . . . . . 45 193 Julian Satran Expires August 2003 5 194 iSCSI 19-January-03 196 3.5.1.6 Ready To Transfer (R2T) . . . . . . . . . . . . . . 45 197 3.5.2 Requests/Responses carrying SCSI and iSCSI Payload . . . 46 198 3.5.2.1 Asynchronous Message . . . . . . . . . . . . . . . . 46 199 3.5.3 Requests/Responses Carrying iSCSI Only Payload . . . . . 46 200 3.5.3.1 Text Request and Text Response . . . . . . . . . . . 46 201 3.5.3.2 Login Request and Login Response . . . . . . . . . . 46 202 3.5.3.3 Logout Request and Response . . . . . . . . . . . . 47 203 3.5.3.4 SNACK Request . . . . . . . . . . . . . . . . . . . 47 204 3.5.3.5 Reject . . . . . . . . . . . . . . . . . . . . . . . 47 205 3.5.3.6 NOP-Out Request and NOP-In Response . . . . . . . . 48 206 4. SCSI Mode Parameters for iSCSI . . . . . . . . . . . . . . . . 49 207 5. Login and Full Feature Phase Negotiation . . . . . . . . . . . 50 208 5.1 Text Format . . . . . . . . . . . . . . . . . . . . . . . . 51 209 5.2 Text Mode Negotiation . . . . . . . . . . . . . . . . . . . 54 210 5.2.1 List negotiations . . . . . . . . . . . . . . . . . . . 56 211 5.2.2 Simple-value Negotiations . . . . . . . . . . . . . . . 56 212 5.3 Login Phase . . . . . . . . . . . . . . . . . . . . . . . . 57 213 5.3.1 Login Phase Start . . . . . . . . . . . . . . . . . . . 59 214 5.3.2 iSCSI Security Negotiation . . . . . . . . . . . . . . . 61 215 5.3.3 Operational Parameter Negotiation During the Login Phase 62 216 5.3.4 Connection Reinstatement . . . . . . . . . . . . . . . . 63 217 5.3.5 Session Reinstatement, Closure, and Timeout . . . . . . 63 218 5.3.5.1 Loss of Nexus Notification . . . . . . . . . . . . . 64 219 5.3.6 Session Continuation and Failure . . . . . . . . . . . . 64 220 5.4 Operational Parameter Negotiation Outside the Login Phase . 64 221 6. iSCSI Error Handling and Recovery . . . . . . . . . . . . . . . 66 222 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 66 223 6.1.1 Background . . . . . . . . . . . . . . . . . . . . . . . 66 224 6.1.2 Goals . . . . . . . . . . . . . . . . . . . . . . . . . 66 225 6.1.3 Protocol Features and State Expectations . . . . . . . . 67 226 6.1.4 Recovery Classes . . . . . . . . . . . . . . . . . . . . 67 227 6.1.4.1 Recovery Within-command . . . . . . . . . . . . . . 68 228 6.1.4.2 Recovery Within-connection . . . . . . . . . . . . . 69 229 6.1.4.3 Connection Recovery . . . . . . . . . . . . . . . . 69 230 6.1.4.4 Session Recovery . . . . . . . . . . . . . . . . . . 70 231 6.1.5 Error Recovery Hierarchy . . . . . . . . . . . . . . . . 70 232 6.2 Retry and Reassign in Recovery . . . . . . . . . . . . . . . 72 233 6.2.1 Usage of Retry . . . . . . . . . . . . . . . . . . . . . 72 234 6.2.2 Allegiance Reassignment . . . . . . . . . . . . . . . . 73 235 6.3 Usage Of Reject PDU in Recovery . . . . . . . . . . . . . . 74 236 6.4 Connection Timeout Management . . . . . . . . . . . . . . . 74 237 6.4.1 Timeouts on Transport Exception Events . . . . . . . . . 74 238 6.4.2 Timeouts on Planned Decommissioning . . . . . . . . . . 75 239 6.5 Implicit Termination of Tasks . . . . . . . . . . . . . . . 75 240 6.6 Format Errors . . . . . . . . . . . . . . . . . . . . . . . 76 241 6.7 Digest Errors . . . . . . . . . . . . . . . . . . . . . . . 76 242 6.8 Sequence Errors . . . . . . . . . . . . . . . . . . . . . . 77 243 6.9 SCSI Timeouts . . . . . . . . . . . . . . . . . . . . . . . 78 245 Julian Satran Expires August 2003 6 246 iSCSI 19-January-03 248 6.10 Negotiation Failures . . . . . . . . . . . . . . . . . . . 78 249 6.11 Protocol Errors . . . . . . . . . . . . . . . . . . . . . . 79 250 6.12 Connection Failures . . . . . . . . . . . . . . . . . . . . 79 251 6.13 Session Errors . . . . . . . . . . . . . . . . . . . . . . 80 252 7. State Transitions . . . . . . . . . . . . . . . . . . . . . . . 81 253 7.1 Standard Connection State Diagrams . . . . . . . . . . . . . 81 254 7.1.1 State Descriptions for Initiators and Targets . . . . . 81 255 7.1.2 State Transition Descriptions for Initiators and Targets 82 256 7.1.3 Standard Connection State Diagram for an Initiator . . . 85 257 7.1.4 Standard Connection State Diagram for a Target . . . . . 87 258 7.2 Connection Cleanup State Diagram for Initiators and Targets 89 259 7.2.1 State Descriptions for Initiators and Targets . . . . . 90 260 7.2.2 State Transition Descriptions for Initiators and Targets 91 261 7.3 Session State Diagrams . . . . . . . . . . . . . . . . . . . 92 262 7.3.1 Session State Diagram for an Initiator . . . . . . . . . 92 263 7.3.2 Session State Diagram for a Target . . . . . . . . . . . 93 264 7.3.3 State Descriptions for Initiators and Targets . . . . . 94 265 7.3.4 State Transition Descriptions for Initiators and Targets 94 266 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 96 267 8.1 iSCSI Security Mechanisms . . . . . . . . . . . . . . . . . 96 268 8.2 In-band Initiator-Target Authentication . . . . . . . . . . 96 269 8.2.1 CHAP Considerations . . . . . . . . . . . . . . . . . . 97 270 8.2.2 SRP Considerations . . . . . . . . . . . . . . . . . . . 99 271 8.3 IPsec . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 272 8.3.1 Data Integrity and Authentication . . . . . . . . . . . 99 273 8.3.2 Confidentiality . . . . . . . . . . . . . . . . . . . .100 274 8.3.3 Policy, Security Associations, and Cryptographic Key 275 Management . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 276 9. Notes to Implementers . . . . . . . . . . . . . . . . . . . . .102 277 9.1 Multiple Network Adapters . . . . . . . . . . . . . . . . .102 278 9.1.1 Conservative Reuse of ISIDs . . . . . . . . . . . . . .102 279 9.1.2 iSCSI Name, ISID, and TPGT Use . . . . . . . . . . . . .103 280 9.2 Autosense and Auto Contingent Allegiance (ACA) . . . . . . .104 281 9.3 iSCSI Timeouts . . . . . . . . . . . . . . . . . . . . . . .104 282 9.4 Command Retry and Cleaning Old Command Instances . . . . . .105 283 9.5 Synch and Steering Layer and Performance . . . . . . . . . .105 284 9.6 Considerations for State-dependent Devices and Long-lasting SCSI 285 Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . .105 286 9.6.1 Determining the Proper ErrorRecoveryLevel . . . . . . .106 287 10. iSCSI PDU Formats . . . . . . . . . . . . . . . . . . . . . .107 288 10.1 iSCSI PDU Length and Padding . . . . . . . . . . . . . . .107 289 10.2 PDU Template, Header, and Opcodes . . . . . . . . . . . . .107 290 10.2.1 Basic Header Segment (BHS) . . . . . . . . . . . . . .108 291 10.2.1.1 I . . . . . . . . . . . . . . . . . . . . . . . . .108 292 10.2.1.2 Opcode . . . . . . . . . . . . . . . . . . . . . .108 293 10.2.1.3 Final (F) bit . . . . . . . . . . . . . . . . . . .109 294 10.2.1.4 Opcode-specific Fields . . . . . . . . . . . . . .109 295 10.2.1.5 TotalAHSLength . . . . . . . . . . . . . . . . . .109 297 Julian Satran Expires August 2003 7 298 iSCSI 19-January-03 300 10.2.1.6 DataSegmentLength . . . . . . . . . . . . . . . . .110 301 10.2.1.7 LUN . . . . . . . . . . . . . . . . . . . . . . . .110 302 10.2.1.8 Initiator Task Tag . . . . . . . . . . . . . . . .110 303 10.2.2 Additional Header Segment (AHS) . . . . . . . . . . . .110 304 10.2.2.1 AHSType . . . . . . . . . . . . . . . . . . . . . .110 305 10.2.2.2 AHSLength . . . . . . . . . . . . . . . . . . . . .111 306 10.2.2.3 Extended CDB AHS . . . . . . . . . . . . . . . . .111 307 10.2.2.4 Bidirectional Expected Read-Data Length AHS . . . .111 308 10.2.3 Header Digest and Data Digest . . . . . . . . . . . . .111 309 10.2.4 Data Segment . . . . . . . . . . . . . . . . . . . . .112 310 10.3 SCSI Command . . . . . . . . . . . . . . . . . . . . . . . .113 311 10.3.1 Flags and Task Attributes (byte 1) . . . . . . . . . .113 312 10.3.2 CmdSN - Command Sequence Number . . . . . . . . . . . .114 313 10.3.3 ExpStatSN . . . . . . . . . . . . . . . . . . . . . . .114 314 10.3.4 Expected Data Transfer Length . . . . . . . . . . . . .114 315 10.3.5 CDB - SCSI Command Descriptor Block . . . . . . . . . .115 316 10.3.6 Data Segment - Command Data . . . . . . . . . . . . . .115 317 10.4 SCSI Response . . . . . . . . . . . . . . . . . . . . . . .116 318 10.4.1 Flags (byte 1) . . . . . . . . . . . . . . . . . . . .116 319 10.4.2 Status . . . . . . . . . . . . . . . . . . . . . . . .117 320 10.4.3 Response . . . . . . . . . . . . . . . . . . . . . . .117 321 10.4.4 SNACK Tag . . . . . . . . . . . . . . . . . . . . . . .118 322 10.4.5 Residual Count . . . . . . . . . . . . . . . . . . . .118 323 10.4.6 Bidirectional Read Residual Count . . . . . . . . . . .118 324 10.4.7 Data Segment - Sense and Response Data Segment . . . .119 325 10.4.7.1 SenseLength . . . . . . . . . . . . . . . . . . . .119 326 10.4.7.2 Sense Data . . . . . . . . . . . . . . . . . . . .119 327 10.4.8 ExpDataSN . . . . . . . . . . . . . . . . . . . . . . .120 328 10.4.9 StatSN - Status Sequence Number . . . . . . . . . . . .120 329 10.4.10 ExpCmdSN - Next Expected CmdSN from this Initiator . .120 330 10.4.11 MaxCmdSN - Maximum CmdSN from this Initiator . . . . .120 331 10.5 Task Management Function Request . . . . . . . . . . . . . .121 332 10.5.1 Function . . . . . . . . . . . . . . . . . . . . . . .121 333 10.5.2 TotalAHSLength and DataSegmentLength . . . . . . . . .124 334 10.5.3 LUN . . . . . . . . . . . . . . . . . . . . . . . . . .124 335 10.5.4 Referenced Task Tag . . . . . . . . . . . . . . . . . .124 336 10.5.5 RefCmdSN . . . . . . . . . . . . . . . . . . . . . . .124 337 10.5.6 ExpDataSN . . . . . . . . . . . . . . . . . . . . . . .124 338 10.6 Task Management Function Response . . . . . . . . . . . . .126 339 10.6.1 Response . . . . . . . . . . . . . . . . . . . . . . .126 340 10.6.2 Task Management Actions on Task Sets . . . . . . . . .127 341 10.6.3 TotalAHSLength and DataSegmentLength . . . . . . . . .128 342 10.7 SCSI Data-out & SCSI Data-in . . . . . . . . . . . . . . . .129 343 10.7.1 F (Final) Bit . . . . . . . . . . . . . . . . . . . . .130 344 10.7.2 A (Acknowledge) bit . . . . . . . . . . . . . . . . . .131 345 10.7.3 Flags (byte 1) . . . . . . . . . . . . . . . . . . . .131 346 10.7.4 Target Transfer Tag and LUN . . . . . . . . . . . . . .132 347 10.7.5 DataSN . . . . . . . . . . . . . . . . . . . . . . . .132 349 Julian Satran Expires August 2003 8 350 iSCSI 19-January-03 352 10.7.6 Buffer Offset . . . . . . . . . . . . . . . . . . . . .132 353 10.7.7 DataSegmentLength . . . . . . . . . . . . . . . . . . .133 354 10.8 Ready To Transfer (R2T) . . . . . . . . . . . . . . . . . .134 355 10.8.1 TotalAHSLength and DataSegmentLength . . . . . . . . .135 356 10.8.2 R2TSN . . . . . . . . . . . . . . . . . . . . . . . . .135 357 10.8.3 StatSN . . . . . . . . . . . . . . . . . . . . . . . .135 358 10.8.4 Desired Data Transfer Length and Buffer Offset . . . .135 359 10.8.5 Target Transfer Tag . . . . . . . . . . . . . . . . . .136 360 10.9 Asynchronous Message . . . . . . . . . . . . . . . . . . . .137 361 10.9.1 AsyncEvent . . . . . . . . . . . . . . . . . . . . . .137 362 10.9.2 AsyncVCode . . . . . . . . . . . . . . . . . . . . . .139 363 10.9.3 LUN . . . . . . . . . . . . . . . . . . . . . . . . . .139 364 10.9.4 Sense Data and iSCSI Event Data . . . . . . . . . . . .139 365 10.9.4.1 SenseLength . . . . . . . . . . . . . . . . . . . .139 366 10.10 Text Request . . . . . . . . . . . . . . . . . . . . . . .141 367 10.10.1 F (Final) Bit . . . . . . . . . . . . . . . . . . . .141 368 10.10.2 C (Continue) Bit . . . . . . . . . . . . . . . . . . .142 369 10.10.3 Initiator Task Tag . . . . . . . . . . . . . . . . . .142 370 10.10.4 Target Transfer Tag . . . . . . . . . . . . . . . . .142 371 10.10.5 Text . . . . . . . . . . . . . . . . . . . . . . . . .143 372 10.11 Text Response . . . . . . . . . . . . . . . . . . . . . . .144 373 10.11.1 F (Final) Bit . . . . . . . . . . . . . . . . . . . .144 374 10.11.2 C (Continue) Bit . . . . . . . . . . . . . . . . . . .145 375 10.11.3 Initiator Task Tag . . . . . . . . . . . . . . . . . .145 376 10.11.4 Target Transfer Tag . . . . . . . . . . . . . . . . .145 377 10.11.5 StatSN . . . . . . . . . . . . . . . . . . . . . . . .145 378 10.11.6 Text Response Data . . . . . . . . . . . . . . . . . .145 379 10.12 Login Request . . . . . . . . . . . . . . . . . . . . . . .147 380 10.12.1 T (Transit) Bit . . . . . . . . . . . . . . . . . . .147 381 10.12.2 C (Continue) Bit . . . . . . . . . . . . . . . . . . .147 382 10.12.3 CSG and NSG . . . . . . . . . . . . . . . . . . . . .148 383 10.12.4 Version . . . . . . . . . . . . . . . . . . . . . . .148 384 10.12.4.1 Version-max . . . . . . . . . . . . . . . . . . .148 385 10.12.4.2 Version-min . . . . . . . . . . . . . . . . . . .148 386 10.12.5 ISID . . . . . . . . . . . . . . . . . . . . . . . . .148 387 10.12.6 TSIH . . . . . . . . . . . . . . . . . . . . . . . . .150 388 10.12.7 Connection ID - CID . . . . . . . . . . . . . . . . .150 389 10.12.8 CmdSN . . . . . . . . . . . . . . . . . . . . . . . .150 390 10.12.9 ExpStatSN . . . . . . . . . . . . . . . . . . . . . .151 391 10.12.10 Login Parameters . . . . . . . . . . . . . . . . . .151 392 10.13 Login Response . . . . . . . . . . . . . . . . . . . . . .152 393 10.13.1 Version-max . . . . . . . . . . . . . . . . . . . . .152 394 10.13.2 Version-active . . . . . . . . . . . . . . . . . . . .152 395 10.13.3 TSIH . . . . . . . . . . . . . . . . . . . . . . . . .153 396 10.13.4 StatSN . . . . . . . . . . . . . . . . . . . . . . . .153 397 10.13.5 Status-Class and Status-Detail . . . . . . . . . . . .153 398 10.13.6 T (Transit) bit . . . . . . . . . . . . . . . . . . .156 399 10.13.7 C (Continue) Bit . . . . . . . . . . . . . . . . . . .156 401 Julian Satran Expires August 2003 9 402 iSCSI 19-January-03 404 10.13.8 Login Parameters . . . . . . . . . . . . . . . . . . .156 405 10.14 Logout Request . . . . . . . . . . . . . . . . . . . . . .157 406 10.14.1 Reason Code . . . . . . . . . . . . . . . . . . . . .158 407 10.14.2 TotalAHSLength and DataSegmentLength . . . . . . . . .159 408 10.14.3 CID . . . . . . . . . . . . . . . . . . . . . . . . .159 409 10.14.4 ExpStatSN . . . . . . . . . . . . . . . . . . . . . .159 410 10.14.5 Implicit termination of tasks . . . . . . . . . . . .159 411 10.15 Logout Response . . . . . . . . . . . . . . . . . . . . . .161 412 10.15.1 Response . . . . . . . . . . . . . . . . . . . . . . .161 413 10.15.2 TotalAHSLength and DataSegmentLength . . . . . . . . .161 414 10.15.3 Time2Wait . . . . . . . . . . . . . . . . . . . . . .162 415 10.15.4 Time2Retain . . . . . . . . . . . . . . . . . . . . .162 416 10.16 SNACK Request . . . . . . . . . . . . . . . . . . . . . .163 417 10.16.1 Type . . . . . . . . . . . . . . . . . . . . . . . . .164 418 10.16.2 Data Acknowledgement . . . . . . . . . . . . . . . . .164 419 10.16.3 Resegmentation . . . . . . . . . . . . . . . . . . . .164 420 10.16.4 Initiator Task Tag . . . . . . . . . . . . . . . . . .165 421 10.16.5 Target Transfer Tag or SNACK Tag . . . . . . . . . . .165 422 10.16.6 BegRun . . . . . . . . . . . . . . . . . . . . . . . .165 423 10.16.7 RunLength . . . . . . . . . . . . . . . . . . . . . .166 424 10.17 Reject . . . . . . . . . . . . . . . . . . . . . . . . . .167 425 10.17.1 Reason . . . . . . . . . . . . . . . . . . . . . . . .167 426 10.17.2 DataSN/R2TSN . . . . . . . . . . . . . . . . . . . . .169 427 10.17.3 StatSN, ExpCmdSN and MaxCmdSN . . . . . . . . . . . .169 428 10.17.4 Complete Header of Bad PDU . . . . . . . . . . . . . .169 429 10.18 NOP-Out . . . . . . . . . . . . . . . . . . . . . . . . . .170 430 10.18.1 Initiator Task Tag . . . . . . . . . . . . . . . . . .170 431 10.18.2 Target Transfer Tag . . . . . . . . . . . . . . . . .171 432 10.18.3 Ping Data . . . . . . . . . . . . . . . . . . . . . .171 433 10.19 NOP-In . . . . . . . . . . . . . . . . . . . . . . . . . .172 434 10.19.1 Target Transfer Tag . . . . . . . . . . . . . . . . .173 435 10.19.2 StatSN . . . . . . . . . . . . . . . . . . . . . . . .173 436 10.19.3 LUN . . . . . . . . . . . . . . . . . . . . . . . . .173 437 11. iSCSI Security Text Keys and Authentication Methods . . . . .174 438 11.1 AuthMethod . . . . . . . . . . . . . . . . . . . . . . . .174 439 11.1.1 Kerberos . . . . . . . . . . . . . . . . . . . . . . .176 440 11.1.2 Simple Public-Key Mechanism (SPKM) . . . . . . . . . .176 441 11.1.3 Secure Remote Password (SRP) . . . . . . . . . . . . .177 442 11.1.4 Challenge Handshake Authentication Protocol (CHAP) . .178 443 12. Login/Text Operational Text Keys . . . . . . . . . . . . . . .180 444 12.1 HeaderDigest and DataDigest . . . . . . . . . . . . . . . .180 445 12.2 MaxConnections . . . . . . . . . . . . . . . . . . . . . .182 446 12.3 SendTargets . . . . . . . . . . . . . . . . . . . . . . . .182 447 12.4 TargetName . . . . . . . . . . . . . . . . . . . . . . . .182 448 12.5 InitiatorName . . . . . . . . . . . . . . . . . . . . . . .183 449 12.6 TargetAlias . . . . . . . . . . . . . . . . . . . . . . . .183 450 12.7 InitiatorAlias . . . . . . . . . . . . . . . . . . . . . .184 451 12.8 TargetAddress . . . . . . . . . . . . . . . . . . . . . . .184 453 Julian Satran Expires August 2003 10 454 iSCSI 19-January-03 456 12.9 TargetPortalGroupTag . . . . . . . . . . . . . . . . . . .185 457 12.10 InitialR2T . . . . . . . . . . . . . . . . . . . . . . . .185 458 12.11 ImmediateData . . . . . . . . . . . . . . . . . . . . . .186 459 12.12 MaxRecvDataSegmentLength . . . . . . . . . . . . . . . . .186 460 12.13 MaxBurstLength . . . . . . . . . . . . . . . . . . . . . .187 461 12.14 FirstBurstLength . . . . . . . . . . . . . . . . . . . . .187 462 12.15 DefaultTime2Wait . . . . . . . . . . . . . . . . . . . . .188 463 12.16 DefaultTime2Retain . . . . . . . . . . . . . . . . . . . .188 464 12.17 MaxOutstandingR2T . . . . . . . . . . . . . . . . . . . .188 465 12.18 DataPDUInOrder . . . . . . . . . . . . . . . . . . . . . .189 466 12.19 DataSequenceInOrder . . . . . . . . . . . . . . . . . . .189 467 12.20 ErrorRecoveryLevel . . . . . . . . . . . . . . . . . . . .189 468 12.21 SessionType . . . . . . . . . . . . . . . . . . . . . . .190 469 12.22 The Private or Public Extension Key Format . . . . . . . .190 470 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . .192 471 13.1 Naming Requirements . . . . . . . . . . . . . . . . . . . .193 472 13.2 Mechanism Specification Requirements . . . . . . . . . . .193 473 13.3 Publication Requirements . . . . . . . . . . . . . . . . .193 474 13.4 Security Requirements . . . . . . . . . . . . . . . . . . .193 475 13.5 Registration Procedure . . . . . . . . . . . . . . . . . .194 476 13.5.1 Present the iSCSI extension item to the Community . . .194 477 13.5.2 iSCSI extension item review and IESG approval . . . . .194 478 13.5.3 IANA Registration . . . . . . . . . . . . . . . . . . .194 479 13.5.4 Standard iSCSI extension item-label format . . . . . .194 480 13.6 IANA Procedures for Registering iSCSI extension items . . .195 481 References and Bibliography . . . . . . . . . . . . . . . . . . 196 482 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 198 483 Appendix A. Sync and Steering with Fixed Interval Markers . . . .199 484 A.1 Markers At Fixed Intervals . . . . . . . . . . . . . . . .199 485 A.2 Initial Marker-less Interval . . . . . . . . . . . . . . .200 486 A.3 Negotiation . . . . . . . . . . . . . . . . . . . . . . . .200 487 A.3.1 OFMarker, IFMarker . . . . . . . . . . . . . . . . . .200 488 A.3.2 OFMarkInt, IFMarkInt . . . . . . . . . . . . . . . . .201 489 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . .202 490 B.1 Read Operation Example . . . . . . . . . . . . . . . . . .202 491 B.2 Write Operation Example . . . . . . . . . . . . . . . . . .202 492 B.3 R2TSN/DataSN Use Examples . . . . . . . . . . . . . . . . .202 493 B.4 CRC Examples . . . . . . . . . . . . . . . . . . . . . . .205 494 Appendix C. Login Phase Examples . . . . . . . . . . . . . . . . .207 495 Appendix D. SendTargets Operation . . . . . . . . . . . . . . . .215 496 Appendix E. Algorithmic Presentation of Error Recovery Classes . .219 497 E.1 General Data Structure and Procedure Description . . . . .219 498 E.2 Within-command Error Recovery Algorithms . . . . . . . . .220 499 E.2.1 Procedure Descriptions . . . . . . . . . . . . . . . .220 500 E.2.2 Initiator Algorithms . . . . . . . . . . . . . . . . .221 501 E.2.3 Target Algorithms . . . . . . . . . . . . . . . . . .223 502 E.3 Within-connection Recovery Algorithms . . . . . . . . . . .225 503 E.3.1 Procedure Descriptions . . . . . . . . . . . . . . . .225 505 Julian Satran Expires August 2003 11 506 iSCSI 19-January-03 508 E.3.2 Initiator Algorithms . . . . . . . . . . . . . . . . .226 509 E.3.3 Target Algorithms . . . . . . . . . . . . . . . . . .228 510 E.4 Connection Recovery Algorithms . . . . . . . . . . . . . .229 511 E.4.1 Procedure Descriptions . . . . . . . . . . . . . . . .229 512 E.4.2 Initiator Algorithms . . . . . . . . . . . . . . . . .229 513 E.4.3 Target Algorithms . . . . . . . . . . . . . . . . . .232 514 Appendix F. Clearing Effects of Various Events on Targets . . . .234 515 F.1 Clearing Effects on iSCSI Objects . . . . . . . . . . . . .234 516 F.2 Clearing Effects on SCSI Objects . . . . . . . . . . . . .237 517 Full Copyright Statement . . . . . . . . . . . . . . . . . . . . 238 518 Notice of Intellectual Property Rights . . . . . . . . . . . . . 238 520 Julian Satran Expires August 2003 12 521 iSCSI 19-January-03 523 1. Introduction 525 The Small Computer Systems Interface (SCSI) is a popular family of 526 protocols for communicating with I/O devices, especially storage 527 devices. SCSI is a client-server architecture. Clients of a SCSI 528 interface are called "initiators". Initiators issue SCSI "commands" 529 to request services from components, logical units, of a server 530 known as a "target". A "SCSI transport" maps the client-server SCSI 531 protocol to a specific interconnect. Initiators are one endpoint of 532 a SCSI transport and targets are the other endpoint. 534 The SCSI protocol has been mapped over various transports, including 535 Parallel SCSI, IPI, IEEE-1394 (firewire) and Fibre Channel. These 536 transports are I/O specific and have limited distance capabilities. 538 The iSCSI protocol defined in this document describes a means of 539 transporting of the SCSI packets over TCP/IP, providing for an 540 interoperable solution which can take advantage of existing Internet 541 infrastructure, Internet management facilities and address distance 542 limitations. 544 Julian Satran Expires August 2003 13 545 iSCSI 19-January-03 547 2. Definitions and Acronyms 549 2.1 Definitions 551 - Alias: An alias string can also be associated with an iSCSI Node. 552 The alias allows an organization to associate a user-friendly string 553 with the iSCSI Name. However, the alias string is not a substitute 554 for the iSCSI Name. 556 - CID (Connection ID): Connections within a session are identified 557 by a connection ID. It is a unique ID for this connection within the 558 session for the initiator. It is generated by the initiator and 559 presented to the target during login requests and during logouts 560 that close connections. 562 - Connection: A connection is a TCP connection. Communication 563 between the initiator and target occurs over one or more TCP 564 connections. The TCP connections carry control messages, SCSI 565 commands, parameters, and data within iSCSI Protocol Data Units 566 (iSCSI PDUs). 568 - iSCSI Device: A SCSI Device using an iSCSI service delivery 569 subsystem. Service Delivery Subsystem is defined by [SAM2] as a 570 transport mechanism for SCSI commands and responses. 572 - iSCSI Initiator Name: The iSCSI Initiator Name specifies the 573 worldwide unique name of the initiator. 575 - iSCSI Initiator Node: The "initiator". 577 - iSCSI Layer: This layer builds/receives iSCSI PDUs and relays/ 578 receives them to/from one or more TCP connections that form an 579 initiator-target "session". 581 - iSCSI Name: The name of an iSCSI initiator or iSCSI target. 583 - iSCSI Node: The iSCSI Node represents a single iSCSI initiator or 584 iSCSI target. There are one or more iSCSI Nodes within a Network 585 Entity. The iSCSI Node is accessible via one or more Network 586 Portals. An iSCSI Node is identified by its iSCSI Name. The 587 separation of the iSCSI Name from the addresses used by and for the 588 iSCSI Node allows multiple iSCSI nodes to use the same address, and 589 the same iSCSI node to use multiple addresses. 591 - iSCSI Target Name: The iSCSI Target Name specifies the worldwide 592 unique name of the target. 594 - iSCSI Target Node: The "target". 596 - iSCSI Task: An iSCSI task is an iSCSI request for which a response 597 is expected. 599 - iSCSI Transfer Direction: The iSCSI transfer direction is defined 600 with regard to the initiator. Outbound or outgoing transfers are 602 Julian Satran Expires August 2003 14 603 iSCSI 19-January-03 605 transfers from the initiator to the target, while inbound or incoming 606 transfers are from the target to the initiator. 608 - ISID: The initiator part of the Session Identifier. It is 609 explicitly specified by the initiator during Login. 611 - I_T nexus: According to [SAM2], the I_T nexus is a relationship 612 between a SCSI Initiator Port and a SCSI Target Port. For iSCSI, 613 this relationship is a session, defined as a relationship between an 614 iSCSI Initiator's end of the session (SCSI Initiator Port) and the 615 iSCSI Target's Portal Group. The I_T nexus can be identified by the 616 conjunction of the SCSI port names; that is, the I_T nexus 617 identifier is the tuple (iSCSI Initiator Name + ',i,'+ ISID, iSCSI 618 Target Name + ',t,'+ Portal Group Tag). 620 - Network Entity: The Network Entity represents a device or gateway 621 that is accessible from the IP network. A Network Entity must have 622 one or more Network Portals, each of which can be used to gain 623 access to the IP network by some iSCSI Nodes contained in that 624 Network Entity. 626 - Network Portal: The Network Portal is a component of a Network 627 Entity that has a TCP/IP network address and that may be used by an 628 iSCSI Node within that Network Entity for the connection(s) within 629 one of its iSCSI sessions. A Network Portal in an initiator is 630 identified by its IP address. A Network Portal in a target is 631 identified by its IP address and its listening TCP port. 633 - Originator: In a negotiation or exchange, the party that initiates 634 the negotiation or exchange. 636 - PDU (Protocol Data Unit): The initiator and target divide their 637 communications into messages. The term "iSCSI protocol data unit" 638 (iSCSI PDU) is used for these messages. 640 - Portal Groups: iSCSI supports multiple connections within the same 641 session; some implementations will have the ability to combine 642 connections in a session across multiple Network Portals. A Portal 643 Group defines a set of Network Portals within an iSCSI Network 644 Entity that collectively supports the capability of coordinating a 645 session with connections spanning these portals. Not all Network 646 Portals within a Portal Group need participate in every session 647 connected through that Portal Group. One or more Portal Groups may 648 provide access to an iSCSI Node. Each Network Portal, as utilized by 649 a given iSCSI Node, belongs to exactly one portal group within that 650 node. 652 - Portal Group Tag: This 16-bit quantity identifies a Portal Group 653 within an iSCSI Node. All Network Portals with the same portal group 654 tag in the context of a given iSCSI Node are in the same Portal 655 Group. 657 - Recovery R2T: An R2T generated by a target upon detecting the loss 658 of one or more Data-Out PDUs through one of the following means: a 660 Julian Satran Expires August 2003 15 661 iSCSI 19-January-03 663 digest error, a sequence error, or a sequence reception timeout. A 664 recovery 665 R2T carries the next unused R2TSN, but requests all or part of the 666 data burst that an earlier R2T (with a lower R2TSN) had already 667 requested. 669 - Responder: In a negotiation or exchange, the party that responds 670 to the originator of the negotiation or exchange. 672 - SCSI Device: This is the SAM2 term for an entity that contains one 673 or more SCSI ports that are connected to a service delivery 674 subsystem and supports a SCSI application protocol. For example, a 675 SCSI Initiator Device contains one or more SCSI Initiator Ports and 676 zero or more application clients. A Target Device contains one or 677 more SCSI Target Ports and one or more device servers and associated 678 logical units. For iSCSI, the SCSI Device is the component within an 679 iSCSI Node that provides the SCSI functionality. As such, there can 680 be, at most, one SCSI Device within a given iSCSI Node. Access to 681 the SCSI Device can only be achieved in an iSCSI normal operational 682 session. The SCSI Device Name is defined to be the iSCSI Name of the 683 node. 685 - SCSI Layer: This builds/receives SCSI CDBs (Command Descriptor 686 Blocks) and relays/receives them with the remaining command execute 687 [SAM2] parameters to/from the iSCSI Layer. 689 - Session: The group of TCP connections that link an initiator with 690 a target form a session (loosely equivalent to a SCSI I-T nexus). 691 TCP connections can be added and removed from a session. Across all 692 connections within a session, an initiator sees one and the same 693 target. 695 - SSID (Session ID): A session between an iSCSI initiator and an 696 iSCSI target is defined by a session ID that is a tuple composed of 697 an initiator part (ISID) and a target part (Target Portal Group 698 Tag). The ISID is explicitly specified by the initiator at session 699 establishment. The Target Portal Group Tag is implied by the 700 initiator through the selection of the TCP endpoint at connection 701 establishment. The TargetPortalGroupTag key must also be returned by 702 the target as a confimation during connection establishment. 704 - SCSI Initiator Port: This maps to the endpoint of an iSCSI normal 705 operational session. An iSCSI normal operational session is 706 negotiated through the login process between an iSCSI initiator node 707 and an iSCSI target node. At successful completion of this process, 708 a SCSI Initiator Port is created within the SCSI Initiator Device. 709 The SCSI Initiator Port Name and SCSI Initiator Port Identifier are 710 both defined to be the iSCSI Initiator Name together with (a) a 711 label that identifies it as an initiator port name/identifier and 712 (b) the ISID portion of the session identifier. 714 - SCSI Port: This is the SAM2 term for an entity in a SCSI Device 715 that provides the SCSI functionality to interface with a service 716 delivery subsystem. For iSCSI, the definition of the SCSI Initiator 717 Port and the SCSI Target Port are different. 719 Julian Satran Expires August 2003 16 720 iSCSI 19-January-03 722 - SCSI Port Name: A name made up as UTF-8 characters and includes 723 the iSCSI Name + 'i' or 't' + ISID or Portal Group Tag. 725 - SCSI Target Port: This maps to an iSCSI Target Portal Group. 727 - SCSI Target Port Name and SCSI Target Port Identifier: These are 728 both defined to be the iSCSI Target Name together with (a) a label 729 that identifies it as a target port name/identifier and (b) the 730 portal group tag. 732 - Target Portal Group Tag: A numerical identifier (16-bit) for an 733 iSCSI Target Portal Group. 735 - TSIH (Target Session Identifying Handle): A target assigned tag 736 for a session with a specific named initiator. The target generates 737 it during session establishment. Its internal format and content are 738 not defined by this protocol except for the value 0 that is reserved 739 and used by the initiator to indicate a new session. It is given to 740 the target during additional connection establishment for the same 741 session. 743 Julian Satran Expires August 2003 17 744 iSCSI 19-January-03 746 2.2 Acronyms 748 AcronymDefinition 749 -------------------------------------------------------------- 750 3DES Triple Data Encryption Standard 751 ACA Auto Contingent Allegiance 752 AEN Asynchronous Event Notification 753 AES Advanced Encryption Standard 754 AH Additional Header (not the IPsec AH!) 755 AHS Additional Header Segment 756 API Application Programming Interface 757 ASC Additional Sense Code 758 ASCII American Standard Code for Information Interchange 759 ASCQ Additional Sense Code Qualifier 760 BHS Basic Header Segment 761 CBC Cipher Block Chaining 762 CD Compact Disk 763 CDB Command Descriptor Block 764 CHAP Challenge Handshake Authentication Protocol 765 CID Connection ID 766 CO Connection Only 767 CRC Cyclic Redundancy Check 768 CRL Certificate Revocation List 769 CSG Current Stage 770 CSM Connection State Machine 771 DES Data Encryption Standard 772 DNS Domain Name Server 773 DOI Domain of Interpretation 774 DVD Digital Versatile Disk 775 ESP Encapsulating Security Payload 776 EUI Extended Unique Identifier 777 FFP Full Feature Phase 778 FFPO Full Feature Phase Only 779 FIM Fixed Interval Marker 780 Gbps Gigabits per Second 781 HBA Host Bus Adapter 782 HMAC Hashed Message Authentication Code 783 I_T Initiator_Target 784 I_T_L Initiator_Target_LUN 785 IANA Internet Assigned Numbers Authority 786 ID Identifier 787 IDN Internationalized Domain Name 788 IEEE Institute of Electrical & Electronics Engineers 789 IETF Internet Engineering Task Force 790 IKE Internet Key Exchange 791 I/O Input - Output 792 IO Initialize Only 793 IP Internet Protocol 794 IPsec Internet Protocol Security 795 IPv4 Internet Protocol Version 4 796 IPv6 Internet Protocol Version 6 797 IQN iSCSI Qualified Name 798 ISID Initiator Session ID 799 ITN iSCSI Target Name 800 ITT Initiator Task Tag 801 KRB5 Kerberos V5 803 Julian Satran Expires August 2003 18 804 iSCSI 19-January-03 806 LFL Lower Functional Layer 807 LTDS Logical-Text-Data-Segment 808 LO Leading Only 809 LU Logical Unit 810 LUN Logical Unit Number 811 MAC Message Authentication Codes 812 NA Not Applicable 813 NIC Network Interface Card 814 NOP No Operation 815 NSG Next Stage 816 OS Operating System 817 PDU Protocol Data Unit 818 PKI Public Key Infrastructure 819 R2T Ready To Transfer 820 R2TSN Ready To Transfer Sequence Number 821 RDMA Remote Direct Memory Access 822 RFC Request For Comments 823 SAM SCSI Architecture Model 824 SAM2 SCSI Architecture Model - 2 825 SAN Storage Area Network 826 SCSI Small Computer Systems Interface 827 SN Sequence Number 828 SNACK Selective Negative Acknowledgment - also 829 Sequence Number Acknowledgement for data 830 SPKM Simple Public-Key Mechanism 831 SRP Secure Remote Password 832 SSID Session ID 833 SW Session Wide 834 TCB Task Control Block 835 TCP Transmission Control Protocol 836 TPGT Target Portal Group Tag 837 TSIH Target Session Identifying Handle 838 TTT Target Transfer Tag 839 UFL Upper Functional Layer 840 ULP Upper Level Protocol 841 URN Uniform Resource Names 842 UTF Universal Transformation Format 843 WG Working Group 845 2.3 Conventions 847 In examples, "I->" and "T->" show iSCSI PDUs sent by the initiator 848 and target respectively. 850 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 851 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 852 document are to be interpreted as described in RFC2119. 854 iSCSI messages - PDUs - are represented by diagrams as in the 855 following example: 857 Julian Satran Expires August 2003 19 858 iSCSI 19-January-03 860 Byte/ 0 | 1 | 2 | 3 | 861 / | | | | 862 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 863 +---------------+---------------+---------------+---------------+ 864 0| Basic Header Segment (BHS) | 865 +---------------+---------------+---------------+---------------+ 866 ---------- 867 +| | 868 +---------------+---------------+---------------+---------------+ 870 The diagrams include byte and bit numbering. 872 The following representation and ordering rules are observed in this 873 document: 875 - Word Rule 876 - Half-word Rule 877 - Byte Rule 879 2.3.1 Word Rule 881 A word holds four consecutive bytes. Whenever a word has numeric 882 content, it is considered an unsigned number in base 2 positional 883 representation with the lowest numbered byte (e.g., byte 0) bit 0 884 representing 2**31 and bit 1 representing 2**30 through lowest 885 numbered byte + 3 (e.g., byte 3) bit 7 representing 2**0. 887 Decimal and hexadecimal representation of word values map this 888 representation to decimal or hexadecimal positional notation. 890 2.3.2 Half-Word Rule 892 A half-word holds two consecutive bytes. Whenever a half-word has 893 numeric content it is considered an unsigned number in base 2 894 positional representation with the lowest numbered byte (e.g., byte 895 0) bit 0 representing 2**15 and bit 1 representing 2**14 through 896 lowest numbered byte + 1 (e.g., byte 1) bit 7 representing 2**0. 898 Decimal and hexadecimal representation of half-word values map this 899 representation to decimal or hexadecimal positional notation. 901 2.3.3 Byte Rule 903 For every PDU, bytes are sent and received in increasing numbered 904 order (network order). 906 Whenever a byte has numerical content it is considered an unsigned 907 number in base 2 positional representation with bit 0 representing 908 2**7 and bit 1 representing 2**6 through bit 7 representing 2**0. 910 Julian Satran Expires August 2003 20 911 iSCSI 19-January-03 913 3. Overview 915 3.1 SCSI Concepts 917 The SCSI Architecture Model-2 [SAM2] describes in detail the 918 architecture of the SCSI family of I/O protocols. This section 919 provides a brief background of the SCSI architecture and is intended 920 to familiarize readers with its terminology. 922 At the highest level, SCSI is a family of interfaces for requesting 923 services from I/O devices, including hard drives, tape drives, CD 924 and DVD drives, printers, and scanners. In SCSI terminology, an 925 individual I/O device is called a "logical unit" (LU). 927 SCSI is a client-server architecture. Clients of a SCSI interface 928 are called "initiators". Initiators issue SCSI "commands" to request 929 services from components, logical units, of a server known as a 930 "target". The "device server" on the logical unit accepts SCSI 931 commands and processes them. 933 A "SCSI transport" maps the client-server SCSI protocol to a 934 specific interconnect. Initiators are one endpoint of a SCSI 935 transport. The "target" is the other endpoint. A target can contain 936 multiple Logical Units (LUs). Each Logical Unit has an address 937 within a target called a Logical Unit Number (LUN). 939 A SCSI task is a SCSI command or possibly a linked set of SCSI 940 commands. Some LUs support multiple pending (queued) tasks, but the 941 queue of tasks is managed by the logical unit. The target uses an 942 initiator provided "task tag" to distinguish between tasks. Only one 943 command in a task can be outstanding at any given time. 945 Each SCSI command results in an optional data phase and a required 946 response phase. In the data phase, information can travel from the 947 initiator to target (e.g., WRITE), target to initiator (e.g., READ), 948 or in both directions. In the response phase, the target returns the 949 final status of the operation, including any errors. 951 Command Descriptor Blocks (CDB) are the data structures used to 952 contain the command parameters that an initiator sends to a target. 953 The CDB content and structure is defined by [SAM2] and device-type 954 specific SCSI standards. 956 3.2 iSCSI Concepts and Functional Overview 958 The iSCSI protocol is a mapping of the SCSI remote procedure 959 invocation model (see [SAM2]) over the TCP protocol. SCSI commands 960 are carried by iSCSI requests and SCSI responses and status are 961 carried by iSCSI responses. iSCSI also uses the request response 962 mechanism for iSCSI protocol mechanisms. 964 For the remainder of this document, the terms "initiator" and 965 "target" refer to "iSCSI initiator node" and "iSCSI target node", 966 respectively (see Section 3.4.1 iSCSI Architecture Model) unless 967 otherwise qualified. 969 Julian Satran Expires August 2003 21 970 iSCSI 19-January-03 972 In keeping with similar protocols, the initiator and target divide 973 their communications into messages. This document uses the term 974 "iSCSI protocol data unit" (iSCSI PDU) for these messages. 976 For performance reasons, iSCSI allows a "phase-collapse". A command 977 and its associated data may be shipped together from initiator to 978 target, and data and responses may be shipped together from targets. 980 The iSCSI transfer direction is defined with respect to the 981 initiator. Outbound or outgoing transfers are transfers from an 982 initiator to a target, while inbound or incoming transfers are from 983 a target to an initiator. 985 An iSCSI task is an iSCSI request for which a response is expected. 987 In this document "iSCSI request", "iSCSI command", request, or 988 (unqualified) command have the same meaning. Also, unless otherwise 989 specified, status, response, or numbered response have the same 990 meaning. 992 3.2.1 Layers and Sessions 994 The following conceptual layering model is used to specify initiator 995 and target actions and the way in which they relate to transmitted 996 and received Protocol Data Units: 998 a) the SCSI layer builds/receives SCSI CDBs (Command 999 Descriptor Blocks) and passes/receives them with the remaining 1000 command execute parameters ([SAM2]) to/from 1001 b) the iSCSI layer that builds/receives iSCSI PDUs and relays/ 1002 receives them to/from one or more TCP connections; the group of 1003 connections form an initiator-target "session". 1005 Communication between the initiator and target occurs over one or 1006 more TCP connections. The TCP connections carry control messages, 1007 SCSI commands, parameters, and data within iSCSI Protocol Data Units 1008 (iSCSI PDUs). The group of TCP connections that link an initiator 1009 with a target form a session (loosely equivalent to a SCSI I_T 1010 nexus, see Section 3.4.2 SCSI Architecture Model). A session is 1011 defined by a session ID that is composed of an initiator part and a 1012 target part. TCP connections can be added and removed from a 1013 session. Each connections within a session is identified by a 1014 connection ID (CID). 1016 Across all connections within a session, an initiator sees one 1017 "target image". All target identifying elements, such as LUN, are 1018 the same. A target also sees one "initiator image" across all 1019 connections within a session. Initiator identifying elements, such 1020 as the Initiator Task Tag, are global across the session regardless 1021 of the connection on which they are sent or received. 1023 iSCSI targets and initiators MUST support at least one TCP 1024 connection and MAY support several connections in a session. For 1025 error recovery purposes, targets and initiators that support a 1027 Julian Satran Expires August 2003 22 1028 iSCSI 19-January-03 1030 single active connection in a session SHOULD support two connections 1031 during recovery. 1033 3.2.2 Ordering and iSCSI Numbering 1035 iSCSI uses Command and Status numbering schemes and a Data 1036 sequencing scheme. 1038 Command numbering is session-wide and is used for ordered command 1039 delivery over multiple connections. It can also be used as a 1040 mechanism for command flow control over a session. 1042 Status numbering is per connection and is used to enable missing 1043 status detection and recovery in the presence of transient or 1044 permanent communication errors. 1046 Data sequencing is per command or part of a command (R2T triggered 1047 sequence) and is used to detect missing data and/or R2T PDUs due to 1048 header digest errors. 1050 Typically, fields in the iSCSI PDUs communicate the Sequence Numbers 1051 between the initiator and target. During periods when traffic on a 1052 connection is unidirectional, iSCSI NOP-Out/In PDUs may be utilized 1053 to synchronize the command and status ordering counters of the 1054 target and initiator. 1056 3.2.2.1 Command Numbering and Acknowledging 1058 iSCSI performs ordered command delivery within a session. All 1059 commands (initiator-to-target PDUs) in transit from the initiator to 1060 the target are numbered. 1062 iSCSI considers a task to be instantiated on the target in response 1063 to every request issued by the initiator. A set of task management 1064 operations including abort and reassign (see Section 10.5 Task 1065 Management Function Request) may be performed on any iSCSI task. 1066 Some iSCSI tasks are SCSI tasks, and many SCSI activities are 1067 related to a SCSI task ([SAM2]). In all cases, the task is 1068 identified by the Initiator Task Tag for the life of the task. 1070 The command number is carried by the iSCSI PDU as CmdSN (Command- 1071 Sequence-Number). The numbering is session-wide. Outgoing iSCSI PDUs 1072 carry this number. The iSCSI initiator allocates CmdSNs with a 32- 1073 bit unsigned counter (modulo 2**32). Comparisons and arithmetic on 1074 CmdSN use Serial Number Arithmetic as defined in [RFC1982] where 1075 SERIAL_BITS = 32. 1077 Commands meant for immediate delivery are marked with an immediate 1078 delivery flag; they MUST also carry the current CmdSN. CmdSN does 1079 not advance after a command marked for immediate delivery is sent. 1081 Command numbering starts with the first login request on the first 1082 connection of a session (the leading login on the leading 1083 connection) and command numbers are incremented by 1 for every non- 1084 immediate command issued afterwards. 1086 Julian Satran Expires August 2003 23 1087 iSCSI 19-January-03 1089 If immediate delivery is used with task management commands, these 1090 commands may reach the target before the tasks on which they are 1091 supposed to act. However their CmdSN serves as a marker of their 1092 position in the stream of commands. The initiator and target must 1093 ensure that the task management commands act as specified by [SAM2]. 1094 For example, both commands and responses appear as if delivered in 1095 order. Whenever CmdSN for an outgoing PDU is not specified by an 1096 explicit rule, CmdSN will carry the current value of the local CmdSN 1097 variable (see later in this section). 1099 The means by which an implementation decides to mark a PDU for 1100 immediate delivery or by which iSCSI decides by itself to mark a PDU 1101 for immediate delivery are beyond the scope of this document. 1103 The number of commands used for immediate delivery is not limited 1104 and their delivery to execution is not acknowledged through the 1105 numbering scheme. Immediate commands MAY be rejected by the iSCSI 1106 target layer due to lack of resources. An iSCSI target MUST be able 1107 to handle at least one immediate task management command and one 1108 immediate non-task-management iSCSI command per connection at any 1109 time. 1111 In this document, delivery for execution means delivery to the SCSI 1112 execution engine or an iSCSI protocol specific execution engine 1113 (e.g., for text requests with public or private extension keys 1114 involving an execution component). With the exception of the 1115 commands marked for immediate delivery, the iSCSI target layer MUST 1116 deliver the commands for execution in the order specified by CmdSN. 1117 Commands marked for immediate delivery may be delivered by the iSCSI 1118 target layer for execution as soon as detected. iSCSI may avoid 1119 delivering some commands to the SCSI target layer if required by a 1120 prior SCSI or iSCSI action (e.g., CLEAR TASK SET Task Management 1121 request received before all the commands on which it was supposed to 1122 act). 1124 On any connection, the iSCSI initiator MUST send the commands in 1125 increasing order of CmdSN, except for commands that are 1126 retransmitted due to digest error recovery and connection recovery. 1128 For the numbering mechanism, the initiator and target maintain the 1129 following three variables for each session: 1131 - CmdSN - the current command Sequence Number, advanced by 1 on 1132 each command shipped except for commands marked for immediate 1133 delivery. CmdSN always contains the number to be assigned to 1134 the next Command PDU. 1135 - ExpCmdSN - the next expected command by the target. The 1136 target acknowledges all commands up to, but not including, 1137 this number. The initiator treats all commands with CmdSN less 1138 than ExpCmdSN as acknowledged. The target iSCSI layer sets the 1139 ExpCmdSN to the largest non-immediate CmdSN that it can 1140 deliver for execution plus 1 (no holes in the CmdSN sequence). 1141 - MaxCmdSN - the maximum number to be shipped. The queuing 1142 capacity of the receiving iSCSI layer is MaxCmdSN - ExpCmdSN + 1143 1. 1145 Julian Satran Expires August 2003 24 1146 iSCSI 19-January-03 1148 The initiator's ExpCmdSN and MaxCmdSN are derived from target-to- 1149 initiator PDU fields. Comparisons and arithmetic on ExpCmdSN and 1150 MaxCmdSN MUST use Serial Number Arithmetic as defined in [RFC1982] 1151 where SERIAL_BITS = 32. 1153 The target MUST NOT transmit a MaxCmdSN that is less than ExpCmdSN- 1154 1. For non-immediate commands, the CmdSN field can take any value 1155 from ExpCmdSN to MaxCmdSN inclusive. The target MUST silently ignore 1156 any non-immediate command outside of this range or non-immediate 1157 duplicates within the range. The CmdSN carried by immediate commands 1158 may lie outside the ExpCmdSN to MaxCmdSN range. For example, if the 1159 initiator has previously sent a non-immediate command carrying the 1160 CmdSN equal to MaxCmdSN, the target window is closed. For group task 1161 management commands issued as immediate commands, CmdSN indicates 1162 the scope of the group action (e.g., on ABORT TASK SET indicates 1163 which commands are aborted). 1165 MaxCmdSN and ExpCmdSN fields are processed by the initiator as 1166 follows: 1168 -If the PDU MaxCmdSN is less than the PDU ExpCmdSN-1 (in Serial 1169 Arithmetic Sense), they are both ignored. 1170 -If the PDU MaxCmdSN is greater than the local MaxCmdSN (in 1171 Serial Arithmetic Sense), it updates the local MaxCmdSN; 1172 otherwise, it is ignored. 1173 -If the PDU ExpCmdSN is greater than the local ExpCmdSN (in 1174 Serial Arithmetic Sense), it updates the local ExpCmdSN; 1175 otherwise, it is ignored. 1177 This sequence is required because updates may arrive out of order 1178 (e.g., the updates are sent on different TCP connections). 1180 iSCSI initiators and targets MUST support the command numbering 1181 scheme. 1183 A numbered iSCSI request will not change its allocated CmdSN, 1184 regardless of the number of times and circumstances in which it is 1185 reissued (see Section 6.2.1 Usage of Retry). At the target, CmdSN is 1186 only relevant when the command has not created any state related to 1187 its execution (execution state); afterwards, CmdSN becomes 1188 irrelevant. Testing for the execution state (represented by 1189 identifying the Initiator Task Tag) MUST precede any other action at 1190 the target. If no execution state is found, it is followed by 1191 ordering and delivery. If an execution state is found, it is 1192 followed by delivery. 1194 If an initiator issues a command retry for a command with CmdSN R on 1195 a connection when the session CmdSN value is Q, it MUST NOT advance 1196 the CmdSN past R + 2**31 -1 unless the connection is no longer 1197 operational (i.e., it has returned to the FREE state, see Section 1198 7.1.3 Standard Connection State Diagram for an Initiator), the 1199 connection has been reinstated (see Section 5.3.4 Connection 1200 Reinstatement), or a non-immediate command with CmdSN equal or 1201 greater than Q was issued subsequent to the command retry on the 1202 same connection and the reception of that command is acknowledged by 1204 Julian Satran Expires August 2003 25 1205 iSCSI 19-January-03 1207 the target (see Section 9.4 Command Retry and Cleaning Old Command 1208 Instances). 1210 A target MUST NOT issue a command response or DATA-In PDU with 1211 status before acknowledging the command. However, the 1212 acknowledgement can be included in the response or Data-in PDU. 1214 3.2.2.2 Response/Status Numbering and Acknowledging 1216 Responses in transit from the target to the initiator are numbered. 1217 The StatSN (Status Sequence Number) is used for this purpose. StatSN 1218 is a counter maintained per connection. ExpStatSN is used by the 1219 initiator to acknowledge status. The status sequence number space is 1220 32-bit unsigned-integers and the arithmetic operations are the 1221 regular mod(2**32) arithmetic. 1223 Status numbering starts with the Login response to the first Login 1224 request of the connection. The Login response includes an initial 1225 value for status numbering (any initial value is valid). 1227 To enable command recovery, the target MAY maintain enough state 1228 information for data and status recovery after a connection failure. 1229 A target doing so can safely discard all of the state information 1230 maintained for recovery of a command after the delivery of the 1231 status for the command (numbered StatSN) is acknowledged through 1232 ExpStatSN. 1234 A large absolute difference between StatSN and ExpStatSN may 1235 indicate a failed connection. Initiators MUST undertake recovery 1236 actions if the difference is greater than an implementation defined 1237 constant that MUST NOT exceed 2**31-1. 1239 Initiators and Targets MUST support the response-numbering scheme. 1241 3.2.2.3 Data Sequencing 1243 Data and R2T PDUs transferred as part of some command execution MUST 1244 be sequenced. The DataSN field is used for data sequencing. For 1245 input (read) data PDUs, DataSN starts with 0 for the first data PDU 1246 of an input command and advances by 1 for each subsequent data PDU. 1247 For output data PDUs, DataSN starts with 0 for the first data PDU of 1248 a sequence (the initial unsolicited sequence or any data PDU 1249 sequence issued to satisfy an R2T) and advances by 1 for each 1250 subsequent data PDU. R2Ts are also sequenced per command. For 1251 example, the first R2T has an R2TSN of 0 and advances by 1 for each 1252 subsequent R2T. For bidirectional commands, the target uses the 1253 DataSN/R2TSN to sequence Data-In and R2T PDUs in one continuous 1254 sequence (undifferentiated). Unlike command and status, data PDUs 1255 and R2Ts are not acknowledged by a field in regular outgoing PDUs. 1256 Data-In PDUs can be acknowledged on demand by a special form of the 1257 SNACK PDU. Data and R2T PDUs are implicitly acknowledged by status 1258 for the command. The DataSN/R2TSN field enables the initiator to 1259 detect missing data or R2T PDUs. 1261 Julian Satran Expires August 2003 26 1262 iSCSI 19-January-03 1264 For any read or bidirectional command, a target MUST issue less than 1265 2**32 combined R2T and Data-In PDUs. Any output data sequence MUST 1266 contain less than 2**32 Data-Out PDUs. 1268 3.2.3 iSCSI Login 1270 The purpose of the iSCSI login is to enable a TCP connection for 1271 iSCSI use, authentication of the parties, negotiation of the 1272 session's parameters and marking of the connection as belonging to 1273 an iSCSI session. 1275 A session is used to identify to a target all the connections with a 1276 given initiator that belong to the same I_T nexus. (For more details 1277 on how a session relates to an I_T nexus, see Section 3.4.2 SCSI 1278 Architecture Model). 1280 The targets listen on a well-known TCP port or other TCP port for 1281 incoming connections. The initiator begins the login process by 1282 connecting to one of these TCP ports. 1284 As part of the login process, the initiator and target SHOULD 1285 authenticate each other and MAY set a security association protocol 1286 for the session. This can occur in many different ways and is 1287 subject to negotiation. 1289 To protect the TCP connection, an IPsec security association MAY be 1290 established before the Login request. For information on using IPsec 1291 security for iSCSI see Chapter 8 and [SEC-IPS]. 1293 The iSCSI Login Phase is carried through Login requests and 1294 responses. Once suitable authentication has occurred and operational 1295 parameters have been set, the session transitions to Full Feature 1296 Phase and the initiator may start to send SCSI commands. The 1297 security policy for whether, and by what means, a target chooses to 1298 authorize an initiator is beyond the scope of this document. For a 1299 more detailed description of the Login Phase, see Chapter 5. 1301 The login PDU includes the ISID part of the session ID (SSID). The 1302 target portal group that services the login is implied by the 1303 selection of the connection endpoint. For a new session, the TSIH is 1304 zero. As part of the response, the target generates a TSIH. 1306 During session establishment, the target identifies the SCSI 1307 initiator port (the "I" in the "I_T nexus") through the value pair 1308 (InitiatorName, ISID). We describe InitiatorName later in this 1309 section. Any persistent state (e.g., persistent reservations) on the 1310 target that is associated with a SCSI initiator port is identified 1311 based on this value pair. Any state associated with the SCSI target 1312 port (the "T" in the "I_T nexus") is identified externally by the 1313 TargetName and portal group tag (see Section 3.4.1 iSCSI 1314 Architecture Model). ISID is subject to reuse restrictions because 1315 it is used to identify a persistent state (see Section 3.4.3 1316 Consequences of the Model). 1318 Julian Satran Expires August 2003 27 1319 iSCSI 19-January-03 1321 Before the Full Feature Phase is established, only Login Request and 1322 Login Response PDUs are allowed. Login requests and responses MUST 1323 be used exclusively during Login. On any connection, the login phase 1324 MUST immediately follow TCP connection establishment and a 1325 subsequent Login Phase MUST NOT occur before tearing down a 1326 connection. 1328 A target receiving any PDU except a Login request before the Login 1329 phase is started MUST immediately terminate the connection on which 1330 the PDU was received. Once the Login phase has started, if the 1331 target receives any PDU except a Login request, it MUST send a Login 1332 reject (with Status "invalid during login") and then disconnect. If 1333 the initiator receives any PDU except a Login response, it MUST 1334 immediately terminate the connection. 1336 3.2.4 iSCSI Full Feature Phase 1338 Once the initiator is authorized to do so, the iSCSI session is in 1339 the iSCSI Full Feature Phase. A session is in Full Feature Phase 1340 after successfully finishing the Login Phase on the first (leading) 1341 connection of a session. A connection is in Full Feature Phase if 1342 the session is in Full Feature Phase and the connection login has 1343 completed successfully. An iSCSI connection is not in Full Feature 1344 Phase 1346 a) when it does not have an established transport connection, 1347 OR 1348 b) when it has a valid transport connection, but a successful 1349 login was not performed or the connection is currently logged 1350 out. 1352 In a normal Full Feature Phase, the initiator may send SCSI commands 1353 and data to the various LUs on the target by encapsulating them in 1354 iSCSI PDUs that go over the established iSCSI session. 1356 3.2.4.1 Command Connection Allegiance 1358 For any iSCSI request issued over a TCP connection, the 1359 corresponding response and/or other related PDU(s) MUST be sent over 1360 the same connection. We call this "connection allegiance". If the 1361 original connection fails before the command is completed, the 1362 connection allegiance of the command may be explicitly reassigned to 1363 a different transport connection as described in detail in Section 1364 6.2 Retry and Reassign in Recovery. 1366 Thus, if an initiator issues a READ command, the target MUST send 1367 the requested data, if any, followed by the status to the initiator 1368 over the same TCP connection that was used to deliver the SCSI 1369 command. If an initiator issues a WRITE command, the initiator MUST 1370 send the data, if any, for that command over the same TCP connection 1371 that was used to deliver the SCSI command. The target MUST return 1372 Ready To Transfer (R2T), if any, and the status over the same TCP 1373 connection that was used to deliver the SCSI command. Retransmission 1374 requests (SNACK PDUs) and the data and status that they generate 1375 MUST also use the same connection. 1377 Julian Satran Expires August 2003 28 1378 iSCSI 19-January-03 1380 However, consecutive commands that are part of a SCSI linked 1381 command-chain task (see [SAM2]) MAY use different connections. 1382 Connection allegiance is strictly per-command and not per-task. 1383 During the iSCSI Full Feature Phase, the initiator and target MAY 1384 interleave unrelated SCSI commands, their SCSI Data, and responses 1385 over the session. 1387 3.2.4.2 Data Transfer Overview 1389 Outgoing SCSI data (initiator to target user data or command 1390 parameters) is sent as either solicited data or unsolicited data. 1391 Solicited data are sent in response to R2T PDUs. Unsolicited data 1392 can be sent as part of an iSCSI command PDU ("immediate data") or in 1393 separate iSCSI data PDUs. 1395 Immediate data are assumed to originate at offset 0 in the initiator 1396 SCSI write-buffer (outgoing data buffer). All other Data PDUs have 1397 the buffer offset set explicitly in the PDU header. 1399 An initiator may send unsolicited data up to FirstBurstLength as 1400 immediate (up to the negotiated maximum PDU length), in a separate 1401 PDU sequence or both. All subsequent data MUST be solicited. The 1402 maximum length of an individual data PDU or the immediate-part of 1403 the first unsolicited burst MAY be negotiated at login. 1405 The maximum amount of unsolicited data that can be sent with a 1406 command is negotiated at login through the FirstBurstLength key. A 1407 target MAY separately enable immediate data (through the 1408 ImmediateData key) without enabling the more general (separate data 1409 PDUs) form of unsolicited data (through the InitialR2T key). 1411 Unsolicited data on write are meant to reduce the effect of latency 1412 on throughput (no R2T is needed to start sending data). In addition, 1413 immediate data is meant to reduce the protocol overhead (both 1414 bandwidth and execution time). 1416 An iSCSI initiator MAY choose not to send unsolicited data, only 1417 immediate data or FirstBurstLength bytes of unsolicited data with a 1418 command. If any non-immediate unsolicited data is sent, the total 1419 unsolicited data MUST be either FirstBurstLength, or all of the data 1420 if the total amount is less than the FirstBurstLength. 1422 It is considered an error for an initiator to send unsolicited data 1423 PDUs to a target that operates in R2T mode (only solicited data are 1424 allowed). It is also an error for an initiator to send more 1425 unsolicited data, whether immediate or as separate PDUs, than 1426 FirstBurstLength. 1428 An initiator MUST honor an R2T data request for a valid outstanding 1429 command (i.e., carrying a valid Initiator Task Tag) and deliver all 1430 the requested data provided the command is supposed to deliver 1431 outgoing data and the R2T specifies data within the command bounds. 1432 The initiator action is unspecified for receiving an R2T request 1433 that specifies data, all or part, outside of the bounds of the 1434 command. 1436 Julian Satran Expires August 2003 29 1437 iSCSI 19-January-03 1439 A target SHOULD NOT silently discard data and then request 1440 retransmission through R2T. Initiators SHOULD NOT keep track of the 1441 data transferred to or from the target (scoreboarding). SCSI targets 1442 perform residual count calculation to check how much data was 1443 actually transferred to or from the device by a command. This may 1444 differ from the amount the initiator sent and/or received for 1445 reasons such as retransmissions and errors. Read or bidirectional 1446 commands implicitly solicit the transmission of the entire amount of 1447 data covered by the command. SCSI data packets are matched to their 1448 corresponding SCSI commands by using tags specified in the protocol. 1450 In addition, iSCSI initiators and targets MUST enforce some ordering 1451 rules. When unsolicited data is used, the order of the unsolicited 1452 data on each connection MUST match the order in which the commands 1453 on that connection are sent. Command and unsolicited data PDUs may 1454 be interleaved on a single connection as long as the ordering 1455 requirements of each are maintained (e.g., command N+1 MAY be sent 1456 before the unsolicited Data-Out PDUs for command N, but the 1457 unsolicited Data-Out PDUs for command N MUST precede the unsolicited 1458 Data-Out PDUs of command N+1). A target that receives data out of 1459 order MAY terminate the session. 1461 3.2.4.3 Tags and Integrity Checks 1463 Initiator tags for pending commands are unique initiator-wide for a 1464 session. Target tags are not strictly specified by the protocol. It 1465 is assumed that target tags are used by the target to tag (alone or 1466 in combination with the LUN) the solicited data. Target tags are 1467 generated by the target and "echoed" by the initiator. These 1468 mechanisms are designed to accomplish efficient data delivery along 1469 with a large degree of control over the data flow. 1471 As the Initiator Task Tag is used to identify a task during its 1472 execution the iSCSI initiator and target MUST verify that all other 1473 fields used in task related PDUs have values that are consistent 1474 with the values used at the task instantiation based on Initiator 1475 Task Tag (e.g., the LUN used in an R2T PDU MUST be the same as the 1476 one used in the SCSI command PDU used to instantiate the task). 1477 Using inconsistent field values is considered a protocol error. 1479 3.2.4.4 Task Management 1481 SCSI task management assumes that individual tasks and task groups 1482 can be aborted solely based on the task tags (for individual tasks) 1483 or the timing of the task management command (for task groups) and 1484 that the task management action is executed synchronously - i.e, no 1485 message involving an aborted task will be seen by the SCSI initiator 1486 after receiving the task management response. In iSCSI initiators 1487 and targets interact asynchronously over several connections. iSCSI 1488 specifies the protocol mechanism and implementation requirements 1489 needed to present a synchronous view while using an asynchronous 1490 infrastructure. 1492 Julian Satran Expires August 2003 30 1493 iSCSI 19-January-03 1495 3.2.5 iSCSI Connection Termination 1497 An iSCSI connection may be terminated by use of a transport 1498 connection shutdown or a transport reset. Transport reset is assumed 1499 to be an exceptional event. 1501 Graceful TCP connection shutdowns are done by sending TCP FINs. A 1502 graceful transport connection shutdown SHOULD only be initiated by 1503 either party when the connection is not in iSCSI Full Feature Phase. 1504 A target MAY terminate a Full Feature Phase connection on internal 1505 exception events, but it SHOULD announce the fact through an 1506 Asynchronous Message PDU. Connection termination with outstanding 1507 commands may require recovery actions. 1509 If a connection is terminated while in Full Feature Phase, 1510 connection cleanup (see section 7) is required prior to recovery. By 1511 doing connection cleanup before starting recovery, the initiator and 1512 target will avoid receiving stale PDUs after recovery. 1514 3.2.6 iSCSI Names 1516 Both targets and initiators require names for the purpose of 1517 identification. In addition, names enable iSCSI storage resources to 1518 be managed regardless of location (address). An iSCSI node name is 1519 also the SCSI device name of an iSCSI device. The iSCSI name of a 1520 SCSI device is the principal object used in authentication of 1521 targets to initiators and initiators to targets. This name is also 1522 used to identify and manage iSCSI storage resources. 1524 iSCSI names must be unique within the operation domain of the end 1525 user. However, because the operation domain of an IP network is 1526 potentially worldwide, the iSCSI name formats are architected to be 1527 worldwide unique. To assist naming authorities in the construction 1528 of worldwide unique names, iSCSI provides two name formats for 1529 different types of naming authorities. 1531 iSCSI names are associated with iSCSI nodes, and not iSCSI network 1532 adapter cards, to ensure that the replacement of network adapter 1533 cards does not require reconfiguration of all SCSI and iSCSI 1534 resource allocation information. 1536 Some SCSI commands require that protocol-specific identifiers be 1537 communicated within SCSI CDBs. See Section 3.4.2 SCSI Architecture 1538 Model for the definition of the SCSI port name/identifier for iSCSI 1539 ports. 1541 An initiator may discover the iSCSI Target Names to which it has 1542 access, along with their addresses, using the SendTargets text 1543 request, or other techniques discussed in [NDT]. 1545 3.2.6.1 iSCSI Name Properties 1547 Each iSCSI node, whether an initiator or target, MUST have an iSCSI 1548 name. 1550 Julian Satran Expires August 2003 31 1551 iSCSI 19-January-03 1553 Initiators and targets MUST support the receipt of iSCSI names of up 1554 to the maximum length of 223 bytes. 1556 The initiator MUST present both its iSCSI Initiator Name and the 1557 iSCSI Target Name to which it wishes to connect in the first login 1558 request of a new session or connection. The only exception is if a 1559 discovery session (see Section 2.3 iSCSI Session Types) is to be 1560 established. In this case, the iSCSI Initiator Name is still 1561 required, but the iSCSI Target Name MAY be omitted. 1563 iSCSI names have the following properties: 1565 a) iSCSI names are globally unique. No two initiators or 1566 targets can have the same name. 1567 b) iSCSI names are permanent. An iSCSI initiator node or 1568 target node has the same name for its lifetime. 1569 c) iSCSI names do not imply a location or address. An iSCSI 1570 initiator or target can move, or have multiple addresses. A 1571 change of address does not imply a change of name. 1572 d) iSCSI names do not rely on a central name broker; the 1573 naming authority is distributed. 1574 e) iSCSI names support integration with existing unique naming 1575 schemes. 1576 f) iSCSI names rely on existing naming authorities. iSCSI does 1577 not create any new naming authority. 1579 The encoding of an iSCSI name has the following properties: 1581 a) iSCSI names have the same encoding method regardless of the 1582 underlying protocols. 1583 b) iSCSI names are relatively simple to compare. The algorithm 1584 for comparing two iSCSI names for equivalence does not rely on 1585 an external server. 1586 c) iSCSI names are composed only of displayable characters. 1587 iSCSI names allow the use of international character sets but 1588 are not case sensitive. No whitespace characters are used in 1589 iSCSI names. 1590 d) iSCSI names may be transported using both binary and ASCII- 1591 based protocols. 1593 An iSCSI name really names a logical software entity, and is not 1594 tied to a port or other hardware that can be changed. For instance, 1595 an initiator name should name the iSCSI initiator node, not a 1596 particular NIC or HBA. When multiple NICs are used, they should 1597 generally all present the same iSCSI initiator name to the targets, 1598 because they are simply paths to the same SCSI layer. In most 1599 operating systems, the named entity is the operating system image. 1601 Similarly, a target name should not be tied to hardware interfaces 1602 that can be changed. A target name should identify the logical 1603 target and must be the same for the target regardless of the 1605 Julian Satran Expires August 2003 32 1606 iSCSI 19-January-03 1608 physical portion being addressed. This assists iSCSI initiators in 1609 determining that the two targets it has discovered are really two 1610 paths to the same target. 1612 The iSCSI name is designed to fulfill the functional requirements 1613 for Uniform Resource Names (URN) [RFC1737]. For example, it is 1614 required that the name have a global scope, be independent of 1615 address or location, and be persistent and globally unique. Names 1616 must be extensible and scalable with the use of naming authorities. 1617 The name encoding should be both human and machine readable. See 1618 [RFC1737] for further requirements. 1620 3.2.6.2 iSCSI Name Encoding 1622 An iSCSI name MUST be a UTF-8 encoding of a string of Unicode 1623 characters with the following properties: 1624 - It is in Normalization Form C (see "Unicode Normalization 1625 Forms" [UNICODE]). 1626 - It only contains characters allowed by the output of the iSCSI 1627 stringprep template (described in [STPREP-iSCSI]). 1628 - The following characters are used for formatting iSCSI names: 1630 - dash ('-'=U+002d) 1631 - dot ('.'=U+002e) 1632 - colon (':'=U+003a) 1634 - The UTF-8 encoding of the name is not larger than 223 bytes. 1636 The stringprep process is described in [STPREP]; iSCSI's use of the 1637 stringprep process is described in [STPREP-iSCSI]. Stringprep is a 1638 method designed by the Internationalized Domain Name (IDN) working 1639 group to translate human-typed strings into a format that can be 1640 compared as opaque strings. Strings MUST NOT include punctuation, 1641 spacing, diacritical marks, or other characters that could get in 1642 the way of readability. The stringprep process also converts strings 1643 into equivalent strings of lower-case characters. 1645 The stringprep process does not need to be implemented if the names 1646 are only generated using numeric and lower-case (any character set) 1647 alphabetic characters. 1649 Once iSCSI names encoded in UTF-8 are "normalized" they may be 1650 safely compared byte-for-byte. 1652 3.2.6.3 iSCSI Name Structure 1654 An iSCSI name consists of two parts--a type designator followed by a 1655 unique name string. 1657 The iSCSI name does not define any new naming authorities. Instead, 1658 it supports two existing ways of designating naming authorities: an 1659 iSCSI-Qualified Name, using domain names to identify a naming 1660 authority, and the EUI format, where the IEEE Registration Authority 1661 assists in the formation of worldwide unique names (EUI-64 format). 1663 Julian Satran Expires August 2003 33 1664 iSCSI 19-January-03 1666 The type designator strings currently defined are: 1668 iqn. - iSCSI Qualified name 1669 eui. - Remainder of the string is an IEEE EUI-64 1670 identifier, in ASCII-encoded hexadecimal. 1672 These two naming authority designators were considered sufficient at 1673 the time of writing this document. The creation of additional 1674 naming type designators for iSCSI may be considered by the IETF and 1675 detailed in separate RFCs. 1677 3.2.6.3.1 Type "iqn." (iSCSI Qualified Name) 1679 This iSCSI name type can be used by any organization that owns a 1680 domain name. This naming format is useful when an end user or 1681 service provider wishes to assign iSCSI names for targets and/or 1682 initiators. 1684 To generate names of this type, the person or organization 1685 generating the name must own a registered domain name. This domain 1686 name does not have to be active, and does not have to resolve to an 1687 address; it just needs to be reserved to prevent others from 1688 generating iSCSI names using the same domain name. 1690 Since a domain name can expire, be acquired by another entity, or 1691 may be used to generate iSCSI names by both owners, the domain name 1692 must be additionally qualified by a date during which the naming 1693 authority owned the domain name. A date code is provided as part of 1694 the "iqn." format for this reason. 1696 The iSCSI qualified name string consists of: 1698 - The string "iqn.", used to distinguish these names from "eui." 1699 formatted names. 1700 - A date code, in yyyy-mm format. This date MUST be a date 1701 during which the naming authority owned the domain name used 1702 in this format, and SHOULD be the first month in which the 1703 domain name was owned by this naming authority at 00:01 GMT of 1704 the first day of the month. This date code uses the Gregorian 1705 calendar. All four digits in the year must be present. Both 1706 digits of the month must be present, with January == "01" and 1707 December == "12". The dash must be included. 1708 - A dot "." 1709 - The reversed domain name of the naming authority (person or 1710 organization) creating this iSCSI name. 1711 - An optional, colon (:) prefixed, string within the character 1712 set and length boundaries that the owner of the domain name 1713 deems appropriate. This may contain product types, serial 1714 numbers, host identifiers, or software keys (e.g, it may 1715 include colons to separate organization boundaries). With the 1716 exception of the colon prefix, the owner of the domain name 1717 can assign everything after the reversed domain name as 1718 desired. It is the responsibility of the entity that is the 1719 naming authority to ensure that the iSCSI names it assigns are 1721 Julian Satran Expires August 2003 34 1722 iSCSI 19-January-03 1724 worldwide unique. For example, "Example Storage Arrays, Inc.", 1725 might own the domain name "example.com". 1727 The following are examples of iSCSI qualified names that might be 1728 generated by "EXAMPLE Storage Arrays, Inc." 1730 Naming String defined by 1731 Type Date Auth "example.com" naming authority 1732 +--++-----+ +---------+ +--------------------------------+ 1733 | || | | | | | 1735 iqn.2001-04.com.example:storage:diskarrays-sn-a8675309 1736 iqn.2001-04.com.example 1737 iqn.2001-04.com.example:storage.tape1.sys1.xyz 1738 iqn.2001-04.com.example:storage.disk2.sys1.xyz 1740 3.2.6.3.2 Type "eui." (IEEE EUI-64 format) 1742 The IEEE Registration Authority provides a service for assigning 1743 globally unique identifiers [EUI]. The EUI-64 format is used to 1744 build a global identifier in other network protocols. For example, 1745 Fibre Channel defines a method of encoding it into a WorldWideName. 1746 For more information on registering for EUI identifiers, see [OUI]. 1748 The format is "eui." followed by an EUI-64 identifier (16 ASCII- 1749 encoded hexadecimal digits). 1751 Example iSCSI name: 1753 Type EUI-64 identifier (ASCII-encoded hexadecimal) 1754 +--++--------------+ 1755 | || | 1756 eui.02004567A425678D 1758 The IEEE EUI-64 iSCSI name format might be used when a manufacturer 1759 is already registered with the IEEE Registration Authority and uses 1760 EUI-64 formatted worldwide unique names for its products. 1762 More examples of name construction are discussed in [NDT]. 1764 3.2.7 Persistent State 1766 iSCSI does not require any persistent state maintenance across 1767 sessions. However, in some cases, SCSI requires persistent 1768 identification of the SCSI initiator port name (See Section 3.4.2 1769 SCSI Architecture Model and Section 3.4.3 Consequences of the 1770 Model). 1772 iSCSI sessions do not persist through power cycles and boot 1773 operations. 1775 All iSCSI session and connection parameters are re-initialized on 1776 session and connection creation. 1778 Julian Satran Expires August 2003 35 1779 iSCSI 19-January-03 1781 Commands persist beyond connection termination if the session 1782 persists and command recovery within the session is supported. 1783 However, when a connection is dropped, command execution, as 1784 perceived by iSCSI (i.e., involving iSCSI protocol exchanges for the 1785 affected task), is suspended until a new allegiance is established 1786 by the 'task reassign' task management function. (See Section 10.5 1787 Task Management Function Request.) 1789 3.2.8 Message Synchronization and Steering 1791 iSCSI presents a mapping of the SCSI protocol onto TCP. This 1792 encapsulation is accomplished by sending iSCSI PDUs of varying 1793 lengths. Unfortunately, TCP does not have a built-in mechanism for 1794 signaling message boundaries at the TCP layer. iSCSI overcomes this 1795 obstacle by placing the message length in the iSCSI message header. 1796 This serves to delineate the end of the current message as well as 1797 the beginning of the next message. 1799 In situations where IP packets are delivered in order from the 1800 network, iSCSI message framing is not an issue and messages are 1801 processed one after the other. In the presence of IP packet 1802 reordering (i.e., frames being dropped), legacy TCP implementations 1803 store the "out of order" TCP segments in temporary buffers until the 1804 missing TCP segments arrive, upon which the data must be copied to 1805 the application buffers. In iSCSI, it is desirable to steer the SCSI 1806 data within these out of order TCP segments into the pre-allocated 1807 SCSI buffers rather than store them in temporary buffers. This 1808 decreases the need for dedicated reassembly buffers as well as the 1809 latency and bandwidth related to extra copies. 1811 Relying solely on the "message length" information from the iSCSI 1812 message header may make it impossible to find iSCSI message 1813 boundaries in subsequent TCP segments due to the loss of a TCP 1814 segment that contains the iSCSI message length. The missing TCP 1815 segment(s) must be received before any of the following segments can 1816 be steered to the correct SCSI buffers (due to the inability to 1817 determine the iSCSI message boundaries). Since these segments cannot 1818 be steered to the correct location, they must be saved in temporary 1819 buffers that must then be copied to the SCSI buffers. 1821 Different schemes can be used to recover synchronization. To make 1822 these schemes work, iSCSI implementations have to make sure that the 1823 appropriate protocol layers are provided with enough information to 1824 implement a synchronization and/or data steering mechanism. One of 1825 these schemes is detailed in Appendix A. - Sync and Steering with 1826 Fixed Interval Markers -. 1828 The Fixed Interval Markers (FIM) scheme works by inserting markers 1829 in the payload stream at fixed intervals that contain the offset to 1830 the start of the next iSCSI PDU. 1832 Under normal circumstances (no PDU loss or data reception out of 1833 order), iSCSI data steering can be accomplished by using the 1834 identifying tag and the data offset fields in the iSCSI header in 1835 addition to the TCP sequence number from the TCP header. The 1836 identifying tag helps associate the PDU with a SCSI buffer address 1838 Julian Satran Expires August 2003 36 1839 iSCSI 19-January-03 1841 while the data offset and TCP sequence number are used to determine 1842 the offset within the buffer. 1844 When the part of the TCP data stream containing an iSCSI PDU header 1845 is delayed or lost, markers may be used to minimize the damage as 1846 follows: 1848 - Markers indicate where the next iSCSI PDU starts and enable 1849 continued processing when iSCSI headers have to be dropped due 1850 to data errors discovered at iSCSI level (e.g., iSCSI header 1851 CRC errors). 1852 - Markers help minimize the amount of data that has to be kept 1853 by the TCP/iSCSI layer while waiting for a late TCP packet 1854 arrival or recovery, because later they might help find iSCSI 1855 PDU headers and use the information contained in those to 1856 steer data to SCSI buffers. 1858 3.2.8.1 Sync/Steering and iSCSI PDU Length 1860 When a large iSCSI message is sent, the TCP segment(s) that contain 1861 the iSCSI header may be lost. The remaining TCP segment(s) up to the 1862 next iSCSI message must be buffered (in temporary buffers) because 1863 the iSCSI header that indicates to which SCSI buffers the data are 1864 to be steered was lost. To minimize the amount of buffering, it is 1865 recommended that the iSCSI PDU length be restricted to a small value 1866 (perhaps a few TCP segments in length). During login, each end of 1867 the iSCSI session specifies the maximum iSCSI PDU length it will 1868 accept. 1870 3.3 iSCSI Session Types 1872 iSCSI defines two types of sessions: 1874 a) Normal operational session - an unrestricted session. 1875 b) Discovery-session - a session only opened for target 1876 discovery. The target MUST ONLY accept text requests with the 1877 SendTargets key and a logout request with reason "close the 1878 session". All other requests MUST be rejected. 1880 The session type is defined during login with key=value parameter in 1881 the login command. 1883 3.4 SCSI to iSCSI Concepts Mapping Model 1885 The following diagram shows an example of how multiple iSCSI Nodes 1886 (targets in this case) can coexist within the same Network Entity 1887 and can share Network Portals (IP addresses and TCP ports). Other 1888 more complex configurations are also possible. For detailed 1889 descriptions of the components of these diagrams, see Section 3.4.1 1890 iSCSI Architecture Model . 1892 Julian Satran Expires August 2003 37 1893 iSCSI 19-January-03 1895 +-----------------------------------+ 1896 | Network Entity (iSCSI Client) | 1897 | | 1898 | +-------------+ | 1899 | | iSCSI Node | | 1900 | | (Initiator) | | 1901 | +-------------+ | 1902 | | | | 1903 | +--------------+ +--------------+ | 1904 | |Network Portal| |Network Portal| | 1905 | | 10.1.30.4 | | 10.1.40.6 | | 1906 +-+--------------+-+--------------+-+ 1907 | | 1908 | IP Networks | 1909 | | 1910 +-+--------------+-+--------------+-+ 1911 | |Network Portal| |Network Portal| | 1912 | | 10.1.30.21 | | 10.1.40.3 | | 1913 | | TCP Port 3260| | TCP Port 3260| | 1914 | +--------------+ +--------------+ | 1915 | | | | 1916 | ----------------- | 1917 | | | | 1918 | +-------------+ +--------------+ | 1919 | | iSCSI Node | | iSCSI Node | | 1920 | | (Target) | | (Target) | | 1921 | +-------------+ +--------------+ | 1922 | | 1923 | Network Entity (iSCSI Server) | 1924 +-----------------------------------+ 1926 3.4.1 iSCSI Architecture Model 1928 This section describes the part of the iSCSI architecture model that 1929 has the most bearing on the relationship between iSCSI and the SCSI 1930 Architecture Model. 1932 a) Network Entity - represents a device or gateway that is 1933 accessible from the IP network. A Network Entity must have one 1934 or more Network Portals (see item d), each of which can be used 1935 by some iSCSI Nodes (see item (b)) contained in that Network 1936 Entity to gain access to the IP network. 1938 b) iSCSI Node - represents a single iSCSI initiator or iSCSI 1939 target. There are one or more iSCSI Nodes within a Network 1940 Entity. The iSCSI Node is accessible via one or more Network 1941 Portals (see item d). An iSCSI Node is identified by its iSCSI 1942 Name (see Section 3.2.6 iSCSI Names and Chapter 12). The 1943 separation of the iSCSI Name from the addresses used by and for 1944 the iSCSI node allows multiple iSCSI nodes to use the same 1945 addresses, and the same iSCSI node to use multiple addresses. 1947 Julian Satran Expires August 2003 38 1948 iSCSI 19-January-03 1950 c) An alias string may also be associated with an iSCSI Node. 1951 The alias allows an organization to associate a user friendly 1952 string with the iSCSI Name. However, the alias string is not a 1953 substitute for the iSCSI Name. 1955 d) Network Portal - a component of a Network Entity that has a 1956 TCP/IP network address and that may be used by an iSCSI Node 1957 within that Network Entity for the connection(s) within one of 1958 its iSCSI sessions. In an initiator, it is identified by its IP 1959 address. In a target, it is identified by its IP address and 1960 its listening TCP port. 1962 e) Portal Groups - iSCSI supports multiple connections within 1963 the same session; some implementations will have the ability to 1964 combine connections in a session across multiple Network 1965 Portals. A Portal Group defines a set of Network Portals within 1966 an iSCSI Node that collectively supports the capability of 1967 coordinating a session with connections that span these 1968 portals. Not all Network Portals within a Portal Group need to 1969 participate in every session connected through that Portal 1970 Group. One or more Portal Groups may provide access to an iSCSI 1971 Node. Each Network Portal, as utilized by a given iSCSI Node, 1972 belongs to exactly one portal group within that node. Portal 1973 Groups are identified within an iSCSI Node by a portal group 1974 tag, a simple unsigned-integer between 0 and 65535 (see Section 1975 12.3 SendTargets). All Network Portals with the same portal 1976 group tag in the context of a given iSCSI Node are in the same 1977 Portal Group. 1979 Both iSCSI Initiators and iSCSI Targets have portal groups, 1980 though only the iSCSI Target Portal Groups are used directly in 1981 the iSCSI protocol (e.g., in SendTargets). For references to 1982 the Initiator Portal Groups, see Section 9.1.1 Conservative 1983 Reuse of ISIDs. 1985 f) Portals within a Portal Group should support similar 1986 session parameters, because they may participate in a common 1987 session 1989 The following diagram shows an example of one such configuration on 1990 a target and how a session that shares Network Portals within a 1991 Portal Group may be established. 1993 Julian Satran Expires August 2003 39 1994 iSCSI 19-January-03 1996 ----------------------------IP Network--------------------- 1997 | | | 1998 +----|---------------|-----+ +----|---------+ 1999 | +---------+ +---------+ | | +---------+ | 2000 | | Network | | Network | | | | Network | | 2001 | | Portal | | Portal | | | | Portal | | 2002 | +--|------+ +---------+ | | +---------+ | 2003 | | | | | | | 2004 | | Portal | | | | Portal | 2005 | | Group 1 | | | | Group 2 | 2006 +--------------------------+ +--------------+ 2007 | | | 2008 +--------|---------------|--------------------|--------------------+ 2009 | | | | | 2010 | +----------------------------+ +-----------------------------+ | 2011 | | iSCSI Session (Target side)| | iSCSI Session (Target side) | | 2012 | | | | | | 2013 | | (TSIH = 56) | | (TSIH = 48) | | 2014 | +----------------------------+ +-----------------------------+ | 2015 | | 2016 | iSCSI Target Node | 2017 | (within Network Entity, not shown) | 2018 +------------------------------------------------------------------+ 2020 3.4.2 SCSI Architecture Model 2022 This section describes the relationship between the SCSI 2023 Architecture Model [SAM2] and constructs of the SCSI device, SCSI 2024 port and I_T nexus, and the iSCSI constructs described in Section 2025 3.4.1 iSCSI Architecture Model. 2027 This relationship implies implementation requirements in order to 2028 conform to the SAM2 model and other SCSI operational functions. 2029 These requirements are detailed in Section 3.4.3 Consequences of the 2030 Model. 2032 The following list outlines mappings of SCSI architectural elements 2033 to iSCSI. 2035 a) SCSI Device - the SAM2 term for an entity that contains one 2036 or more SCSI ports that are connected to a service delivery 2037 subsystem and supports a SCSI application protocol. For 2038 example, a SCSI Initiator Device contains one or more SCSI 2039 Initiator Ports and zero or more application clients. A SCSI 2040 Target Device contains one or more SCSI Target Ports and one or 2041 more logical units. For iSCSI, the SCSI Device is the component 2042 within an iSCSI Node that provides the SCSI functionality. As 2043 such, there can be one SCSI Device, at most, within an iSCSI 2044 Node. Access to the SCSI Device can only be achieved in an 2045 iSCSI normal operational session (see Section 3.3 iSCSI Session 2046 Types). The SCSI Device Name is defined to be the iSCSI Name of 2047 the node and MUST be used in the iSCSI protocol. 2049 Julian Satran Expires August 2003 40 2050 iSCSI 19-January-03 2052 b) SCSI Port - the SAM2 term for an entity in a SCSI Device 2053 that provides the SCSI functionality to interface with a 2054 service delivery subsystem or transport. For iSCSI, the 2055 definition of SCSI Initiator Port and SCSI Target Port are 2056 different. 2058 SCSI Initiator Port: This maps to one endpoint of an iSCSI 2059 normal operational session (see Section 3.3 iSCSI Session 2060 Types). An iSCSI normal operational session is negotiated 2061 through the login process between an iSCSI initiator node and 2062 an iSCSI target node. At successful completion of this process, 2063 a SCSI Initiator Port is created within the SCSI Initiator 2064 Device. The SCSI Initiator Port Name and SCSI Initiator Port 2065 Identifier are both defined to be the iSCSI Initiator Name 2066 together with (a) a label that identifies it as an initiator 2067 port name/identifier and (b) the ISID portion of the session 2068 identifier. 2070 SCSI Target Port: This maps to an iSCSI Target Portal Group. 2071 The SCSI Target Port Name and the SCSI Target Port Identifier 2072 are both defined to be the iSCSI Target Name together with (a) 2073 a label that identifies it as a target port name/identifier and 2074 (b) the portal group tag. 2076 The SCSI Port Name MUST be used in iSCSI. When used in SCSI 2077 parameter data, the SCSI port name MUST be encoded as: 2078 - The iSCSI Name in UTF-8 format, followed by 2079 - a comma separator (1 byte), followed by 2080 - the ASCII character 'i' (for SCSI Initiator Port) or 2081 the ASCII character 't' (for SCSI Target Port) (1 byte), 2082 followed by 2083 - a comma separator (1 byte), followed by 2084 - a text encoding as a hex-constant (see Section 5.1 Text 2085 Format) of the ISID (for SCSI initiator port) or the 2086 portal group tag (for SCSI target port) including the 2087 initial 0X or 0x and the terminating null (14 bytes). 2089 The ASCII character 'i' or 't' is the label that 2090 identifies this port as either a SCSI Initiator Port or a 2091 SCSI Target Port. 2093 c) I_T nexus - a relationship between a SCSI Initiator Port 2094 and a SCSI Target Port, according to [SAM2]. For iSCSI, this 2095 relationship is a session, defined as a relationship between an 2096 iSCSI Initiator's end of the session (SCSI Initiator Port) and 2097 the iSCSI Target's Portal Group. The I_T nexus can be 2098 identified by the conjunction of the SCSI port names or by the 2099 iSCSI session identifier SSID. iSCSI defines the I_T nexus 2101 Julian Satran Expires August 2003 41 2102 iSCSI 19-January-03 2104 identifier to be the tuple (iSCSI Initiator Name + 'i' + ISID, 2105 iSCSI Target Name + 't' + Portal Group Tag). 2107 NOTE: The I_T nexus identifier is not equal to the session 2108 identifier (SSID). 2110 3.4.3 Consequences of the Model 2112 This section describes implementation and behavioral requirements 2113 that result from the mapping of SCSI constructs to the iSCSI 2114 constructs defined above. Between a given SCSI initiator port and a 2115 given SCSI target port, only one I_T nexus (session) can exist. No 2116 more than one nexus relationship (parallel nexus) is allowed by 2117 [SAM2]. Therefore, between a given iSCSI initiator node and an iSCSI 2118 target node, at any given time, only one session can exist with the 2119 same session identifier (SSID). 2121 These assumptions lead to the following conclusions and 2122 requirements: 2124 ISID RULE: Between a given iSCSI Initiator and iSCSI Target Portal 2125 Group (SCSI target port), there can only be one session with a given 2126 value for ISID that identifies the SCSI initiator port. See Section 2127 10.12.5 ISID. 2129 The structure of the ISID that contains a naming authority component 2130 (see Section 10.12.5 ISID and [NDT]) provides a mechanism to 2131 facilitate compliance with the ISID rule. (See Section 9.1.1 2132 Conservative Reuse of ISIDs.) 2134 The iSCSI Initiator Node should manage the assignment of ISIDs prior 2135 to session initiation. The "ISID RULE" does not preclude the use of 2136 the same ISID from the same iSCSI Initiator with different Target 2137 Portal Groups on the same iSCSI target or on other iSCSI targets 2138 (see Section 9.1.1 Conservative Reuse of ISIDs). Allowing this would 2139 be analogous to a single SCSI Initiator Port having relationships 2140 (nexus) with multiple SCSI target ports on the same SCSI target 2141 device or SCSI target ports on other SCSI target devices. It is also 2142 possible to have multiple sessions with different ISIDs to the same 2143 Target Portal Group. Each such session would be considered to be 2144 with a different initiator even when the sessions originate from the 2145 same initiator device. The same ISID may be used by a different 2146 iSCSI initiator because it is the iSCSI Name together with the ISID 2147 that identifies the SCSI Initiator Port. 2149 NOTE: A consequence of the ISID RULE and the specification for the 2150 I_T nexus identifier is that two nexus with the same identifier 2151 should never exist at the same time. 2153 TSIH RULE: The iSCSI Target selects a non-zero value for the TSIH at 2154 session creation (when an initiator presents a 0 value at Login). 2155 After being selected, the same TSIH value MUST be used whenever 2156 initiator or target refers to the session and a TSIH is required. 2158 Julian Satran Expires August 2003 42 2159 iSCSI 19-January-03 2161 3.4.3.1 I_T Nexus State 2163 Certain nexus relationships contain an explicit state (e.g., 2164 initiator-specific mode pages) that may need to be preserved by the 2165 device server [SAM2] in a logical unit through changes or failures 2166 in the iSCSI layer (e.g., session failures). In order for that state 2167 to be restored, the iSCSI initiator should reestablish its session 2168 (re-login) to the same Target Portal Group using the previous ISID. 2169 That is, it should perform session recovery as described in Chapter 2170 6. This is because the SCSI initiator port identifier and the SCSI 2171 target port identifier (or relative target port) form the datum that 2172 the SCSI logical unit device server uses to identify the I_T nexus. 2174 3.5 Request/Response Summary 2176 This section lists and briefly describes all the iSCSI PDU types 2177 (request and responses). 2179 All iSCSI PDUs are built as a set of one or more header segments 2180 (basic and auxiliary) and zero or one data segments. The header 2181 group and the data segment may each be followed by a CRC (digest). 2183 The basic header segment has a fixed length of 48 bytes. 2185 3.5.1 Request/Response Types Carrying SCSI Payload 2187 3.5.1.1 SCSI-Command 2189 This request carries the SCSI CDB and all the other SCSI execute 2190 command procedure call (see [SAM2]) IN arguments such as task 2191 attributes, Expected Data Transfer Length for one or both transfer 2192 directions (the latter for bidirectional commands), and Task Tag (as 2193 part of the I_T_L_x nexus). The I_T_L nexus is derived by the 2194 initiator and target from the LUN field in the request and the I_T 2195 nexus is implicit in the session identification. 2197 In addition, the SCSI-command PDU carries information required for 2198 the proper operation of the iSCSI protocol - the command sequence 2199 number (CmdSN) and the expected status number (ExpStatSN) on the 2200 connection it is issued. 2202 All or part of the SCSI output (write) data associated with the SCSI 2203 command may be sent as part of the SCSI-Command PDU as a data 2204 segment. 2206 3.5.1.2 SCSI-Response 2208 The SCSI-Response carries all the SCSI execute-command procedure 2209 call (see [SAM2]) OUT arguments and the SCSI execute-command 2210 procedure call return value. 2212 The SCSI-Response contains the residual counts from the operation, 2213 if any, an indication of whether the counts represent an overflow or 2214 an underflow, and the SCSI status if the status is valid or a 2215 response code (a non-zero return value for the execute-command 2216 procedure call) if the status is not valid. 2218 Julian Satran Expires August 2003 43 2219 iSCSI 19-January-03 2221 For a valid status that indicates that the command has been 2222 processed, but resulted in an exception (e.g., a SCSI CHECK 2223 CONDITION), the PDU data segment contains the associated sense data. 2224 The use of Autosense ([SAM2]) is REQUIRED by iSCSI. 2226 Some data segment content may also be associated (in the data 2227 segment) with a non-zero response code. 2229 In addition, the SCSI-Response PDU carries information required for 2230 the proper operation of the iSCSI protocol: 2232 - The number of Data-In PDUs that a target has sent (to enable 2233 the initiator to check that all have arrived). 2234 - StatSN - the Status Sequence Number on this connection. 2235 - ExpCmdSN - the next Expected Command Sequence Number at the 2236 target. 2237 - MaxCmdSN - the maximum CmdSN acceptable at the target from 2238 this initiator. 2240 3.5.1.3 Task Management Function Request 2242 The Task Management function request provides an initiator with a 2243 way to explicitly control the execution of one or more SCSI Tasks or 2244 iSCSI functions. The PDU carries a function identifier (which task 2245 management function to perform) and enough information to 2246 unequivocally identify the task or task-set on which to perform the 2247 action, even if the task(s) to act upon has not yet arrived or has 2248 been discarded due to an error. 2250 The referenced tag identifies an individual task if the function 2251 refers to an individual task. 2253 The I_T_L nexus identifies task sets. In iSCSI the I_T_L nexus is 2254 identified by the LUN and the session identification (the session 2255 identifies an I_T nexus). 2257 For task sets, the CmdSN of the Task Management function request 2258 helps identify the tasks upon which to act, namely all tasks 2259 associated with a LUN and having a CmdSN preceding the Task 2260 Management function request CmdSN. 2262 For a Task Management function the coordination between responses to 2263 the tasks affected and the Task Management function response is done 2264 by the target. 2266 3.5.1.4 Task Management Function Response 2268 The Task Management function response carries an indication of 2269 function completion for a Task Management function request including 2270 how it completed (response and qualifier) and additional information 2271 for failure responses. 2273 After the Task Management response indicates Task Management 2274 function completion, the initiator will not receive any additional 2275 responses from the affected tasks. 2277 Julian Satran Expires August 2003 44 2278 iSCSI 19-January-03 2280 3.5.1.5 SCSI Data-out and SCSI Data-in 2282 SCSI Data-out and SCSI Data-in are the main vehicles by which SCSI 2283 data payload is carried between initiator and target. Data payload 2284 is associated with a specific SCSI command through the Initiator 2285 Task Tag. For target convenience, outgoing solicited data also 2286 carries a Target Transfer Tag (copied from R2T) and the LUN. Each 2287 PDU contains the payload length and the data offset relative to the 2288 buffer address contained in the SCSI execute command procedure call. 2290 In each direction, the data transfer is split into "sequences". An 2291 end-of-sequence is indicated by the F bit. 2293 An outgoing sequence is either unsolicited (only the first sequence 2294 can be unsolicited) or consists of all the Data-Out PDUs sent in 2295 response to an R2T. 2297 Input sequences are built to enable the direction switching for 2298 bidirectional commands. 2300 For input, the target may request positive acknowledgement of input 2301 data. This is limited to sessions that support error recovery and is 2302 implemented through the A bit in the SCSI Data-in PDU header. 2304 Data-in and Data-out PDUs also carry the DataSN to enable the 2305 initiator and target to detect missing PDUs (discarded due to an 2306 error). 2308 In addition, StatSN is carried by the Data-In PDUs. 2310 To enable a SCSI command to be processed while involving a minimum 2311 number of messages, the last SCSI Data-in PDU passed for a command 2312 may also contain the status if the status indicates termination with 2313 no exceptions (no sense or response involved). 2315 3.5.1.6 Ready To Transfer (R2T) 2317 R2T is the mechanism by which the SCSI target "requests" the 2318 initiator for output data. R2T specifies to the initiator the offset 2319 of the requested data relative to the buffer address from the 2320 execute command procedure call and the length of the solicited data. 2322 To help the SCSI target associate the resulting Data-out with an 2323 R2T, the R2T carries a Target Transfer Tag that will be copied by 2324 the initiator in the solicited SCSI Data-out PDUs. There are no 2325 protocol specific requirements with regard to the value of these 2326 tags, but it is assumed that together with the LUN, they will enable 2327 the target to associate data with an R2T. 2329 R2T also carries information required for proper operation of the 2330 iSCSI protocol, such as: 2332 - R2TSN (to enable an initiator to detect a missing R2T) 2333 - StatSN 2335 Julian Satran Expires August 2003 45 2336 iSCSI 19-January-03 2338 - ExpCmdSN 2339 - MaxCmdSN 2341 3.5.2 Requests/Responses carrying SCSI and iSCSI Payload 2343 3.5.2.1 Asynchronous Message 2345 Asynchronous Messages are used to carry SCSI asynchronous events 2346 (AEN) and iSCSI asynchronous messages. 2348 When carrying an AEN, the event details are reported as sense data 2349 in the data segment. 2351 3.5.3 Requests/Responses Carrying iSCSI Only Payload 2353 3.5.3.1 Text Request and Text Response 2355 Text requests and responses are designed as a parameter negotiation 2356 vehicle and as a vehicle for future extension. 2358 In the data segment Text Requests/Responses carry text information 2359 using a simple "key=value" syntax. 2361 Text Request/Responses may form extended sequences using the same 2362 Initiator Task Tag. The initiator uses the F (Final) flag bit in the 2363 text request header to indicate its readiness to terminate a 2364 sequence. The target uses the F (Final) flag bit in the text 2365 response header to indicate its consent to sequence termination. 2367 Text Request and Responses also use the Target Transfer Tag to 2368 indicate continuation of an operation or a new beginning. A target 2369 that wishes to continue an operation will set the Target Transfer 2370 Tag in a Text Response to a value different from the default 2371 0xffffffff. An initiator willing to continue will copy this value 2372 into the Target Transfer Tag of the next Text Request. If the 2373 initiator wants to restart the current target negotiation (start 2374 fresh) will set the Target Transfer Tag to 0xffffffff. 2376 Although a complete exchange is always started by the initiator, 2377 specific parameter negotiations may be initiated by the initiator or 2378 target. 2380 3.5.3.2 Login Request and Login Response 2382 Login Requests and Responses are used exclusively during the Login 2383 Phase of each connection to set up the session and connection 2384 parameters. (The Login Phase consists of a sequence of login 2385 requests and responses carrying the same Initiator Task Tag.) 2387 A connection is identified by an arbitrarily selected connection-ID 2388 (CID) that is unique within a session. 2390 Similar to the Text Requests and Responses, Login Requests/Responses 2391 carry key=value text information with a simple syntax in the data 2392 segment. 2394 Julian Satran Expires August 2003 46 2395 iSCSI 19-January-03 2397 The Login Phase proceeds through several stages (security 2398 negotiation, operational parameter negotiation) that are selected 2399 with two binary coded fields in the header -- the "current stage" 2400 (CSG) and the "next stage" (NSG) with the appearance of the latter 2401 being signaled by the "transit" flag (T). 2403 The first Login Phase of a session plays a special role, called the 2404 leading login, which determines some header fields (e.g., the 2405 version number, the maximum number of connections, and the session 2406 identification). 2408 The CmdSN initial value is also set by the leading login. 2410 StatSN for each connection is initiated by the connection login. 2412 A login request may indicate an implied logout (cleanup) of the 2413 connection to be logged in (a connection restart) by using the same 2414 Connection ID (CID) as an existing connection as well as the same 2415 session identifying elements of the session to which the old 2416 connection was associated. 2418 3.5.3.3 Logout Request and Response 2420 Logout Requests and Responses are used for the orderly closing of 2421 connections for recovery or maintenance. The logout request may be 2422 issued following a target prompt (through an asynchronous message) 2423 or at an initiators initiative. When issued on the connection to be 2424 logged out no other request may follow it. 2426 The Logout response indicates that the connection or session cleanup 2427 is completed and no other responses will arrive on the connection 2428 (if received on the logging out connection). In addition, the Logout 2429 Response indicates how long the target will continue to hold 2430 resources for recovery (e.g., command execution that continues on a 2431 new connection) in the text key Time2Retain and how long the 2432 initiator must wait before proceeding with recovery in the text key 2433 Time2Wait. 2435 3.5.3.4 SNACK Request 2437 With the SNACK Request, the initiator requests retransmission of 2438 numbered-responses or data from the target. A single SNACK request 2439 covers a contiguous set of missing items, called a run, of a given 2440 type of items. The type is indicated in a type field in the PDU 2441 header. The run is composed of an initial item (StatSN, DataSN, 2442 R2TSN) and the number of missed Status, Data, or R2T PDUs. For long 2443 data-in sequences, the target may request (at predefined minimum 2444 intervals) a positive acknowledgement for the data sent. A SNACK 2445 request with a type field that indicates ACK and the number of Data- 2446 In PDUs acknowledged conveys this positive acknowledgement. 2448 3.5.3.5 Reject 2450 Reject enables the target to report an iSCSI error condition (e.g., 2451 protocol, unsupported option) that uses a Reason field in the PDU 2453 Julian Satran Expires August 2003 47 2454 iSCSI 19-January-03 2456 header and includes the complete header of the bad PDU in the Reject 2457 PDU data segment. 2459 3.5.3.6 NOP-Out Request and NOP-In Response 2461 This request/response pair may be used by an initiator and target as 2462 a "ping" mechanism to verify that a connection/session is still 2463 active and all of its components are operational. Such a ping may be 2464 triggered by the initiator or target. The triggering party indicates 2465 that it wants a reply by setting a value different from the default 2466 0xffffffff in the corresponding Initiator/Target Transfer Tag. 2468 NOP-In/NOP-Out may also be used "unidirectional" to convey to the 2469 initiator/target command, status or data counter values when there 2470 is no other "carrier" and there is a need to update the initiator/ 2471 target. 2473 Julian Satran Expires August 2003 48 2474 iSCSI 19-January-03 2476 4. SCSI Mode Parameters for iSCSI 2478 There are no iSCSI specific mode pages. 2480 Julian Satran Expires August 2003 49 2481 iSCSI 19-January-03 2483 5. Login and Full Feature Phase Negotiation 2485 iSCSI parameters are negotiated at session or connection 2486 establishment by using Login Requests and Responses (see Section 2487 3.2.3 iSCSI Login) and during Full Feature Phase (Section 3.2.4 2488 iSCSI Full Feature Phase) by using Text Requests and Responses. In 2489 both cases the mechanism used is an exchange of iSCSI-text-key=value 2490 pairs. For brevity iSCSI-text-keys are called just keys in the rest 2491 of this document. 2493 Keys are either declarative or require negotiation and the key 2494 description indicates if the key is declarative or requires 2495 negotiation. 2497 For the declarative keys the declaring party sets a value for the 2498 key. The key specification indicates if the key can be declared by 2499 the initiator, target or both. 2501 For the keys that require negotiation one of the parties (the 2502 proposing party) proposes a value or set of values by including the 2503 key=value in the data part of a Login or Text Request or Response. 2504 The other party (the accepting party) makes a selection based on the 2505 value or list of values proposed and includes the selected value in 2506 a key=value in the data part of the following Login or Text Response 2507 or Request. For most of the keys both the initiator and target can 2508 be proposing parties. 2510 The Login process proceeds in two stages - the security negotiation 2511 stage and the operational parameter negotiation stage. Both stages 2512 are optional but at least one of them has to be present to enable 2513 setting some mandatory parameters. 2515 If present, the security negotiation stage precedes the operational 2516 parameter negotiation stage. 2518 Progression from stage to stage is controlled by the T (Transition) 2519 bit in the Login Request/Response PDU header. Through the T bit set 2520 to 1, the initiator indicates that it would like to transition. The 2521 target agrees to the transition (and selects the next stage) when 2522 ready. A field in the Login PDU header indicates the current stage 2523 (CSG) and during transition, another field indicates the next stage 2524 (NSG) proposed (initiator) and selected (target). 2526 The Text negotiation process is used to negotiate or declare 2527 operational parameters. The negotiation process is controlled by the 2528 F (final) bit in the PDU header. During text negotiations, the F bit 2529 is used by the initiator to indicate that it is ready to finish the 2530 negotiation and by the Target to acquiesce the end of negotiation. 2532 Since some key=value pairs may not fit entirely in a single PDU, the 2533 C (continuation) bit is used (both in Login and Text) to indicate 2534 that "more follows". 2536 The text negotiation uses an additional mechanism by which a target 2537 may deliver larger amounts of data to an enquiring initiator. The 2538 target sets a Target Task Tag to be used as a bookmark which when 2540 Julian Satran Expires August 2003 50 2541 iSCSI 19-January-03 2543 returned by the initiator, means "go on". If reset to a "neutral 2544 value", it means "forget about the rest". 2546 This chapter details types of keys and values used, the syntax rules 2547 for parameter formation, and the negotiation schemes to be used with 2548 different types of parameters. 2550 5.1 Text Format 2552 The initiator and target send a set of key=value pairs encoded in 2553 UTF-8 Unicode. All the text keys and text values specified in this 2554 document are to be presented and interpreted in the case in which 2555 they appear in this document. They are case sensitive. 2557 The following character symbols are used in this document for text 2558 items (the hexadecimal values represent Unicode code points): 2560 (a-z, A-Z) - letters 2561 (0-9) - digits 2562 " " (0x20) - space 2563 "." (0x2e) - dot 2564 "-" (0x2d) - minus 2565 "+" (0x2b) - plus 2566 "@" (0x40) - commercial at 2567 "_" (0x5f) - underscore 2568 "=" (0x3d) - equal 2569 ":" (0x3a) - colon 2570 "/" (0x2f) - solidus or slash 2571 "[" (0x5b) - left bracket 2572 "]" (0x5d) - right bracket 2573 null (0x00) - null separator 2574 "," (0x2c) - comma 2575 "~" (0x7e) - tilde 2577 Key=value pairs may span PDU boundaries. An initiator or target that 2578 sends partial key=value text within a PDU indicates that more text 2579 follows by setting the C bit in the Text or Login Request or Text or 2580 Login Response to 1. Data segments in a series of PDUs that have the 2581 C bit set to 1 and end with a PDU that have the C bit set to 0, or 2582 include a single PDU that has the C bit set to 0 have to be 2583 considered as forming a single logical-text-data-segment (LTDS). 2585 Every key=value pair, including the last or only pair in a LTDS, 2586 MUST be followed by one null (0x00) delimiter. 2588 A key-name is whatever precedes the first = in the key=value pair. 2589 The term key is used frequently in this document in place of key- 2590 name. 2592 A value is whatever follows the first = in the key=value pair up to 2593 the end of the key=value pair, but not including the null delimiter. 2595 The following definitions will be used in the rest of this document: 2597 standard-label: A string of one or more characters that consist 2598 of letters, digits, dot, minus, plus, commercial at, or 2600 Julian Satran Expires August 2003 51 2601 iSCSI 19-January-03 2603 underscore. A standard-label MUST begin with a capital letter 2604 and must not exceed 63 characters. 2606 key-name: A standard-label. 2608 text-value: A string of zero or more characters that consist of 2609 letters, digits, dot, minus, plus, commercial at, underscore, 2610 slash, left bracket, right bracket, or colon. 2612 iSCSI-name-value: A string of one or more characters that 2613 consist of minus, dot, colon, or any character allowed by the 2614 output of the iSCSI string-prep template as specified in 2615 [STPREP-iSCSI] (see also Section 3.2.6.2 iSCSI Name Encoding). 2617 iSCSI-local-name-value: A UTF-8 string; no null characters are 2618 allowed in the string. This encoding is to be used for 2619 localized (internationalized) aliases. 2621 boolean-value: The string "Yes" or "No". 2623 hex-constant: A hexadecimal constant encoded as a string that 2624 starts with "0x" or "0X" followed by one or more digits or the 2625 letters a, b, c, d, e, f, A, B, C, D, E, or F. Hex-constants 2626 are used to encode numerical values or binary strings. When 2627 used to encode numerical values, the excessive use of leading 2628 0 digits is discouraged. The string following 0X (or 0x) 2629 represents a base16 number that starts with the most 2630 significant base16 digit, followed by all other digits in 2631 decreasing order of significance and ending with the least- 2632 significant base16 digit. When used to encode binary strings, 2633 hexadecimal constants have an implicit byte-length that 2634 includes four bits for every hexadecimal digit of the 2635 constant, including leading zeroes. For example, a hex- 2636 constant of n hexadecimal digits has a byte-length of (the 2637 integer part of) (n+1)/2. 2639 decimal-constant: An unsigned decimal number with the digit 0 or 2640 a string of one or more digits that start with a non-zero 2641 digit. Decimal-constants are used to encode numerical values 2642 or binary strings. Decimal constants can only be used to 2643 encode binary strings if the stringlength is explicitly 2644 specified. There is no implicit length for decimal strings. 2645 Decimal-constant MUST NOT be used for parameter values if the 2646 values can be equal or greater than 2**64 (numerical) or for 2647 binary strings that can be longer than 64 bits. 2649 base64-constant: base64 constant encoded as a string that starts 2650 with "0b" or "0B" followed by 1 or more digits or letters or 2651 plus or slash or equal. The encoding is done according to 2652 [RFC2045] and each character, except equal, represents a 2653 base64 digit or a 6-bit binary string. Base64-constants are 2654 used to encode numerical-values or binary strings. When used 2655 to encode numerical values, the excessive use of leading 0 2656 digits (encoded as A) is discouraged. The string following 0B 2657 (or 0b) represents a base64 number that starts with the most 2658 significant base64 digit, followed by all other digits in 2660 Julian Satran Expires August 2003 52 2661 iSCSI 19-January-03 2663 decreasing order of significance and ending with the least- 2664 significant base64 digit; the least significant base64 digit 2665 may be optionally followed by pad digits (encoded as equal) 2666 that are not considered as part of the number. When used to 2667 encode binary strings, base64-constants have an implicit byte- 2668 length that includes six bits for every character of the 2669 constant, excluding trailing equals (i.e., a base64-constant 2670 of n base64 characters excluding the trailing equals has a 2671 byte-length of ((the integer part of) (n*3/4)). Correctly 2672 encoded base64 strings cannot have n values of 1, 5 ... k*4+1. 2674 numerical-value: An unsigned integer always less than 2**64 2675 encoded as a decimal-constant or a hex-constant. Unsigned 2676 integer arithmetic applies to numerical-values. 2678 large-numerical-value: An unsigned integer that can be larger 2679 than or equal to 2**64 encoded as a hex constant, or base64- 2680 constant. Unsigned integer arithmetic applies to large- 2681 numeric-values. 2683 numeric-range: Two numerical-values separated by a tilde where 2684 the value to the right of tilde must not be lower than the 2685 value to the left. 2687 regular-binary-value: A binary string not longer than 64 bits 2688 encoded as a decimal constant, hex constant, or base64- 2689 constant. The length of the string is either specified by the 2690 key definition or is the implicit byte-length of the encoded 2691 string. 2693 large-binary-value: A binary string longer than 64 bits encoded 2694 as a hex-constant or base64-constant. The length of the string 2695 is either specified by the key definition or is the implicit 2696 byte-length of the encoded string. 2698 binary-value: A regular-binary-value or a large-binary-value. 2699 Operations on binary values are key specific. 2701 simple-value: Text-value, iSCSI-name-value, boolean-value, 2702 numeric-value, a numeric-range, or a binary-value. 2704 list-of-values: A sequence of text-values separated by a comma. 2706 If not otherwise specified, the maximum length of a simple-value 2707 (not its encoded representation) is 255 bytes not including the 2708 delimiter (comma or zero byte). 2710 Any iSCSI target or initiator MUST support receiving at least 8192 2711 bytes of key=value data in a negotiation sequence. When proposing or 2712 accepting authentication methods that explicitly require support for 2713 very long authentication items, the initiator and target MUST 2714 support receiving of at least 64 kilobytes of key=value data (see 2715 Appendix 11.1.2 - Simple Public-Key Mechanism (SPKM) - that require 2716 support for public key certificates). 2718 Julian Satran Expires August 2003 53 2719 iSCSI 19-January-03 2721 5.2 Text Mode Negotiation 2723 During login, and thereafter, some session or connection parameters 2724 are either declared or negotiated through an exchange of textual 2725 information. 2727 The initiator starts the negotiation and/or declaration through a 2728 Text or Login request and indicates when it is ready for completion 2729 (by setting the F bit to 1 and keeping it to 1 in a Text Request or 2730 the T bit in the Login Request). As negotiation text may span PDU 2731 boundaries, a Text or Login Request or Text or Login Response PDU 2732 that have the C bit set to 1 MUST NOT have the F/T bit set to 1. 2734 A target receiving a Text or Login Request with the C bit set to 1 2735 MUST answer with a Text or Login Response with no data segment 2736 (DataSegmentLength 0). An initiator receiving a Text or Login 2737 Response with the C bit set to 1 MUST answer with a Text or Login 2738 Request with no data segment (DataSegmentLength 0). 2740 A target or initiator SHOULD NOT use a Text or Login Response or 2741 Text or Login Request with no data segment (DataSegmentLength 0) 2742 unless explicitly required by a general or a key-specific 2743 negotiation rule. 2745 The format of a declaration is: 2747 Declarer-> = 2749 The general format of text negotiation is: 2751 Proposer-> = 2752 Acceptor-> ={|NotUnderstood|Irrelevant|Reject} 2754 Thus a declaration is a one-way textual exchange while a negotiation 2755 is a two-way exchange. 2757 The proposer or declarer can either be the initiator or the target, 2758 and the acceptor can either be the target or initiator, 2759 respectively. Targets are not limited to respond to key=value pairs 2760 as proposed by the initiator. The target may propose key=value pairs 2761 of its own. 2763 All negotiations are explicit (i.e., the result MUST only be based 2764 on newly exchanged or declared values). There are no implicit 2765 proposals. If a proposal is not made, then a reply cannot be 2766 expected. Conservative design also requires that default values 2767 should not be relied upon when use of some other value has serious 2768 consequences. 2770 The value proposed or declared can be a numerical-value, a 2771 numerical-range defined by lower and upper value with both integers 2772 separated by tilde, a binary value, a text-value, an iSCSI-name- 2773 value, an iSCSI-local-name-value, a boolean-value (Yes or No), or a 2774 list of comma separated text-values. A range, a large-numerical- 2775 value, an iSCSI-name-value and an iSCSI-local-name-value MAY ONLY be 2777 Julian Satran Expires August 2003 54 2778 iSCSI 19-January-03 2780 used if it is explicitly allowed. An accepted value can be a 2781 numerical-value, a large-numerical-value, a text-value, or a 2782 boolean-value. 2784 If a specific key is not relevant for the current negotiation, the 2785 acceptor may answer with the constant "Irrelevant" for all types of 2786 negotiation. However the negotiation is not considered as failed if 2787 the answer is "Irrelevant". The "Irrelevant" answer is meant for 2788 those cases in which several keys are presented by a proposing party 2789 but the selection made by the acceptor for one of the keys makes 2790 other keys irrelevant. The following example illustrates the use of 2791 "Irrelevant": 2793 I->T OFMarker=Yes,OFMarkInt=2048~8192 2794 T->I OFMarker=No,OFMarkInt=Irrelevant 2796 I->T X#vkey1=(bla,alb,None),X#vkey2=(bla,alb) 2797 T->I X#vkey1=None,X#vkey2=Irrelevant 2799 Any key not understood by the acceptor may be ignored by the 2800 acceptor without affecting the basic function. However, the answer 2801 for a key not understood MUST be key=NotUnderstood. 2803 The constants "None", "Reject", "Irrelevant", and "NotUnderstood" 2804 are reserved and MUST ONLY be used as described here. Violation of 2805 this rule is a protocol error (in particular the use of "Reject", 2806 "Irrelevant", and "NotUnderstood" as proposed values). 2808 Reject or Irrelevant are legitimate negotiation options where 2809 allowed but their excessive use is discouraged. A negotiation is 2810 considered complete when the acceptor has sent the key value pair 2811 even if the value is "Reject", "Irrelevant", or "NotUnderstood. 2812 Sending the key again would be a re-negotiation and is forbidden for 2813 many keys. 2815 If the acceptor sends "Reject" as an answer the negotiated key is 2816 left at its current value (or default if no value was set). If the 2817 current value is not acceptable to the proposer on the connection or 2818 to the session it is sent, the proposer MAY choose to terminate the 2819 connection or session. 2821 All keys in this document, except for the X extension formats, MUST 2822 be supported by iSCSI initiators and targets when used as specified 2823 here. If used as specified, these keys MUST NOT be answered with 2824 NotUnderstood. 2826 Implementers may introduce new keys by prefixing them with X- 2827 followed by their (reversed) domain name, or with new keys 2828 registered with IANA prefixing them with X#. For example, the entity 2829 owning the domain example.com can issue: 2831 X-com.example.bar.foo.do_something=3 2833 or a new registered key may be used as in: 2835 Julian Satran Expires August 2003 55 2836 iSCSI 19-January-03 2838 X#SuperCalyPhraGilistic=Yes 2840 Implementers MAY also introduce new values, but ONLY for new keys or 2841 authentication methods (see Section 11 iSCSI Security Text Keys and 2842 Authentication Methods), or digests (see Section 12.1 HeaderDigest 2843 and DataDigest). 2845 Whenever parameter action or acceptance are dependent on other 2846 parameters, the dependency rules and parameter sequence must be 2847 specified with the parameters. 2849 In the Login Phase (see Section 5.3 Login Phase), every stage is a 2850 separate negotiation. In the FullFeaturePhase, a Text Request 2851 Response sequence is a negotiation. Negotiations MUST be handled as 2852 atomic operations. For example, all negotiated values go into effect 2853 after the negotiation concludes in agreement or are ignored if the 2854 negotiation fails. 2856 Some parameters may be subject to integrity rules (e.g., parameter-x 2857 must not exceed parameter-y or parameter-u not 1 implies parameter-v 2858 be Yes). Whenever required, integrity rules are specified with the 2859 keys. Checking for compliance with the integrity rule must only be 2860 performed after all the parameters are available (the existent and 2861 the newly negotiated). An iSCSI target MUST perform integrity 2862 checking before the new parameters take effect. An initiator MAY 2863 perform integrity checking. 2865 An iSCSI initiator or target MAY terminate a negotiation that does 2866 not end within a reasonable time or number of exchanges. 2868 5.2.1 List negotiations 2870 In list negotiation, the originator sends a list of values (which 2871 may include "None") in its order of preference. 2873 The responding party MUST respond with the same key and the first 2874 value that it supports (and is allowed to use for the specific 2875 originator) selected from the originator list. 2877 The constant "None" MUST always be used to indicate a missing 2878 function. However, "None" is only a valid selection if it is 2879 explicitly proposed. 2881 If an acceptor does not understand any particular value in a list, 2882 it MUST ignore it. If an acceptor does not support, does not 2883 understand, or is not allowed to use any of the proposed options 2884 with a specific originator, it may use the constant "Reject" or 2885 terminate the negotiation. The selection of a value not proposed 2886 MUST be handled as a protocol error. 2888 5.2.2 Simple-value Negotiations 2890 For simple-value negotiations, the accepting party MUST answer with 2891 the same key. The value it selects becomes the negotiation result. 2893 Julian Satran Expires August 2003 56 2894 iSCSI 19-January-03 2896 Proposing a value not admissible (e.g., not within the specified 2897 bounds) MAY be answered with the constant "Reject" or the acceptor 2898 MAY select an admissible value. 2900 The selection, by the acceptor, of a value not admissible under the 2901 selection rules is considered a protocol error. The selection rules 2902 are key-specific. 2904 For a numerical range the value selected must be an integer within 2905 the proposed range or "Reject" (if the range is unacceptable). 2907 For Boolean negotiations (i.e., keys taking the values Yes or No), 2908 the accepting party MUST answer with the same key and the result of 2909 the negotiation when the received value does not determine that 2910 result by itself. The last value transmitted becomes the negotiation 2911 result. The rules for selecting the value to answer with are 2912 expressed as Boolean functions of the value received, and the value 2913 that the accepting party would have selected if given a choice. 2915 Specifically, the two cases in which answers are OPTIONAL are: 2917 - The Boolean function is "AND" and the value "No" is received. 2918 The outcome of the negotiation is "No". 2919 - The Boolean function is "OR" and the value "Yes" is received. 2920 The outcome of the negotiation is "Yes". 2922 Responses are REQUIRED in all other cases, and the value chosen and 2923 sent by the acceptor becomes the outcome of the negotiation. 2925 5.3 Login Phase 2927 The Login Phase establishes an iSCSI connection between an initiator 2928 and a target; it creates also a new session or associates the 2929 connection to an existing session. The Login Phase sets the iSCSI 2930 protocol parameters, security parameters, and authenticates the 2931 initiator and target to each other. 2933 The Login Phase is only implemented via Login request and responses. 2934 The whole Login Phase is considered as a single task and has a 2935 single Initiator Task Tag (similar to the linked SCSI commands). 2937 The default MaxRecvDataSegmentLength is used during Login. 2939 The Login Phase sequence of requests and responses proceeds as 2940 follows: 2942 - Login initial request 2943 - Login partial response (optional) 2944 - More Login requests and responses (optional) 2945 - Login Final-Response (mandatory) 2947 The initial login request of any connection MUST include the 2948 InitiatorName key=value pair. The initial login request of the first 2949 connection of a session MAY also include the SessionType key=value 2950 pair. For any connection within a session whose type is not 2952 Julian Satran Expires August 2003 57 2953 iSCSI 19-January-03 2955 "Discovery", the first login request MUST also include the 2956 TargetName key=value pair. 2958 The Login Final-response accepts or rejects the Login request. 2960 The Login Phase MAY include a SecurityNegotiation stage and a 2961 LoginOperationalNegotiation stage and MUST include at least one of 2962 them, but the included stage MAY be empty except for the mandatory 2963 names. 2965 The login requests and responses contain a field (CSG) that 2966 indicates the current negotiation stage (SecurityNegotiation or 2967 LoginOperationalNegotiation). If both stages are used, the 2968 SecurityNegotiation MUST precede the LoginOperationalNegotiation. 2970 Some operational parameters can be negotiated outside the login 2971 through Text requests and responses. 2973 Security MUST be completely negotiated within the Login Phase. The 2974 use of underlying IPsec security is specified in Chapter 8 and in 2975 [SEC-IPS]. iSCSI support for security within the protocol only 2976 consists of authentication in the Login Phase. 2978 In some environments, a target or an initiator is not interested in 2979 authenticating its counterpart. It is possible to bypass 2980 authentication through the Login request and response. 2982 The initiator and target MAY want to negotiate iSCSI authentication 2983 parameters. Once this negotiation is completed, the channel is 2984 considered secure. 2986 Most of the negotiation keys are only allowed in a specific stage. 2987 The SecurityNegotiation keys appear in Chapter 11 and the 2988 LoginOperationalNegotiation keys appear in Chapter 12. Only a 2989 limited set of keys (marked as Any-Stage in Chapter 12) may be used 2990 in any of the two stages. 2992 Any given Login request or response belongs to a specific stage; 2993 this determines the negotiation keys allowed with the request or 2994 response. It is considered to be a protocol error to send a key not 2995 allowed in the current stage. 2997 Stage transition is performed through a command exchange (request/ 2998 response) that carries the T bit and the same CSG code. During this 2999 exchange, the next stage is selected by the target through the "next 3000 stage" code (NSG). The selected NSG MUST NOT exceed the value stated 3001 by the initiator. The initiator can request a transition whenever it 3002 is ready, but a target can only respond with a transition after one 3003 is proposed by the initiator. 3005 In a negotiation sequence, the T bit settings in one pair of login 3006 request-responses have no bearing on the T bit settings of the next 3007 pair. An initiator that has a T bit set to 1 in one pair and is 3008 answered with a T bit setting of 0 may issue the next request with T 3009 bit set to 0. 3011 Julian Satran Expires August 2003 58 3012 iSCSI 19-January-03 3014 When a transition is requested by the initiator and acknowledged by 3015 the target, both the initiator and target switch to the selected 3016 stage. 3018 Targets MUST NOT submit parameters that require an additional 3019 initiator login request in a login response with the T bit set to 1. 3021 Stage transitions during login (including entering and exit) are 3022 only possible as outlined in the following table: 3024 +-----------------------------------------------------------+ 3025 |From To -> | Security | Operational | FullFeature | 3026 | | | | | | 3027 | V | | | | 3028 +-----------------------------------------------------------+ 3029 | (start) | yes | yes | no | 3030 +-----------------------------------------------------------+ 3031 | Security | no | yes | yes | 3032 +-----------------------------------------------------------+ 3033 | Operational | no | no | yes | 3034 +-----------------------------------------------------------+ 3036 The Login Final-Response that accepts a Login Request can only come 3037 as a response to a Login request with the T bit set to 1, and both 3038 the request and response MUST indicate FullFeaturePhase as the next 3039 phase via the NSG field. 3041 Neither the initiator nor the target should attempt to declare or 3042 negotiate a parameter more than once during login except for 3043 responses to specific keys that explicitly allow repeated key 3044 declarations (e.g., TargetAddress). An attempt to renegotiate/ 3045 redeclare parameters not specifically allowed MUST be detected by 3046 the initiator and target. If such an attempt is detected by the 3047 target, the target MUST respond with Login reject (initiator error); 3048 if detected by the initiator, the initiator MUST drop the 3049 connection. 3051 5.3.1 Login Phase Start 3053 The Login Phase starts with a login request from the initiator to 3054 the target. The initial login request includes: 3056 -Protocol version supported by the initiator. 3057 -iSCSI Initiator Name and iSCSI Target Name 3058 -ISID, TSIH, and connection Ids 3059 -Negotiation stage that the initiator is ready to enter. 3061 A login may create a new session or it may add a connection to an 3062 existing session. Between a given iSCSI Initiator Node (selected 3063 only by an InitiatorName) and a given iSCSI target defined by an 3064 iSCSI TargetName and a Target Portal Group Tag, the login results 3065 are defined by the following table: 3067 Julian Satran Expires August 2003 59 3068 iSCSI 19-January-03 3070 +------------------------------------------------------------------+ 3071 |ISID | TSIH | CID | Target action | 3072 +------------------------------------------------------------------+ 3073 |new | non-zero | any | fail the login | 3074 | | | | ("session does not exist") | 3075 +------------------------------------------------------------------+ 3076 |new | zero | any | instantiate a new session | 3077 +------------------------------------------------------------------+ 3078 |existing | zero | any | do session reinstatement | 3079 | | | | (see section 5.3.5) | 3080 +------------------------------------------------------------------+ 3081 |existing | non-zero | new | add a new connection to | 3082 | | existing | | the session | 3083 +------------------------------------------------------------------+ 3084 |existing | non-zero |existing| do connection reinstatement| 3085 | | existing | | (see section 5.3.4) | 3086 +------------------------------------------------------------------+ 3087 |existing | non-zero | any | fail the login | 3088 | | new | | ("session does not exist") | 3089 +------------------------------------------------------------------+ 3091 Determination of "existing" or "new" are made by the target. 3093 Optionally, the login request may include: 3095 -Security parameters 3096 OR 3097 -iSCSI operational parameters 3098 AND/OR 3099 -The next negotiation stage that the initiator is ready to 3100 enter. 3102 The target can answer the login in the following ways: 3104 -Login Response with Login reject. This is an immediate 3105 rejection from the target that causes the connection to 3106 terminate and the session to terminate if this is the first 3107 (or only) connection of a new session. The T bit and the CSG 3108 and NSG fields are reserved. 3109 -Login Response with Login accept as a final response (T bit set 3110 to 1 and the NSG in both request and response are set to 3111 FullFeaturePhase). The response includes the protocol version 3112 supported by the target and the session ID, and may include 3113 iSCSI operational or security parameters (that depend on the 3114 current stage). 3115 -Login Response with Login Accept as a partial response (NSG not 3116 set to FullFeaturePhase in both request and response) that 3117 indicates the start of a negotiation sequence. The response 3118 includes the protocol version supported by the target and 3119 either security or iSCSI parameters (when no security 3120 mechanism is chosen) supported by the target. 3122 If the initiator decides to forego the SecurityNegotiation stage, it 3123 issues the Login with the CSG set to LoginOperationalNegotiation and 3125 Julian Satran Expires August 2003 60 3126 iSCSI 19-January-03 3128 the target may reply with a Login Response that indicates that it is 3129 unwilling to accept the connection (see Section 10.13 Login 3130 Response) without SecurityNegotiation and will terminate the 3131 connection with a response of Authentication failure (see Section 3132 10.13.5 Status-Class and Status-Detail). 3134 If the initiator is willing to negotiate iSCSI security, but is 3135 unwilling to make the initial parameter proposal and may accept a 3136 connection without iSCSI security, it issues the Login with the T 3137 bit set to 1, the CSG set to SecurityNegotiation, and NSG set to 3138 LoginOperationalNegotiation. If the target is also ready to skip 3139 security, the login response only contains the TargetPortalGroupTag 3140 key (see Section 12.9 TargetPortalGroupTag), the T bit set to 1, the 3141 CSG set to SecurityNegotiation, and NSG set to 3142 LoginOperationalNegotiation. 3144 An initiator that chooses to operate without iSCSI security and with 3145 all the operational parameters taking the default values issues the 3146 Login with the T bit set to 1, the CSG set to 3147 LoginOperationalNegotiation, and NSG set to FullFeaturePhase. If the 3148 target is also ready to forego security and can finish its 3149 LoginOperationalNegotiation, the Login response has T bit set to 1, 3150 the CSG set to LoginOperationalNegotiation, and NSG set to 3151 FullFeaturePhase in the next stage. 3153 During the Login Phase the iSCSI target MUST return the 3154 TargetPortalGroupTag key with the first Login Response PDU with 3155 which it is allowed to do so (i.e., the first Login Response issued 3156 after the first Login Request with the C bit set to 0) for all 3157 session types. The TargetPortalGroupTag key value indicates the 3158 iSCSI portal group servicing the Login Request PDU. If the 3159 reconfiguration of iSCSI portal groups is a concern in a given 3160 environment, the iSCSI initiator should use this key to ascertain 3161 that it had indeed initiated the Login Phase with the intended 3162 target portal group. 3164 5.3.2 iSCSI Security Negotiation 3166 The security exchange sets the security mechanism and authenticates 3167 the initiator user and the target to each other. The exchange 3168 proceeds according to the authentication method chosen in the 3169 negotiation phase and is conducted using the login requests' and 3170 responses' key=value parameters. 3172 An initiator directed negotiation proceeds as follows: 3174 -The initiator sends a login request with an ordered list of the 3175 options it supports (authentication algorithm). The options 3176 are listed in the initiator's order of preference. The 3177 initiator MAY also send private or public extension options. 3179 -The target MUST reply with the first option in the list it 3180 supports and is allowed to use for the specific initiator 3181 unless it does not support any in which case it MUST answer 3182 with "Reject" (see Section 5.2 Text Mode Negotiation). The 3184 Julian Satran Expires August 2003 61 3185 iSCSI 19-January-03 3187 parameters are encoded in UTF8 as key=value. For security 3188 parameters, see Chapter 11. 3190 -When the initiator considers that it is ready to conclude the 3191 SecurityNegotiation stage, it sets the T bit to 1 and the NSG 3192 to what it would like the next stage to be. The target will 3193 then set the T bit to 1 and set NSG to the next stage in the 3194 Login response when it finishes sending its security keys. The 3195 next stage selected will be the one the target selected. If 3196 the next stage is FullFeaturePhase, the target MUST respond 3197 with a Login Response with the TSIH value. 3199 If the security negotiation fails at the target, then the target 3200 MUST send the appropriate Login Response PDU. If the security 3201 negotiation fails at the initiator, the initiator SHOULD close the 3202 connection. 3204 It should be noted that the negotiation might also be directed by 3205 the target if the initiator does support security, but is not ready 3206 to direct the negotiation (propose options). 3208 5.3.3 Operational Parameter Negotiation During the Login Phase 3210 Operational parameter negotiation during the login MAY be done: 3212 - Starting with the first Login request if the initiator does 3213 not propose any security/ integrity option. 3214 - Starting immediately after the security negotiation if the 3215 initiator and target perform such a negotiation. 3217 Operational parameter negotiation MAY involve several Login request- 3218 response exchanges started and terminated by the initiator. The 3219 initiator MUST indicate its intent to terminate the negotiation by 3220 setting the T bit to 1; the target sets the T bit to 1 on the last 3221 response. 3223 If the target responds to a Login request that has the T bit set to 3224 1 with a Login response that has the T bit set to 0, the initiator 3225 should keep sending the Login request (even empty) with the T bit 3226 set to 1, while it still wants to switch stage, until it receives 3227 the Login Response that has the T bit set to 1 or it receives a key 3228 that requires it to set the T bit to 0. 3230 Some session specific parameters can only be specified during the 3231 Login Phase of the first connection of a session (i.e., begun by a 3232 login request that contains a zero-valued TSIH) - the leading Login 3233 Phase (e.g., the maximum number of connections that can be used for 3234 this session). 3236 A session is operational once it has at least one connection in 3237 FullFeaturePhase. New or replacement connections can only be added 3238 to a session after the session is operational. 3240 For operational parameters, see Chapter 12. 3242 Julian Satran Expires August 2003 62 3243 iSCSI 19-January-03 3245 5.3.4 Connection Reinstatement 3247 Connection reinstatement is the process of an initiator logging in 3248 with a ISID-TSIH-CID combination that is possibly active from the 3249 target's perspective, which causes the implicit logging out of the 3250 connection corresponding to the CID and reinstating a new Full 3251 Feature Phase iSCSI connection in its place (with the same CID). 3252 Thus, the TSIH in the Login PDU MUST be non-zero and CID does not 3253 change during a connection reinstatement. The Login request performs 3254 the logout function of the old connection if an explicit logout was 3255 not performed earlier. In sessions with a single connection, this 3256 may imply the opening of a second connection with the sole purpose 3257 of cleaning up the first. Targets MUST support opening a second 3258 connection even when they do not support multiple connections in 3259 Full Feature Phase if ErrorRecoveryLevel is 2 and SHOULD support 3260 opening a second connection if ErrorRecoveryLevel is less than 2. 3262 If the operational ErrorRecoveryLevel is 2, connection reinstatement 3263 enables future task reassignment. If the operational 3264 ErrorRecoveryLevel is less than 2, connection reinstatement is the 3265 replacement of the old CID without enabling task reassignment. In 3266 this case, all the tasks that were active on the old CID must be 3267 immediately terminated without further notice to the initiator. 3269 The initiator connection state MUST be CLEANUP_WAIT (section 7.1.3) 3270 when the initiator attempts a connection reinstatement. 3272 In practical terms, in addition to the implicit logout of the old 3273 connection, reinstatement is equivalent to a new connection login. 3275 5.3.5 Session Reinstatement, Closure, and Timeout 3277 Session reinstatement is the process of the initiator logging in 3278 with an ISID that is possibly active from the target's perspective. 3279 Thus implicitly logging out the session that corresponds to the ISID 3280 and reinstating a new iSCSI session in its place (with the same 3281 ISID). Therefore, the TSIH in the Login PDU MUST be zero to signal 3282 session reinstatement. Session reinstatement causes all the tasks 3283 that were active on the old session to be immediately terminated by 3284 the target without further notice to the initiator. 3286 The initiator session state MUST be FAILED (Section 7.3 Session 3287 State Diagrams) when the initiator attempts a session reinstatement. 3289 Session closure is an event defined to be one of the following: 3291 - A successful "session close" logout. 3292 - A successful "connection close" logout for the last Full 3293 Feature Phase connection when no other connection in the 3294 session is waiting for cleanup (Section 7.2 Connection Cleanup 3295 State Diagram for Initiators and Targets) and no tasks in the 3296 session are waiting for reassignment. 3298 Session timeout is an event defined to occur when the last 3299 connection state timeout expires and no tasks are waiting for 3301 Julian Satran Expires August 2003 63 3302 iSCSI 19-January-03 3304 reassignment. This takes the session to the FREE state (N6 3305 transition in the session state diagram). 3307 5.3.5.1 Loss of Nexus Notification 3309 The iSCSI layer provides the SCSI layer with the "I_T nexus loss" 3310 notification when any one of the following events happens: 3312 a) Successful completion of session reinstatement. 3313 b) Session closure event. 3314 c) Session timeout event. 3316 Certain SCSI object clearing actions may result due to the 3317 notification in the SCSI end nodes, as documented in Appendix F. - 3318 Clearing Effects of Various Events on Targets -. 3320 5.3.6 Session Continuation and Failure 3322 Session continuation is the process by which the state of a 3323 preexisting session continues to be used by connection reinstatement 3324 (Section 5.3.4 Connection Reinstatement), or by adding a connection 3325 with a new CID. Either of these actions associates the new transport 3326 connection with the session state. 3328 Session failure is an event where the last Full Feature Phase 3329 connection reaches the CLEANUP_WAIT state (Section 7.2 Connection 3330 Cleanup State Diagram for Initiators and Targets), or completes a 3331 successful recovery logout thus causing all active tasks (that are 3332 formerly allegiant to the connection) to start waiting for task 3333 reassignment. 3335 5.4 Operational Parameter Negotiation Outside the Login Phase 3337 Some operational parameters MAY be negotiated outside (after) the 3338 Login Phase. 3340 Parameter negotiation in Full Feature Phase is done through Text 3341 requests and responses. Operational parameter negotiation MAY 3342 involve several Text request-response exchanges, which the initiator 3343 always starts, terminates, and uses the same Initiator Task Tag. The 3344 initiator MUST indicate its intent to terminate the negotiation by 3345 setting the F bit to 1; the target sets the F bit to 1 on the last 3346 response. 3348 If the target responds to a Text request with the F bit set to 1 3349 with a Text response with the F bit set to 0 , the initiator should 3350 keep sending the Text request (even empty) with the F bit set to 1, 3351 while it still wants to finish the negotiation, until it receives 3352 the Text response with the F bit set to 1. Responding to a Text 3353 request with the F bit set to 1 with an empty (no key=value pairs) 3354 response with the F bit set to 0 is discouraged. 3356 Targets MUST NOT submit parameters that require an additional 3357 initiator Text request in a Text response with the F bit set to 1. 3359 Julian Satran Expires August 2003 64 3360 iSCSI 19-January-03 3362 In a negotiation sequence, the F bit settings in one pair of Text 3363 request-responses have no bearing on the F bit settings of the next 3364 pair. An initiator that has the F bit set to 1 in a request and is 3365 being answered with an F bit setting of 0 may issue the next request 3366 with the F bit set to 0. 3368 Whenever the target responds with the F bit set to 0, it MUST set 3369 the Target Transfer Tag to a value other than the default 3370 0xffffffff. 3372 An initiator MAY reset an operational parameter negotiation by 3373 issuing a Text request with the Target Transfer Tag set to the value 3374 0xffffffff after receiving a response with the Target Transfer Tag 3375 set to a value other than 0xffffffff. A target may reset an 3376 operational parameter negotiation by answering a Text request with a 3377 Reject PDU. 3379 Neither the initiator nor the target should attempt to declare or 3380 negotiate a parameter more than once during any negotiation sequence 3381 without an intervening operational parameter negotiation reset, 3382 except for responses to specific keys that explicitly allow repeated 3383 key declarations (e.g., TargetAddress). If detected by the target, 3384 this MUST result in a Reject PDU with a reason of "protocol error". 3385 The initiator MUST reset the negotiation as outlined above. 3387 Parameters negotiated by a text exchange negotiation sequence only 3388 become effective after the negotiation sequence is completed. 3390 Julian Satran Expires August 2003 65 3391 iSCSI 19-January-03 3393 6. iSCSI Error Handling and Recovery 3395 6.1 Overview 3397 6.1.1 Background 3399 The following two considerations prompted the design of much of the 3400 error recovery functionality in iSCSI: 3402 i) An iSCSI PDU may fail the digest check and be dropped, 3403 despite being received by the TCP layer. The iSCSI 3404 layer must optionally be allowed to recover such 3405 dropped PDUs. 3406 ii) A TCP connection may fail at any time during the data 3407 transfer. All the active tasks must optionally be 3408 allowed to be continued on a different TCP connection 3409 within the same session. 3411 Implementations have considerable flexibility in deciding what 3412 degree of error recovery to support, when to use it and by which 3413 mechanisms to achieve the required behavior. Only the externally 3414 visible actions of the error recovery mechanisms must be 3415 standardized to ensure interoperability. 3417 This chapter describes a general model for recovery in support of 3418 interoperability. See Appendix E. - Algorithmic Presentation of 3419 Error Recovery Classes - for further detail on how the described 3420 model may be implemented. Compliant implementations do not have to 3421 match the implementation details of this model as presented, but the 3422 external behavior of such implementations must correspond to the 3423 externally observable characteristics of the presented model. 3425 6.1.2 Goals 3427 The major design goals of the iSCSI error recovery scheme are as 3428 follows: 3430 a) Allow iSCSI implementations to meet different requirements 3431 by defining a collection of error recovery mechanisms that 3432 implementations may choose from. 3433 b) Ensure interoperability between any two implementations 3434 supporting different sets of error recovery capabilities. 3435 c) Define the error recovery mechanisms to ensure command 3436 ordering even in the face of errors, for initiators that demand 3437 ordering. 3438 d) Do not make additions in the fast path, but allow moderate 3439 complexity in the error recovery path. 3440 e) Prevent both the initiator and target from attempting to 3441 recover the same set of PDUs at the same time. For example, 3442 there must be a clear "error recovery functionality 3443 distribution" between the initiator and target. 3445 Julian Satran Expires August 2003 66 3446 iSCSI 19-January-03 3448 6.1.3 Protocol Features and State Expectations 3450 The initiator mechanisms defined in connection with error recovery 3451 are: 3453 a) NOP-OUT to probe sequence numbers of the target (section 3454 10.18) 3455 b) Command retry (section 6.2.1) 3456 c) Recovery R2T support (section 6.7) 3457 d) Requesting retransmission of status/data/R2T using the 3458 SNACK facility (section 10.16) 3459 e) Acknowledging the receipt of the data (section 10.16) 3460 f) Reassigning the connection allegiance of a task to a 3461 different TCP connection (section 6.2.2) 3462 g) Terminating the entire iSCSI session to start afresh 3463 (section 6.1.4.4) 3465 The target mechanisms defined in connection with error recovery are: 3467 a) NOP-IN to probe sequence numbers of the initiator (section 3468 10.19) 3469 b) Requesting retransmission of data using the recovery R2T 3470 feature (section 6.7) 3471 c) SNACK support (section 10.16) 3472 d) Requesting that parts of read data be acknowledged (section 3473 10.7.2) 3474 e) Allegiance reassignment support (section 6.2.2) 3475 f) Terminating the entire iSCSI session to force the initiator 3476 to start over (section 6.1.4.4) 3478 For any outstanding SCSI command, it is assumed that iSCSI, in 3479 conjunction with SCSI at the initiator, is able to keep enough 3480 information to be able to rebuild the command PDU, and that outgoing 3481 data is available (in host memory) for retransmission while the 3482 command is outstanding. It is also assumed that at the target, 3483 incoming data (read data) MAY be kept for recovery or it can be 3484 reread from a device server. 3486 It is further assumed that a target will keep the "status & sense" 3487 for a command it has executed if it supports status retransmission. 3488 A target that agrees to support data retransmission is expected to 3489 be prepared to retransmit the outgoing data (i.e., Data-In) on 3490 request until either the status for the completed command is 3491 acknowledged, or the data in question has been separately 3492 acknowledged. 3494 6.1.4 Recovery Classes 3496 iSCSI enables the following classes of recovery (in the order of 3497 increasing scope of affected iSCSI tasks): 3499 Julian Satran Expires August 2003 67 3500 iSCSI 19-January-03 3502 - Within a command (i.e., without requiring command restart). 3503 - Within a connection (i.e., without requiring the connection to 3504 be rebuilt, but perhaps requiring command restart). 3505 - Connection recovery (i.e., perhaps requiring connections to be 3506 rebuilt and commands to be reissued). 3507 - Session recovery. 3509 The recovery scenarios detailed in the rest of this section are 3510 representative rather than exclusive. In every case, they detail the 3511 lowest class recovery that MAY be attempted. The implementer is left 3512 to decide under which circumstances to escalate to the next recovery 3513 class and/or what recovery classes to implement. Both the iSCSI 3514 target and initiator MAY escalate the error handling to an error 3515 recovery class, which impacts a larger number of iSCSI tasks in any 3516 of the cases identified in the following discussion. 3518 In all classes, the implementer has the choice of deferring errors 3519 to the SCSI initiator (with an appropriate response code), in which 3520 case the task, if any, has to be removed from the target and all the 3521 side-effects, such as ACA, must be considered. 3523 Use of within-connection and within-command recovery classes MUST 3524 NOT be attempted before the connection is in Full Feature Phase. 3526 In the detailed description of the recover classes the mandating 3527 terms (MUST, SHOULD, MAY, etc.) indicate normative actions to be 3528 executed if the recovery class is supported and used. 3530 6.1.4.1 Recovery Within-command 3532 At the target, the following cases lend themselves to within-command 3533 recovery: 3535 - Lost data PDU - realized through one of the following: 3536 a) Data digest error - dealt with as specified in Section 6.7 3537 Digest Errors, using the option of a recovery R2T. 3538 b) Sequence reception timeout (no data or partial-data-and-no- 3539 F-bit) - considered an implicit sequence error and dealt with 3540 as specified in Section 6.8 Sequence Errors, using the option 3541 of a recovery R2T. 3542 c) Header digest error, which manifests as a sequence 3543 reception timeout or a sequence error - dealt with as specified 3544 in Section 6.8 Sequence Errors, using the option of a recovery 3545 R2T. 3547 At the initiator, the following cases lend themselves to within- 3548 command recovery: 3550 Lost data PDU or lost R2T - realized through one of the 3551 following: 3552 a) Data digest error - dealt with as specified in Section 6.7 3553 Digest Errors, using the option of a SNACK. 3555 Julian Satran Expires August 2003 68 3556 iSCSI 19-January-03 3558 b) Sequence reception timeout (no status) or response 3559 reception timeout - dealt with as specified in Section 6.8 3560 Sequence Errors, using the option of a SNACK. 3561 c) Header digest error, which manifests as a sequence 3562 reception timeout or a sequence error - dealt with as specified 3563 in Section 6.8 Sequence Errors, using the option of a SNACK. 3565 To avoid a race with the target, which may already have a recovery 3566 R2T or a termination response on its way, an initiator SHOULD NOT 3567 originate a SNACK for an R2T based on its internal timeouts (if 3568 any). Recovery in this case is better left to the target. 3570 The timeout values used by the initiator and target are outside the 3571 scope of this document. Sequence reception timeout is generally a 3572 large enough value to allow the data sequence transfer to be 3573 complete. 3575 6.1.4.2 Recovery Within-connection 3577 At the initiator, the following cases lend themselves to within- 3578 connection recovery: 3580 - Requests not acknowledged for a long time. Requests are 3581 acknowledged explicitly through ExpCmdSN or implicitly by 3582 receiving data and/or status. The initiator MAY retry non- 3583 acknowledged commands as specified in Section 6.2 Retry and 3584 Reassign in Recovery. 3586 - Lost iSCSI numbered Response. It is recognized by either 3587 identifying a data digest error on a Response PDU or a Data-In 3588 PDU carrying the status, or by receiving a Response PDU with a 3589 higher StatSN than expected. In the first case, digest error 3590 handling is done as specified in Section 6.7 Digest Errors 3591 using the option of a SNACK. In the second case, sequence 3592 error handling is done as specified in Section 6.8 Sequence 3593 Errors, using the option of a SNACK. 3595 At the target, the following cases lend themselves to within- 3596 connection recovery: 3598 - Status/Response not acknowledged for a long time. The target 3599 MAY issue a NOP-IN (with a valid Target Transfer Tag or 3600 otherwise) that carries the next status sequence number it is 3601 going to use in the StatSN field. This helps the initiator 3602 detect any missing StatSN(s) and issue a SNACK for the status. 3604 The timeout values used by the initiator and the target are outside 3605 the scope of this document. 3607 6.1.4.3 Connection Recovery 3609 At an iSCSI initiator, the following cases lend themselves to 3610 connection recovery: 3612 Julian Satran Expires August 2003 69 3613 iSCSI 19-January-03 3615 - TCP connection failure: The initiator MUST close the 3616 connection. It then MUST either implicitly or explicitly 3617 logout the failed connection with the reason code "remove the 3618 connection for recovery" and reassign connection allegiance 3619 for all commands still in progress associated with the failed 3620 connection on one or more connections (some or all of which 3621 MAY be newly established connections) using the "Task 3622 reassign" task management function (see Section 10.5.1 3623 Function). For an initiator, a command is in progress as long 3624 as it has not received a response or a Data-In PDU including 3625 status. 3627 Note: The logout function is mandatory. However, a new 3628 connection establishment is only mandatory if the failed 3629 connection was the last or only connection in the session. 3631 - Receiving an Asynchronous Message that indicates one or all 3632 connections in a session has been dropped. The initiator MUST 3633 handle it as a TCP connection failure for the connection(s) 3634 referred to in the Message. 3636 At an iSCSI target, the following cases lend themselves to 3637 connection recovery: 3639 - TCP connection failure. The target MUST close the connection 3640 and, if more than one connection is available, the target 3641 SHOULD send an Asynchronous Message that indicates it has 3642 dropped the connection. Then, the target will wait for the 3643 initiator to continue recovery. 3645 6.1.4.4 Session Recovery 3647 Session recovery should be performed when all other recovery 3648 attempts have failed. Very simple initiators and targets MAY 3649 perform session recovery on all iSCSI errors and rely on recovery on 3650 the SCSI layer and above. 3652 Session recovery implies the closing of all TCP connections, 3653 internally aborting all executing and queued tasks for the given 3654 initiator at the target, terminating all outstanding SCSI commands 3655 with an appropriate SCSI service response at the initiator, and 3656 restarting a session on a new set of connection(s) (TCP connection 3657 establishment and login on all new connections). 3659 For possible clearing effects of session recovery on SCSI and iSCSI 3660 objects, refer to Appendix F. - Clearing Effects of Various Events 3661 on Targets -. 3663 6.1.5 Error Recovery Hierarchy 3665 The error recovery classes described so far are organized into a 3666 hierarchy for ease in understanding and to limit the implementation 3667 complexity. With few and well defined recovery levels 3668 interoperability is easier to achieve. The attributes of this 3669 hierarchy are as follows: 3671 Julian Satran Expires August 2003 70 3672 iSCSI 19-January-03 3674 a) Each level is a superset of the capabilities of the 3675 previous level. For example, Level 1 support implies supporting 3676 all capabilities of Level 0 and more. 3677 b) As a corollary, supporting a higher error recovery level 3678 means increased sophistication and possibly an increase in 3679 resource requirements. 3680 c) Supporting error recovery level "n" is advertised and 3681 negotiated by each iSCSI entity by exchanging the text key 3682 "ErrorRecoveryLevel=n". The lower of the two exchanged values 3683 is the operational ErrorRecoveryLevel for the session. 3685 The following diagram represents the error recovery hierarchy. 3687 + 3688 / 3689 / 2 \ <-- Connection recovery 3690 +-----+ 3691 / 1 \ <-- Digest failure recovery 3692 +---------+ 3693 / 0 \ <-- Session failure recovery 3694 +-------------+ 3696 The following table lists the error recovery capabilities expected 3697 from the implementations that support each error recovery level. 3699 +-------------------+--------------------------------------------+ 3700 |ErrorRecoveryLevel | Associated Error recovery capabilities | 3701 +-------------------+--------------------------------------------+ 3702 | 0 | Session recovery class | 3703 | | (Section 6.1.4.4 Session Recovery) | 3704 +-------------------+--------------------------------------------+ 3705 | 1 | Digest failure recovery (See Note below.) | 3706 | | plus the capabilities of ER Level 0 | 3707 +-------------------+--------------------------------------------+ 3708 | 2 | Connection recovery class | 3709 | | (Section 6.1.4.3 Connection Recovery) | 3710 | | plus the capabilities of ER Level 1 | 3711 +-------------------+--------------------------------------------+ 3713 Note: Digest failure recovery is comprised of two recovery classes: 3714 Within-Connection recovery class (Section 6.1.4.2 Recovery Within- 3715 connection) and Within-Command recovery class (Section 6.1.4.1 3716 Recovery Within-command). 3718 When a defined value of ErrorRecoveryLevel is proposed by an 3719 originator in a text negotiation, the originator MUST support the 3720 functionality defined for the proposed value and additionally, 3721 functionality corresponding to any defined value numerically less 3722 than the proposed. When a defined value of ErrorRecoveryLevel is 3723 returned by a responder in a text negotiation, the responder MUST 3724 support the functionality corresponding to the ErrorRecoveryLevel it 3725 is accepting. 3727 Julian Satran Expires August 2003 71 3728 iSCSI 19-January-03 3730 When either party attempts to use error recovery functionality 3731 beyond what is negotiated, the recovery attempts MAY fail unless an 3732 apriori agreement outside the scope of this document exists between 3733 the two parties to provide such support. 3735 Implementations MUST support error recovery level "0", while the 3736 rest are OPTIONAL to implement. In implementation terms, the above 3737 striation means that the following incremental sophistication with 3738 each level is required. 3740 +-------------------+---------------------------------------------+ 3741 |Level transition | Incremental requirement | 3742 +-------------------+---------------------------------------------+ 3743 | 0->1 | PDU retransmissions on the same connection | 3744 +-------------------+---------------------------------------------+ 3745 | 1->2 | Retransmission across connections and | 3746 | | allegiance reassignment | 3747 +-------------------+---------------------------------------------+ 3749 6.2 Retry and Reassign in Recovery 3751 This section summarizes two important and somewhat related iSCSI 3752 protocol features used in error recovery. 3754 6.2.1 Usage of Retry 3756 By resending the same iSCSI command PDU ("retry") in the absence of 3757 a command acknowledgement (by way of an ExpCmdSN update) or a 3758 response, an initiator attempts to "plug" (what it thinks are) the 3759 discontinuities in CmdSN ordering on the target end. Discarded 3760 command PDUs, due to digest errors, may have created these 3761 discontinuities. 3763 Retry MUST NOT be used for reasons other than plugging command 3764 sequence gaps, and in particular, cannot be used for requesting PDU 3765 retransmissions from a target. Any such PDU retransmission requests 3766 for a currently allegiant command in progress may be made using the 3767 SNACK mechanism described in section 10.16, although the usage of 3768 SNACK is OPTIONAL. 3770 If initiators, as part of plugging command sequence gaps as 3771 described above, inadvertently issue retries for allegiant commands 3772 already in progress (i.e., targets did not see the discontinuities 3773 in CmdSN ordering), the duplicate commands are silently ignored by 3774 targets as specified in section 3.2.2.1. 3776 When an iSCSI command is retried, the command PDU MUST carry the 3777 original Initiator Task Tag and the original operational attributes 3778 (e.g., flags, function names, LUN, CDB etc.) as well as the original 3779 CmdSN. The command being retried MUST be sent on the same connection 3780 as the original command unless the original connection was already 3781 successfully logged out. 3783 Julian Satran Expires August 2003 72 3784 iSCSI 19-January-03 3786 6.2.2 Allegiance Reassignment 3788 By issuing a "task reassign" task management request (Section 10.5.1 3789 Function), the initiator signals its intent to continue an already 3790 active command (but with no current connection allegiance) as part 3791 of connection recovery. This means that a new connection allegiance 3792 is requested for the command, which seeks to associate it to the 3793 connection on which the task management request is being issued. 3794 Before the allegiance reassignment is attempted for a task, an 3795 implicit or explicit Logout with the reason code "remove the 3796 connection for recovery" ( see section 10.14) MUST be successfully 3797 completed for the previous connection to which the task was 3798 allegiant. 3800 In reassigning connection allegiance for a command, the targets 3801 SHOULD continue the command from its current state. For example, 3802 when reassigning read commands, the target SHOULD take advantage of 3803 the ExpDataSN field provided by the Task Management function request 3804 (which must be set to zero if there was no data transfer) and bring 3805 the read command to completion by sending the remaining data and 3806 sending (or resending) the status. ExpDataSN acknowledges all data 3807 sent up to, but not including, the Data-In PDU and or R2T with 3808 DataSN (or R2TSN) equal to ExpDataSN. However, targets may choose to 3809 send/receive all unacknowledged data or all of the data on a 3810 reassignment of connection allegiance if unable to recover or 3811 maintain accurate an state. Initiators MUST not subsequently 3812 request data retransmission through Data SNACK for PDUs numbered 3813 less than ExpDataSN (i.e., prior to the acknowledged sequence 3814 number). For all types of commands, a reassignment request implies 3815 that the task is still considered in progress by the initiator and 3816 the target must conclude the task appropriately if the target 3817 returns the "Function Complete" response to the reassignment 3818 request. This might possibly involve retransmission of data/R2T/ 3819 status PDUs as necessary, but MUST involve the (re)transmission of 3820 the status PDU. 3822 It is OPTIONAL for targets to support the allegiance reassignment. 3823 This capability is negotiated via the ErrorRecoveryLevel text key 3824 during the login time. When a target does not support allegiance 3825 reassignment, it MUST respond with a Task Management response code 3826 of "Allegiance reassignment not supported". If allegiance 3827 reassignment is supported by the target, but the task is still 3828 allegiant to a different connection, or a successful recovery Logout 3829 of the previously allegiant connection was not performed, the target 3830 MUST respond with a Task Management response code of "Task still 3831 allegiant". 3833 If allegiance reassignment is supported by the target, the Task 3834 Management response to the reassignment request MUST be issued 3835 before the reassignment becomes effective. 3837 If a SCSI Command that involves data input is reassigned, any SNACK 3838 Tag it holds for a final response from the original connection is 3839 deleted and the default value of 0 MUST be used instead. 3841 Julian Satran Expires August 2003 73 3842 iSCSI 19-January-03 3844 6.3 Usage Of Reject PDU in Recovery 3846 Targets MUST NOT implicitly terminate an active task by sending a 3847 Reject PDU for any PDU exchanged during the life of the task. If the 3848 target decides to terminate the task, a Response PDU (SCSI, Text, 3849 Task, etc.) must be returned by the target to conclude the task. If 3850 the task had never been active before the Reject (i.e., the Reject 3851 is on the command PDU), targets should not send any further 3852 responses because the command itself is being discarded. 3854 The above rule means that the initiator can eventually expect a 3855 response on receiving Rejects, if the received Reject is for a PDU 3856 other than the command PDU itself. The non-command Rejects only have 3857 diagnostic value in logging the errors, and they can be used for 3858 retransmission decisions by the initiators. 3860 The CmdSN of the rejected command PDU (if it is a non-immediate 3861 command) MUST NOT be considered received by the target (i.e., a 3862 command sequence gap must be assumed for the CmdSN), even though the 3863 CmdSN of the rejected command PDU may be reliably ascertained. Upon 3864 receiving the Reject, the initiator MUST plug the CmdSN gap in order 3865 to continue to use the session. The gap may be plugged either by 3866 transmitting a command PDU with the same CmdSN, or by aborting the 3867 task (see section 6.9 on how an abort may plug a CmdSN gap). 3869 When a data PDU is rejected and its DataSN can be ascertained, a 3870 target MUST advance ExpDataSN for the current data burst if a 3871 recovery R2T is being generated. The target MAY advance its 3872 ExpDataSN if it does not attempt to recover the lost data PDU. 3874 6.4 Connection Timeout Management 3876 iSCSI defines two session-global timeout values (in seconds) - 3877 Time2Wait and Time2Retain - that are applicable when an iSCSI Full 3878 Feature Phase connection is taken out of service either 3879 intentionally or by an exception. Time2Wait is the initial "respite 3880 time" before attempting an explicit/implicit Logout for the CID in 3881 question or task reassignment for the affected tasks (if any). 3882 Time2Retain is the maximum time after the initial respite interval 3883 that the task and/or connection state(s) is/are guaranteed to be 3884 maintained on the target to cater to a possible recovery attempt. 3885 Recovery attempts for the connection and/or task(s) SHOULD NOT be 3886 made before Time2Wait seconds, but MUST be completed within 3887 Time2Retain seconds after that initial Time2Wait waiting period. 3889 6.4.1 Timeouts on Transport Exception Events 3891 A transport connection shutdown or a transport reset without any 3892 preceding iSCSI protocol interactions informing the end-points of 3893 the fact causes a Full Feature Phase iSCSI connection to be abruptly 3894 terminated. The timeout values to be used in this case are the 3895 negotiated values of defaultTime2Wait (Section 12.15 3896 DefaultTime2Wait) and DefaultTime2Retain (Section 12.16 3897 DefaultTime2Retain) text keys for the session. 3899 Julian Satran Expires August 2003 74 3900 iSCSI 19-January-03 3902 6.4.2 Timeouts on Planned Decommissioning 3904 Any planned decommissioning of a Full Feature Phase iSCSI connection 3905 is preceded by either a Logout Response PDU, or an Async Message 3906 PDU. The Time2Wait and Time2Retain field values (section 10.15) in a 3907 Logout Response PDU, and the Parameter2 and Parameter3 fields of an 3908 Async Message (AsyncEvent types "drop the connection" or "drop all 3909 the connections"; section 10.9.1) specify the timeout values to be 3910 used in each of these cases. 3912 These timeout values are only applicable for the affected 3913 connection, and the tasks active on that connection. These timeout 3914 values have no bearing on initiator timers (if any) that are already 3915 running on connections or tasks associated with that session. 3917 6.5 Implicit Termination of Tasks 3919 A target implicitly terminates the active tasks due to iSCSI 3920 protocol dynamics in the following cases: 3922 a) When a connection is implicitly or explicitly logged out 3923 with the reason code of "Close the connection" and there are 3924 active tasks allegiant to that connection. 3926 b) When a connection fails and eventually the connection state 3927 times out (state transition M1 in Section 7.2.2 State 3928 Transition Descriptions for Initiators and Targets) and there 3929 are active tasks allegiant to that connection. 3931 c) When a successful Logout with the reason code of "remove 3932 the connection for recovery" is performed while there are 3933 active tasks allegiant to that connection, and those tasks 3934 eventually time out after the Time2Wait and Time2Retain periods 3935 without allegiance reassignment. 3937 d) When a connection is implicitly or explicitly logged out 3938 with the reason code of "Close the session" and there are 3939 active tasks in that session. 3941 If the tasks terminated in the above cases a), b, c) and d)are SCSI 3942 tasks, they must be internally terminated as if with CHECK CONDITION 3943 status. This status is only meaningful for appropriately handling 3944 the internal SCSI state and SCSI side effects with respect to 3945 ordering because this status is never communicated back as a 3946 terminating status to the initiator. However additional actions may 3947 have to be taken at SCSI level depending on the SCSI context as 3948 defined by the SCSI standards (e.g., queued commands and ACA, UA for 3949 the next command on the I_T nexus in cases a), b), and c) etc. - see 3950 [SAM] and [SPC3]). 3952 Julian Satran Expires August 2003 75 3953 iSCSI 19-January-03 3955 6.6 Format Errors 3957 The following two explicit violations of PDU layout rules are format 3958 errors: 3960 a) Illegal contents of any PDU header field except the Opcode 3961 (legal values are specified in Section 10 iSCSI PDU Formats). 3962 b) Inconsistent field contents (consistent field contents are 3963 specified in Section 10 iSCSI PDU Formats). 3965 Format errors indicate a major implementation flaw in one of the 3966 parties. 3968 When a target or an initiator receives an iSCSI PDU with a format 3969 error, it MUST immediately terminate all transport connections in 3970 the session either with a connection close or with a connection 3971 reset and escalate the format error to session recovery (see Section 3972 6.1.4.4 Session Recovery). 3974 6.7 Digest Errors 3976 The discussion of the legal choices in handling digest errors below 3977 excludes session recovery as an explicit option, but either party 3978 detecting a digest error may choose to escalate the error to session 3979 recovery. 3981 When a target or an initiator receives any iSCSI PDU, with a header 3982 digest error, it MUST either discard the header and all data up to 3983 the beginning of a later PDU or close the connection. Because the 3984 digest error indicates that the length field of the header may have 3985 been corrupted, the location of the beginning of a later PDU needs 3986 to be reliably ascertained by other means such as the operation of a 3987 sync and steering layer. 3989 When a target receives any iSCSI PDU with a payload digest error, it 3990 MUST answer with a Reject PDU with a reason code of Data-Digest- 3991 Error and discard the PDU. 3993 - If the discarded PDU is a solicited or unsolicited iSCSI data 3994 PDU (for immediate data in a command PDU, non-data PDU rule 3995 below applies), the target MUST do one of the following: 3996 a) Request retransmission with a recovery R2T. 3997 b) Terminate the task with a response PDU with a CHECK 3998 CONDITION Status and an iSCSI Condition of "protocol 3999 service CRC error" (Section 10.4.7.2 Sense Data). If the 4000 target chooses to implement this option, it MUST wait to 4001 receive all the data (signaled by a Data PDU with the 4002 final bit set for all outstanding R2Ts) before sending 4003 the response PDU. A task management command (such as an 4004 abort task) from the initiator during this wait may also 4005 conclude the task. 4006 - No further action is necessary for targets if the discarded 4007 PDU is a non-data PDU. In case of immediate data being 4009 Julian Satran Expires August 2003 76 4010 iSCSI 19-January-03 4012 present on a discarded command, the immediate data is 4013 implicitly recovered when the task is retried (see section 4014 6.2.1) followed by the entire data transfer for the task. 4016 When an initiator receives any iSCSI PDU with a payload digest 4017 error, it MUST discard the PDU. 4018 - If the discarded PDU is an iSCSI data PDU, the initiator MUST 4019 do one of the following: 4021 a) Request the desired data PDU through SNACK. In response 4022 to the SNACK, the target MUST either resend the data PDU 4023 or reject the SNACK with a Reject PDU with a reason code 4024 of "SNACK reject" in which case: 4025 i)If the status has not already been sent for the 4026 command, the target MUST terminate the command with 4027 a CHECK CONDITION Status and an iSCSI Condition of 4028 "SNACK rejected" (Section 10.4.7.2 Sense Data). 4029 ii)If the status was already sent, no further action 4030 is necessary for the target. The initiator in this 4031 case MUST wait for the status to be received and 4032 then discard it, so as to internally signal the 4033 completion with CHECK CONDITION Status and an iSCSI 4034 Condition of "protocol service CRC error" (Section 4035 10.4.7.2 Sense Data). 4036 b) Abort the task and terminate the command with an error. 4038 - If the discarded PDU is a response PDU, the initiator MUST do 4039 one of the following: 4041 a) Request PDU retransmission with a status SNACK. 4042 b) Logout the connection for recovery and continue the 4043 tasks on a different connection instance as described in 4044 Section 6.2 Retry and Reassign in Recovery. 4045 c) Logout to close the connection (abort all the commands 4046 associated with the connection). 4048 - No further action is necessary for initiators if the discarded 4049 PDU is an unsolicited PDU (e.g., Async, Reject). Task 4050 timeouts as in the initiator waiting for a command completion, 4051 or process timeouts as in the target waiting for a Logout will 4052 ensure that the correct operational behavior will result in 4053 these cases despite the discarded PDU. 4055 6.8 Sequence Errors 4057 When an initiator receives an iSCSI R2T/data PDU with an out of 4058 order R2TSN/DataSN or a SCSI response PDU with an ExpDataSN that 4059 implies missing data PDU(s), it means that the initiator must have 4060 detected a header or payload digest error on one or more earlier 4061 R2T/data PDUs. The initiator MUST address these implied digest 4063 Julian Satran Expires August 2003 77 4064 iSCSI 19-January-03 4066 errors as described in Section 6.7 Digest Errors. When a target 4067 receives a data PDU with an out of order DataSN, it means that the 4068 target must have hit a header or payload digest error on at least 4069 one of the earlier data PDUs. The target MUST address these implied 4070 digest errors as described in Section 6.7 Digest Errors. 4072 When an initiator receives an iSCSI status PDU with an out of order 4073 StatSN that implies missing responses, it MUST address the one or 4074 more missing status PDUs as described in Section 6.7 Digest Errors. 4075 As a side effect of receiving the missing responses, the initiator 4076 may discover missing data PDUs. If the initiator wants to recover 4077 the missing data for a command, it MUST NOT acknowledge the received 4078 responses that start from the StatSN of the relevant command, until 4079 it has completed receiving all the data PDUs of the command. 4081 When an initiator receives duplicate R2TSNs (due to proactive 4082 retransmission of R2Ts by the target) or duplicate DataSNs (due to 4083 proactive SNACKs by the initiator), it MUST discard the duplicates. 4085 6.9 SCSI Timeouts 4087 An iSCSI initiator MAY attempt to plug a command sequence gap on the 4088 target end (in the absence of an acknowledgement of the command by 4089 way of ExpCmdSN) before the ULP timeout by retrying the 4090 unacknowledged command, as described in Section 6.2 Retry and 4091 Reassign in Recovery. 4093 On a ULP timeout for a command (that carried a CmdSN of n), if the 4094 iSCSI initiator intends to continue the session it MUST abort the 4095 command by either using an appropriate Task Management function 4096 request for the specific command, or a "close the connection" 4097 Logout. When using an ABORT TASK, if the ExpCmdSN is still less 4098 than (n+1), the target may see the abort request while missing the 4099 original command itself due to one of the following reasons: 4101 - Original command was dropped due to digest error. 4102 - Connection on which the original command was sent was 4103 successfully logged out. On logout, the unacknowledged 4104 commands issued on the connection being logged out are 4105 discarded. 4107 If the abort request is received and the original command is 4108 missing, targets MUST consider the original command with that 4109 RefCmdSN to be received and issue a Task Management response with 4110 the response code: "Function Complete". This response concludes the 4111 task on both ends. 4113 6.10 Negotiation Failures 4115 Text request and response sequences, when used to set/negotiate 4116 operational parameters, constitute the negotiation/parameter 4117 setting. A negotiation failure is considered to be one or more of 4118 the following: 4120 - None of the choices, or the stated value, is acceptable to one 4121 of the sides in the negotiation. 4123 Julian Satran Expires August 2003 78 4124 iSCSI 19-January-03 4126 - The text request timed out and possibly terminated. 4127 - The text request was answered with a Reject PDU. 4129 The following two rules should be used to address negotiation 4130 failures: 4132 - During Login, any failure in negotiation MUST be considered a 4133 login process failure and the Login Phase must be terminated, 4134 and with it, the connection. If the target detects the 4135 failure, it must terminate the login with the appropriate 4136 login response code. 4138 - A failure in negotiation, while in the Full Feature Phase, 4139 will terminate the entire negotiation sequence that may 4140 consist of a series of text requests that use the same 4141 Initiator Task Tag. The operational parameters of the session 4142 or the connection MUST continue to be the values agreed upon 4143 during an earlier successful negotiation (i.e., any partial 4144 results of this unsuccessful negotiation MUST NOT take effect 4145 and MUST be discarded). 4147 6.11 Protocol Errors 4149 Mapping framed messages over a "stream" connection, such as TCP, 4150 makes the proposed mechanisms vulnerable to simple software framing 4151 errors. On the other hand, the introduction of framing mechanisms to 4152 limit the effects of these errors may be onerous on performance for 4153 simple implementations. Command Sequence Numbers and the above 4154 mechanisms for connection drop and reestablishment help handle this 4155 type of mapping errors. 4157 All violations of iSCSI PDU exchange sequences specified in this 4158 draft are also protocol errors. This category of errors can only be 4159 addressed by fixing the implementations; iSCSI defines Reject and 4160 response codes to enable this. 4162 6.12 Connection Failures 4164 iSCSI can keep a session in operation if it is able to keep/ 4165 establish at least one TCP connection between the initiator and the 4166 target in a timely fashion. Targets and/or initiators may recognize 4167 a failing connection by either transport level means (TCP), a gap in 4168 the command sequence number, a response stream that is not filled 4169 for a long time, or by a failing iSCSI NOP (acting as a ping). The 4170 latter MAY be used periodically to increase the speed and likelihood 4171 of detecting connection failures. Initiators and targets MAY also 4172 use the keep-alive option on the TCP connection to enable early link 4173 failure detection on otherwise idle links. 4175 On connection failure, the initiator and target MUST do one of the 4176 following: 4178 - Attempt connection recovery within the session (Section 4179 6.1.4.3 Connection Recovery). 4181 Julian Satran Expires August 2003 79 4182 iSCSI 19-January-03 4184 - Logout the connection with the reason code "closes the 4185 connection" (Section 10.14.5 Implicit termination of tasks), 4186 re-issue missing commands, and implicitly terminate all active 4187 commands. This option requires support for the within- 4188 connection recovery class (Section 6.1.4.2 Recovery Within- 4189 connection). 4190 - Perform session recovery (Section 6.1.4.4 Session Recovery). 4192 Either side may choose to escalate to session recovery (via the 4193 initiator dropping all the connections, or via an Async Message that 4194 announces the similar intent from a target), and the other side MUST 4195 give it precedence. On a connection failure, a target MUST 4196 terminate and/or discard all of the active immediate commands 4197 regardless of which of the above options is used (i.e., immediate 4198 commands are not recoverable across connection failures). 4200 6.13 Session Errors 4202 If all of the connections of a session fail and cannot be 4203 reestablished in a short time, or if initiators detect protocol 4204 errors repeatedly, an initiator may choose to terminate a session 4205 and establish a new session. 4207 In this case, the initiator takes the following actions: 4209 - Resets or closes all the transport connections. 4210 - Terminates all outstanding requests with an appropriate 4211 response before initiating a new session. If the same I_T 4212 nexus is intended to be reestablished, the initiator MUST 4213 employ session reinstatement (see section 5.3.5). 4215 When the session timeout (the connection state timeout for the last 4216 failed connection) happens on the target, it takes the following 4217 actions: 4219 - Resets or closes the TCP connections (closes the session). 4220 - Terminates all active tasks that were allegiant to the 4221 connection(s) that constituted the session. 4223 A target MUST also be prepared to handle a session reinstatement 4224 request from the initiator, that may be addressing session errors. 4226 Julian Satran Expires August 2003 80 4227 iSCSI 19-January-03 4229 7. State Transitions 4231 iSCSI connections and iSCSI sessions go through several well-defined 4232 states from the time they are created to the time they are cleared. 4234 The connection state transitions are described in two separate but 4235 dependent state diagrams for ease in understanding. The first 4236 diagram, "standard connection state diagram", describes the 4237 connection state transitions when the iSCSI connection is not 4238 waiting for, or undergoing, a cleanup by way of an explicit or 4239 implicit Logout. The second diagram, "connection cleanup state 4240 diagram", describes the connection state transitions while 4241 performing the iSCSI connection cleanup. 4243 The "session state diagram" describes the state transitions an iSCSI 4244 session would go through during its lifetime, and it depends on the 4245 states of possibly multiple iSCSI connections that participate in 4246 the session. 4248 States and transitions are described in text, tables and diagrams. 4249 The diagrams are used for illustration. The text and the tables are 4250 the governing specification 4252 7.1 Standard Connection State Diagrams 4254 7.1.1 State Descriptions for Initiators and Targets 4256 State descriptions for the standard connection state diagram are as 4257 follows: 4258 -S1: FREE 4259 -initiator: State on instantiation, or after successful 4260 connection closure. 4261 -target: State on instantiation, or after successful 4262 connection closure. 4263 -S2: XPT_WAIT 4264 -initiator: Waiting for a response to its transport connection 4265 establishment request. 4266 -target: Illegal 4267 -S3: XPT_UP 4268 -initiator: Illegal 4269 -target: Waiting for the Login process to commence. 4271 -S4: IN_LOGIN 4272 -initiator: Waiting for the Login process to conclude, 4273 possibly involving several PDU exchanges. 4274 -target: Waiting for the Login process to conclude, possibly 4275 involving several PDU exchanges. 4276 -S5: LOGGED_IN 4277 -initiator: In Full Feature Phase, waiting for all internal, 4278 iSCSI, and transport events. 4279 -target: In Full Feature Phase, waiting for all internal, 4280 iSCSI, and transport events. 4282 Julian Satran Expires August 2003 81 4283 iSCSI 19-January-03 4285 -S6: IN_LOGOUT 4286 -initiator: Waiting for a Logout response. 4287 -target: Waiting for an internal event signaling completion of 4288 logout processing. 4289 -S7: LOGOUT_REQUESTED 4290 -initiator: Waiting for an internal event signaling readiness 4291 to proceed with Logout. 4292 -target: Waiting for the Logout process to start after having 4293 requested a Logout via an Async Message. 4294 -S8: CLEANUP_WAIT 4295 -initiator: Waiting for the context and/or resources to 4296 initiate the cleanup processing for this CSM. 4297 -target: Waiting for the cleanup process to start for this 4298 CSM. 4299 7.1.2 State Transition Descriptions for Initiators and Targets 4301 -T1: 4302 -initiator: Transport connect request was made (e.g., TCP SYN 4303 sent). 4304 -target: Illegal 4305 -T2: 4306 -initiator: Transport connection request timed out, a 4307 transport reset was received, or an internal event of 4308 receiving a Logout response (success) on another connection 4309 for a "close the session" Logout request was received. 4310 -target:Illegal 4311 -T3: 4312 -initiator: Illegal 4313 -target: Received a valid transport connection request that 4314 establishes the transport connection. 4315 -T4: 4316 -initiator: Transport connection established, thus prompting 4317 the initiator to start the iSCSI Login. 4318 -target: Initial iSCSI Login request was received. 4319 -T5: 4320 -initiator: The final iSCSI Login response with a Status-Class 4321 of zero was received. 4322 -target: The final iSCSI Login request to conclude the Login 4323 Phase was received, thus prompting the target to send the 4324 final iSCSI Login response with a Status-Class of zero. 4325 -T6: 4326 -initiator: Illegal 4327 -target: Timed out waiting for an iSCSI Login, transport 4328 disconnect indication was received, transport reset was 4329 received, or an internal event indicating a transport timeout 4330 was received. In all these cases, the connection is to be 4331 closed. 4333 Julian Satran Expires August 2003 82 4334 iSCSI 19-January-03 4336 -T7: 4337 -initiator - one of the following events caused the 4338 transition: 4339 - The final iSCSI Login response was received with a non- 4340 zero Status-Class. 4341 - Login timed out. 4342 - A transport disconnect indication was received. 4343 - A transport reset was received. 4344 - An internal event indicating a transport timeout was 4345 received. 4346 - An internal event of receiving a Logout response 4347 (success) on another connection for a "close the 4348 session" Logout request was received. 4350 In all these cases, the transport connection is closed. 4352 -target - one of the following events caused the transition: 4353 - The final iSCSI Login request to conclude the Login 4354 Phase was received, prompting the target to send the 4355 final iSCSI Login response with a non-zero Status-Class. 4356 - Login timed out. 4357 - Transport disconnect indication was received. 4358 - Transport reset was received. 4359 - An internal event indicating a transport timeout was 4360 received . 4361 - On another connection a "close the session" Logout 4362 request was received. 4364 In all these cases, the connection is to be closed. 4365 -T8: 4366 -initiator: An internal event of receiving a Logout response 4367 (success) on another connection for a "close the session" 4368 Logout request was received, thus closing this connection 4369 requiring no further cleanup. 4370 -target: An internal event of sending a Logout response 4371 (success) on another connection for a "close the session" 4372 Logout request was received, or an internal event of a 4373 successful connection/session reinstatement is received, thus 4374 prompting the target to close this connection cleanly. 4375 -T9, T10: 4376 -initiator: An internal event that indicates the readiness to 4377 start the Logout process was received, thus prompting an 4378 iSCSI Logout to be sent by the initiator. 4379 -target: An iSCSI Logout request was received. 4380 -T11, T12: 4381 -initiator: Async PDU with AsyncEvent "Request Logout" was 4382 received. 4384 Julian Satran Expires August 2003 83 4385 iSCSI 19-January-03 4387 -target: An internal event that requires the decommissioning 4388 of the connection is received, thus causing an Async PDU with 4389 an AsyncEvent "Request Logout" to be sent. 4390 -T13: 4391 -initiator: An iSCSI Logout response (success) was received, 4392 or an internal event of receiving a Logout response (success) 4393 on another connection for a "close the session" Logout 4394 request was received. 4395 -target: An internal event was received that indicates 4396 successful processing of the Logout, which prompts an iSCSI 4397 Logout response (success) to be sent; an internal event of 4398 sending a Logout response (success) on another connection for 4399 a "close the session" Logout request was received; or an 4400 internal event of a successful connection/session 4401 reinstatement is received. In all these cases, the transport 4402 connection is closed. 4404 -T14: 4405 -initiator: Async PDU with AsyncEvent "Request Logout" was 4406 received again. 4407 -target: Illegal 4408 -T15, T16: 4409 -initiator: One or more of the following events caused this 4410 transition: 4411 -Internal event that indicates a transport connection 4412 timeout was received thus prompting transport RESET or 4413 transport connection closure. 4414 -A transport RESET. 4415 -A transport disconnect indication. 4416 -Async PDU with AsyncEvent "Drop connection" (for this 4417 CID). 4418 -Async PDU with AsyncEvent "Drop all connections". 4419 -target: One or more of the following events caused this 4420 transition: 4421 -Internal event that indicates a transport connection 4422 timeout was received, thus prompting transport RESET or 4423 transport connection closure. 4424 -An internal event of a failed connection/session 4425 reinstatement is received. 4426 -A transport RESET. 4427 -A transport disconnect indication. 4428 -Internal emergency cleanup event was received which 4429 prompts an Async PDU with AsyncEvent "Drop connection" 4430 (for this CID), or event "Drop all connections". 4432 -T17: 4433 -initiator: One or more of the following events caused this 4434 transition: 4436 Julian Satran Expires August 2003 84 4437 iSCSI 19-January-03 4439 -Logout response, (failure i.e., a non-zero status) was 4440 received, or Logout timed out. 4441 -Any of the events specified for T15 and T16. 4442 -target: One or more of the following events caused this 4443 transition: 4444 -Internal event that indicates a failure of the Logout 4445 processing was received, which prompts a Logout response 4446 (failure, i.e., a non-zero status) to be sent. 4447 -Any of the events specified for T15 and T16. 4448 -T18: 4449 -initiator: An internal event of receiving a Logout response 4450 (success) on another connection for a "close the session" 4451 Logout request was received. 4453 -target: An internal event of sending a Logout response 4454 (success) on another connection for a "close the session" 4455 Logout request was received, or an internal event of a 4456 successful connection/session reinstatement is received. In 4457 both these cases, the connection is closed. 4459 The CLEANUP_WAIT state (S8) implies that there are possible iSCSI 4460 tasks that have not reached conclusion and are still considered 4461 busy. 4463 7.1.3 Standard Connection State Diagram for an Initiator 4465 Symbolic names for States: 4467 S1: FREE 4468 S2: XPT_WAIT 4469 S4: IN_LOGIN 4470 S5: LOGGED_IN 4471 S6: IN_LOGOUT 4472 S7: LOGOUT_REQUESTED 4473 S8: CLEANUP_WAIT 4475 States S5, S6, and S7 constitute the Full Feature Phase operation of 4476 the connection. 4478 The state diagram is as follows: 4480 Julian Satran Expires August 2003 85 4481 iSCSI 19-January-03 4483 -------<-------------+ 4484 +--------->/ S1 \<----+ | 4485 T13| +->\ /<-+ \ | 4486 | / ---+--- \ \ | 4487 | / | T2 \ | | 4488 | T8 | |T1 | | | 4489 | | | / |T7 | 4490 | | | / | | 4491 | | | / | | 4492 | | V / / | 4493 | | ------- / / | 4494 | | / S2 \ / | 4495 | | \ / / | 4496 | | ---+--- / | 4497 | | |T4 / | 4498 | | V / | T18 4499 | | ------- / | 4500 | | / S4 \ | 4501 | | \ / | 4502 | | ---+--- | T15 4503 | | |T5 +--------+---------+ 4504 | | | /T16+-----+------+ | 4505 | | | / -+-----+--+ | | 4506 | | | / / S7 \ |T12| | 4507 | | | / +->\ /<-+ V V 4508 | | | / / -+----- ------- 4509 | | | / /T11 |T10 / S8 4510 | | V / / V +----+ \ / 4511 | | ---+-+- ----+-- | ------- 4512 | | / S5 \T9 / S6 \<+ ^ 4513 | +-----\ /--->\ / T14 | 4514 | ------- --+----+------+T17 4515 +---------------------------+ 4517 The following state transition table represents the above diagram. 4518 Each row represents the starting state for a given transition, which 4519 after taking a transition marked in a table cell would end in the 4520 state represented by the column of the cell. For example, from state 4521 S1, the connection takes the T1 transition to arrive at state S2. 4522 The fields marked "-" correspond to undefined transitions. 4524 Julian Satran Expires August 2003 86 4525 iSCSI 19-January-03 4527 +----+---+---+---+---+----+---+ 4528 |S1 |S2 |S4 |S5 |S6 |S7 |S8 | 4529 ---+----+---+---+---+---+----+---+ 4530 S1| - |T1 | - | - | - | - | - | 4531 ---+----+---+---+---+---+----+---+ 4532 S2|T2 |- |T4 | - | - | - | - | 4533 ---+----+---+---+---+---+----+---+ 4534 S4|T7 |- |- |T5 | - | - | - | 4535 ---+----+---+---+---+---+----+---+ 4536 S5|T8 |- |- | - |T9 |T11 |T15| 4537 ---+----+---+---+---+---+----+---+ 4538 S6|T13 |- |- | - |T14|- |T17| 4539 ---+----+---+---+---+---+----+---+ 4540 S7|T18 |- |- | - |T10|T12 |T16| 4541 ---+----+---+---+---+---+----+---+ 4542 S8| - |- |- | - | - | - | - | 4543 ---+----+---+---+---+---+----+---+ 4545 7.1.4 Standard Connection State Diagram for a Target 4547 Symbolic names for States: 4548 S1: FREE 4549 S3: XPT_UP 4550 S4: IN_LOGIN 4551 S5: LOGGED_IN 4552 S6: IN_LOGOUT 4553 S7: LOGOUT_REQUESTED 4554 S8: CLEANUP_WAIT 4556 States S5, S6, and S7 constitute the Full Feature Phase operation of 4557 the connection. 4559 The state diagram is as follows: 4561 Julian Satran Expires August 2003 87 4562 iSCSI 19-January-03 4564 -------<-------------+ 4565 +--------->/ S1 \<----+ | 4566 T13| +->\ /<-+ \ | 4567 | / ---+--- \ \ | 4568 | / | T6 \ | | 4569 | T8 | |T3 | | | 4570 | | | / |T7 | 4571 | | | / | | 4572 | | | / | | 4573 | | V / / | 4574 | | ------- / / | 4575 | | / S3 \ / | 4576 | | \ / / | T18 4577 | | ---+--- / | 4578 | | |T4 / | 4579 | | V / | 4580 | | ------- / | 4581 | | / S4 \ | 4582 | | \ / | 4583 | | ---+--- T15 | 4584 | | |T5 +--------+---------+ 4585 | | | /T16+-----+------+ | 4586 | | | / -+-----+---+ | | 4587 | | | / / S7 \ |T12| | 4588 | | | / +->\ /<-+ V V 4589 | | | / / -+----- ------- 4590 | | | / /T11 |T10 / S8 4591 | | V / / V \ / 4592 | | ---+-+- ------- ------- 4593 | | / S5 \T9 / S6 \ ^ 4594 | +-----\ /--->\ / | 4595 | ------- --+----+--------+T17 4596 +---------------------------+ 4598 The following state transition table represents the above diagram, 4599 and follows the conventions described for the initiator diagram. 4601 Julian Satran Expires August 2003 88 4602 iSCSI 19-January-03 4604 +----+---+---+---+---+----+---+ 4605 |S1 |S3 |S4 |S5 |S6 |S7 |S8 | 4606 ---+----+---+---+---+---+----+---+ 4607 S1| - |T3 | - | - | - | - | - | 4608 ---+----+---+---+---+---+----+---+ 4609 S3|T6 |- |T4 | - | - | - | - | 4610 ---+----+---+---+---+---+----+---+ 4611 S4|T7 |- |- |T5 | - | - | - | 4612 ---+----+---+---+---+---+----+---+ 4613 S5|T8 |- |- | - |T9 |T11 |T15| 4614 ---+----+---+---+---+---+----+---+ 4615 S6|T13 |- |- | - |- |- |T17| 4616 ---+----+---+---+---+---+----+---+ 4617 S7|T18 |- |- | - |T10|T12 |T16| 4618 ---+----+---+---+---+---+----+---+ 4619 S8| - |- |- | - | - | - | - | 4620 ---+----+---+---+---+---+----+---+ 4622 7.2 Connection Cleanup State Diagram for Initiators and Targets 4624 Symbolic names for states: 4626 R1: CLEANUP_WAIT (same as S8) 4627 R2: IN_CLEANUP 4628 R3: FREE (same as S1) 4630 Whenever a connection state machine (e.g., CSM-C) enters the 4631 CLEANUP_WAIT state (S8), it must go through the state transitions 4632 described in the connection cleanup state diagram either a) using a 4633 separate full-feature phase connection (let's call it CSM-E) in the 4634 LOGGED_IN state in the same session, or b) using a new transport 4635 connection (let's call it CSM-I) in the FREE state that is to be 4636 added to the same session. In the CSM-E case, an explicit logout for 4637 the CID that corresponds to CSM-C (either as a connection or session 4638 logout) needs to be performed to complete the cleanup. In the CSM-I 4639 case, an implicit logout for the CID that corresponds to CSM-C needs 4640 to be performed by way of connection reinstatement (section 5.3.4) 4641 for that CID. In either case, the protocol exchanges on CSM-E or 4642 CSM-I determine the state transitions for CSM-C. Therefore, this 4643 cleanup state diagram is only applicable to the instance of the 4644 connection in cleanup (i.e., CSM-C). In the case of an implicit 4645 logout for example, CSM-C reaches FREE (R3) at the time CSM-I 4646 reaches LOGGED_IN. In the case of an explicit logout, CSM-C reaches 4647 FREE (R3) when CSM-E receives a successful logout response while 4648 continuing to be in the LOGGED_IN state. 4650 An initiator must initiate an explicit or implicit connection logout 4651 for a connection in the CLEANUP_WAIT state, if the initiator intends 4652 to continue using the associated iSCSI session. 4654 The following state diagram applies to both initiators and targets. 4656 Julian Satran Expires August 2003 89 4657 iSCSI 19-January-03 4659 ------- 4660 / R1 4661 +--\ /<-+ 4662 / ---+--- 4663 / | \ M3 4664 M1 | |M2 | 4665 | | / 4666 | | / 4667 | | / 4668 | V / 4669 | ------- / 4670 | / R2 4671 | \ / 4672 | ------- 4673 | | 4674 | |M4 4675 | | 4676 | | 4677 | | 4678 | V 4679 | ------- 4680 | / R3 4681 +---->\ / 4682 ------- 4684 The following state transition table represents the above diagram, 4685 and follows the same conventions as in earlier sections. 4687 +----+----+----+ 4688 |R1 |R2 |R3 | 4689 -----+----+----+----+ 4690 R1 | - |M2 |M1 | 4691 -----+----+----+----+ 4692 R2 |M3 | - |M4 | 4693 -----+----+----+----+ 4694 R3 | - | - | - | 4695 -----+----+----+----+ 4697 7.2.1 State Descriptions for Initiators and Targets 4699 -R1: CLEANUP_WAIT (Same as S8) 4700 -initiator: Waiting for the internal event to initiate the 4701 cleanup processing for CSM-C. 4702 -target: Waiting for the cleanup process to start for CSM-C. 4703 -R2: IN_CLEANUP 4704 -initiator: Waiting for the connection cleanup process to 4705 conclude for CSM-C. 4706 -target: Waiting for the connection cleanup process to 4707 conclude for CSM-C. 4708 -R3: FREE (Same as S1) 4709 -initiator: End state for CSM-C. 4710 -target: End state for CSM-C. 4712 Julian Satran Expires August 2003 90 4713 iSCSI 19-January-03 4715 7.2.2 State Transition Descriptions for Initiators and Targets 4717 -M1: One or more of the following events was received: 4718 -initiator: 4719 -An internal event that indicates connection state 4720 timeout. 4721 -An internal event of receiving a successful Logout 4722 response on a different connection for a "close the 4723 session" Logout. 4724 -target: 4725 -An internal event that indicates connection state 4726 timeout. 4727 -An internal event of sending a Logout response (success) 4728 on a different connection for a "close the session" 4729 Logout request. 4731 -M2: An implicit/explicit logout process was initiated by the 4732 initiator. 4733 -In CSM-I usage: 4734 -initiator: An internal event requesting the connection 4735 (or session) reinstatement was received, thus prompting a 4736 connection (or session) reinstatement Login to be sent 4737 transitioning CSM-I to state IN_LOGIN. 4738 -target: A connection/session reinstatement Login was 4739 received while in state XPT_UP. 4740 -In CSM-E usage: 4741 -initiator: An internal event that indicates that an 4742 explicit logout was sent for this CID in state LOGGED_IN. 4743 -target: An explicit logout was received for this CID in 4744 state LOGGED_IN. 4745 -M3: Logout failure detected 4746 -In CSM-I usage: 4747 -initiator: CSM-I failed to reach LOGGED_IN and arrived 4748 into FREE instead. 4749 -target: CSM-I failed to reach LOGGED_IN and arrived into 4750 FREE instead. 4751 -In CSM-E usage: 4752 -initiator: CSM-E either moved out of LOGGED_IN, or Logout 4753 timed out and/or aborted, or Logout response (failure) 4754 was received. 4755 -target: CSM-E either moved out of LOGGED_IN, Logout 4756 timed out and/or aborted, or an internal event that 4757 indicates a failed Logout processing was received. A 4758 Logout response (failure) was sent in the last case. 4760 -M4: Successful implicit/explicit logout was performed. 4761 - In CSM-I usage: 4763 Julian Satran Expires August 2003 91 4764 iSCSI 19-January-03 4766 -initiator: CSM-I reached state LOGGED_IN, or an internal 4767 event of receiving a Logout response (success) on another 4768 connection for a "close the session" Logout request was 4769 received. 4770 -target: CSM-I reached state LOGGED_IN, or an internal 4771 event of sending a Logout response (success) on a 4772 different connection for a "close the session" Logout 4773 request was received. 4774 - In CSM-E usage: 4775 -initiator: CSM-E stayed in LOGGED_IN and received a 4776 Logout response (success), or an internal event of 4777 receiving a Logout response (success) on another 4778 connection for a "close the session" Logout request was 4779 received. 4780 -target: CSM-E stayed in LOGGED_IN and an internal event 4781 indicating a successful Logout processing was received, 4782 or an internal event of sending a Logout response 4783 (success) on a different connection for a "close the 4784 session" Logout request was received. 4786 7.3 Session State Diagrams 4788 7.3.1 Session State Diagram for an Initiator 4790 Symbolic Names for States: 4792 Q1: FREE 4793 Q3: LOGGED_IN 4794 Q4: FAILED 4795 State Q3 represents the Full Feature Phase operation of the session. 4797 The state diagram is as follows: 4799 ------- 4800 / Q1 4801 +------>\ /<-+ 4802 / ---+--- | 4803 / | |N3 4804 N6 | |N1 | 4805 | | | 4806 | N4 | | 4807 | +--------+ | / 4808 | | | | / 4809 | | | | / 4810 | | V V / 4811 -+--+-- -----+- 4812 / Q4 \ N5 / Q3 4813 \ /<---\ / 4814 ------- ------- 4816 The state transition table is as follows: 4818 Julian Satran Expires August 2003 92 4819 iSCSI 19-January-03 4821 +----+----+----+ 4822 |Q1 |Q3 |Q4 | 4823 -----+----+----+----+ 4824 Q1 | - |N1 | - | 4825 -----+----+----+----+ 4826 Q3 |N3 | - |N5 | 4827 -----+----+----+----+ 4828 Q4 |N6 |N4 | - | 4829 -----+----+----+----+ 4831 7.3.2 Session State Diagram for a Target 4833 Symbolic Names for States: 4835 Q1: FREE 4836 Q2: ACTIVE 4837 Q3: LOGGED_IN 4838 Q4: FAILED 4839 Q5: IN_CONTINUE 4841 State Q3 represents the Full Feature Phase operation of the session. 4843 The state diagram is as follows: 4845 ------- 4846 +------------------>/ Q1 4847 / +-------------->\ /<-+ 4848 | | ---+--- | 4849 | | ^ | |N3 4850 N6 | |N11 N9| V N1 | 4851 | | +------ | 4852 | | / Q2 \ | 4853 | | \ / | 4854 | --+---- +--+--- | 4855 | / Q5 \ | | 4856 | \ / N10 | | 4857 | +-+---+------------+ |N2 / 4858 | ^ | | | / 4859 |N7| |N8 | | / 4860 | | | | V / 4861 -+--+-V V----+- 4862 / Q4 \ N5 / Q3 4863 \ /<-------------\ / 4864 ------- ------- 4866 The state transition table is as follows: 4868 Julian Satran Expires August 2003 93 4869 iSCSI 19-January-03 4871 +----+----+----+----+----+ 4872 |Q1 |Q2 |Q3 |Q4 |Q5 | 4873 -----+----+----+----+----+----+ 4874 Q1 | - |N1 | - | - | - | 4875 -----+----+----+----+----+----+ 4876 Q2 |N9 | - |N2 | - | - | 4877 -----+----+----+----+----+----+ 4878 Q3 |N3 | - | - |N5 | - | 4879 -----+----+----+----+----+----+ 4880 Q4 |N6 | - | - | - |N7 | 4881 -----+----+----+----+----+----+ 4882 Q5 |N11 | - |N10 |N8 | - | 4883 -----+----+----+----+----+----+ 4885 7.3.3 State Descriptions for Initiators and Targets 4887 -Q1: FREE 4888 -initiator: State on instantiation or after cleanup. 4889 -target: State on instantiation or after cleanup. 4891 -Q2: ACTIVE 4892 -initiator: Illegal. 4893 -target: The first iSCSI connection in the session 4894 transitioned to IN_LOGIN, waiting for it to complete the 4895 login process. 4896 -Q3: LOGGED_IN 4897 -initiator: Waiting for all session events. 4898 -target: Waiting for all session events. 4900 -Q4: FAILED 4901 -initiator: Waiting for session recovery or session 4902 continuation. 4903 -target: Waiting for session recovery or session continuation. 4904 -Q5: IN_CONTINUE 4905 -initiator: Illegal. 4906 -target: Waiting for session continuation attempt to reach a 4907 conclusion. 4909 7.3.4 State Transition Descriptions for Initiators and Targets 4911 -N1: 4912 -initiator: At least one transport connection reached the 4913 LOGGED_IN state. 4914 -target: The first iSCSI connection in the session had reached 4915 the IN_LOGIN state. 4916 -N2: 4917 -initiator: Illegal. 4918 -target: At least one iSCSI connection reached the LOGGED_IN 4919 state. 4921 Julian Satran Expires August 2003 94 4922 iSCSI 19-January-03 4924 -N3: 4925 -initiator: Graceful closing of the session via session 4926 closure (Section 5.3.6 Session Continuation and Failure). 4927 -target: Graceful closing of the session via session closure 4928 (Section 5.3.6 Session Continuation and Failure) or a 4929 successful session reinstatement cleanly closed the session. 4930 -N4: 4931 -initiator: A session continuation attempt succeeded. 4932 -target: Illegal. 4934 -N5: 4935 -initiator: Session failure (Section 5.3.6 Session 4936 Continuation and Failure) occurred. 4937 -target: Session failure (Section 5.3.6 Session Continuation 4938 and Failure) occurred. 4939 -N6: 4940 -initiator: Session state timeout occurred, or a session 4941 reinstatement cleared this session instance. This results in 4942 the freeing of all associated resources and the session state 4943 is discarded. 4944 -target: Session state timeout occurred, or a session 4945 reinstatement cleared this session instance. This results in 4946 the freeing of all associated resources and the session state 4947 is discarded. 4949 -N7: 4950 -initiator: Illegal. 4951 -target: A session continuation attempt is initiated. 4953 -N8: 4954 -initiator: Illegal. 4955 -target: The last session continuation attempt failed. 4957 -N9: 4958 -initiator: Illegal. 4959 -target: Login attempt on the leading connection failed. 4961 -N10: 4962 -initiator: Illegal. 4963 -target: A session continuation attempt succeeded. 4965 -N11: 4966 -initiator: Illegal. 4967 -target: A successful session reinstatement cleanly closed the 4968 session. 4970 Julian Satran Expires August 2003 95 4971 iSCSI 19-January-03 4973 8. Security Considerations 4975 Historically, native storage systems have not had to consider 4976 security because their environments offered minimal security risks. 4977 That is, these environments consisted of storage devices either 4978 directly attached to hosts or connected via a Storage Area Network 4979 (SAN) distinctly separate from the communications network. The use 4980 of storage protocols, such as SCSI, over IP-networks requires that 4981 security concerns be addressed. iSCSI implementations MUST provide 4982 means of protection against active attacks (e.g., pretending to be 4983 another identity, message insertion, deletion, modification, and 4984 replaying) and passive attacks (e.g.,eavesdropping, gaining 4985 advantage by analyzing the data sent over the line). 4987 Although technically possible, iSCSI SHOULD NOT be configured 4988 without security. iSCSI configured without security should be 4989 confined, in extreme cases, to closed environments without any 4990 security risk. [SEC-IPS] specifies the mechanisms that must be used 4991 in order to mitigate risks fully described in that document. 4993 The following section describes the security mechanisms provided by 4994 an iSCSI implementation. 4996 8.1 iSCSI Security Mechanisms 4998 The entities involved in iSCSI security are the initiator, target, 4999 and the IP communication end points. iSCSI scenarios in which 5000 multiple initiators or targets share a single communication end 5001 point are expected. To accommodate such scenarios, iSCSI uses two 5002 separate security mechanisms: In-band authentication between the 5003 initiator and the target at the iSCSI connection level (carried out 5004 by exchange of iSCSI Login PDUs), and packet protection (integrity, 5005 authentication, and confidentiality) by IPsec at the IP level. The 5006 two security mechanisms complement each other. The in-band 5007 authentication provides end-to-end trust (at login time) between the 5008 iSCSI initiator and the target while IPsec provides a secure channel 5009 between the IP communication end points. 5011 Further details on typical iSCSI scenarios and the relation between 5012 the initiators, targets, and the communication end points can be 5013 found in [SEC-IPS]. 5015 8.2 In-band Initiator-Target Authentication 5017 During login, the target MUST authenticate the initiator and the 5018 initiator MAY authenticate the target. The authentication is 5019 performed on every new iSCSI connection by an exchange of iSCSI 5020 Login PDUs using a negotiated authentication method. 5022 The authentication method cannot assume an underlying IPsec 5023 protection, because IPsec is optional to use. An attacker should 5024 gain as little advantage as possible by inspecting the 5025 authentication phase PDUs. Therefore, a method using clear text (or 5026 equivalent) passwords is not acceptable; on the other hand, identity 5027 protection is not strictly required. 5029 Julian Satran Expires August 2003 96 5030 iSCSI 19-January-03 5032 The authentication mechanism protects against an unauthorized login 5033 to storage resources by using a false identity (spoofing). Once the 5034 authentication phase is completed, if the underlying IPsec is not 5035 used, all PDUs are sent and received in clear. The authentication 5036 mechanism alone (without underlying IPsec) should only be used when 5037 there is no risk of eavesdropping, message insertion, deletion, 5038 modification, and replaying. 5040 Section 11 iSCSI Security Text Keys and Authentication Methods 5041 defines several authentication methods and the exact steps that must 5042 be followed in each of them, including the iSCSI-text-keys and their 5043 allowed values in each step. Whenever an iSCSI initiator gets a 5044 response whose keys, or their values, are not according to the step 5045 definition, it MUST abort the connection. Whenever an iSCSI target 5046 gets a response whose keys, or their values, are not according to 5047 the step definition, it MUST answer with a Login reject with the 5048 "Initiator Error" or "Missing Parameter" status. These statuses are 5049 not intended for cryptographically incorrect values such as the CHAP 5050 response, for which "Authentication Failure" status MUST be 5051 specified. The importance of this rule can be illustrated in CHAP 5052 with target authentication (see Section 11.1.4 Challenge Handshake 5053 Authentication Protocol (CHAP)) where the initiator would have been 5054 able to conduct a reflection attack by omitting his response key 5055 (CHAP_R) using the same CHAP challenge as the target and reflecting 5056 the target's response back to the target. In CHAP, this is prevented 5057 because the target must answer the missing CHAP_R key with a Login 5058 reject with the "Missing Parameter" status. 5060 For some of the authentication methods, a key specifies the identity 5061 of the iSCSI initiator or target for authentication purposes. The 5062 value associated with that key MAY be different from the iSCSI name 5063 and SHOULD be configurable. (CHAP_N, see Section 11.1.4 Challenge 5064 Handshake Authentication Protocol (CHAP) and SRP_U, see Section 5065 11.1.3 Secure Remote Password (SRP)). 5067 8.2.1 CHAP Considerations 5069 Compliant iSCSI initiators and targets MUST implement the CHAP 5070 authentication method [RFC1994] (according to Section 11.1.4 5071 Challenge Handshake Authentication Protocol (CHAP) including the 5072 target authentication option). 5074 When CHAP is performed over a non-encrypted channel, it is 5075 vulnerable to an off-line dictionary attack. Implementations MUST 5076 support use of up to 128 bit random CHAP secrets, including the 5077 means to generate such secrets and to accept them from an external 5078 generation source. Implementations MUST NOT provide secret 5079 generation (or expansion) means other than random generation. 5081 An administrative entity of an environment in which CHAP is used 5082 with a secret that has less than 96 random bits MUST enforce IPsec 5083 encryption (according to the implementation requirements in Section 5084 8.3.2 Confidentiality) to protect the connection. Moreover, in this 5085 case IKE authentication with group pre-shared cryptographic keys 5087 Julian Satran Expires August 2003 97 5088 iSCSI 19-January-03 5090 SHOULD NOT be used unless it is not essential to protect group 5091 members against off-line dictionary attacks by other members. 5093 A compliant implementation SHOULD NOT continue with the login step 5094 in which it should send a CHAP response (CHAP_R, Section 11.1.4 5095 Challenge Handshake Authentication Protocol (CHAP)) unless it can 5096 verify that the CHAP secret is at least 96 bits, or that IPsec 5097 encryption is being used to protect the connection. 5099 Any CHAP secret used for initiator authentication MUST NOT be 5100 configured for authentication of any target, and any CHAP secret 5101 used for target authentication MUST NOT be configured for 5102 authentication of any initiator. If the CHAP response received by 5103 one end of an iSCSI connection is the same as the CHAP response that 5104 the receiving endpoint would have generated for the same CHAP 5105 challenge, the response MUST be treated as an authentication failure 5106 and cause the connection to close (this ensures that the same CHAP 5107 secret is not used for authentication in both directions). Also, if 5108 an iSCSI implementation can function as both initiator and target, 5109 different CHAP secrets and identities MUST be configured for these 5110 two roles. The following is an example of the attacks prevented by 5111 the above requirements: 5113 Rogue wants to impersonate Storage to Alice, and knows that a 5114 single secret is used for both directions of Storage-Alice 5115 authentication. 5117 Rogue convinces Alice to open two connections to Rogue, and 5118 Rogue identifies itself as Storage on both connections. 5120 Rogue issues a CHAP challenge on connection 1, waits for Alice 5121 to respond, and then reflects Alice's challenge as the initial 5122 challenge to Alice on connection 2. 5124 If Alice doesn't check for the reflection across connections, 5125 Alice's response on connection 2 enables Rogue to impersonate 5126 Storage on connection 1, even though Rogue does not know the 5127 Alice-Storage CHAP secret. 5129 Originators MUST NOT reuse the CHAP challenge sent by the Responder 5130 for the other direction of a bidirectional authentication. 5131 Responders MUST check for this condition and close the iSCSI TCP 5132 connection if it occurs. 5134 The same CHAP secret SHOULD NOT be configured for authentication of 5135 multiple initiators or multiple targets, as this enables any of them 5136 to impersonate any other one of them, and compromising one of them 5137 enables the attacker to impersonate any of them. It is recommended 5138 that iSCSI implementations check for use of identical CHAP secrets 5139 by different peers when this check is feasible, and take appropriate 5140 measures to warn users and/or administrators when this is detected. 5141 A single CHAP secret MAY be used for authentication of an individual 5142 initiator to multiple targets. Likewise, a single CHAP secret MAY be 5143 used for authentication of an individual target to multiple 5144 initiators. 5146 Julian Satran Expires August 2003 98 5147 iSCSI 19-January-03 5149 8.2.2 SRP Considerations 5151 The strength of the SRP authentication method (specified in 5152 [RFC2945]) is dependent on the characteristics of the group being 5153 used (i.e., the prime modulus N and generator g). As described in 5154 [RFC2945], N is required to be a Sophie-German prime (of the form N 5155 = 2q + 1, where q is also prime) and the generator g is a primitive 5156 root of GF(n). In iSCSI authentication, the prime modulus N MUST be 5157 at least 768 bits. 5159 The list of allowed SRP groups is provided in [SEC-IPS]. 5161 8.3 IPsec 5163 iSCSI uses the IPsec mechanism for packet protection (cryptographic 5164 integrity, authentication, and confidentiality) at the IP level 5165 between the iSCSI communicating end points. The following sections 5166 describe the IPsec protocols that must be implemented for data 5167 integrity and authentication, confidentiality, and cryptographic key 5168 management. 5170 An iSCSI initiator or target may provide the required IPsec support 5171 fully integrated or in conjunction with an IPsec front-end device. 5172 In the latter case, the compliance requirements with regard to IPsec 5173 support apply to the "combined device". Only the "combined device" 5174 is to be considered an iSCSI device. 5176 Detailed considerations and recommendations for using IPsec for 5177 iSCSI are provided in [SEC-IPS]. 5179 8.3.1 Data Integrity and Authentication 5181 Data authentication and integrity is provided by a cryptographic 5182 keyed Message Authentication Code in every sent packet. This code 5183 protects against message insertion, deletion, and modification. 5184 Protection against message replay is realized by using a sequence 5185 counter. 5187 An iSCSI compliant initiator or target MUST provide data integrity 5188 and authentication by implementing IPsec [RFC2401] with ESP 5189 [RFC2406] in tunnel mode and MAY provide data integrity and 5190 authentication by implementing IPsec with ESP in transport mode. The 5191 IPsec implementation MUST fulfill the following iSCSI specific 5192 requirements: 5194 - HMAC-SHA1 MUST be implemented [RFC2404]. 5195 - AES CBC MAC with XCBC extensions SHOULD be implemented 5196 [AESCBC]. 5198 The ESP anti-replay service MUST also be implemented. 5200 At the high speeds iSCSI is expected to operate, a single IPsec SA 5201 could rapidly cycle through the 32-bit IPsec sequence number space. 5202 In view of this, it may be desirable in the future for an iSCSI 5203 implementation that operates at speeds of 1 Gbps or greater to 5204 implement the IPsec sequence number extension [SEQ-EXT]. 5206 Julian Satran Expires August 2003 99 5207 iSCSI 19-January-03 5209 8.3.2 Confidentiality 5211 Confidentiality is provided by encrypting the data in every packet. 5212 When confidentiality is used it MUST be accompanied by data 5213 integrity and authentication to provide comprehensive protection 5214 against eavesdropping, message insertion, deletion, modification, 5215 and replaying. 5217 An iSCSI compliant initiator or target MUST provide confidentiality 5218 by implementing IPsec [RFC2401] with ESP [RFC2406] in tunnel mode 5219 and MAY provide confidentiality by implementing IPsec with ESP in 5220 transport mode, with the following iSCSI specific requirements: 5222 - 3DES in CBC mode MUST be implemented [RFC2451]. 5223 - AES in Counter mode SHOULD be implemented [AESCTR]. 5225 DES in CBC mode SHOULD NOT be used due to its inherent weakness. 5226 The NULL encryption algorithm MUST also be implemented. 5228 8.3.3 Policy, Security Associations, and Cryptographic Key Management 5230 A compliant iSCSI implementation MUST meet the cryptographic key 5231 management requirements of the IPsec protocol suite. Authentication, 5232 security association negotiation, and cryptographic key management 5233 MUST be provided by implementing IKE [RFC2409] using the IPsec DOI 5234 [RFC2407] with the following iSCSI specific requirements: 5236 - Peer authentication using a pre-shared cryptographic key MUST 5237 be supported. Certificate-based peer authentication using 5238 digital signatures MAY be supported. Peer authentication using 5239 the public key encryption methods outlined in IKE sections 5.2 5240 and 5.3[7] SHOULD NOT be used. 5242 - When digital signatures are used to achieve authentication, an 5243 IKE negotiator SHOULD use IKE Certificate Request Payload(s) 5244 to specify the certificate authority. IKE negotiators SHOULD 5245 check the pertinent Certificate Revocation List (CRL) before 5246 accepting a PKI certificate for use in IKE authentication 5247 procedures. 5249 - Conformant iSCSI implementations MUST support IKE Main Mode 5250 and SHOULD support Aggressive Mode. IKE main mode with pre- 5251 shared key authentication method SHOULD NOT be used when 5252 either the initiator or the target uses dynamically assigned 5253 IP addresses. While in many cases pre-shared keys offer good 5254 security, situations in which dynamically assigned addresses 5255 are used force the use of a group pre-shared key, which 5256 creates vulnerability to a man-in-the-middle attack. 5258 - In the IKE Phase 2 Quick Mode, exchanges for creating the 5259 Phase 2 SA, the Identity Payload, fields MUST be present. 5260 ID_IPV4_ADDR, ID_IPV6_ADDR (if the protocol stack supports 5261 IPv6) and ID_FQDN Identity payloads MUST be supported; 5262 ID_USER_FQDN SHOULD be supported. The IP Subnet, IP Address 5264 Julian Satran Expires August 2003 100 5265 iSCSI 19-January-03 5267 Range, ID_DER_ASN1_DN, and ID_DER_ASN1_GN formats SHOULD NOT 5268 be used. The ID_KEY_ID Identity Payload MUST NOT be used. 5270 Manual cryptographic keying MUST NOT be used because it does not 5271 provide the necessary re-keying support. 5273 When IPsec is used, the receipt of an IKE Phase 2 delete message 5274 SHOULD NOT be interpreted as a reason for tearing down the iSCSI TCP 5275 connection. If additional traffic is sent on it, a new IKE Phase 2 5276 SA will be created to protect it. 5278 The method used by the initiator to determine whether the target 5279 should be connected using IPsec is regarded as an issue of IPsec 5280 policy administration, and thus not defined in the iSCSI standard. 5282 If an iSCSI target is discovered via a SendTargets request in a 5283 discovery session not using IPsec, the initiator should assume that 5284 it does not need IPsec to establish a session to that target. If an 5285 iSCSI target is discovered using a discovery session that does use 5286 IPsec, the initiator SHOULD use IPsec when establishing a session to 5287 that target. 5289 Julian Satran Expires August 2003 101 5290 iSCSI 19-January-03 5292 9. Notes to Implementers 5294 This section notes some of the performance and reliability 5295 considerations of the iSCSI protocol. This protocol was designed to 5296 allow efficient silicon and software implementations. The iSCSI task 5297 tag mechanism was designed to enable Direct Data Placement (DDP - a 5298 DMA form) at the iSCSI level or lower. 5300 The guiding assumption made throughout the design of this protocol 5301 is that targets are resource constrained relative to initiators. 5303 Implementers are also advised to consider the implementation 5304 consequences of the iSCSI to SCSI mapping model as outlined in 5305 Section 3.4.3 Consequences of the Model. 5307 9.1 Multiple Network Adapters 5309 The iSCSI protocol allows multiple connections, not all of which 5310 need to go over the same network adapter. If multiple network 5311 connections are to be utilized with hardware support, the iSCSI 5312 protocol command-data-status allegiance to one TCP connection 5313 ensures that there is no need to replicate information across 5314 network adapters or otherwise require them to cooperate. 5316 However, some task management commands may require some loose form 5317 of cooperation or replication at least on the target. 5319 9.1.1 Conservative Reuse of ISIDs 5321 Historically, the SCSI model (and implementations and applications 5322 based on that model) has assumed that SCSI ports are static, 5323 physical entities. Recent extensions to the SCSI model have taken 5324 advantage of persistent worldwide unique names for these ports. In 5325 iSCSI however, the SCSI initiator ports are the endpoints of 5326 dynamically created sessions, so the presumptions of "static and 5327 physical" do not apply. In any case, the model clauses 5328 (particularly, Section 3.4.2 SCSI Architecture Model) provide for 5329 persistent, reusable names for the iSCSI-type SCSI initiator ports 5330 even though there does not need to be any physical entity bound to 5331 these names. 5333 To both minimize the disruption of legacy applications and to better 5334 facilitate the SCSI features that rely on persistent names for SCSI 5335 ports, iSCSI implementations SHOULD attempt to provide a stable 5336 presentation of SCSI Initiator Ports (both to the upper OS-layers 5337 and to the targets to which they connect). This can be achieved in 5338 an initiator implementation by conservatively reusing ISIDs. In 5339 other words, the same ISID should be used in the Login process to 5340 multiple target portal groups (of the same iSCSI Target or different 5341 iSCSI Targets). The ISID RULE (Section 3.4.3 Consequences of the 5342 Model) only prohibits reuse to the same target portal group. It does 5343 not "preclude" reuse to other target portal groups. 5344 The principle of conservative reuse "encourages" reuse to other 5345 target portal groups. When a SCSI target device sees the same 5346 (InitiatorName, ISID) pair in different sessions to different target 5347 portal groups, it can identify the underlying SCSI Initiator Port on 5349 Julian Satran Expires August 2003 102 5350 iSCSI 19-January-03 5352 each session as the same SCSI port. In effect, it can recognize 5353 multiple paths from the same source. 5355 9.1.2 iSCSI Name, ISID, and TPGT Use 5357 The designers of the iSCSI protocol envisioned there being one iSCSI 5358 Initiator Node Name per operating system image on a machine. This 5359 enables SAN resource configuration and authentication schemes based 5360 on a system's identity. It supports the notion that it should be 5361 possible to assign access to storage resources based on "initiator 5362 device" identity. 5364 When there are multiple hardware or software components coordinated 5365 as a single iSCSI Node, there must be some (logical) entity that 5366 represents the iSCSI Node that makes the iSCSI Node Name available 5367 to all components involved in session creation and login. Similarly, 5368 this entity that represents the iSCSI Node must be able to 5369 coordinate session identifier resources (ISID for initiators) to 5370 enforce both the ISID and TSIH RULES (see Section 3.4.3 Consequences 5371 of the Model). 5373 For targets, because of the closed environment, implementation of 5374 this entity should be straightforward. However, vendors of iSCSI 5375 hardware (e.g., NICs or HBAs) intended for targets, SHOULD provide 5376 mechanisms for configuration of the iSCSI Node Name across the 5377 portal groups instantiated by multiple instances of these components 5378 within a target. 5380 However, complex targets making use of multiple Target Portal Group 5381 Tags may reconfigure them to achieve various quality goals. The 5382 initiators have two mechanisms at their disposal to discover and/or 5383 check reconfiguring targets - the discovery session type and a key 5384 returned by the target during login to confirm the TPGT. An 5385 initiator should attempt to "rediscover" the target configuration 5386 anytime a session is terminated unexpectedly. 5388 For initiators, in the long term, it is expected that operating 5389 system vendors will take on the role of this entity and provide 5390 standard APIs that can inform components of their iSCSI Node Name 5391 and can configure and/or coordinate ISID allocation, use, and reuse. 5393 Recognizing that such initiator APIs are not available today, other 5394 implementations of the role of this entity are possible. For 5395 example, a human may instantiate the (common) Node name as part of 5396 the installation process of each iSCSI component involved in session 5397 creation and login. This may be done either by pointing the 5398 component to a vendor-specific location for this datum or to a 5399 system-wide location. The structure of the ISID namespace (see 5400 Section 10.12.5 ISID and [NDT]) facilitates implementation of the 5401 ISID coordination by allowing each component vendor to independently 5402 (of other vendor's components) coordinate allocation, use, and reuse 5403 of its own partition of the ISID namespace in a vendor-specific 5404 manner. Partitioning of the ISID namespace within initiator portal 5405 groups managed by that vendor allows each such initiator portal 5406 group to act independently of all other portal groups when selecting 5408 Julian Satran Expires August 2003 103 5409 iSCSI 19-January-03 5411 an ISID for a login; this facilitates enforcement of the ISID RULE 5412 (see Section 3.4.3 Consequences of the Model) at the initiator. 5414 A vendor of iSCSI hardware (e.g., NICs or HBAs) intended for use in 5415 initiators MUST implement a mechanism for configuring the iSCSI Node 5416 Name. Vendors, and administrators must ensure that iSCSI Node Names 5417 are unique worldwide. It is therefore important that when one 5418 chooses to reuse the iSCSI Node Name of a disabled unit, not to re- 5419 assign that name to the original unit unless its worldwide 5420 uniqueness can be ascertained again. 5422 In addition, a vendor of iSCSI hardware must implement a mechanism 5423 to configure and/or coordinate ISIDs for all sessions managed by 5424 multiple instances of that hardware within a given iSCSI Node. Such 5425 configuration might be either permanently pre-assigned at the 5426 factory (in a necessarily globally unique way), statically assigned 5427 (e.g., partitioned across all the NICs at initialization in a 5428 locally unique way), or dynamically assigned (e.g., on-line 5429 allocator, also in a locally unique way). In the latter two cases, 5430 the configuration may be via public APIs (perhaps driven by an 5431 independent vendor's software, such as the OS vendor) or via private 5432 APIs driven by the vendor's own software. 5434 9.2 Autosense and Auto Contingent Allegiance (ACA) 5436 Autosense refers to the automatic return of sense data to the 5437 initiator in case a command did not complete successfully. iSCSI 5438 initiators and targets MUST support and use autosense. 5440 ACA helps preserve ordered command execution in the presence of 5441 errors. As iSCSI can have many commands in-flight between initiator 5442 and target, iSCSI initiators and targets SHOULD support ACA. 5444 9.3 iSCSI Timeouts 5446 iSCSI recovery actions are often dependent on iSCSI time-outs being 5447 recognized and acted upon before SCSI time-outs. Determining the 5448 right time-outs to use for various iSCSI actions (command 5449 acknowledgements expected, status acknowledgements, etc.) is very 5450 much dependent on infrastructure (hardware, links, TCP/IP stack, 5451 iSCSI driver). As a guide, the implementer may use an average Nop- 5452 Out/Nop-In turnaround delay multiplied by a "safety factor" (e.g., 5453 4) as a good estimate for the basic delay of the iSCSI stack for a 5454 given connection. The safety factor should account for the network 5455 load variability. For connection teardown the implementer may want 5456 to consider also TCP common practice for the given infrastructure. 5458 Text negotiations MAY also be subject to either time-limits or 5459 limits in the number of exchanges. Those SHOULD be generous enough 5460 to avoid affecting interoperability (e.g., allowing each key to be 5461 negotiated on a separate exchange). 5463 The relation between iSCSI timeouts and SCSI timeouts should also be 5464 considered. SCSI timeouts should be longer than iSCSI timeouts plus 5465 the time required for iSCSI recovery whenever iSCSI recovery is 5466 planned. Alternatively, an implementer may choose to interlock iSCSI 5468 Julian Satran Expires August 2003 104 5469 iSCSI 19-January-03 5471 timeouts and recovery with SCSI timeouts so that SCSI recovery will 5472 become active only where iSCSI is not planned to, or failed to, 5473 recover. 5475 The implementer may also want to consider the interaction between 5476 various iSCSI exception events - such as a digest failure - and 5477 subsequent timeouts. When iSCSI error recovery is active, a digest 5478 failure is likely to result in discovering a missing command or data 5479 PDU. In these cases, an implementer may want to lower the timeout 5480 values to enable faster initiation for recovery procedures. 5482 9.4 Command Retry and Cleaning Old Command Instances 5484 To avoid having old, retried command instances appear in a valid 5485 command window after a command sequence number wrap around, the 5486 protocol requires (see Section 3.2.2.1 Command Numbering and 5487 Acknowledging) that on every connection on which a retry has been 5488 issued, a non-immediate command be issued and acknowledged within a 5489 2**31-1 commands interval from the CmdSN of the retried command. 5490 This requirement can be fulfilled by an implementation in several 5491 ways. 5493 The simplest technique to use is to send a (non-retry) non-immediate 5494 SCSI command (or a NOP if no SCSI command is available for a while) 5495 after every command retry on the connection on which the retry was 5496 attempted. As errors are deemed rare events, this technique is 5497 probably the most effective, as it does not involve additional 5498 checks at the initiator when issuing commands. 5500 9.5 Synch and Steering Layer and Performance 5502 While a synch and steering layer is optional, an initiator/target 5503 that does not have it working against a target/initiator that 5504 demands synch and steering may experience performance degradation 5505 caused by packet reordering and loss. Providing a synch and steering 5506 mechanism is recommended for all high-speed implementations. 5508 9.6 Considerations for State-dependent Devices and Long-lasting SCSI 5509 Operations 5511 Sequential access devices operate on the principle that the position 5512 of the device is based on the last command processed. As such, 5513 command processing order and knowledge of whether or not the 5514 previous command was processed is of the utmost importance to 5515 maintain data integrity. For example, inadvertent retries of SCSI 5516 commands when it is not known if the previous SCSI command was 5517 processed is a potential data integrity risk. 5519 For a sequential access device, consider the scenario in which a 5520 SCSI SPACE command to backspace one filemark is issued and then re- 5521 issued due to no status received for the command. If the first SPACE 5522 command was actually processed, the re-issued SPACE command, if 5523 processed, will cause the position to change. Thus, a subsequent 5524 write operation will write data to the wrong position and any 5525 previous data at that position will be overwritten. 5527 Julian Satran Expires August 2003 105 5528 iSCSI 19-January-03 5530 For a medium changer device, consider the scenario in which an 5531 EXCHANGE MEDIUM command (the SOURCE ADDRESS and DESTINATION ADDRESS 5532 are the same thus performing a swap) is issued and then re-issued 5533 due to no status received for the command. If the first EXCHANGE 5534 MEDIUM command was actually processed, the re-issued EXCHANGE MEDIUM 5535 command, if processed, will perform the swap again. The net effect 5536 is no swap was performed thus leaving a data integrity exposure. 5538 All commands that change the state of the device (as in SPACE 5539 commands for sequential access devices, and EXCHANGE MEDIUM for 5540 medium changer device), MUST be issued as non-immediate commands for 5541 deterministic and in order delivery to iSCSI targets. 5543 For many of those state changing commands, the execution model also 5544 assumes that the command is executed exactly once. Devices 5545 implementing READ POSITION and LOCATE provide a means for SCSI level 5546 command recovery and new tape-class devices should support those 5547 commands. In their absence a retry at SCSI level is difficult and 5548 error recovery at iSCSI level is advisable. 5550 Devices operating on long latency delivery subsystems and performing 5551 long lasting SCSI operations may need mechanisms that enable 5552 connection replacement while commands are running (e.g., during an 5553 extended copy operation). 5555 9.6.1 Determining the Proper ErrorRecoveryLevel 5557 The implementation and use of a specific ErrorRecoveryLevel should 5558 be determined based on the deployment scenarios of a given iSCSI 5559 implementation. Generally, the following factors must be 5560 considered before deciding on the proper level of recovery: 5562 a) Application resilience to I/O failures. 5563 b) Required level of availability in the face of transport 5564 connection failures. 5565 c) Probability of transport layer "checksum escape". This in 5566 turn decides the iSCSI digest failure frequency, and thus the 5567 criticality of iSCSI-level error recovery. The details of 5568 estimating this probability are outside the scope of this 5569 document. 5571 A consideration of the above factors for SCSI tape devices as an 5572 example suggests that implementations SHOULD use 5573 ErrorRecoveryLevel=1 when transport connection failure is not a 5574 concern and SCSI level recovery is unavailable, and 5575 ErrorRecoveryLevel=2 when the connection failure is also of high 5576 likelihood during a backup/retrieval. 5578 For extended copy operations, implementations SHOULD use 5579 ErrorRecoveryLevel=2 whenever there is a relatively high likelihood 5580 of connection failure. 5582 Julian Satran Expires August 2003 106 5583 iSCSI 19-January-03 5585 10. iSCSI PDU Formats 5587 All multi-byte integers that are specified in formats defined in 5588 this document are to be represented in network byte order (i.e., big 5589 endian). Any field that appears in this document assumes that the 5590 most significant byte is the lowest numbered byte and the most 5591 significant bit (within byte or field) is the lowest numbered bit 5592 unless specified otherwise. 5594 Any compliant sender MUST set all bits not defined and all reserved 5595 fields to zero unless specified otherwise. Any compliant receiver 5596 MUST ignore any bit not defined and all reserved fields unless 5597 specified otherwise. Receipt of reserved code values in defined 5598 fields MUST be reported as a protocol error. 5600 Reserved fields are marked by the word "reserved", some abbreviation 5601 of "reserved", or by "." for individual bits when no other form of 5602 marking is technically feasible. 5604 10.1 iSCSI PDU Length and Padding 5606 iSCSI PDUs are padded to the closest integer number of four byte 5607 words. The padding bytes SHOULD be sent as 0. 5609 10.2 PDU Template, Header, and Opcodes 5611 All iSCSI PDUs have one or more header segments and, optionally, a 5612 data segment. After the entire header segment group a header-digest 5613 MAY follow. The data segment MAY also be followed by a data-digest. 5615 The Basic Header Segment (BHS) is the first segment in all of the 5616 iSCSI PDUs. The BHS is a fixed-length 48-byte header segment. It MAY 5617 be followed by Additional Header Segments (AHS), a Header-Digest, a 5618 Data Segment, and/or a Data-Digest. 5620 The overall structure of an iSCSI PDU is as follows: 5622 Byte/ 0 | 1 | 2 | 3 | 5623 / | | | | 5624 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5625 +---------------+---------------+---------------+---------------+ 5626 0/ Basic Header Segment (BHS) / 5627 +/ / 5628 +---------------+---------------+---------------+---------------+ 5629 48/ Additional Header Segment 1 (AHS) (optional) / 5630 +/ / 5631 +---------------+---------------+---------------+---------------+ 5632 / Additional Header Segment 2 (AHS) (optional) / 5633 +/ / 5634 +---------------+---------------+---------------+---------------+ 5635 ---- 5636 +---------------+---------------+---------------+---------------+ 5637 / Additional Header Segment n (AHS) (optional) / 5638 +/ / 5639 +---------------+---------------+---------------+---------------+ 5641 Julian Satran Expires August 2003 107 5642 iSCSI 19-January-03 5644 ---- 5645 +---------------+---------------+---------------+---------------+ 5646 k/ Header-Digest (optional) / 5647 +/ / 5648 +---------------+---------------+---------------+---------------+ 5649 l/ Data Segment(optional) / 5650 +/ / 5651 +---------------+---------------+---------------+---------------+ 5652 m/ Data-Digest (optional) / 5653 +/ / 5654 +---------------+---------------+---------------+---------------+ 5656 All PDU segments and digests are padded to the closest integer 5657 number of four byte words. For example, all PDU segments and digests 5658 start at a four byte word boundary and the padding ranges from 0 to 5659 3 bytes. The padding bytes SHOULD be sent as 0. 5661 iSCSI response PDUs do not have AH Segments. 5663 10.2.1 Basic Header Segment (BHS) 5665 The BHS is 48 bytes long. The Opcode and DataSegmentLength fields 5666 appear in all iSCSI PDUs. In addition, when used, the Initiator Task 5667 Tag and Logical Unit Number always appear in the same location in 5668 the header. 5670 The format of the BHS is: 5672 Byte/ 0 | 1 | 2 | 3 | 5673 / | | | | 5674 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5675 +---------------+---------------+---------------+---------------+ 5676 0|.|I| Opcode |F| Opcode-specific fields | 5677 +---------------+---------------+---------------+---------------+ 5678 4|TotalAHSLength | DataSegmentLength | 5679 +---------------+---------------+---------------+---------------+ 5680 8| LUN or Opcode-specific fields | 5681 + + 5682 12| | 5683 +---------------+---------------+---------------+---------------+ 5684 16| Initiator Task Tag | 5685 +---------------+---------------+---------------+---------------+ 5686 20/ Opcode-specific fields / 5687 +/ / 5688 +---------------+---------------+---------------+---------------+ 5689 48 5691 10.2.1.1 I 5693 For request PDUs, the I bit set to 1 is an immediate delivery 5694 marker. 5696 10.2.1.2 Opcode 5698 The Opcode indicates the type of iSCSI PDU the header encapsulates. 5700 Julian Satran Expires August 2003 108 5701 iSCSI 19-January-03 5703 The Opcodes are divided into two categories: initiator opcodes and 5704 target opcodes. Initiator opcodes are in PDUs sent by the initiator 5705 (request PDUs). Target opcodes are in PDUs sent by the target 5706 (response PDUs). 5708 Initiators MUST NOT use target opcodes and targets MUST NOT use 5709 initiator opcodes. 5711 Initiator opcodes defined in this specification are: 5713 0x00 NOP-Out 5714 0x01 SCSI Command (encapsulates a SCSI Command Descriptor Block) 5715 0x02 SCSI Task Management function request 5716 0x03 Login Request 5717 0x04 Text Request 5718 0x05 SCSI Data-out (for WRITE operations) 5719 0x06 Logout Request 5720 0x10 SNACK Request 5721 0x1c-0x1e Vendor specific codes 5723 Target opcodes are: 5725 0x20 NOP-In 5726 0x21 SCSI Response - contains SCSI status and possibly sense 5727 information or other response information. 5728 0x22 SCSI Task Management function response 5729 0x23 Login Response 5730 0x24 Text Response 5731 0x25 SCSI Data-in - for READ operations. 5732 0x26 Logout Response 5733 0x31 Ready To Transfer (R2T) - sent by target when it is ready 5734 to receive data. 5735 0x32 Asynchronous Message - sent by target to indicate certain 5736 special conditions. 5737 0x3c-0x3e Vendor specific codes 5738 0x3f Reject 5740 All other opcodes are reserved. 5742 10.2.1.3 Final (F) bit 5744 When set to 1 it indicates the final (or only) PDU of a sequence. 5746 10.2.1.4 Opcode-specific Fields 5748 These fields have different meanings for different opcode types. 5750 10.2.1.5 TotalAHSLength 5752 Total length of all AHS header segments in units of four byte words 5753 including padding, if any. 5755 Julian Satran Expires August 2003 109 5756 iSCSI 19-January-03 5758 The TotalAHSLength is only used in PDUs that have an AHS and MUST be 5759 0 in all other PDUs. 5761 10.2.1.6 DataSegmentLength 5763 This is the data segment payload length in bytes (excluding 5764 padding). The DataSegmentLength MUST be 0 whenever the PDU has no 5765 data segment. 5767 10.2.1.7 LUN 5769 Some opcodes operate on a specific Logical Unit. The Logical Unit 5770 Number (LUN) field identifies which Logical Unit. If the opcode does 5771 not relate to a Logical Unit, this field is either ignored or may be 5772 used in an opcode specific way. The LUN field is 64-bits and should 5773 be formatted in accordance with [SAM2]. For example, LUN[0] from 5774 [SAM2] is BHS byte 8 and so on up to LUN[7] from [SAM2], which is 5775 BHS byte 15. 5777 10.2.1.8 Initiator Task Tag 5779 The initiator assigns a Task Tag to each iSCSI task it issues. While 5780 a task exists, this tag MUST uniquely identify the task session- 5781 wide. 5782 SCSI may also use the initiator task tag as part of the SCSI task 5783 identifier when the timespan during which an iSCSI initiator task 5784 tag must be unique extends over the timespan during which a SCSI 5785 task tag must be unique. However, the iSCSI Initiator Task Tag must 5786 exist and be unique even for untagged SCSI commands. 5788 10.2.2 Additional Header Segment (AHS) 5790 The general format of an AHS is: 5792 Byte/ 0 | 1 | 2 | 3 | 5793 / | | | | 5794 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5795 +---------------+---------------+---------------+---------------+ 5796 0| AHSLength | AHSType | AHS-Specific | 5797 +---------------+---------------+---------------+---------------+ 5798 4/ AHS-Specific / 5799 +/ / 5800 +---------------+---------------+---------------+---------------+ 5801 x 5803 10.2.2.1 AHSType 5805 The AHSType field is coded as follows: 5807 bit 0-1 - Reserved 5809 bit 2-7 - AHS code 5811 0 - Reserved 5812 1 - Extended CDB 5813 2 - Expected Bidirectional Read Data Length 5815 Julian Satran Expires August 2003 110 5816 iSCSI 19-January-03 5818 3 - 63 Reserved 5820 10.2.2.2 AHSLength 5822 This field contains the effective length in bytes of the AHS 5823 excluding AHSType and AHSLength and padding, if any. The AHS is 5824 padded to the smallest integer number of 4 byte words (i.e., from 0 5825 up to 3 padding bytes). 5827 10.2.2.3 Extended CDB AHS 5829 The format of the Extended CDB AHS is: 5831 Byte/ 0 | 1 | 2 | 3 | 5832 / | | | | 5833 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5834 +---------------+---------------+---------------+---------------+ 5835 0| AHSLength (CDBLength-15) | 0x01 | Reserved | 5836 +---------------+---------------+---------------+---------------+ 5837 4/ ExtendedCDB...+padding / 5838 +/ / 5839 +---------------+---------------+---------------+---------------+ 5840 x 5842 This type of AHS MUST NOT be used if the CDBLength is less than 17. 5843 The length includes the reserved byte 3. 5845 10.2.2.4 Bidirectional Expected Read-Data Length AHS 5847 The format of the Bidirectional Read Expected Data Transfer Length 5848 AHS is: 5850 Byte/ 0 | 1 | 2 | 3 | 5851 / | | | | 5852 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5853 +---------------+---------------+---------------+---------------+ 5854 0| AHSLength (0x0005) | 0x02 | Reserved | 5855 +---------------+---------------+---------------+---------------+ 5856 4| Expected Read-Data Length | 5857 +---------------+---------------+---------------+---------------+ 5858 8 5860 10.2.3 Header Digest and Data Digest 5862 Optional header and data digests protect the integrity of the header 5863 and data, respectively. The digests, if present, are located, 5864 respectively, after the header and PDU-specific data, and cover the 5865 proper data and the padding bytes. 5867 The existence and type of digests are negotiated during the Login 5868 Phase. 5870 The separation of the header and data digests is useful in iSCSI 5871 routing applications, in which only the header changes when a 5873 Julian Satran Expires August 2003 111 5874 iSCSI 19-January-03 5876 message is forwarded. In this case, only the header digest should be 5877 recalculated. 5879 Digests are not included in data or header length fields. 5881 A zero-length Data Segment also implies a zero-length data-digest. 5883 10.2.4 Data Segment 5885 The (optional) Data Segment contains PDU associated data. Its 5886 payload effective length is provided in the BHS field - 5887 DataSegmentLength. The Data Segment is also padded to an integer 5888 number of 4 byte words. 5890 Julian Satran Expires August 2003 112 5891 iSCSI 19-January-03 5893 10.3 SCSI Command 5895 The format of the SCSI Command PDU is: 5897 Byte/ 0 | 1 | 2 | 3 | 5898 / | | | | 5899 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 5900 +---------------+---------------+---------------+---------------+ 5901 0|.|I| 0x01 |F|R|W|. .|ATTR | Reserved | 5902 +---------------+---------------+---------------+---------------+ 5903 4|TotalAHSLength | DataSegmentLength | 5904 +---------------+---------------+---------------+---------------+ 5905 8| Logical Unit Number (LUN) | 5906 + + 5907 12| | 5908 +---------------+---------------+---------------+---------------+ 5909 16| Initiator Task Tag | 5910 +---------------+---------------+---------------+---------------+ 5911 20| Expected Data Transfer Length | 5912 +---------------+---------------+---------------+---------------+ 5913 24| CmdSN | 5914 +---------------+---------------+---------------+---------------+ 5915 28| ExpStatSN | 5916 +---------------+---------------+---------------+---------------+ 5917 32/ SCSI Command Descriptor Block (CDB) / 5918 +/ / 5919 +---------------+---------------+---------------+---------------+ 5920 48/ AHS (Optional) / 5921 +---------------+---------------+---------------+---------------+ 5922 x/ Header Digest (Optional) / 5923 +---------------+---------------+---------------+---------------+ 5924 y/ (DataSegment, Command Data) (Optional) / 5925 +/ / 5926 +---------------+---------------+---------------+---------------+ 5927 z/ Data Digest (Optional) / 5928 +---------------+---------------+---------------+---------------+ 5930 10.3.1 Flags and Task Attributes (byte 1) 5932 The flags for a SCSI Command are: 5934 bit 0 (F) is set to 1 when no unsolicited SCSI Data-Out PDUs 5935 follow this PDU. When F=1 for a write and if Expected Data 5936 Transfer Length is larger than the DataSegmentLength, the 5937 target may solicit additional data through R2T. 5939 bit 1 (R) is set to 1 when the command is expected to input 5940 data. 5942 bit 2 (W) is set to 1 when the command is expected to output 5943 data. 5945 bit 3-4 Reserved. 5947 bit 5-7 contains Task Attributes. 5949 Julian Satran Expires August 2003 113 5950 iSCSI 19-January-03 5952 Task Attributes (ATTR) have one of the following integer values (see 5953 [SAM2] for details): 5955 0 - Untagged 5956 1 - Simple 5957 2 - Ordered 5958 3 - Head of Queue 5959 4 - ACA 5960 5-7 - Reserved 5962 Setting both the W and the F bit to 0 is an error. 5963 Either or both of R and W MAY be 1 when either the Expected Data 5964 Transfer Length and/or Bidirectional Read Expected Data Transfer 5965 Length are 0, but they MUST NOT both be 0 when the Expected Data 5966 Transfer Length and/or Bidirectional Read Expected Data Transfer 5967 Length are not 0 (i.e., when some data transfer is expected the 5968 transfer direction is indicated by the R and/or W bit). 5970 10.3.2 CmdSN - Command Sequence Number 5972 Enables ordered delivery across multiple connections in a single 5973 session. 5975 10.3.3 ExpStatSN 5977 Command responses up to ExpStatSN-1 (mod 2**32) have been received 5978 (acknowledges status) on the connection. 5980 10.3.4 Expected Data Transfer Length 5982 For unidirectional operations, the Expected Data Transfer Length 5983 field contains the number of bytes of data involved in this SCSI 5984 operation. For a unidirectional write operation (W flag set to 1 and 5985 R flag set to 0), the initiator uses this field to specify the 5986 number of bytes of data it expects to transfer for this operation. 5987 For a unidirectional read operation (W flag set to 0 and R flag set 5988 to 1), the initiator uses this field to specify the number of bytes 5989 of data it expects the target to transfer to the initiator. It 5990 corresponds to the SAM2 byte count. 5992 For bidirectional operations (both R and W flags are set to 1), this 5993 field contains the number of data bytes involved in the write 5994 transfer. For bidirectional operations, an additional header segment 5995 MUST be present in the header sequence that indicates the 5996 Bidirectional Read Expected Data Transfer Length. The Expected Data 5997 Transfer Length field and the Bidirectional Read Expected Data 5998 Transfer Length field correspond to the SAM2 byte count 6000 If the Expected Data Transfer Length for a write and the length of 6001 the immediate data part that follows the command (if any) are the 6002 same, then no more data PDUs are expected to follow. In this case, 6003 the F bit MUST be set to 1. 6005 If the Expected Data Transfer Length is higher than the 6006 FirstBurstLength (the negotiated maximum amount of unsolicited data 6008 Julian Satran Expires August 2003 114 6009 iSCSI 19-January-03 6011 the target will accept), the initiator MUST send the maximum amount 6012 of unsolicited data OR ONLY the immediate data, if any. 6014 Upon completion of a data transfer, the target informs the initiator 6015 (through residual counts) of how many bytes were actually processed 6016 (sent and/or received) by the target. 6018 10.3.5 CDB - SCSI Command Descriptor Block 6020 There are 16 bytes in the CDB field to accommodate the commonly used 6021 CDBs. Whenever the CDB is larger than 16 bytes, an Extended CDB AHS 6022 MUST be used to contain the CDB spillover. 6024 10.3.6 Data Segment - Command Data 6026 Some SCSI commands require additional parameter data to accompany 6027 the SCSI command. This data may be placed beyond the boundary of the 6028 iSCSI header in a data segment. Alternatively, user data (e.g., 6029 from a WRITE operation) can be placed in the data segment (both 6030 cases are referred to as immediate data). These data are governed by 6031 the rules for solicited vs. unsolicited data outlined in Section 6032 3.2.4.2 Data Transfer Overview. 6034 Julian Satran Expires August 2003 115 6035 iSCSI 19-January-03 6037 10.4 SCSI Response 6039 The format of the SCSI Response PDU is: 6041 Byte/ 0 | 1 | 2 | 3 | 6042 / | | | | 6043 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6044 +---------------+---------------+---------------+---------------+ 6045 0|.|.| 0x21 |1|. .|o|u|O|U|.| Response | Status | 6046 +---------------+---------------+---------------+---------------+ 6047 4|TotalAHSLength | DataSegmentLength | 6048 +---------------+---------------+---------------+---------------+ 6049 8| Reserved | 6050 + + 6051 12| | 6052 +---------------+---------------+---------------+---------------+ 6053 16| Initiator Task Tag | 6054 +---------------+---------------+---------------+---------------+ 6055 20| SNACK Tag or Reserved | 6056 +---------------+---------------+---------------+---------------+ 6057 24| StatSN | 6058 +---------------+---------------+---------------+---------------+ 6059 28| ExpCmdSN | 6060 +---------------+---------------+---------------+---------------+ 6061 32| MaxCmdSN | 6062 +---------------+---------------+---------------+---------------+ 6063 36| ExpDataSN or Reserved | 6064 +---------------+---------------+---------------+---------------+ 6065 40| Bidirectional Read Residual Count or Reserved | 6066 +---------------+---------------+---------------+---------------+ 6067 44| Residual Count or Reserved | 6068 +---------------+---------------+---------------+---------------+ 6069 48| Header-Digest (Optional) | 6070 +---------------+---------------+---------------+---------------+ 6071 / Data Segment (Optional) / 6072 +/ / 6073 +---------------+---------------+---------------+---------------+ 6074 | Data-Digest (Optional) | 6075 +---------------+---------------+---------------+---------------+ 6077 10.4.1 Flags (byte 1) 6079 bit 1-2 Reserved. 6081 bit 3 - (o) set for Bidirectional Read Residual Overflow. In 6082 this case, the Bidirectional Read Residual Count indicates the 6083 number of bytes that were not transferred to the initiator 6084 because the initiator's Expected Bidirectional Read Data 6085 Transfer Length was not sufficient. 6087 bit 4 - (u) set for Bidirectional Read Residual Underflow. In 6088 this case, the Bidirectional Read Residual Count indicates the 6089 number of bytes that were not transferred to the initiator out 6090 of the number of bytes expected to be transferred. 6092 Julian Satran Expires August 2003 116 6093 iSCSI 19-January-03 6095 bit 5 - (O) set for Residual Overflow. In this case, the 6096 Residual Count indicates the number of bytes that were not 6097 transferred because the initiator's Expected Data Transfer 6098 Length was not sufficient. For a bidirectional operation, the 6099 Residual Count contains the residual for the write operation. 6101 bit 6 - (U) set for Residual Underflow. In this case, the 6102 Residual Count indicates the number of bytes that were not 6103 transferred out of the number of bytes that were expected to 6104 be transferred. For a bidirectional operation, the Residual 6105 Count contains the residual for the write operation. 6107 bit 7 - (0) Reserved. 6109 Bits O and U and bits o and u are mutually exclusive (i.e., having 6110 both o and u or O and U set to 1 is a protocol error). 6111 For a response other than "Command Completed at Target", bits 3-6 6112 MUST be 0. 6114 10.4.2 Status 6116 The Status field is used to report the SCSI status of the command 6117 (as specified in [SAM2]) and is only valid if the Response Code is 6118 Command Completed at target. 6120 Some of the status codes defined in [SAM2] are: 6122 0x00 GOOD 6123 0x02 CHECK CONDITION 6124 0x08 BUSY 6125 0x18 RESERVATION CONFLICT 6126 0x28 TASK SET FULL 6127 0x30 ACA ACTIVE 6128 0x40 TASK ABORTED 6130 See [SAM2] for the complete list and definitions. 6132 If a SCSI device error is detected while data from the initiator is 6133 still expected (the command PDU did not contain all the data and the 6134 target has not received a Data PDU with the final bit Set), the 6135 target MUST wait until it receives a Data PDU with the F bit set in 6136 the last expected sequence before sending the Response PDU. 6138 10.4.3 Response 6140 This field contains the iSCSI service response. 6142 iSCSI service response codes defined in this specification are: 6144 0x00 - Command Completed at Target 6145 0x01 - Target Failure 6146 0x80-0xff - Vendor specific 6148 All other response codes are reserved. 6150 Julian Satran Expires August 2003 117 6151 iSCSI 19-January-03 6153 The Response is used to report a Service Response. The mapping of 6154 the response code into a SCSI service response code value, if 6155 needed, is outside the scope of this document. However, in symbolic 6156 terms response value 0x00 maps to the SCSI service response (see 6157 [SAM2] and [SPC3]) of TASK COMPLETE or LINKED COMMAND COMPLETE. All 6158 other Response values map to the SCSI service response of SERVICE 6159 DELIVERY OR TARGET FAILURE. 6161 If a SCSI Response PDU does not arrive before the session is 6162 terminated, the SCSI service response is SERVICE DELIVERY OR TARGET 6163 FAILURE. 6165 A non-zero response field indicates a failure to execute the command 6166 in which case the Status and Sense fields are undefined. 6168 10.4.4 SNACK Tag 6170 This field contains a copy of the SNACK Tag of the last SNACK Tag 6171 accepted by the target on the same connection and for the command 6172 for which the response is issued. Otherwise it is reserved and 6173 should be set to 0. 6175 After issuing a R-Data SNACK the initiator must discard any SCSI 6176 status unless contained in an SCSI Response PDU carrying the same 6177 SNACK Tag as the last issued R-Data SNACK for the SCSI command on 6178 the current connection. 6180 For a detailed discussion on R-Data SNACK see Section 10.16 SNACK 6181 Request. 6183 10.4.5 Residual Count 6185 The Residual Count field MUST be valid in the case where either the 6186 U bit or the O bit is set. If neither bit is set, the Residual Count 6187 field is reserved. Targets may set the residual count and initiators 6188 may use it when the response code is "completed at target" (even if 6189 the status returned is not GOOD). If the O bit is set, the Residual 6190 Count indicates the number of bytes that were not transferred 6191 because the initiator's Expected Data Transfer Length was not 6192 sufficient. If the U bit is set, the Residual Count indicates the 6193 number of bytes that were not transferred out of the number of bytes 6194 expected to be transferred. 6196 10.4.6 Bidirectional Read Residual Count 6198 The Bidirectional Read Residual Count field MUST be valid in the 6199 case where either the u bit or the o bit is set. If neither bit is 6200 set, the Bidirectional Read Residual Count field is reserved. 6201 Targets may set the Bidirectional Read Residual Count and initiators 6202 may use it when the response code is "completed at target". If the o 6203 bit is set, the Bidirectional Read Residual Count indicates the 6204 number of bytes that were not transferred to the initiator because 6205 the initiator's Expected Bidirectional Read Transfer Length was not 6206 sufficient. If the u bit is set, the Bidirectional Read Residual 6207 Count indicates the number of bytes that were not transferred to the 6208 initiator out of the number of bytes expected to be transferred. 6210 Julian Satran Expires August 2003 118 6211 iSCSI 19-January-03 6213 10.4.7 Data Segment - Sense and Response Data Segment 6215 iSCSI targets MUST support and enable autosense. If Status is CHECK 6216 CONDITION (0x02), then the Data Segment MUST contain sense data for 6217 the failed command. 6219 For some iSCSI responses, the response data segment MAY contain some 6220 response related information, (e.g., for a target failure, it may 6221 contain a vendor specific detailed description of the failure). 6223 If the DataSegmentLength is not 0, the format of the Data Segment is 6224 as follows: 6225 Byte/ 0 | 1 | 2 | 3 | 6226 / | | | | 6227 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6228 +---------------+---------------+---------------+---------------+ 6229 0|SenseLength | Sense Data | 6230 +---------------+---------------+---------------+---------------+ 6231 x/ Sense Data / 6232 +---------------+---------------+---------------+---------------+ 6233 y/ Response Data / 6234 / / 6235 +---------------+---------------+---------------+---------------+ 6236 z| 6238 10.4.7.1 SenseLength 6240 Length of Sense Data. 6242 10.4.7.2 Sense Data 6244 The Sense Data contains detailed information about a check condition 6245 and [SPC3] specifies the format and content of the Sense Data. 6247 Certain iSCSI conditions result in the command being terminated at 6248 the target (response Command Completed at Target) with a SCSI Check 6249 Condition Status as outlined in the next table: 6251 +--------------------------+----------+---------------------------+ 6252 | iSCSI Condition |Sense | Additional Sense Code & | 6253 | |Key | Qualifier | 6254 +--------------------------+----------+---------------------------+ 6255 | Unexpected unsolicited |Aborted | ASC = 0x0c ASCQ = 0x0c | 6256 | data |Command-0B| Write Error | 6257 +--------------------------+----------+---------------------------+ 6258 | Incorrect amount of data |Aborted | ASC = 0x0c ASCQ = 0x0d | 6259 | |Command-0B| Write Error | 6260 +--------------------------+----------+---------------------------+ 6261 | Protocol Service CRC |Aborted | ASC = 0x47 ASCQ = 0x05 | 6262 | error |Command-0B| CRC Error Detected | 6263 +--------------------------+----------+---------------------------+ 6264 | SNACK rejected |Aborted | ASC = 0x11 ASCQ = 0x13 | 6265 | |Command-0B| Read Error | 6266 +--------------------------+----------+---------------------------+ 6268 Julian Satran Expires August 2003 119 6269 iSCSI 19-January-03 6271 The target reports the "Incorrect amount of data" condition if 6272 during data output the total data length to output is greater than 6273 FirstBurstLength and the initiator sent unsolicited non-immediate 6274 data but the total amount of unsolicited data is different than 6275 FirstBurstLength. The target reports the same error when the amount 6276 of data sent as a reply to an R2T does not match the amount 6277 requested. 6279 10.4.8 ExpDataSN 6281 The number of Data-In (read) PDUs the target has sent for the 6282 command. 6284 This field is reserved if the response code is not Command Completed 6285 at Target or the command is a write command. 6287 10.4.9 StatSN - Status Sequence Number 6289 StatSN is a Sequence Number that the target iSCSI layer generates 6290 per connection and that in turn, enables the initiator to 6291 acknowledge status reception. StatSN is incremented by 1 for every 6292 response/status sent on a connection except for responses sent as a 6293 result of a retry or SNACK. In the case of responses sent due to a 6294 retransmission request, the StatSN MUST be the same as the first 6295 time the PDU was sent unless the connection has since been 6296 restarted. 6297 10.4.10 ExpCmdSN - Next Expected CmdSN from this Initiator 6299 ExpCmdSN is a Sequence Number that the target iSCSI returns to the 6300 initiator to acknowledge command reception. It is used to update a 6301 local variable with the same name. An ExpCmdSN equal to MaxCmdSN+1 6302 indicates that the target cannot accept new commands. 6304 10.4.11 MaxCmdSN - Maximum CmdSN from this Initiator 6306 MaxCmdSN is a Sequence Number that the target iSCSI returns to the 6307 initiator to indicate the maximum CmdSN the initiator can send. It 6308 is used to update a local variable with the same name. If MaxCmdSN 6309 is equal to ExpCmdSN-1, this indicates to the initiator that the 6310 target cannot receive any additional commands. When MaxCmdSN changes 6311 at the target while the target has no pending PDUs to convey this 6312 information to the initiator, it MUST generate a NOP-IN to carry the 6313 new MaxCmdSN. 6315 Julian Satran Expires August 2003 120 6316 iSCSI 19-January-03 6318 10.5 Task Management Function Request 6320 Byte/ 0 | 1 | 2 | 3 | 6321 / | | | | 6322 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6323 +---------------+---------------+---------------+---------------+ 6324 0|.|I| 0x02 |1| Function | Reserved | 6325 +---------------+---------------+---------------+---------------+ 6326 4|TotalAHSLength | DataSegmentLength | 6327 +---------------+---------------+---------------+---------------+ 6328 8| Logical Unit Number (LUN) or Reserved | 6329 + + 6330 12| | 6331 +---------------+---------------+---------------+---------------+ 6332 16| Initiator Task Tag | 6333 +---------------+---------------+---------------+---------------+ 6334 20| Referenced Task Tag or 0xffffffff | 6335 +---------------+---------------+---------------+---------------+ 6336 24| CmdSN | 6337 +---------------+---------------+---------------+---------------+ 6338 28| ExpStatSN | 6339 +---------------+---------------+---------------+---------------+ 6340 32| RefCmdSN or Reserved | 6341 +---------------+---------------+---------------+---------------+ 6342 36| ExpDataSN or Reserved | 6343 +---------------+---------------+---------------+---------------+ 6344 40/ Reserved / 6345 +/ / 6346 +---------------+---------------+---------------+---------------+ 6347 48| Header-Digest (Optional) | 6348 +---------------+---------------+---------------+---------------+ 6350 10.5.1 Function 6352 The Task Management functions provide an initiator with a way to 6353 explicitly control the execution of one or more Tasks (SCSI and 6354 iSCSI tasks). The Task Management function codes are listed below. 6355 For a more detailed description of SCSI task management, see [SAM2]. 6357 1 - ABORT TASK - aborts the task identified by the Referenced 6358 Task Tag field. 6360 2 - ABORT TASK SET - aborts all Tasks issued via this session 6361 on the logical unit. 6363 3 - CLEAR ACA - clears the Auto Contingent Allegiance 6364 condition. 6366 4 - CLEAR TASK SET - aborts all Tasks in the appropriate task 6367 set as defined by the TST field in the Control mode page (see 6368 [SPC3]). 6370 5 - LOGICAL UNIT RESET 6372 6 - TARGET WARM RESET 6374 Julian Satran Expires August 2003 121 6375 iSCSI 19-January-03 6377 7 - TARGET COLD RESET 6379 8 - TASK REASSIGN - reassigns connection allegiance for the 6380 task identified by the Initiator Task Tag field to this 6381 connection, thus resuming the iSCSI exchanges for the task. 6383 For all these functions, the Task Management function response MUST 6384 be returned as detailed in Section 10.6 Task Management Function 6385 Response. All these functions apply to the referenced tasks 6386 regardless of whether they are proper SCSI tasks or tagged iSCSI 6387 operations. Task management requests must act on all the commands 6388 from the same session having a CmdSN lower than the task management 6389 CmdSN. LOGICAL UNIT RESET, TARGET WARM RESET and TARGET COLD RESET 6390 may affect commands from other sessions or commands from the same 6391 session with CmdSN equal or exceeding CmdSN. 6393 If the task management request is marked for immediate delivery, it 6394 must be considered immediately for execution, but the operations 6395 involved (all or part of them) may be postponed to allow the target 6396 to receive all relevant tasks. According to [SAM2], for all the 6397 tasks covered by the Task Management response (i.e., with CmdSN 6398 lower than the task management command CmdSN) but except the Task 6399 Management response to a TASK REASSIGN, additional responses MUST 6400 NOT be delivered to the SCSI layer after the Task Management 6401 response. The iSCSI initiator MAY deliver to the SCSI layer all 6402 responses received before the Task Management response (i.e., it is 6403 a matter of implementation if the SCSI responses, received before 6404 the Task Management response but after the task management request 6405 was issued, are delivered to the SCSI layer by the iSCSI layer in 6406 the initiator). The iSCSI target MUST ensure that no responses for 6407 the tasks covered by a task management function are delivered to the 6408 iSCSI initiator after the Task Management response except for a task 6409 covered by a TASK REASSIGN. 6411 For ABORT TASK SET and CLEAR TASK SET, the issuing initiator MUST 6412 continue to respond to all valid target transfer tags (received via 6413 R2T, Text Response, NOP-In, or SCSI Data-in PDUs) related to the 6414 affected task set, even after issuing the task management request. 6415 The issuing initiator SHOULD however terminate (i.e., by setting the 6416 F-bit to 1) these response sequences as quickly as possible. The 6417 target on its part MUST wait for responses on all affected target 6418 transfer tags before acting on either of these two task management 6419 requests. In case all or part of the response sequence is not 6420 received (due to digest errors) for a valid TTT, the target MAY 6421 treat it as a case of within-command error recovery class (see 6422 Section 6.1.4.1 Recovery Within-command) if it is supporting 6423 ErrorRecoveryLevel >= 1, or alternatively may drop the connection to 6424 complete the requested task set function. 6426 If an ABORT TASK is issued for a task created by an immediate 6427 command then RefCmdSN MUST be that of the Task Management request 6428 itself (i.e. CmdSN and RefCmdSN are equal); otherwise RefCmdSN MUST 6429 be set to the CmdSN of the task to be aborted (lower than CmdSN). 6431 If the connection is still active (it is not undergoing an implicit 6432 or explicit logout), ABORT TASK MUST be issued on the same 6434 Julian Satran Expires August 2003 122 6435 iSCSI 19-January-03 6437 connection to which the task to be aborted is allegiant at the time 6438 the Task Management Request is issued. If the connection is 6439 implicitly or explicitly logged out (i.e., no other request will be 6440 issued on the failing connection and no other response will be 6441 received on the failing connection), then an ABORT TASK function 6442 request may be issued on another connection. This Task Management 6443 request will then establish a new allegiance for the command to be 6444 aborted as well as abort it (i.e., the task to be aborted will not 6445 have to be retried or reassigned, and its status, if issued but not 6446 acknowledged, will be reissued followed by the Task Management 6447 response). 6449 At the target an ABORT TASK function MUST NOT be executed on a Task 6450 Management request; such a request MUST result in Task Management 6451 response of "Function rejected". 6453 For the LOGICAL UNIT RESET function, the target MUST behave as 6454 dictated by the Logical Unit Reset function in [SAM2]. 6456 The implementation of the TARGET WARM RESET function and the TARGET 6457 COLD RESET function is OPTIONAL and when implemented, should act as 6458 described below. The TARGET WARM RESET is also subject to SCSI 6459 access controls on the requesting initiator as defined in [SPC3]. 6460 When authorization fails at the target, the appropriate response as 6461 described in Section 10.6 Task Management Function Response MUST be 6462 returned by the target. The TARGET COLD RESET function is not 6463 subject to SCSI access controls, but its execution privileges may be 6464 managed by iSCSI mechanisms such as login authentication. 6466 When executing the TARGET WARM RESET and TARGET COLD RESET 6467 functions, the target cancels all pending operations on all Logical 6468 Units known by the issuing initiator. Both functions are equivalent 6469 to the Target Reset function specified by [SAM2]. They can affect 6470 many other initiators logged in with the servicing SCSI target port. 6472 The target MUST treat the TARGET COLD RESET function additionally as 6473 a power on event, thus terminating all of its TCP connections to all 6474 initiators (all sessions are terminated). For this reason, the 6475 Service Response (defined by [SAM2]) for this SCSI task management 6476 function may not be reliably delivered to the issuing initiator 6477 port. 6479 For the TASK REASSIGN function, the target should reassign the 6480 connection allegiance to this new connection (and thus resume iSCSI 6481 exchanges for the task). TASK REASSIGN MUST ONLY be received by the 6482 target after the connection on which the command was previously 6483 executing has been successfully logged-out. The Task Management 6484 response MUST be issued before the reassignment becomes effective. 6485 For additional usage semantics see Section 6.2 Retry and Reassign in 6486 Recovery. 6488 At the target a TASK REASSIGN function request MUST NOT be executed 6489 to reassign the connection allegiance of a Task Management function 6490 request, an active text negotiation task, or a Logout task; such a 6491 request MUST result in Task Management response of "Function 6492 rejected". 6494 Julian Satran Expires August 2003 123 6495 iSCSI 19-January-03 6497 TASK REASSIGN MUST be issued as an immediate command. 6499 10.5.2 TotalAHSLength and DataSegmentLength 6501 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 6503 10.5.3 LUN 6505 This field is required for functions that address a specific LU 6506 (ABORT TASK, CLEAR TASK SET, ABORT TASK SET, CLEAR ACA, LOGICAL UNIT 6507 RESET) and is reserved in all others. 6509 10.5.4 Referenced Task Tag 6511 The Initiator Task Tag of the task to be aborted for the ABORT TASK 6512 function or reassigned for the TASK REASSIGN function. 6513 For all the other functions this field MUST be set to the reserved 6514 value 0xffffffff. 6516 10.5.5 RefCmdSN 6518 If an ABORT TASK is issued for a task created by an immediate 6519 command then RefCmdSN MUST be that of the Task Management request 6520 itself (i.e. CmdSN and RefCmdSN are equal). 6522 For an ABORT TASK of a task created by non-immediate command 6523 RefCmdSN MUST be set to the CmdSN of the task identified by the 6524 Referenced Task Tag field. Targets must use this field as described 6525 in section 10.6.1 when the task identified by the Referenced Task 6526 Tag field is not with the target. 6528 Otherwise, this field is reserved. 6530 10.5.6 ExpDataSN 6532 For recovery purposes, the iSCSI target and initiator maintain a 6533 data acknowledgement reference number - the first input DataSN 6534 number unacknowledged by the initiator. When issuing a new command, 6535 this number is set to 0. If the function is TASK REASSIGN, which 6536 establishes a new connection allegiance for a previously issued Read 6537 or Bidirectional command, ExpDataSN will contain an updated data 6538 acknowledgement reference number or the value 0; the latter 6539 indicating that the data acknowledgement reference number is 6540 unchanged. The initiator MUST discard any data PDUs from the 6541 previous execution that it did not acknowledge and the target MUST 6542 transmit all Data-in PDUs (if any) starting with the data 6543 acknowledgement reference number. The number of retransmitted PDUs 6544 may or may not be the same as the original transmission depending on 6545 if there was a change in MaxRecvDataSegmentLength in the 6546 reassignment. The target MAY also send no more Data-In PDUs if all 6547 data has been acknowledged. 6549 The value of ExpDataSN MUST be 0 or higher than the DataSN of the 6550 last acknowledged Data-In PDU, but not larger than DataSN+1 of the 6552 Julian Satran Expires August 2003 124 6553 iSCSI 19-January-03 6555 last Data-IN PDU sent by the target. Any other value MUST be ignored 6556 by the target. 6558 For other functions this field is reserved. 6560 Julian Satran Expires August 2003 125 6561 iSCSI 19-January-03 6563 10.6 Task Management Function Response 6565 Byte/ 0 | 1 | 2 | 3 | 6566 / | | | | 6567 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6568 +---------------+---------------+---------------+---------------+ 6569 0|.|.| 0x22 |1| Reserved | Response | Reserved | 6570 +---------------+---------------+---------------+---------------+ 6571 4|TotalAHSLength | DataSegmentLength | 6572 +---------------------------------------------------------------+ 6573 8/ Reserved / 6574 / / 6575 +---------------+---------------+---------------+---------------+ 6576 16| Initiator Task Tag | 6577 +---------------+---------------+---------------+---------------+ 6578 20| Reserved | 6579 +---------------+---------------+---------------+---------------+ 6580 24| StatSN | 6581 +---------------+---------------+---------------+---------------+ 6582 28| ExpCmdSN | 6583 +---------------+---------------+---------------+---------------+ 6584 32| MaxCmdSN | 6585 +---------------+---------------+---------------+---------------+ 6586 36/ Reserved / 6587 +/ / 6588 +---------------+---------------+---------------+---------------+ 6589 48| Header-Digest (Optional) | 6590 +---------------+---------------+---------------+---------------+ 6592 For the functions ABORT TASK, ABORT TASK SET, CLEAR ACA, CLEAR TASK 6593 SET, LOGICAL UNIT RESET, TARGET COLD RESET, TARGET WARM RESET and 6594 TASK REASSIGN, the target performs the requested Task Management 6595 function and sends a Task Management response back to the initiator. 6596 For TASK REASSIGN, the new connection allegiance MUST ONLY become 6597 effective at the target after the target issues the Task Management 6598 Response. 6600 10.6.1 Response 6602 The target provides a Response, which may take on the following 6603 values: 6605 a) 0 - Function complete. 6606 b) 1 - Task does not exist. 6607 c) 2 - LUN does not exist. 6608 d) 3 - Task still allegiant. 6609 e) 4 - Task allegiance reassignment not supported. 6610 f) 5 - Task management function not supported. 6611 g) 6 - Function authorization failed. 6612 h) 255 - Function rejected. 6614 All other values are reserved. 6616 Julian Satran Expires August 2003 126 6617 iSCSI 19-January-03 6619 For a discussion on usage of response codes 3 and 4, see Section 6620 6.2.2 Allegiance Reassignment. 6622 For the TARGET COLD RESET and TARGET WARM RESET functions, the 6623 target cancels all pending operations across all Logical Units known 6624 to the issuing initiator. For the TARGET COLD RESET function, the 6625 target MUST then close all of its TCP connections to all initiators 6626 (terminates all sessions). 6628 The mapping of the response code into a SCSI service response code 6629 value, if needed, is outside the scope of this document. However, in 6630 symbolic terms Response values 0 and 1 map to the SCSI service 6631 response of FUNCTION COMPLETE. All other Response values map to the 6632 SCSI service response of FUNCTION REJECTED. If a Task Management 6633 function response PDU does not arrive before the session is 6634 terminated, the SCSI service response is SERVICE DELIVERY OR TARGET 6635 FAILURE. 6637 The response to ABORT TASK SET and CLEAR TASK SET MUST only be 6638 issued by the target after all of the commands affected have been 6639 received by the target, the corresponding task management functions 6640 have been executed by the SCSI target, and the delivery of all 6641 responses delivered until the task management function completion 6642 have been confirmed (acknowledged through ExpStatSN) by the 6643 initiator on all connections of this session. For the exact 6644 timeline of events, refer to Section 10.6.2 Task Management Actions 6645 on Task Sets. 6647 For the ABORT TASK function, 6649 a) If the Referenced Task Tag identifies a valid task leading 6650 to a successful termination, then targets must return the 6651 "Function complete" response. 6652 b) If the Referenced Task Tag does not identify an existing 6653 task, but if the CmdSN indicated by the RefCmdSN field in the 6654 Task Management function request is within the valid CmdSN 6655 window and less than the CmdSN of the Task Management function 6656 request itself, then targets must consider the CmdSN received 6657 and return the "Function complete" response. 6658 c) If the Referenced Task Tag does not identify an existing 6659 task and if the CmdSN indicated by the RefCmdSN field in the 6660 Task Management function request is outside the valid CmdSN 6661 window, then targets must return the "Task does not exist" 6662 response. 6664 10.6.2 Task Management Actions on Task Sets 6666 The execution of ABORT TASK SET and CLEAR TASK SET Task Management 6667 function requests consists of the following sequence of events in 6668 the specified order on each of the entities. 6670 The initiator: 6672 Julian Satran Expires August 2003 127 6673 iSCSI 19-January-03 6675 a) Issues ABORT TASK SET/CLEAR TASK SET request. 6676 b) Continues to respond to each target transfer tag 6677 received for the affected task set. 6678 c) Receives any responses for the tasks in the affected 6679 task set (may process them as usual because they are 6680 guaranteed to be valid). 6681 d) Receives the task set management response, thus 6682 concluding all the tasks in the affected task set. 6684 The target: 6686 a) Receives the ABORT TASK SET/CLEAR TASK SET request. 6687 b) Waits for all target transfer tags to be responded to 6688 and for all affected tasks in the task set to be 6689 received. 6690 c) Propagates the command to and receives the response from 6691 the target SCSI layer. 6692 d) Takes note of last-sent StatSN on each of the 6693 connections in the session, and waits for 6694 acknowledgement of each StatSN (may solicit for 6695 acknowledgement by way of a NOP-In). 6696 e) Sends the task set management response. 6698 10.6.3 TotalAHSLength and DataSegmentLength 6700 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 6702 Julian Satran Expires August 2003 128 6703 iSCSI 19-January-03 6705 10.7 SCSI Data-out & SCSI Data-in 6707 The SCSI Data-out PDU for WRITE operations has the following format: 6709 Byte/ 0 | 1 | 2 | 3 | 6710 / | | | | 6711 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6712 +---------------+---------------+---------------+---------------+ 6713 0|.|.| 0x05 |F| Reserved | 6714 +---------------+---------------+---------------+---------------+ 6715 4|TotalAHSLength | DataSegmentLength | 6716 +---------------+---------------+---------------+---------------+ 6717 8| LUN or Reserved | 6718 + + 6719 12| | 6720 +---------------+---------------+---------------+---------------+ 6721 16| Initiator Task Tag | 6722 +---------------+---------------+---------------+---------------+ 6723 20| Target Transfer Tag or 0xffffffff | 6724 +---------------+---------------+---------------+---------------+ 6725 24| Reserved | 6726 +---------------+---------------+---------------+---------------+ 6727 28| ExpStatSN | 6728 +---------------+---------------+---------------+---------------+ 6729 32| Reserved | 6730 +---------------+---------------+---------------+---------------+ 6731 36| DataSN | 6732 +---------------+---------------+---------------+---------------+ 6733 40| Buffer Offset | 6734 +---------------+---------------+---------------+---------------+ 6735 44| Reserved | 6736 +---------------+---------------+---------------+---------------+ 6737 48| Header-Digest (Optional) | 6738 +---------------+---------------+---------------+---------------+ 6739 / DataSegment / 6740 +/ / 6741 +---------------+---------------+---------------+---------------+ 6742 | Data-Digest (Optional) | 6743 +---------------+---------------+---------------+---------------+ 6745 The SCSI Data-in PDU for READ operations has the following format: 6747 Julian Satran Expires August 2003 129 6748 iSCSI 19-January-03 6750 Byte/ 0 | 1 | 2 | 3 | 6751 / | | | | 6752 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6753 +---------------+---------------+---------------+---------------+ 6754 0|.|.| 0x25 |F|A|0 0 0|O|U|S| Reserved |Status or Rsvd | 6755 +---------------+---------------+---------------+---------------+ 6756 4|TotalAHSLength | DataSegmentLength | 6757 +---------------+---------------+---------------+---------------+ 6758 8| LUN or Reserved | 6759 + + 6760 12| | 6761 +---------------+---------------+---------------+---------------+ 6762 16| Initiator Task Tag | 6763 +---------------+---------------+---------------+---------------+ 6764 20| Target Transfer Tag or 0xffffffff | 6765 +---------------+---------------+---------------+---------------+ 6766 24| StatSN or Reserved | 6767 +---------------+---------------+---------------+---------------+ 6768 28| ExpCmdSN | 6769 +---------------+---------------+---------------+---------------+ 6770 32| MaxCmdSN | 6771 +---------------+---------------+---------------+---------------+ 6772 36| DataSN | 6773 +---------------+---------------+---------------+---------------+ 6774 40| Buffer Offset | 6775 +---------------+---------------+---------------+---------------+ 6776 44| Residual Count | 6777 +---------------+---------------+---------------+---------------+ 6778 48| Header-Digest (Optional) | 6779 +---------------+---------------+---------------+---------------+ 6780 / DataSegment / 6781 +/ / 6782 +---------------+---------------+---------------+---------------+ 6783 | Data-Digest (Optional) | 6784 +---------------+---------------+---------------+---------------+ 6786 Status can accompany the last Data-in PDU if the command did not end 6787 with an exception (i.e., the status is "good status" - GOOD, 6788 CONDITION MET or INTERMEDIATE CONDITION MET). The presence of 6789 status (and of a residual count) is signaled though the S flag bit. 6790 Although targets MAY choose to send even non-exception status in 6791 separate responses, initiators MUST support non-exception status in 6792 Data-In PDUs. 6794 10.7.1 F (Final) Bit 6796 For outgoing data, this bit is 1 for the last PDU of unsolicited 6797 data or the last PDU of a sequence that answers an R2T. 6799 For incoming data, this bit is 1 for the last input (read) data PDU 6800 of a sequence. Input can be split into several sequences, each 6801 having its own F bit. Splitting the data stream into sequences does 6802 not affect DataSN counting on Data-In PDUs. It MAY be used as a 6803 "change direction" indication for Bidirectional operations that need 6804 such a change. 6806 Julian Satran Expires August 2003 130 6807 iSCSI 19-January-03 6809 DataSegmentLength MUST not exceed MaxRecvDataSegmentLength for the 6810 direction it is sent and the total of all the DataSegmentLength of 6811 all PDUs in a sequence MUST not exceed MaxBurstLength (or 6812 FirstBurstLength for unsolicited data). However the number of 6813 individual PDUs in a sequence (or in total) may be higher than the 6814 MaxBurstLength (or FirstBurstLength) to MaxRecvDataSegmentLength 6815 ratio (as PDUs may be limited in length by the sender capabilities). 6816 Using DataSegmentLength of 0 may increase beyond what is reasonable 6817 for the number of PDUs and should therefore be avoided. 6819 For Bidirectional operations, the F bit is 1 for both the end of the 6820 input sequences and the end of the output sequences. 6822 10.7.2 A (Acknowledge) bit 6824 For sessions with ErrorRecoveryLevel 1 or higher, the target sets 6825 this bit to 1 to indicate that it requests a positive 6826 acknowledgement from the initiator for the data received. The 6827 target should use the A bit moderately; it MAY only set the A bit to 6828 1 once every MaxBurstLength bytes, or on the last Data-In PDU that 6829 concludes the entire requested read data transfer for the task from 6830 the target's perspective, and it MUST NOT do so more frequently. The 6831 target MUST NOT set to 1 the A bit for sessions with 6832 ErrorRecoveryLevel=0. The initiator MUST ignore the A bit set to 1 6833 for sessions with ErrorRecoveryLevel=0. 6835 On receiving a Data-In PDU with the A bit set to 1 on a session with 6836 ErrorRecoveryLevel greater than 0, if there are no holes in the read 6837 data until that Data-In PDU, the initiator MUST issue a SNACK of 6838 type DataACK except when it is able to acknowledge the status for 6839 the task immediately via ExpStatSN on other outbound PDUs if the 6840 status for the task is also received. In the latter case 6841 (acknowledgement through ExpStatSN), sending a SNACK of type DataACK 6842 in response to the A bit is OPTIONAL, but if it is done, it must not 6843 be sent after the status acknowledgement through ExpStatSN. If the 6844 initiator has detected holes in the read data prior to that Data-In 6845 PDU, it MUST postpone issuing the SNACK of type DataACK until the 6846 holes are filled. An initiator also MUST NOT acknowledge the status 6847 for the task before those holes are filled. A status 6848 acknowledgement for a task that generated the Data-In PDUs is 6849 considered by the target as an implicit acknowledgement of the Data- 6850 In PDUs if such an acknowledgement was requested by the target. 6852 10.7.3 Flags (byte 1) 6854 The last SCSI Data packet sent from a target to an initiator for a 6855 SCSI command that completed successfully (with a status of GOOD, 6856 CONDITION MET, INTERMEDIATE or INTERMEDIATE CONDITION MET) may also 6857 optionally contain the Status for the data transfer. In this case, 6858 Sense Data cannot be sent together with the Command Status. If the 6859 command is completed with an error, then the response and sense data 6860 MUST be sent in a SCSI Response PDU (i.e., MUST NOT be sent in a 6861 SCSI Data packet). For Bidirectional commands, the status MUST be 6862 sent in a SCSI Response PDU. 6864 Julian Satran Expires August 2003 131 6865 iSCSI 19-January-03 6867 bit 2-4 - Reserved. 6869 bit 5-6 - used the same as in a SCSI Response. These bits are 6870 only valid when S is set to 1. For details see Section 10.4.1 6871 Flags (byte 1). 6873 bit 7 S (status)- set to indicate that the Command Status field 6874 contains status. If this bit is set to 1, the F bit MUST also 6875 be set to 1. 6877 The fields StatSN, Status, and Residual Count only have meaningful 6878 content if the S bit is set to 1 and their values are defined in 6879 Section 10.4 SCSI Response. 6881 10.7.4 Target Transfer Tag and LUN 6883 On outgoing data, the Target Transfer Tag is provided to the target 6884 if the transfer is honoring an R2T. In this case, the Target 6885 Transfer Tag field is a replica of the Target Transfer Tag provided 6886 with the R2T. 6888 On incoming data, the Target Transfer Tag and LUN MUST be provided 6889 by the target if the A bit is set to 1; otherwise they are reserved. 6890 The Target Transfer Tag and LUN are copied by the initiator into the 6891 SNACK of type DataACK that it issues as a result of receiving a SCSI 6892 Data-in PDU with the A bit set to 1. 6894 The Target Transfer Tag values are not specified by this protocol 6895 except that the value 0xffffffff is reserved and means that the 6896 Target Transfer Tag is not supplied. If the Target Transfer Tag is 6897 provided, then the LUN field MUST hold a valid value and be 6898 consistent with whatever was specified with the command; otherwise, 6899 the LUN field is reserved. 6901 10.7.5 DataSN 6903 For input (read) or bidirectional Data-In PDUs, the DataSN is the 6904 input PDU number within the data transfer for the command identified 6905 by the Initiator Task Tag. 6907 R2T and Data-In PDUs, in the context of bidirectional commands, 6908 share the numbering sequence (see Section 3.2.2.3 Data Sequencing). 6910 For output (write) data PDUs, the DataSN is the Data-Out PDU number 6911 within the current output sequence. The current output sequence is 6912 either identified by the Initiator Task Tag (for unsolicited data) 6913 or is a data sequence generated for one R2T (for data solicited 6914 through R2T). 6916 10.7.6 Buffer Offset 6918 The Buffer Offset field contains the offset of this PDU payload data 6919 within the complete data transfer. The sum of the buffer offset and 6920 length should not exceed the expected transfer length for the 6921 command. 6923 Julian Satran Expires August 2003 132 6924 iSCSI 19-January-03 6926 The order of data PDUs within a sequence is determined by 6927 DataPDUInOrder. When set to Yes, it means that PDUs have to be in 6928 increasing Buffer Offset order and overlays are forbidden. 6930 The ordering between sequences is determined by DataSequenceInOrder. 6931 When set to Yes, it means that sequences have to be in increasing 6932 Buffer Offset order and overlays are forbidden. 6934 10.7.7 DataSegmentLength 6936 This is the data payload length of a SCSI Data-In or SCSI Data-Out 6937 PDU. The sending of 0 length data segments should be avoided, but 6938 initiators and targets MUST be able to properly receive 0 length 6939 data segments. 6941 The Data Segments of Data-in and Data-out PDUs SHOULD be filled to 6942 the integer number of 4 byte words (real payload) unless the F bit 6943 is set to 1. 6945 Julian Satran Expires August 2003 133 6946 iSCSI 19-January-03 6948 10.8 Ready To Transfer (R2T) 6950 Byte/ 0 | 1 | 2 | 3 | 6951 / | | | | 6952 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 6953 +---------------+---------------+---------------+---------------+ 6954 0|.|.| 0x31 |1| Reserved | 6955 +---------------+---------------+---------------+---------------+ 6956 4|TotalAHSLength | DataSegmentLength | 6957 +---------------+---------------+---------------+---------------+ 6958 8| LUN | 6959 + + 6960 12| | 6961 +---------------+---------------+---------------+---------------+ 6962 16| Initiator Task Tag | 6963 +---------------+---------------+---------------+---------------+ 6964 20| Target Transfer Tag | 6965 +---------------+---------------+---------------+---------------+ 6966 24| StatSN | 6967 +---------------+---------------+---------------+---------------+ 6968 28| ExpCmdSN | 6969 +---------------+---------------+---------------+---------------+ 6970 32| MaxCmdSN | 6971 +---------------+---------------+---------------+---------------+ 6972 36| R2TSN | 6973 +---------------+---------------+---------------+---------------+ 6974 40| Buffer Offset | 6975 +---------------+---------------+---------------+---------------+ 6976 44| Desired Data Transfer Length | 6977 +---------------------------------------------------------------+ 6978 48| Header-Digest (Optional) | 6979 +---------------+---------------+---------------+---------------+ 6981 When an initiator has submitted a SCSI Command with data that passes 6982 from the initiator to the target (WRITE), the target may specify 6983 which blocks of data it is ready to receive. The target may request 6984 that the data blocks be delivered in whichever order is convenient 6985 for the target at that particular instant. This information is 6986 passed from the target to the initiator in the Ready To Transfer 6987 (R2T) PDU. 6989 In order to allow write operations without an explicit initial R2T, 6990 the initiator and target MUST have negotiated the key InitialR2T to 6991 No during Login. 6993 An R2T MAY be answered with one or more SCSI Data-out PDUs with a 6994 matching Target Transfer Tag. If an R2T is answered with a single 6995 Data-out PDU, the Buffer Offset in the Data PDU MUST be the same as 6996 the one specified by the R2T, and the data length of the Data PDU 6997 MUST be the same as the Desired Data Transfer Length specified in 6998 the R2T. If the R2T is answered with a sequence of Data PDUs, the 6999 Buffer Offset and Length MUST be within the range of those specified 7000 by R2T, and the last PDU MUST have the F bit set to 1. If the last 7001 PDU (marked with the F bit) is received before the Desired Data 7002 Transfer Length is transferred, a target MAY choose to Reject that 7004 Julian Satran Expires August 2003 134 7005 iSCSI 19-January-03 7007 PDU with "Protocol error" reason code. DataPDUInOrder governs the 7008 Data-Out PDU ordering. If DataPDUInOrder is set to Yes, the Buffer 7009 Offsets and Lengths for consecutive PDUs MUST form a continuous non- 7010 overlapping range and the PDUs MUST be sent in increasing offset 7011 order. 7013 The target may send several R2T PDUs. It, therefore, can have a 7014 number of pending data transfers. The number of outstanding R2T 7015 PDUs are limited by the value of the negotiated key 7016 MaxOutstandingR2T. Within a connection, outstanding R2Ts MUST be 7017 fulfilled by the initiator in the order in which they were received. 7019 R2T PDUs MAY also be used to recover Data Out PDUs. Such an R2T 7020 (Recovery-R2T) is generated by a target upon detecting the loss of 7021 one or more Data-Out PDUs due to: 7023 - Digest error 7024 - Sequence error 7025 - Sequence reception timeout 7027 A Recovery-R2T carries the next unused R2TSN, but requests part of 7028 or the entire data burst that an earlier R2T (with a lower R2TSN) 7029 had already requested. 7031 DataSequenceInOrder governs the buffer offset ordering in 7032 consecutive R2Ts. If DataSequenceInOrder is Yes, then consecutive 7033 R2Ts MUST refer to continuous non-overlapping ranges except for 7034 Recovery-R2Ts. 7036 10.8.1 TotalAHSLength and DataSegmentLength 7038 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 7040 10.8.2 R2TSN 7042 R2TSN is the R2T PDU input PDU number within the command identified 7043 by the Initiator Task Tag. 7045 For bidirectional commands R2T and Data-In PDUs share the input PDU 7046 numbering sequence (see Section 3.2.2.3 Data Sequencing). 7048 10.8.3 StatSN 7050 The StatSN field will contain the next StatSN. The StatSN for this 7051 connection is not advanced after this PDU is sent. 7053 10.8.4 Desired Data Transfer Length and Buffer Offset 7055 The target specifies how many bytes it wants the initiator to send 7056 because of this R2T PDU. The target may request the data from the 7057 initiator in several chunks, not necessarily in the original order 7058 of the data. The target, therefore, also specifies a Buffer Offset 7059 that indicates the point at which the data transfer should begin, 7060 relative to the beginning of the total data transfer. The Desired 7061 Data Transfer Length MUST NOT be 0 and MUST not exceed 7062 MaxBurstLength. 7064 Julian Satran Expires August 2003 135 7065 iSCSI 19-January-03 7067 10.8.5 Target Transfer Tag 7069 The target assigns its own tag to each R2T request that it sends to 7070 the initiator. This tag can be used by the target to easily identify 7071 the data it receives. The Target Transfer Tag and LUN are copied in 7072 the outgoing data PDUs and are only used by the target. There is no 7073 protocol rule about the Target Transfer Tag except that the value 7074 0xffffffff is reserved and MUST NOT be sent by a target in an R2T. 7076 Julian Satran Expires August 2003 136 7077 iSCSI 19-January-03 7079 10.9 Asynchronous Message 7081 An Asynchronous Message may be sent from the target to the initiator 7082 without correspondence to a particular command. The target specifies 7083 the reason for the event and sense data. 7085 Byte/ 0 | 1 | 2 | 3 | 7086 / | | | | 7087 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7088 +---------------+---------------+---------------+---------------+ 7089 0|.|.| 0x32 |1| Reserved | 7090 +---------------+---------------+---------------+---------------+ 7091 4|TotalAHSLength | DataSegmentLength | 7092 +---------------+---------------+---------------+---------------+ 7093 8| LUN or Reserved | 7094 + + 7095 12| | 7096 +---------------+---------------+---------------+---------------+ 7097 16| 0xffffffff | 7098 +---------------+---------------+---------------+---------------+ 7099 20| Reserved | 7100 +---------------+---------------+---------------+---------------+ 7101 24| StatSN | 7102 +---------------+---------------+---------------+---------------+ 7103 28| ExpCmdSN | 7104 +---------------+---------------+---------------+---------------+ 7105 32| MaxCmdSN | 7106 +---------------+---------------+---------------+---------------+ 7107 36| AsyncEvent | AsyncVCode | Parameter1 or Reserved | 7108 +---------------+---------------+---------------+---------------+ 7109 40| Parameter2 or Reserved | Parameter3 or Reserved | 7110 +---------------+---------------+---------------+---------------+ 7111 44| Reserved | 7112 +---------------+---------------+---------------+---------------+ 7113 48| Header-Digest (Optional) | 7114 +---------------+---------------+---------------+---------------+ 7115 / DataSegment - Sense Data and iSCSI Event Data / 7116 +/ / 7117 +---------------+---------------+---------------+---------------+ 7118 | Data-Digest (Optional) | 7119 +---------------+---------------+---------------+---------------+ 7121 Some Asynchronous Messages are strictly related to iSCSI while 7122 others are related to SCSI [SAM2]. 7124 StatSN counts this PDU as an acknowledgeable event (StatSN is 7125 advanced), which allows for initiator and target state 7126 synchronization. 7128 10.9.1 AsyncEvent 7130 The codes used for iSCSI Asynchronous Messages (events) are: 7132 0 - a SCSI Asynchronous Event is reported in the sense data. 7133 Sense Data that accompanies the report, in the data segment, 7135 Julian Satran Expires August 2003 137 7136 iSCSI 19-January-03 7138 identifies the condition. The sending of a SCSI Event 7139 (Asynchronous Event Reporting in SCSI terminology) is 7140 dependent on the target support for SCSI asynchronous event 7141 reporting (see [SAM2]) as indicated in the standard INQUIRY 7142 data (see [SPC3]). Its use may be enabled by parameters in the 7143 SCSI Control mode page (see [SPC3]). 7145 1 - target requests Logout. This Async Message MUST be sent on 7146 the same connection as the one requesting to be logged out. 7147 The initiator MUST honor this request by issuing a Logout as 7148 early as possible, but no later than Parameter3 seconds. 7149 Initiator MUST send a Logout with a reason code of "Close the 7150 connection" OR "Close the session" to close all the 7151 connections. Once this message is received, the initiator 7152 SHOULD NOT issue new iSCSI commands on the connection to be 7153 logged out. The target MAY reject any new I/O requests that it 7154 receives after this Message with the reason code "Waiting for 7155 Logout". If the initiator does not Logout in Parameter3 7156 seconds, the target should send an Async PDU with iSCSI event 7157 code "Dropped the connection" if possible, or simply terminate 7158 the transport connection. Parameter1 and Parameter2 are 7159 reserved. 7161 2 - target indicates it will drop the connection. 7162 The Parameter1 field indicates the CID of the connection going 7163 to be dropped. 7164 The Parameter2 field (Time2Wait) indicates, in seconds, the 7165 minimum time to wait before attempting to reconnect or 7166 reassign. 7167 The Parameter3 field (Time2Retain) indicates the maximum time 7168 allowed to reassign commands after the initial wait (in 7169 Parameter2). 7170 If the initiator does not attempt to reconnect and/or reassign 7171 the outstanding commands within the time specified by 7172 Parameter3, or if Parameter3 is 0, the target will terminate 7173 all outstanding commands on this connection. In this case, no 7174 other responses should be expected from the target for the 7175 outstanding commands on this connection. 7176 A value of 0 for Parameter2 indicates that reconnect can be 7177 attempted immediately. 7179 3 - target indicates it will drop all the connections of this 7180 session. 7181 Parameter1 field is reserved. 7182 The Parameter2 field (Time2Wait) indicates, in seconds, the 7183 minimum time to wait before attempting to reconnect. 7184 The Parameter3 field (Time2Retain) indicates the maximum time 7185 allowed to reassign commands after the initial wait (in 7186 Parameter2). 7187 If the initiator does not attempt to reconnect and/or reassign 7188 the outstanding commands within the time specified by 7189 Parameter3, or if Parameter3 is 0, the session is terminated. 7190 In this case, the target will terminate all outstanding 7191 commands in this session; no other responses should be 7192 expected from the target for the outstanding commands in this 7194 Julian Satran Expires August 2003 138 7195 iSCSI 19-January-03 7197 session. A value of 0 for Parameter2 indicates that reconnect 7198 can be attempted immediately. 7200 4 - target requests parameter negotiation on this connection. 7201 The initiator MUST honor this request by issuing a Text 7202 Request (that can be empty) on the same connection as early as 7203 possible, but no later than Parameter3 seconds, unless a Text 7204 Request is already pending on the connection, or by issuing a 7205 Logout Request. If the initiator does not issue a Text Request 7206 the target may reissue the Asynchronous Message requesting 7207 parameter negotiation. 7209 255 - vendor specific iSCSI Event. The AsyncVCode details the 7210 vendor code, and data MAY accompany the report. 7212 All other event codes are reserved. 7214 10.9.2 AsyncVCode 7216 AsyncVCode is a vendor specific detail code that is only valid if 7217 the AsyncEvent field indicates a vendor specific event. Otherwise, 7218 it is reserved. 7220 10.9.3 LUN 7222 The LUN field MUST be valid if AsyncEvent is 0. Otherwise, this 7223 field is reserved. 7224 10.9.4 Sense Data and iSCSI Event Data 7226 For a SCSI event, this data accompanies the report in the data 7227 segment and identifies the condition. 7229 For an iSCSI event, additional vendor-unique data MAY accompany the 7230 Async event. Initiators MAY ignore the data when not understood 7231 while processing the rest of the PDU. 7233 If the DataSegmentLength is not 0, the format of the DataSegment is 7234 as follows: 7235 Byte/ 0 | 1 | 2 | 3 | 7236 / | | | | 7237 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7238 +---------------+---------------+---------------+---------------+ 7239 0|SenseLength | Sense Data | 7240 +---------------+---------------+---------------+---------------+ 7241 x/ Sense Data / 7242 +---------------+---------------+---------------+---------------+ 7243 y/ iSCSI Event Data / 7244 / / 7245 +---------------+---------------+---------------+---------------+ 7246 z| 7248 10.9.4.1 SenseLength 7250 This is the length of Sense Data. When the Sense Data field is empty 7251 (e.g., the event is not a SCSI event) SenseLength is 0. 7253 Julian Satran Expires August 2003 139 7254 iSCSI 19-January-03 7256 Julian Satran Expires August 2003 140 7257 iSCSI 19-January-03 7259 10.10 Text Request 7261 The Text Request is provided to allow for the exchange of 7262 information and for future extensions. It permits the initiator to 7263 inform a target of its capabilities or to request some special 7264 operations. 7266 Byte/ 0 | 1 | 2 | 3 | 7267 / | | | | 7268 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7269 +---------------+---------------+---------------+---------------+ 7270 0|.|I| 0x04 |F|C| Reserved | 7271 +---------------+---------------+---------------+---------------+ 7272 4|TotalAHSLength | DataSegmentLength | 7273 +---------------+---------------+---------------+---------------+ 7274 8| LUN or Reserved | 7275 + + 7276 12| | 7277 +---------------+---------------+---------------+---------------+ 7278 16| Initiator Task Tag | 7279 +---------------+---------------+---------------+---------------+ 7280 20| Target Transfer Tag or 0xffffffff | 7281 +---------------+---------------+---------------+---------------+ 7282 24| CmdSN | 7283 +---------------+---------------+---------------+---------------+ 7284 28| ExpStatSN | 7285 +---------------+---------------+---------------+---------------+ 7286 32/ Reserved / 7287 +/ / 7288 +---------------+---------------+---------------+---------------+ 7289 48| Header-Digest (Optional) | 7290 +---------------+---------------+---------------+---------------+ 7291 / DataSegment (Text) / 7292 +/ / 7293 +---------------+---------------+---------------+---------------+ 7294 | Data-Digest (Optional) | 7295 +---------------+---------------+---------------+---------------+ 7297 An initiator MUST have at most one outstanding Text Request on a 7298 connection at any given time. 7300 On a connection failure, an initiator must either explicitly abort 7301 any active allegiant text negotiation task or must cause such a task 7302 to be implicitly terminated by the target. 7304 10.10.1 F (Final) Bit 7306 When set to 1, indicates that this is the last or only text request 7307 in a sequence of Text Requests; otherwise, it indicates that more 7308 Text Requests will follow. 7310 Julian Satran Expires August 2003 141 7311 iSCSI 19-January-03 7313 10.10.2 C (Continue) Bit 7315 When set to 1, indicates that the text (set of key=value pairs) in 7316 this Text Request is not complete (it will be continued on 7317 subsequent Text Requests); otherwise, it indicates that this Text 7318 Request ends a set of key=value pairs. A Text Request with the C 7319 bit set to 1 MUST have the F bit set to 0. 7321 10.10.3 Initiator Task Tag 7323 The initiator assigned identifier for this Text Request. If the 7324 command is sent as part of a sequence of text requests and 7325 responses, the Initiator Task Tag MUST be the same for all the 7326 requests within the sequence (similar to linked SCSI commands). The 7327 I bit for all requests in a sequence also MUST be the same. 7329 10.10.4 Target Transfer Tag 7331 When the Target Transfer Tag is set to the reserved value 7332 0xffffffff, it tells the target that this is a new request and the 7333 target resets any internal state associated with the Initiator Task 7334 Tag (resets the current negotiation state). 7336 The target sets the Target Transfer Tag in a text response to a 7337 value other than the reserved value 0xffffffff whenever it indicates 7338 that it has more data to send or more operations to perform that are 7339 associated with the specified Initiator Task Tag. It MUST do so 7340 whenever it sets the F bit to 0 in the response. By copying the 7341 Target Transfer Tag from the response to the next Text Request, the 7342 initiator tells the target to continue the operation for the 7343 specific Initiator Task Tag. The initiator MUST ignore the Target 7344 Transfer Tag in the Text Response when the F bit is set to 1. 7346 This mechanism allows the initiator and target to transfer a large 7347 amount of textual data over a sequence of text-command/text-response 7348 exchanges, or to perform extended negotiation sequences. 7350 If the Target Transfer Tag is not 0xffffffff, the LUN field MUST be 7351 sent by the target in the Text Response. 7353 A target MAY reset its internal negotiation state if an exchange is 7354 stalled by the initiator for a long time or if it is running out of 7355 resources. 7357 Long text responses are handled as in the following example: 7359 I->T Text SendTargets=All (F=1,TTT=0xffffffff) 7360 T->I Text (F=0,TTT=0x12345678) 7361 I->T Text (F=1, TTT=0x12345678) 7362 T->I Text (F=0, TTT=0x12345678) 7363 I->T Text (F=1, TTT=0x12345678) 7364 ... 7365 T->I Text (F=1, TTT=0xffffffff) 7367 Julian Satran Expires August 2003 142 7368 iSCSI 19-January-03 7370 10.10.5 Text 7372 The data lengths of a text request MUST NOT exceed the iSCSI target 7373 MaxRecvDataSegmentLength (a per connection and per direction 7374 negotiated parameter). The text format is specified in Section 5.2 7375 Text Mode Negotiation. 7377 Chapter 11 and Chapter 12 list some basic Text key=value pairs, some 7378 of which can be used in Login Request/Response and some in Text 7379 Request/Response. 7381 A key=value pair can span Text request or response boundaries. A 7382 key=value pair can start in one PDU and continue on the next. In 7383 other words the end of a PDU does not necessarily signal the end of 7384 a key=value pair. 7386 The target responds by sending its response back to the initiator. 7387 The response text format is similar to the request text format. 7388 The text response MAY refer to key=value pairs presented in an 7389 earlier text request and the text in the request may refer to 7390 earlier responses. 7392 Chapter 5 details the rules for the Text Requests and Responses. 7394 Text operations are usually meant for parameter setting/ 7395 negotiations, but can also be used to perform some long lasting 7396 operations. 7398 Text operations that take a long time should be placed in their own 7399 Text request. 7401 Julian Satran Expires August 2003 143 7402 iSCSI 19-January-03 7404 10.11 Text Response 7406 The Text Response PDU contains the target's responses to the 7407 initiator's Text request. The format of the Text field matches that 7408 of the Text request. 7410 Byte/ 0 | 1 | 2 | 3 | 7411 / | | | | 7412 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7413 +---------------+---------------+---------------+---------------+ 7414 0|.|.| 0x24 |F|C| Reserved | 7415 +---------------+---------------+---------------+---------------+ 7416 4|TotalAHSLength | DataSegmentLength | 7417 +---------------+---------------+---------------+---------------+ 7418 8| LUN or Reserved | 7419 + + 7420 12| | 7421 +---------------+---------------+---------------+---------------+ 7422 16| Initiator Task Tag | 7423 +---------------+---------------+---------------+---------------+ 7424 20| Target Transfer Tag or 0xffffffff | 7425 +---------------+---------------+---------------+---------------+ 7426 24| StatSN | 7427 +---------------+---------------+---------------+---------------+ 7428 28| ExpCmdSN | 7429 +---------------+---------------+---------------+---------------+ 7430 32| MaxCmdSN | 7431 +---------------+---------------+---------------+---------------+ 7432 36/ Reserved / 7433 +/ / 7434 +---------------+---------------+---------------+---------------+ 7435 48| Header-Digest (Optional) | 7436 +---------------+---------------+---------------+---------------+ 7437 / DataSegment (Text) / 7438 +/ / 7439 +---------------+---------------+---------------+---------------+ 7440 | Data-Digest (Optional) | 7441 +---------------+---------------+---------------+---------------+ 7443 10.11.1 F (Final) Bit 7445 When set to 1, in response to a Text Request with the Final bit set 7446 to 1, the F bit indicates that the target has finished the whole 7447 operation. Otherwise, if set to 0 in response to a Text Request 7448 with the Final Bit set to 1, it indicates that the target has more 7449 work to do (invites a follow-on text request). A Text Response with 7450 the F bit set to 1 in response to a Text Request with the F bit set 7451 to 0 is a protocol error. 7453 A Text Response with the F bit set to 1 MUST NOT contain key=value 7454 pairs that may require additional answers from the initiator. 7456 A Text Response with the F bit set to 1 MUST have a Target Transfer 7457 Tag field set to the reserved value of 0xffffffff. 7459 Julian Satran Expires August 2003 144 7460 iSCSI 19-January-03 7462 A Text Response with the F bit set to 0 MUST have a Target Transfer 7463 Tag field set to a value other than the reserved 0xffffffff. 7465 10.11.2 C (Continue) Bit 7467 When set to 1, indicates that the text (set of key=value pairs) in 7468 this Text Response is not complete (it will be continued on 7469 subsequent Text Responses); otherwise, it indicates that this Text 7470 Response ends a set of key=value pairs. A Text Response with the C 7471 bit set to 1 MUST have the F bit set to 0. 7473 10.11.3 Initiator Task Tag 7475 The Initiator Task Tag matches the tag used in the initial Text 7476 Request. 7478 10.11.4 Target Transfer Tag 7480 When a target has more work to do (e.g., cannot transfer all the 7481 remaining text data in a single Text Response or has to continue the 7482 negotiation) and has enough resources to proceed, it MUST set the 7483 Target Transfer Tag to a value other than the reserved value of 7484 0xffffffff. Otherwise, the Target Transfer Tag MUST be set to 7485 0xffffffff. 7487 When the Target Transfer Tag is not 0xffffffff, the LUN field may be 7488 significant. 7490 The initiator MUST copy the Target Transfer Tag and LUN in its next 7491 request to indicate that it wants the rest of the data. 7493 When the target receives a Text Request with the Target Transfer Tag 7494 set to the reserved value of 0xffffffff, it resets its internal 7495 information (resets state) associated with the given Initiator Task 7496 Tag (restarts the negotiation). 7498 When a target cannot finish the operation in a single Text Response, 7499 and does not have enough resources to continue, it rejects the Text 7500 Request with the appropriate Reject code. 7502 A target may reset its internal state associated with an Initiator 7503 Task Tag (the current negotiation state), state expressed through 7504 the Target Transfer Tag if the initiator fails to continue the 7505 exchange for some time. The target may reject subsequent Text 7506 Requests with the Target Transfer Tag set to the "stale" value. 7508 10.11.5 StatSN 7510 The target StatSN variable is advanced by each Text Response sent. 7512 10.11.6 Text Response Data 7514 The data lengths of a text response MUST NOT exceed the iSCSI 7515 initiator MaxRecvDataSegmentLength (a per connection and per 7516 direction negotiated parameter). 7518 Julian Satran Expires August 2003 145 7519 iSCSI 19-January-03 7521 The text in the Text Response Data is governed by the same rules as 7522 the text in the Text Request Data (see Section 10.10.5 Text). 7524 Although the initiator is the requesting party and controls the 7525 request-response initiation and termination, the target can offer 7526 key=value pairs of its own as part of a sequence and not only in 7527 response to the initiator. 7529 Julian Satran Expires August 2003 146 7530 iSCSI 19-January-03 7532 10.12 Login Request 7534 After establishing a TCP connection between an initiator and a 7535 target, the initiator MUST start a Login Phase to gain further 7536 access to the target's resources. 7538 The Login Phase (see Chapter 5) consists of a sequence of Login 7539 requests and responses that carry the same Initiator Task Tag. 7541 Login requests are always considered as immediate. 7543 Byte/ 0 | 1 | 2 | 3 | 7544 / | | | | 7545 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7546 +---------------+---------------+---------------+---------------+ 7547 0|.|1| 0x03 |T|C|.|.|CSG|NSG| Version-max | Version-min | 7548 +---------------+---------------+---------------+---------------+ 7549 4|TotalAHSLength | DataSegmentLength | 7550 +---------------+---------------+---------------+---------------+ 7551 8| ISID | 7552 + +---------------+---------------+ 7553 12| | TSIH | 7554 +---------------+---------------+---------------+---------------+ 7555 16| Initiator Task Tag | 7556 +---------------+---------------+---------------+---------------+ 7557 20| CID | Reserved | 7558 +---------------+---------------+---------------+---------------+ 7559 24| CmdSN | 7560 +---------------+---------------+---------------+---------------+ 7561 28| ExpStatSN or Reserved | 7562 +---------------+---------------+---------------+---------------+ 7563 32| Reserved | 7564 +---------------+---------------+---------------+---------------+ 7565 36| Reserved | 7566 +---------------+---------------+---------------+---------------+ 7567 40/ Reserved / 7568 +/ / 7569 +---------------+---------------+---------------+---------------+ 7570 48/ DataSegment - Login Parameters in Text request Format / 7571 +/ / 7572 +---------------+---------------+---------------+---------------+ 7574 10.12.1 T (Transit) Bit 7576 If set to 1, indicates that the initiator is ready to transit to the 7577 next stage. 7579 If the T bit is set to 1 and NSG is FullFeaturePhase, then this also 7580 indicates that the initiator is ready for the Final Login Response 7581 (see Chapter 5). 7583 10.12.2 C (Continue) Bit 7585 When set to 1, indicates that the text (set of key=value pairs) in 7586 this Login Request is not complete (it will be continued on 7587 subsequent Login Requests); otherwise, it indicates that this Login 7589 Julian Satran Expires August 2003 147 7590 iSCSI 19-January-03 7592 Request ends a set of key=value pairs. A Login Request with the C 7593 bit set to 1 MUST have the T bit set to 0. 7595 10.12.3 CSG and NSG 7597 Through these fields, Current Stage (CSG) and Next Stage (NSG), the 7598 Login negotiation requests and responses are associated with a 7599 specific stage in the session (SecurityNegotiation, 7600 LoginOperationalNegotiation, FullFeaturePhase) and may indicate the 7601 next stage to which they want to move (see Chapter 5). The next 7602 stage value is only valid when the T bit is 1; otherwise, it is 7603 reserved. 7605 The stage codes are: 7607 - 0 - SecurityNegotiation 7608 - 1 - LoginOperationalNegotiation 7609 - 3 - FullFeaturePhase 7611 All other codes are reserved. 7613 10.12.4 Version 7615 The version number of the current draft is 0x00. As such, all 7616 devices MUST carry version 0x00 for both Version-min and Version- 7617 max. 7619 10.12.4.1 Version-max 7621 Maximum Version number supported. 7623 All Login requests within the Login Phase MUST carry the same 7624 Version-max. 7626 The target MUST use the value presented with the first login 7627 request. 7629 10.12.4.2 Version-min 7631 All Login requests within the Login Phase MUST carry the same 7632 Version-min. The target MUST use the value presented with the first 7633 login request. 7635 10.12.5 ISID 7637 This is an initiator-defined component of the session identifier and 7638 is structured as follows (see [NDT] and Section 9.1.1 Conservative 7639 Reuse of ISIDs for details): 7641 Julian Satran Expires August 2003 148 7642 iSCSI 19-January-03 7644 Byte/ 0 | 1 | 2 | 3 | 7645 / | | | | 7646 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7647 +---------------+---------------+---------------+---------------+ 7648 8| T | A | B | C | 7649 +---------------+---------------+---------------+---------------+ 7650 12| D | 7651 +---------------+---------------+ 7653 The T field identifies the format and usage of A, B, C, and D as 7654 indicated below: 7656 T 7658 00b OUI-Format 7659 A&B are a 22 bit OUI 7660 (the I/G & U/L bits are omitted) 7661 C&D 24 bit qualifier 7662 01b EN - Format (IANA Enterprise Number) 7663 A - Reserved 7664 B&C EN (IANA Enterprise Number) 7665 D - Qualifier 7666 10b "Random" 7667 A - Reserved 7668 B&C Random 7669 D - Qualifier 7670 11b A,B,C&D Reserved 7672 For the T field values 00b and 01b, a combination of A and B (for 7673 00b) or B and C (for 01b) identifies the vendor or organization 7674 whose component (software or hardware) generates this ISID. A 7675 vendor or organization with one or more OUIs, or one or more 7676 Enterprise Numbers, MUST use at least one of these numbers and 7677 select the appropriate value for the T field when its components 7678 generate ISIDs. An OUI or EN MUST be set in the corresponding 7679 fields in network byte order (byte big-endian). 7681 If the T field is 10b, B and C are set to a random 24-bit unsigned 7682 integer value in network byte order (byte big-endian). See [NDT] 7683 for how this affects the principle of "conservative reuse". 7685 The Qualifier field is a 16 or 24-bit unsigned integer value that 7686 provides a range of possible values for the ISID within the selected 7687 namespace. It may be set to any value within the constraints 7688 specified in the iSCSI protocol (see Section 3.4.3 Consequences of 7689 the Model and Section 9.1.1 Conservative Reuse of ISIDs). 7691 The T field value of 11b is reserved. 7693 If the ISID is derived from something assigned to a hardware adapter 7694 or interface by a vendor, as a preset default value, it MUST be 7695 configurable to a value assigned according to the SCSI port behavior 7696 desired by the system in which it is installed (see Section 9.1.1 7697 Conservative Reuse of ISIDs and Section 9.1.2 iSCSI Name, ISID, and 7698 TPGT Use). The resultant ISID MUST also be persistent over power 7699 cycles, reboot, card swap, etc. 7701 Julian Satran Expires August 2003 149 7702 iSCSI 19-January-03 7704 10.12.6 TSIH 7706 TSIH must be set in the first Login Request. The reserved value 0 7707 MUST be used on the first connection for a new session. Otherwise, 7708 the TSIH sent by the target at the conclusion of the successful 7709 login of the first connection for this session MUST be used. The 7710 TSIH identifies to the target the associated existing session for 7711 this new connection. 7713 All Login requests within a Login Phase MUST carry the same TSIH. 7715 The target MUST check the value presented with the first login 7716 request and act as specified in Section 5.3.1 Login Phase Start. 7718 10.12.7 Connection ID - CID 7720 A unique ID for this connection within the session. 7722 All Login requests within the Login Phase MUST carry the same CID. 7724 The target MUST use the value presented with the first login 7725 request. 7727 A Login request with a non-zero TSIH and a CID equal to that of an 7728 existing connection implies a logout of the connection followed by a 7729 Login (see Section 5.3.4 Connection Reinstatement). For the details 7730 of the implicit Logout Request, see Section 10.14 Logout Request. 7732 10.12.8 CmdSN 7734 CmdSN is either the initial command sequence number of a session 7735 (for the first Login request of a session - the "leading" login), or 7736 the command sequence number in the command stream if the login is 7737 for a new connection in an existing session. 7739 Examples: 7741 - Login on a leading connection - if the leading login carries 7742 the CmdSN 123, all other login requests in the same login 7743 phase carry the CmdSN 123 and the first non-immediate command 7744 in FullFeaturePhase also carries the CmdSN 123. 7746 - Login on other than a leading connection - if the current 7747 CmdSN at the time the first login on the connection is issued 7748 is 500, then that PDU carries CmdSN=500. Subsequent login 7749 requests that are needed to complete this login phase may 7750 carry a CmdSN higher than 500 if non-immediate requests that 7751 were issued on other connections in the same session advance 7752 CmdSN. 7754 If the login request is a leading login request, the target MUST use 7755 the value presented in CmdSN as the target value for ExpCmdSN. 7757 Julian Satran Expires August 2003 150 7758 iSCSI 19-January-03 7760 10.12.9 ExpStatSN 7762 For the first Login Request on a connection this is ExpStatSN for 7763 the old connection and this field is only valid if the Login request 7764 restarts a connection (see Section 5.3.4 Connection Reinstatement). 7766 For subsequent Login Requests it is used to acknowledge the Login 7767 Responses with their increasing StatSN values. 7769 10.12.10 Login Parameters 7771 The initiator MUST provide some basic parameters in order to enable 7772 the target to determine if the initiator may use the target's 7773 resources and the initial text parameters for the security exchange. 7775 All the rules specified in Section 10.10.5 Text for text requests 7776 also hold for login requests. Keys and their explanations are 7777 listed in Chapter 11 (security negotiation keys) and Chapter 12 7778 (operational parameter negotiation keys). All keys in Chapter 12, 7779 except for the X extension formats, MUST be supported by iSCSI 7780 initiators and targets. Keys in Chapter 11 only need to be supported 7781 when the function to which they refer is mandatory to implement. 7783 Julian Satran Expires August 2003 151 7784 iSCSI 19-January-03 7786 10.13 Login Response 7788 The Login Response indicates the progress and/or end of the Login 7789 Phase. 7791 Byte/ 0 | 1 | 2 | 3 | 7792 / | | | | 7793 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 7794 +---------------+---------------+---------------+---------------+ 7795 0|.|.| 0x23 |T|C|.|.|CSG|NSG| Version-max | Version-active| 7796 +---------------+---------------+---------------+---------------+ 7797 4|TotalAHSLength | DataSegmentLength | 7798 +---------------+---------------+---------------+---------------+ 7799 8| ISID | 7800 + +---------------+---------------+ 7801 12| | TSIH | 7802 +---------------+---------------+---------------+---------------+ 7803 16| Initiator Task Tag | 7804 +---------------+---------------+---------------+---------------+ 7805 20| Reserved | 7806 +---------------+---------------+---------------+---------------+ 7807 24| StatSN | 7808 +---------------+---------------+---------------+---------------+ 7809 28| ExpCmdSN | 7810 +---------------+---------------+---------------+---------------+ 7811 32| MaxCmdSN | 7812 +---------------+---------------+---------------+---------------+ 7813 36| Status-Class | Status-Detail | Reserved | 7814 +---------------+---------------+---------------+---------------+ 7815 40/ Reserved / 7816 +/ / 7817 +---------------+---------------+---------------+---------------+ 7818 48/ DataSegment - Login Parameters in Text request Format / 7819 +/ / 7820 +---------------+---------------+---------------+---------------+ 7822 10.13.1 Version-max 7824 This is the highest version number supported by the target. 7826 All Login responses within the Login Phase MUST carry the same 7827 Version-max. 7829 The initiator MUST use the value presented as a response to the 7830 first login request. 7832 10.13.2 Version-active 7834 Indicates the highest version supported by the target and initiator. 7835 If the target does not support a version within the range specified 7836 by the initiator, the target rejects the login and this field 7837 indicates the lowest version supported by the target. 7839 All Login responses within the Login Phase MUST carry the same 7840 Version-active. 7842 Julian Satran Expires August 2003 152 7843 iSCSI 19-January-03 7845 The initiator MUST use the value presented as a response to the 7846 first login request. 7848 10.13.3 TSIH 7850 The TSIH is the target assigned session identifying handle. Its 7851 internal format and content are not defined by this protocol except 7852 for the value 0 that is reserved. With the exception of the Login 7853 Final-Response in a new session, this field should be set to the 7854 TSIH provided by the initiator in the Login Request. For a new 7855 session, the target MUST generate a non-zero TSIH and ONLY return it 7856 in the Login Final-Response (see Section 5.3 Login Phase). 7858 10.13.4 StatSN 7860 For the first Login Response (the response to the first Login 7861 Request), this is the starting status Sequence Number for the 7862 connection. The next response of any kind, including the next login 7863 response, if any, in the same Login Phase, will carry this number + 7864 1. This field is only valid if the Status-Class is 0. 7866 10.13.5 Status-Class and Status-Detail 7868 The Status returned in a Login Response indicates the execution 7869 status of the Login Phase. The status includes: 7871 Status-Class 7872 Status-Detail 7874 0 Status-Class indicates success. 7876 A non-zero Status-Class indicates an exception. In this case, 7877 Status-Class is sufficient for a simple initiator to use when 7878 handling exceptions, without having to look at the Status-Detail. 7879 The Status-Detail allows finer-grained exception handling for more 7880 sophisticated initiators and for better information for logging. 7882 The status classes are as follows: 7884 0 - Success - indicates that the iSCSI target successfully 7885 received, understood, and accepted the request. The numbering 7886 fields (StatSN, ExpCmdSN, MaxCmdSN) are only valid if Status- 7887 Class is 0. 7889 1 - Redirection - indicates that the initiator must take further 7890 action to complete the request. This is usually due to the 7891 target moving to a different address. All of the redirection 7892 status class responses MUST return one or more text key 7893 parameters of the type "TargetAddress", which indicates the 7894 target's new address. A redirection response MAY be issued by 7895 a target prior or after completing a security negotiation if a 7896 security negotiation is required. A redirection SHOULD be 7897 accepted by an initiator even without having the target 7898 complete a security negotiation if any security negotiation is 7899 required, and MUST be accepted by the initiator after the 7901 Julian Satran Expires August 2003 153 7902 iSCSI 19-January-03 7904 completion of the security negotiation if any security 7905 negotiation is required. 7907 2 - Initiator Error (not a format error) - indicates that the 7908 initiator most likely caused the error. This MAY be due to a 7909 request for a resource for which the initiator does not have 7910 permission. The request should not be tried again. 7912 3 - Target Error - indicates that the target sees no errors in 7913 the initiator's login request, but is currently incapable of 7914 fulfilling the request. The initiator may re-try the same 7915 login request later. 7917 The table below shows all of the currently allocated status codes. 7918 The codes are in hexadecimal; the first byte is the status class and 7919 the second byte is the status detail. 7921 Julian Satran Expires August 2003 154 7922 iSCSI 19-January-03 7924 ----------------------------------------------------------------- 7925 Status | Code | Description 7926 |(hex) | 7927 ----------------------------------------------------------------- 7928 Success | 0000 | Login is proceeding OK (*1). 7929 ----------------------------------------------------------------- 7930 Target moved | 0101 | The requested iSCSI Target Name (ITN) 7931 temporarily | | has temporarily moved 7932 | | to the address provided. 7933 ----------------------------------------------------------------- 7934 Target moved | 0102 | The requested ITN has permanently moved 7935 permanently | | to the address provided. 7936 ----------------------------------------------------------------- 7937 Initiator | 0200 | Miscellaneous iSCSI initiator 7938 error | | errors. 7939 ---------------------------------------------------------------- 7940 Authentication| 0201 | The initiator could not be 7941 failure | | successfully authenticated or target 7942 | | authentication is not supported. 7943 ----------------------------------------------------------------- 7944 Authorization | 0202 | The initiator is not allowed access 7945 failure | | to the given target. 7946 ----------------------------------------------------------------- 7947 Not found | 0203 | The requested ITN does not 7948 | | exist at this address. 7949 ----------------------------------------------------------------- 7950 Target removed| 0204 | The requested ITN has been removed and 7951 | |no forwarding address is provided. 7952 ----------------------------------------------------------------- 7953 Unsupported | 0205 | The requested iSCSI version range is 7954 version | | not supported by the target. 7955 ----------------------------------------------------------------- 7956 Too many | 0206 | Too many connections on this SSID. 7957 connections | | 7958 ----------------------------------------------------------------- 7959 Missing | 0207 | Missing parameters (e.g., iSCSI 7960 parameter | | Initiator and/or Target Name). 7961 ----------------------------------------------------------------- 7962 Can't include | 0208 | Target does not support session 7963 in session | | spanning to this connection (address). 7964 ----------------------------------------------------------------- 7965 Session type | 0209 | Target does not support this type of 7966 not supported | | of session or not from this Initiator. 7967 ----------------------------------------------------------------- 7968 Session does | 020a | Attempt to add a connection 7969 not exist | | to a non-existent session. 7970 ----------------------------------------------------------------- 7971 Invalid during| 020b | Invalid Request type during Login. 7972 login | | 7973 ----------------------------------------------------------------- 7974 Target error | 0300 | Target hardware or software error. 7975 ----------------------------------------------------------------- 7976 Service | 0301 | The iSCSI service or target is not 7977 unavailable | | currently operational. 7978 ----------------------------------------------------------------- 7979 Out of | 0302 | The target has insufficient session, 7981 Julian Satran Expires August 2003 155 7982 iSCSI 19-January-03 7984 resources | | connection, or other resources. 7985 ----------------------------------------------------------------- 7987 (*1)If the response T bit is 1 in both the request and the matching 7988 response, and the NSG is FullFeaturePhase in both the request and 7989 the matching response, the Login Phase is finished and the initiator 7990 may proceed to issue SCSI commands. 7992 If the Status Class is not 0, the initiator and target MUST close 7993 the TCP connection. 7995 If the target wishes to reject the login request for more than one 7996 reason, it should return the primary reason for the rejection. 7998 10.13.6 T (Transit) bit 8000 The T bit is set to 1 as an indicator of the end of the stage. If 8001 the T bit is set to 1 and NSG is FullFeaturePhase, then this is also 8002 the Final Login Response (see Chapter 5). A T bit of 0 indicates a 8003 "partial" response, which means "more negotiation needed". 8005 A login response with a T bit set to 1 MUST NOT contain key=value 8006 pairs that may require additional answers from the initiator within 8007 the same stage. 8009 If the status class is 0, the T bit MUST NOT be set to 1 if the T 8010 bit in the request was set to 0. 8012 10.13.7 C (Continue) Bit 8014 When set to 1, indicates that the text (set of key=value pairs) in 8015 this Login Response is not complete (it will be continued on 8016 subsequent Login Responses); otherwise, it indicates that this Login 8017 Response ends a set of key=value pairs. A Login Response with the C 8018 bit set to 1 MUST have the T bit set to 0. 8020 10.13.8 Login Parameters 8022 The target MUST provide some basic parameters in order to enable the 8023 initiator to determine if it is connected to the correct port and 8024 the initial text parameters for the security exchange. 8026 All the rules specified in Section 10.11.6 Text Response Data for 8027 text responses also hold for login responses. Keys and their 8028 explanations are listed in Chapter 11 (security negotiation keys) 8029 and Chapter 12 (operational parameter negotiation keys). All keys in 8030 Chapter 12, except for the X extension formats, MUST be supported by 8031 iSCSI initiators and targets. Keys in Chapter 11, only need to be 8032 supported when the function to which they refer is mandatory to 8033 implement. 8035 Julian Satran Expires August 2003 156 8036 iSCSI 19-January-03 8038 10.14 Logout Request 8040 The Logout request is used to perform a controlled closing of a 8041 connection. 8043 An initiator MAY use a logout request to remove a connection from a 8044 session or to close an entire session. 8046 After sending the Logout request PDU, an initiator MUST NOT send any 8047 new iSCSI requests on the closing connection. If the Logout request 8048 is intended to close the session, new iSCSI requests MUST NOT be 8049 sent on any of the connections participating in the session. 8051 When receiving a Logout request with the reason code of "close the 8052 connection" or "close the session", the target MUST terminate all 8053 pending commands, whether acknowledged via ExpCmdSN or not, on that 8054 connection or session respectively. 8056 When receiving a Logout request with the reason code "remove 8057 connection for recovery", the target MUST discard all requests not 8058 yet acknowledged via ExpCmdSN that were issued on the specified 8059 connection, and suspend all data/status/R2T transfers on behalf of 8060 pending commands on the specified connection. 8062 The target then issues the Logout response and half-closes the TCP 8063 connection (sends FIN). After receiving the Logout response and 8064 attempting to receive the FIN (if still possible), the initiator 8065 MUST completely close the logging-out connection. For the terminated 8066 commands, no additional responses should be expected. 8068 A Logout for a CID may be performed on a different transport 8069 connection when the TCP connection for the CID has already been 8070 terminated. In such a case, only a logical "closing" of the iSCSI 8071 connection for the CID is implied with a Logout. 8073 All commands that were not terminated or not completed (with status) 8074 and acknowledged when the connection is closed completely can be 8075 reassigned to a new connection if the target supports connection 8076 recovery. 8078 If an initiator intends to start recovery for a failing connection, 8079 it MUST use the Logout request to "clean-up" the target end of a 8080 failing connection and enable recovery to start, or the Login 8081 request with a non-zero TSIH and the same CID on a new connection 8082 for the same effect (see Section 10.14.3 CID). In sessions with a 8083 single connection, the connection can be closed and then a new 8084 connection reopened. A connection reinstatement login can be used 8085 for recovery (see Section 5.3.4 Connection Reinstatement). 8087 A successful completion of a logout request with the reason code of 8088 "close the connection" or "remove the connection for recovery" 8089 results at the target in the discarding of unacknowledged commands 8090 received on the connection being logged out. These are commands that 8091 have arrived on the connection being logged out, but have not been 8092 delivered to SCSI because one or more commands with a smaller CmdSN 8093 has not been received by iSCSI. See Section 3.2.2.1 Command 8095 Julian Satran Expires August 2003 157 8096 iSCSI 19-January-03 8098 Numbering and Acknowledging. The resulting holes the in command 8099 sequence numbers will have to be handled by appropriate recovery 8100 (see Chapter 6) unless the session is also closed. 8102 The entire logout discussion in this section is also applicable for 8103 an implicit Logout affected by way of a connection reinstatement or 8104 session reinstatement. When a Login Request performs an implicit 8105 Logout, the implicit Logout is performed as if having the reason 8106 codes specified below: 8108 Reason code Type of implicit Logout 8109 ------------------------------------------- 8110 0 session reinstatement 8111 1 connection reinstatement when 8112 the operational ErrorRecoveryLevel < 2 8113 2 connection reinstatement when 8114 the operational ErrorRecoveryLevel = 2 8116 Byte/ 0 | 1 | 2 | 3 | 8117 / | | | | 8118 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8119 +---------------+---------------+---------------+---------------+ 8120 0|.|I| 0x06 |1| Reason Code | Reserved | 8121 +---------------+---------------+---------------+---------------+ 8122 4|TotalAHSLength | DataSegmentLength | 8123 +---------------------------------------------------------------+ 8124 8/ Reserved / 8125 +/ / 8126 +---------------+---------------+---------------+---------------+ 8127 16| Initiator Task Tag | 8128 +---------------+---------------+---------------+---------------+ 8129 20| CID or Reserved | Reserved | 8130 +---------------+---------------+---------------+---------------+ 8131 24| CmdSN | 8132 +---------------+---------------+---------------+---------------+ 8133 28| ExpStatSN | 8134 +---------------+---------------+---------------+---------------+ 8135 32/ Reserved / 8136 +/ / 8137 +---------------+---------------+---------------+---------------+ 8138 48| Header-Digest (Optional) | 8139 +---------------+---------------+---------------+---------------+ 8141 10.14.1 Reason Code 8143 Reason Code indicates the reason for Logout as follows: 8145 0 - close the session. All commands associated with the session 8146 (if any) are terminated. 8148 1 - close the connection. All commands associated with 8149 connection (if any) are terminated. 8151 Julian Satran Expires August 2003 158 8152 iSCSI 19-January-03 8154 2 - remove the connection for recovery. Connection is closed and 8155 all commands associated with it, if any, are to be prepared 8156 for a new allegiance. 8158 All other values are reserved. 8160 10.14.2 TotalAHSLength and DataSegmentLength 8162 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 8164 10.14.3 CID 8166 This is the connection ID of the connection to be closed (including 8167 closing the TCP stream). This field is only valid if the reason code 8168 is not "close the session". 8170 10.14.4 ExpStatSN 8172 This is the last ExpStatSN value for the connection to be closed. 8174 10.14.5 Implicit termination of tasks 8176 A target implicitly terminates the active tasks due to the iSCSI 8177 protocol in the following cases: 8179 a) When a connection is implicitly or explicitly logged out 8180 with the reason code of "Close the connection" and there are 8181 active tasks allegiant to that connection. 8183 b) When a connection fails and eventually the connection state 8184 times out (state transition M1 in Section 7.2.2 State 8185 Transition Descriptions for Initiators and Targets) and there 8186 are active tasks allegiant to that connection. 8188 c) When a successful recovery Logout is performed while there 8189 are active tasks allegiant to that connection, and those tasks 8190 eventually time out after the Time2Wait and Time2Retain periods 8191 without allegiance reassignment. 8193 d) When a connection is implicitly or explicitly logged out 8194 with the reason code of "Close the session" and there are 8195 active tasks in that session. 8197 If the tasks terminated in any of the above cases are SCSI tasks, 8198 they must be internally terminated as if with CHECK CONDITION 8199 status. This status is only meaningful for appropriately handling 8200 the internal SCSI state and SCSI side effects with respect to 8201 ordering because this status is never communicated back as a 8202 terminating status to the initiator. However additional actions may 8203 have to be taken at SCSI level depending on the SCSI context as 8204 defined by the SCSI standards (e.g., queued commands and ACA, UA for 8206 Julian Satran Expires August 2003 159 8207 iSCSI 19-January-03 8209 the next command on the I_T nexus in cases a), b), and c) etc. - see 8210 [SAM] and [SPC3]). 8212 Julian Satran Expires August 2003 160 8213 iSCSI 19-January-03 8215 10.15 Logout Response 8217 The logout response is used by the target to indicate if the cleanup 8218 operation for the connection(s) has completed. 8220 After Logout, the TCP connection referred by the CID MUST be closed 8221 at both ends (or all connections must be closed if the logout reason 8222 was session close). 8224 Byte/ 0 | 1 | 2 | 3 | 8225 / | | | | 8226 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8227 +---------------+---------------+---------------+---------------+ 8228 0|.|.| 0x26 |1| Reserved | Response | Reserved | 8229 +---------------+---------------+---------------+---------------+ 8230 4|TotalAHSLength | DataSegmentLength | 8231 +---------------------------------------------------------------+ 8232 8/ Reserved / 8233 +/ / 8234 +---------------+---------------+---------------+---------------+ 8235 16| Initiator Task Tag | 8236 +---------------+---------------+---------------+---------------+ 8237 20| Reserved | 8238 +---------------+---------------+---------------+---------------+ 8239 24| StatSN | 8240 +---------------+---------------+---------------+---------------+ 8241 28| ExpCmdSN | 8242 +---------------+---------------+---------------+---------------+ 8243 32| MaxCmdSN | 8244 +---------------+---------------+---------------+---------------+ 8245 36| Reserved | 8246 +---------------------------------------------------------------+ 8247 40| Time2Wait | Time2Retain | 8248 +---------------+---------------+---------------+---------------+ 8249 44| Reserved | 8250 +---------------+---------------+---------------+---------------+ 8251 48| Header-Digest (Optional) | 8252 +---------------+---------------+---------------+---------------+ 8254 10.15.1 Response 8256 Logout response: 8258 0 - connection or session closed successfully. 8260 1 - CID not found. 8262 2 - connection recovery is not supported. If Logout reason code 8263 was recovery and target does not support it as indicated by 8264 the ErrorRecoveryLevel. 8266 3 - cleanup failed for various reasons. 8268 10.15.2 TotalAHSLength and DataSegmentLength 8270 For this PDU TotalAHSLength and DataSegmentLength MUST be 0. 8272 Julian Satran Expires August 2003 161 8273 iSCSI 19-January-03 8275 10.15.3 Time2Wait 8277 If the Logout response code is 0 and if the operational 8278 ErrorRecoveryLevel is 2, this is the minimum amount of time, in 8279 seconds, to wait before attempting task reassignment. If the Logout 8280 response code is 0 and if the operational ErrorRecoveryLevel is less 8281 than 2, this field is to be ignored. 8283 This field is invalid if the Logout response code is 1. 8285 If the Logout response code is 2 or 3, this field specifies the 8286 minimum time to wait before attempting a new implicit or explicit 8287 logout. 8289 If Time2Wait is 0, the reassignment or a new Logout may be attempted 8290 immediately. 8292 10.15.4 Time2Retain 8294 If the Logout response code is 0 and if the operational 8295 ErrorRecoveryLevel is 2, this is the maximum amount of time, in 8296 seconds, after the initial wait (Time2Wait), the target waits for 8297 the allegiance reassignment for any active task after which the task 8298 state is discarded. If the Logout response code is 0 and if the 8299 operational ErrorRecoveryLevel is less than 2, this field is to be 8300 ignored. 8302 This field is invalid if the Logout response code is 1. 8304 If the Logout response code is 2 or 3, this field specifies the 8305 maximum amount of time, in seconds, after the initial wait 8306 (Time2Wait), the target waits for a new implicit or explicit logout. 8308 If it is the last connection of a session, the whole session state 8309 is discarded after Time2Retain. 8311 If Time2Retain is 0, the target has already discarded the connection 8312 (and possibly the session) state along with the task states. No 8313 reassignment or Logout is required in this case. 8315 Julian Satran Expires August 2003 162 8316 iSCSI 19-January-03 8318 10.16 SNACK Request 8320 Byte/ 0 | 1 | 2 | 3 | 8321 / | | | | 8322 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8323 +---------------+---------------+---------------+---------------+ 8324 0|.|.| 0x10 |1|.|.|.| Type | Reserved | 8325 +---------------+---------------+---------------+---------------+ 8326 4|TotalAHSLength | DataSegmentLength | 8327 +---------------+---------------+---------------+---------------+ 8328 8| LUN or Reserved | 8329 + + 8330 12| | 8331 +---------------+---------------+---------------+---------------+ 8332 16| Initiator Task Tag or 0xffffffff | 8333 +---------------+---------------+---------------+---------------+ 8334 20| Target Transfer Tag or SNACK Tag or 0xffffffff | 8335 +---------------+---------------+---------------+---------------+ 8336 24| Reserved | 8337 +---------------+---------------+---------------+---------------+ 8338 28| ExpStatSN | 8339 +---------------+---------------+---------------+---------------+ 8340 32/ Reserved / 8341 +/ / 8342 +---------------+---------------+---------------+---------------+ 8343 40| BegRun | 8344 +---------------------------------------------------------------+ 8345 44| RunLength | 8346 +---------------------------------------------------------------+ 8347 48| Header-Digest (Optional) | 8348 +---------------+---------------+---------------+---------------+ 8350 If the implementation supports ErrorRecoveryLevel greater than zero, 8351 it MUST support all SNACK types. 8353 The SNACK is used by the initiator to request the retransmission of 8354 numbered-responses, data, or R2T PDUs from the target. The SNACK 8355 request indicates the numbered-responses or data "runs" whose 8356 retransmission is requested by the target, where the run starts with 8357 the first StatSN, DataSN, or R2TSN whose retransmission is requested 8358 and indicates the number of Status, Data, or R2T PDUs requested 8359 including the first. 0 has special meaning when used as a starting 8360 number and length: 8362 - When used in RunLength, it means all PDUs starting with the 8363 initial. 8364 - When used in both BegRun and RunLength, it means all 8365 unacknowledged PDUs. 8367 The numbered-response(s) or R2T(s), requested by a SNACK, MUST be 8368 delivered as exact replicas of the ones that the target transmitted 8369 originally except for the fields ExpCmdSN, MaxCmdSN, and ExpDataSN, 8370 which MUST carry the current values. R2T(s)requested by SNACK MUST 8371 also carry the current value of StatSN. 8373 Julian Satran Expires August 2003 163 8374 iSCSI 19-January-03 8376 The numbered Data-In PDUs, requested by a Data SNACK MUST be 8377 delivered as exact replicas of the ones that the target transmitted 8378 originally except for the fields ExpCmdSN and MaxCmdSN, which MUST 8379 carry the current values and except for resegmentation (see Section 8380 10.16.3 Resegmentation). 8382 Any SNACK that requests a numbered-response, Data, or R2T that was 8383 not sent by the target or was already acknowledged by the initiator, 8384 MUST be rejected with a reason code of "Protocol error". 8386 10.16.1 Type 8388 This field encodes the SNACK function as follows: 8390 0-Data/R2T SNACK - requesting retransmission of one or more 8391 Data-In or R2T PDUs. 8393 1-Status SNACK - requesting retransmission of one or more 8394 numbered responses. 8396 2-DataACK - positively acknowledges Data-In PDUs. 8398 3-R-Data SNACK - requesting retransmission of Data-In PDUs with 8399 possible resegmentation and status tagging. 8401 All other values are reserved. 8403 Data/R2T SNACK, Status SNACK, or R-Data SNACK for a command MUST 8404 precede status acknowledgement for the given command. 8406 10.16.2 Data Acknowledgement 8408 If an initiator operates at ErrorRecoveryLevel 1 or higher, it MUST 8409 issue a SNACK of type DataACK after receiving a Data-In PDU with the 8410 A bit set to 1. However, if the initiator has detected holes in the 8411 input sequence, it MUST postpone issuing the SNACK of type DataACK 8412 until the holes are filled. An initiator MAY ignore the A bit if it 8413 deems that the bit is being set aggressively by the target (i.e., 8414 before the MaxBurstLength limit is reached). 8416 The DataACK is used to free resources at the target and not to 8417 request or imply data retransmission. 8419 An initiator MUST NOT request retransmission for any data it had 8420 already acknowledged. 8422 10.16.3 Resegmentation 8424 If the initiator MaxRecvDataSegmentLength changed between the 8425 original transmission and the time the initiator requests 8426 retransmission, the initiator MUST issue a R-Data SNACK (see Section 8427 10.16.1 Type). With R-Data SNACK, the initiator indicates that it 8428 discards all the unacknowledged data and expects the target to 8429 resend it. It also expects resegmentation. In this case, the 8430 retransmitted Data-In PDUs MAY be different from the ones originally 8432 Julian Satran Expires August 2003 164 8433 iSCSI 19-January-03 8435 sent in order to reflect changes in MaxRecvDataSegmentLength. Their 8436 DataSN starts with the BegRun of the last DataACK received by the 8437 target if any was received; otherwise it starts with 0 and is 8438 increased by 1 for each resent Data-In PDU. 8440 A target that has received a R-Data SNACK MUST return a SCSI 8441 Response 8442 that contains a copy of the SNACK Tag field from the R-Data SNACK in 8443 the SCSI Response SNACK Tag field as its last or only Response. For 8444 example, if it has already sent a response containing another value 8445 in the SNACK Tag field or had the status included in the last Data- 8446 In PDU, it must send a new SCSI Response PDU. If a target sends more 8447 than one SCSI Response PDU due to this rule, all SCSI responses must 8448 carry the same StatSN (see Section 10.4.4 SNACK Tag). If an 8449 initiator attempts to recover a lost SCSI Response (with a Status- 8450 SNACK, see Section 10.16.1 Type) when more than one response has 8451 been sent, the target will send the SCSI Response with the latest 8452 content known to the target, including the last SNACK Tag for the 8453 command. 8455 For considerations in allegiance reassignment of a task to a 8456 connection with a different MaxRecvDataSegmentLength, refer to 8457 Section 6.2.2 Allegiance Reassignment. 8459 10.16.4 Initiator Task Tag 8461 For Status SNACK and DataACK, the Initiator Task Tag MUST be set to 8462 the reserved value 0xffffffff. In all other cases, the Initiator 8463 Task Tag field MUST be set to the Initiator Task Tag of the 8464 referenced command. 8466 10.16.5 Target Transfer Tag or SNACK Tag 8468 For an R-Data SNACK, this field MUST contain a value that is 8469 different from 0 or 0xffffffff and is unique for the task 8470 (identified by the Initiator Task Tag). This value MUST be copied by 8471 the iSCSI target in the last or only SCSI Response PDU it issues for 8472 the command. 8474 For DataACK, the Target Transfer Tag MUST contain a copy of the 8475 Target Transfer Tag and LUN provided with the SCSI Data-In PDU with 8476 the A bit set to 1. 8478 In all other cases, the Target Transfer Tag field MUST be set to the 8479 reserved value of 0xffffffff. 8481 10.16.6 BegRun 8483 The DataSN, R2TSN, or StatSN of the first PDU whose retransmission 8484 is requested (Data/R2T and Status SNACK), or the next expected 8485 DataSN (DataACK SNACK). 8487 BegRun 0 when used in conjunction with RunLength 0 means resend all 8488 unacknowledged Data-In, R2T or Response PDUs. 8490 Julian Satran Expires August 2003 165 8491 iSCSI 19-January-03 8493 BegRun MUST be 0 for a R-Data SNACK. 8495 10.16.7 RunLength 8497 The number of PDUs whose retransmission is requested. 8499 RunLength 0 signals that all Data-In, R2T, or Response PDUs carrying 8500 the numbers equal to or greater than BegRun have to be resent. 8502 The RunLength MUST also be 0 for a DataACK SNACK in addition to R- 8503 Data SNACK. 8505 Julian Satran Expires August 2003 166 8506 iSCSI 19-January-03 8508 10.17 Reject 8510 Byte/ 0 | 1 | 2 | 3 | 8511 / | | | | 8512 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8513 +---------------+---------------+---------------+---------------+ 8514 0|.|.| 0x3f |1| Reserved | Reason | Reserved | 8515 +---------------+---------------+---------------+---------------+ 8516 4|TotalAHSLength | DataSegmentLength | 8517 +---------------+---------------+---------------+---------------+ 8518 8/ Reserved / 8519 +/ / 8520 +---------------+---------------+---------------+---------------+ 8521 16| 0xffffffff | 8522 +---------------+---------------+---------------+---------------+ 8523 20| Reserved | 8524 +---------------+---------------+---------------+---------------+ 8525 24| StatSN | 8526 +---------------+---------------+---------------+---------------+ 8527 28| ExpCmdSN | 8528 +---------------+---------------+---------------+---------------+ 8529 32| MaxCmdSN | 8530 +---------------+---------------+---------------+---------------+ 8531 36| DataSN/R2TSN or Reserved | 8532 +---------------+---------------+---------------+---------------+ 8533 40| Reserved | 8534 +---------------+---------------+---------------+---------------+ 8535 44| Reserved | 8536 +---------------+---------------+---------------+---------------+ 8537 48| Header-Digest (Optional) | 8538 +---------------+---------------+---------------+---------------+ 8539 xx/ Complete Header of Bad PDU / 8540 +/ / 8541 +---------------+---------------+---------------+---------------+ 8542 yy/Vendor specific data (if any) / 8543 / / 8544 +---------------+---------------+---------------+---------------+ 8545 zz| Data-Digest (Optional) | 8546 +---------------+---------------+---------------+---------------+ 8548 Reject is used to indicate an iSCSI error condition (protocol, 8549 unsupported option, etc.). 8551 10.17.1 Reason 8553 The reject Reason is coded as follows: 8555 Julian Satran Expires August 2003 167 8556 iSCSI 19-January-03 8558 +------+----------------------------------------+------------------+ 8559 | Code | Explanation | Can the original | 8560 | (hex)| | PDU be re-sent? | 8561 +------+----------------------------------------+------------------+ 8562 | 0x01 | Reserved | no | 8563 | | | | 8564 | 0x02 | Data (payload) Digest Error | yes (Note 1) | 8565 | | | | 8566 | 0x03 | SNACK Reject | yes | 8567 | | | | 8568 | 0x04 | Protocol Error (e.g., SNACK request for| no | 8569 | | a status that was already acknowledged)| | 8570 | | | | 8571 | 0x05 | Command not supported | no | 8572 | | | | 8573 | 0x06 | Immediate Command Reject - too many | yes | 8574 | | immediate commands | | 8575 | | | | 8576 | 0x07 | Task in progress | no | 8577 | | | | 8578 | 0x08 | Invalid Data ACK | no | 8579 | | | | 8580 | 0x09 | Invalid PDU field | no (Note 2) | 8581 | | | | 8582 | 0x0a | Long Operation Reject - Can't generate | yes | 8583 | | Target Transfer Tag - out of resources | | 8584 | | | | 8585 | 0x0b | Negotiation Reset | no | 8586 | | | | 8587 | 0x0c | Waiting for Logout | no | 8588 +------+----------------------------------------+------------------+ 8590 Note 1: For iSCSI, Data-Out PDU retransmission is only done if the 8591 target requests retransmission with a recovery R2T. However, if this 8592 is the data digest error on immediate data, the initiator may choose 8593 to retransmit the whole PDU including the immediate data. 8595 Note 2: A target should use this reason code for all invalid values 8596 of PDU fields that are meant to describe a task, a response, or a 8597 data transfer. Some examples are invalid TTT/ITT, buffer offset, 8598 LUN qualifying a TTT, and an invalid sequence number in a SNACK. 8600 All other values for Reason are reserved. 8602 In all the cases in which a pre-instantiated SCSI task is terminated 8603 because of the reject, the target MUST issue a proper SCSI command 8604 response with CHECK CONDITION as described in Section 10.4.3 8605 Response. In these cases in which a status for the SCSI task was 8606 already sent before the reject, no additional status is required. If 8607 the error is detected while data from the initiator is still 8608 expected (i.e., the command PDU did not contain all the data and the 8609 target has not received a Data-out PDU with the Final bit set to 1 8610 for the unsolicited data, if any, and all outstanding R2Ts, if any), 8611 the target MUST wait until it receives the last expected Data-out 8612 PDUs with the F bit set to 1 before sending the Response PDU. 8614 Julian Satran Expires August 2003 168 8615 iSCSI 19-January-03 8617 For additional usage semantics of Reject PDU, see Section 6.3 Usage 8618 Of Reject PDU in Recovery. 8620 10.17.2 DataSN/R2TSN 8622 This field is only valid if the rejected PDU is a Data/R2T SNACK and 8623 the Reject reason code is "Protocol error" (see Section 10.16 SNACK 8624 Request). The DataSN/R2TSN is the next Data/R2T sequence number 8625 that the target would send for the task, if any. 8627 10.17.3 StatSN, ExpCmdSN and MaxCmdSN 8629 These fields carry their usual values and are not related to the 8630 rejected command 8632 10.17.4 Complete Header of Bad PDU 8634 The target returns the header (not including digest) of the PDU in 8635 error as the data of the response. 8637 Julian Satran Expires August 2003 169 8638 iSCSI 19-January-03 8640 10.18 NOP-Out 8642 Byte/ 0 | 1 | 2 | 3 | 8643 / | | | | 8644 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8645 +---------------+---------------+---------------+---------------+ 8646 0|.|I| 0x00 |1| Reserved | 8647 +---------------+---------------+---------------+---------------+ 8648 4|TotalAHSLength | DataSegmentLength | 8649 +---------------+---------------+---------------+---------------+ 8650 8| LUN or Reserved | 8651 + + 8652 12| | 8653 +---------------+---------------+---------------+---------------+ 8654 16| Initiator Task Tag or 0xffffffff | 8655 +---------------+---------------+---------------+---------------+ 8656 20| Target Transfer Tag or 0xffffffff | 8657 +---------------+---------------+---------------+---------------+ 8658 24| CmdSN | 8659 +---------------+---------------+---------------+---------------+ 8660 28| ExpStatSN | 8661 +---------------+---------------+---------------+---------------+ 8662 32/ Reserved / 8663 +/ / 8664 +---------------+---------------+---------------+---------------+ 8665 48| Header-Digest (Optional) | 8666 +---------------+---------------+---------------+---------------+ 8667 / DataSegment - Ping Data (optional) / 8668 +/ / 8669 +---------------+---------------+---------------+---------------+ 8670 | Data-Digest (Optional) | 8671 +---------------+---------------+---------------+---------------+ 8673 A NOP-Out may be used by an initiator as a "ping request" to verify 8674 that a connection/session is still active and all its components are 8675 operational. The NOP-In response is the "ping echo". 8677 A NOP-Out is also sent by an initiator in response to a NOP-In. 8679 A NOP-Out may also be used to confirm a changed ExpStatSN if another 8680 PDU will not be available for a long time. 8682 Upon receipt of a NOP-In with the Target Transfer Tag set to a valid 8683 value (not the reserved 0xffffffff), the initiator MUST respond with 8684 a NOP-Out. In this case, the NOP-Out Target Transfer Tag MUST 8685 contain a copy of the NOP-In Target Transfer Tag. 8687 10.18.1 Initiator Task Tag 8689 The NOP-Out MUST have the Initiator Task Tag set to a valid value 8690 only if a response in the form of NOP-In is requested (i.e., the 8691 NOP-Out is used as a ping request). Otherwise, the Initiator Task 8692 Tag MUST be set to 0xffffffff. 8694 When a target receives the NOP-Out with a valid Initiator Task Tag, 8695 it MUST respond with a Nop-In Response (see Section 10.19 NOP-In). 8697 Julian Satran Expires August 2003 170 8698 iSCSI 19-January-03 8700 If the Initiator Task Tag contains 0xffffffff, the I bit MUST be set 8701 to 1 and the CmdSN is not advanced after this PDU is sent. 8703 10.18.2 Target Transfer Tag 8705 A target assigned identifier for the operation. 8707 The NOP-Out MUST only have the Target Transfer Tag set if it is 8708 issued in response to a NOP-In with a valid Target Transfer Tag. In 8709 this case, it copies the Target Transfer Tag from the NOP-In PDU. 8710 Otherwise, the Target Transfer Tag MUST be set to 0xffffffff. 8712 When the Target Transfer Tag is set to a value other than 8713 0xffffffff, the LUN field MUST also be copied from the NOP-In. 8715 10.18.3 Ping Data 8717 Ping data are reflected in the NOP-In Response. The length of the 8718 reflected data are limited to MaxRecvDataSegmentLength. The length 8719 of ping data are indicated by the DataSegmentLength. 0 is a valid 8720 value for the DataSegmentLength and indicates the absence of ping 8721 data. 8723 Julian Satran Expires August 2003 171 8724 iSCSI 19-January-03 8726 10.19 NOP-In 8728 Byte/ 0 | 1 | 2 | 3 | 8729 / | | | | 8730 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 8731 +---------------+---------------+---------------+---------------+ 8732 0|.|.| 0x20 |1| Reserved | 8733 +---------------+---------------+---------------+---------------+ 8734 4|TotalAHSLength | DataSegmentLength | 8735 +---------------+---------------+---------------+---------------+ 8736 8| LUN or Reserved | 8737 + + 8738 12| | 8739 +---------------+---------------+---------------+---------------+ 8740 16| Initiator Task Tag or 0xffffffff | 8741 +---------------+---------------+---------------+---------------+ 8742 20| Target Transfer Tag or 0xffffffff | 8743 +---------------+---------------+---------------+---------------+ 8744 24| StatSN | 8745 +---------------+---------------+---------------+---------------+ 8746 28| ExpCmdSN | 8747 +---------------+---------------+---------------+---------------+ 8748 32| MaxCmdSN | 8749 +---------------+---------------+---------------+---------------+ 8750 36/ Reserved / 8751 +/ / 8752 +---------------+---------------+---------------+---------------+ 8753 48| Header-Digest (Optional) | 8754 +---------------+---------------+---------------+---------------+ 8755 / DataSegment - Return Ping Data / 8756 +/ / 8757 +---------------+---------------+---------------+---------------+ 8758 | Data-Digest (Optional) | 8759 +---------------+---------------+---------------+---------------+ 8761 NOP-In is either sent by a target as a response to a NOP-Out, as a 8762 "ping" to an initiator, or as a means to carry a changed ExpCmdSN 8763 and/or MaxCmdSN if another PDU will not be available for a long time 8764 (as determined by the target). 8766 When a target receives the NOP-Out with a valid Initiator Task Tag 8767 (not the reserved value 0xffffffff), it MUST respond with a NOP-In 8768 with the same Initiator Task Tag that was provided in the NOP-Out 8769 request. It MUST also duplicate up to the first 8770 MaxRecvDataSegmentLength bytes of the initiator provided Ping Data. 8771 For such a response, the Target Transfer Tag MUST be 0xffffffff. 8773 Otherwise, when a target sends a NOP-In that is not a response to a 8774 Nop-Out received from the initiator, the Initiator Task Tag MUST be 8775 set to 0xffffffff and the Data Segment MUST NOT contain any data 8776 (DataSegmentLength MUST be 0). 8778 Julian Satran Expires August 2003 172 8779 iSCSI 19-January-03 8781 10.19.1 Target Transfer Tag 8783 If the target is responding to a NOP-Out, this is set to the 8784 reserved value 0xffffffff. 8786 If the target is sending a NOP-In as a Ping (intending to receive a 8787 corresponding NOP-Out), this field is set to a valid value (not the 8788 reserved 0xffffffff). 8790 If the target is initiating a NOP-In without wanting to receive a 8791 corresponding NOP-Out, this field MUST hold the reserved value of 8792 0xffffffff. 8794 10.19.2 StatSN 8796 The StatSN field will always contain the next StatSN. However, when 8797 the Initiator Task Tag is set to 0xffffffff StatSN for the 8798 connection is not advanced after this PDU is sent. 8800 10.19.3 LUN 8802 A LUN MUST be set to a correct value when the Target Transfer Tag is 8803 valid (not the reserved value 0xffffffff). 8805 Julian Satran Expires August 2003 173 8806 iSCSI 19-January-03 8808 11. iSCSI Security Text Keys and Authentication Methods 8810 Only the following keys are used during the SecurityNegotiation 8811 stage of the Login Phase: 8813 SessionType 8814 InitiatorName 8815 TargetName 8816 TargetAddress 8817 InitiatorAlias 8818 TargetAlias 8819 TargetPortalGroupTag 8820 AuthMethod and the keys used by the authentication methods 8821 specified under Section 11.1 AuthMethod along with all of 8822 their associated keys as well as Vendor Specific 8823 Authentication Methods. 8825 NO OTHER keys MAY be used. 8827 SessionType, InitiatorName, TargetName, InitiatorAlias, TargetAlias, 8828 and TargetPortalGroupTag are described in Chapter 12 as they can be 8829 used also in the OperationalNegotiation stage. 8831 All security keys have connection-wide applicability. 8833 11.1 AuthMethod 8835 Use: During Login - Security Negotiation 8836 Senders: Initiator and Target 8837 Scope: connection 8839 AuthMethod = 8841 The main item of security negotiation is the authentication method 8842 (AuthMethod). 8844 The authentication methods that can be used (appear in the list-of- 8845 values) are either those listed in the following table or are 8846 vendor-unique methods: 8848 Julian Satran Expires August 2003 174 8849 iSCSI 19-January-03 8851 +------------------------------------------------------------+ 8852 | Name | Description | 8853 +------------------------------------------------------------+ 8854 | KRB5 | Kerberos V5 - defined in [RFC1510] | 8855 +------------------------------------------------------------+ 8856 | SPKM1 | Simple Public-Key GSS-API Mechanism | 8857 | | defined in [RFC2025] | 8858 +------------------------------------------------------------+ 8859 | SPKM2 | Simple Public-Key GSS-API Mechanism | 8860 | | defined in [RFC2025] | 8861 +------------------------------------------------------------+ 8862 | SRP | Secure Remote Password | 8863 | | defined in [RFC2945] | 8864 +------------------------------------------------------------+ 8865 | CHAP | Challenge Handshake Authentication Protocol| 8866 | | defined in [RFC1994] | 8867 +------------------------------------------------------------+ 8868 | None | No authentication | 8869 +------------------------------------------------------------+ 8871 The AuthMethod selection is followed by an "authentication exchange" 8872 specific to the authentication method selected. 8874 The authentication method proposal may be made by either the 8875 initiator or the target. However the initiator MUST make the first 8876 step specific to the selected authentication method as soon as it is 8877 selected. It follows that if the target makes the authentication 8878 method proposal the initiator sends the first keys(s) of the 8879 exchange together with its authentication method selection. 8881 The authentication exchange authenticates the initiator to the 8882 target, and optionally, the target to the initiator. Authentication 8883 is OPTIONAL to use but MUST be supported by the target and 8884 initiator. 8886 The initiator and target MUST implement CHAP. All other 8887 authentication methods are OPTIONAL. 8889 Private or public extension algorithms MAY also be negotiated for 8890 authentication methods. Whenever a private or public extension 8891 algorithm is part of the default offer (the offer made in absence of 8892 explicit administrative action) the implementer MUST ensure that 8893 CHAP is listed as an alternative in the default offer and "None" is 8894 not part of the default offer. 8896 Extension authentication methods MUST be named using one of the 8897 following two formats: 8899 a) Z-reversed.vendor.dns_name.do_something= 8900 b) Z<#>= 8902 Authentication methods named using the Z- format are used as private 8903 extensions. Authentication methods named using the Z# format are 8905 Julian Satran Expires August 2003 175 8906 iSCSI 19-January-03 8908 used as public extensions that must be registered with IANA and MUST 8909 be described by an informational RFC. 8911 For all of the public or private extension authentication methods, 8912 the method specific keys MUST conform to the format specified in 8913 Section 5.1 Text Format for standard-label. 8915 To identify the vendor for private extension authentication methods, 8916 we suggest you use the reversed DNS-name as a prefix to the proper 8917 digest names. 8919 The part of digest-name following Z- and Z# MUST conform to the 8920 format for standard-label specified in Section 5.1 Text Format. 8922 Support for public or private extension authentication methods is 8923 OPTIONAL. 8925 The following subsections define the specific exchanges for each of 8926 the standardized authentication methods. As mentioned earlier the 8927 first step is always done by the initiator. 8929 11.1.1 Kerberos 8931 For KRB5 (Kerberos V5) [RFC1510], the initiator MUST use: 8933 KRB_AP_REQ= 8935 where KRB_AP_REQ is the client message as defined in [RFC1510]. 8937 The default principal name assumed by an iSCSI initiator or target 8938 (prior to any administrative configuration action) MUST be the iSCSI 8939 Initiator Name or iSCSI Target Name respectively, prefixed by the 8940 string "iscsi/". 8942 If the initiator authentication fails, the target MUST respond with 8943 a Login reject with "Authentication Failure" status. Otherwise, if 8944 the initiator has selected the mutual authentication option (by 8945 setting MUTUAL-REQUIRED in the ap-options field of the KRB_AP_REQ), 8946 the target MUST reply with: 8948 KRB_AP_REP= 8950 where KRB_AP_REP is the server's response message as defined in 8951 [RFC1510]. 8953 If mutual authentication was selected and target authentication 8954 fails, the initiator MUST close the connection. 8956 KRB_AP_REQ and KRB_AP_REP are binary-values and their binary length 8957 (not the length of the character string that represents them in 8958 encoded form) MUST not exceed 65536 bytes. 8960 11.1.2 Simple Public-Key Mechanism (SPKM) 8962 For SPKM1 and SPKM2 [RFC2025], the initiator MUST use: 8964 Julian Satran Expires August 2003 176 8965 iSCSI 19-January-03 8967 SPKM_REQ= 8969 where SPKM-REQ is the first initiator token as defined in [RFC2025]. 8971 [RFC2025] defines situations where each side may send an error token 8972 that may cause the peer to re-generate and resend its last token. 8973 This scheme is followed in iSCSI, and the error token syntax is: 8975 SPKM_ERROR= 8977 However, SPKM-DEL tokens that are defined by [RFC2025] for fatal 8978 errors will not be used by iSCSI. If the target needs to send a 8979 SPKM-DEL token, it will, instead, send a Login "login reject" 8980 message with the "Authentication Failure" status and terminate the 8981 connection. If the initiator needs to send a SPKM-DEL token, it will 8982 close the connection. 8984 In the following sections, we assume that no SPKM-ERROR tokens are 8985 required. 8987 If the initiator authentication fails, the target MUST return an 8988 error. Otherwise, if the AuthMethod is SPKM1 or if the initiator has 8989 selected the mutual authentication option (by setting mutual-state 8990 bit in the options field of the REQ-TOKEN in the SPKM-REQ), the 8991 target MUST reply with: 8993 SPKM_REP_TI= 8995 where SPKM-REP-TI is the target token as defined in [RFC2025]. 8997 If mutual authentication was selected and target authentication 8998 fails, the initiator MUST close the connection. Otherwise, if the 8999 AuthMethod is SPKM1, the initiator MUST continue with: 9001 SPKM_REP_IT= 9003 where SPKM-REP-IT is the second initiator token as defined in 9004 [RFC2025]. If the initiator authentication fails, the target MUST 9005 answer with a Login reject with "Authentication Failure" status. 9007 SPKM requires support for very long authentication items. 9009 All the SPKM-* tokens are binary-values and their binary length (not 9010 the length of the character string that represents them in encoded 9011 form) MUST not exceed 65536 bytes. 9013 11.1.3 Secure Remote Password (SRP) 9015 For SRP [RFC2945], the initiator MUST use: 9017 SRP_U= TargetAuth=Yes /* or TargetAuth=No */ 9019 The target MUST answer with a Login reject with the "Authorization 9020 Failure" status or reply with: 9022 Julian Satran Expires August 2003 177 9023 iSCSI 19-January-03 9025 SRP_GROUP= SRP_s= 9027 Where G1,G2... are proposed groups, in order of preference. 9029 The initiator MUST either close the connection or continue with: 9031 SRP_A= SRP_GROUP= 9033 Where G is one of G1,G2... that were proposed by the target. 9035 The target MUST answer with a Login reject with the "Authentication 9036 Failure" status or reply with: 9038 SRP_B= 9040 The initiator MUST close the connection or continue with: 9042 SRP_M= 9044 If the initiator authentication fails, the target MUST answer with a 9045 Login reject with "Authentication Failure" status. Otherwise, if the 9046 initiator sent TargetAuth=Yes in the first message (requiring target 9047 authentication), the target MUST reply with: 9049 SRP_HM= 9051 If the target authentication fails, the initiator MUST close the 9052 connection. 9054 Where U, s, A, B, M, and H(A | M | K) are defined in [RFC2945] 9055 (using the SHA1 hash function, such as SRP-SHA1) and G,Gn (Gn stands 9056 for G1,G2...) are identifiers of SRP groups specified in [SEC-IPS]. 9057 G, Gn, and U are text strings, s,A,B,M, and H(A | M | K) are binary- 9058 values. The length of s,A,B,M and H(A | M | K) in binary form (not 9059 the length of the character string that represents them in encoded 9060 form) MUST not exceed 1024 bytes. 9062 For the SRP_GROUP, all the groups specified in [SEC-IPS] up to 1536 9063 bits (i.e., SRP-768, SRP-1024, SRP-1280, SRP-1536) must be supported 9064 by initiators and targets. To guarantee interoperability, targets 9065 MUST always offer "SRP-1536" as one of the proposed groups. 9067 11.1.4 Challenge Handshake Authentication Protocol (CHAP) 9069 For CHAP [RFC1994], the initiator MUST use: 9071 CHAP_A= 9073 Where A1,A2... are proposed algorithms, in order of preference. 9075 The target MUST answer with a Login reject with the "Authentication 9076 Failure" status or reply with: 9078 CHAP_A= CHAP_I= CHAP_C= 9080 Julian Satran Expires August 2003 178 9081 iSCSI 19-January-03 9083 Where A is one of A1,A2... that were proposed by the initiator. 9085 The initiator MUST continue with: 9087 CHAP_N= CHAP_R= 9089 or, if it requires target authentication, with: 9091 CHAP_N= CHAP_R= CHAP_I= CHAP_C= 9093 If the initiator authentication fails, the target MUST answer with a 9094 Login reject with "Authentication Failure" status. Otherwise, if the 9095 initiator required target authentication, the target MUST either 9096 answer with a Login reject with "Authentication Failure" or reply 9097 with: 9099 CHAP_N= CHAP_R= 9101 If target authentication fails, the initiator MUST close the 9102 connection. 9104 Where N, (A,A1,A2), I, C, and R are (correspondingly) the Name, 9105 Algorithm, Identifier, Challenge, and Response as defined in 9106 [RFC1994], N is a text string, A,A1,A2, and I are numbers, and C and 9107 R are binary-values and their binary length (not the length of the 9108 character string that represents them in encoded form) MUST not 9109 exceed 1024 bytes. 9111 For the Algorithm, as stated in [RFC1994], one value is required 9112 to be implemented: 9114 5 (CHAP with MD5) 9116 To guarantee interoperability, initiators MUST always offer it as 9117 one of the proposed algorithms. 9119 Julian Satran Expires August 2003 179 9120 iSCSI 19-January-03 9122 12. Login/Text Operational Text Keys 9124 Some session specific parameters MUST only be carried on the leading 9125 connection and cannot be changed after the leading connection login 9126 (e.g., MaxConnections, the maximum number of connections). This 9127 holds for a single connection session with regard to connection 9128 restart. The keys that fall into this category have the use: LO 9129 (Leading Only). 9131 Keys that can only be used during login have the use: IO (initialize 9132 only), while those that can be used in both the Login Phase and Full 9133 Feature Phase have the use: ALL. 9135 Keys that can only be used during Full Feature Phase use FFPO (Full 9136 Feature Phase only). 9138 Keys marked as Any-Stage may also appear in the SecurityNegotiation 9139 stage while all other keys described in this chapter are operational 9140 keys. 9142 Keys that do not require an answer are marked as Declarative 9144 Key scope is indicated as session-wide (SW) or connection-only (CO). 9146 Result function, wherever mentioned, states the function that can be 9147 applied to check the validity of the responder selection. Minimum 9148 means that the selected value cannot exceed the offered value. 9149 Maximum means that the selected value cannot be lower than the 9150 offered value. AND means that the selected value must be a possible 9151 result of a Boolean "and" function with an arbitrary Boolean value 9152 (e.g., if the offered value is No the selected value must be No). OR 9153 means that the selected value must be a possible result of a Boolean 9154 "or" function with an arbitrary Boolean value (e.g., if the offered 9155 value is Yes the selected value must be Yes). 9157 12.1 HeaderDigest and DataDigest 9159 Use: IO 9160 Senders: Initiator and Target 9161 Scope: CO 9163 HeaderDigest = 9164 DataDigest = 9166 Default is None for both HeaderDigest and DataDigest. 9168 Digests enable the checking of end-to-end, non-cryptographic data 9169 integrity beyond the integrity checks provided by the link layers 9170 and the covering of the whole communication path including all 9171 elements that may change the network level PDUs such as routers, 9172 switches, and proxies. 9174 The following table lists cyclic integrity checksums that can be 9175 negotiated for the digests and that MUST be implemented by every 9176 iSCSI initiator and target. These digest options only have error 9177 detection significance. 9179 Julian Satran Expires August 2003 180 9180 iSCSI 19-January-03 9182 +---------------------------------------------+ 9183 | Name | Description | Generator | 9184 +---------------------------------------------+ 9185 | CRC32C | 32 bit CRC |0x11edc6f41| 9186 +---------------------------------------------+ 9187 | None | no digest | 9188 +---------------------------------------------+ 9190 The generator polynomial for this digest is given in hex- 9191 notation(e.g., 0x3b stands for 0011 1011 and the polynomial is 9192 x**5+X**4+x**3+x+1). 9194 When the Initiator and Target agree on a digest, this digest MUST be 9195 used for every PDU in Full Feature Phase. 9197 Padding bytes, when present in a segment covered by a CRC, SHOULD be 9198 set to 0 and are included in the CRC. 9200 The CRC MUST be calculated by a method that produces the same 9201 results as the following process: 9203 - The PDU bits are considered as the coefficients of a 9204 polynomial M(x) of degree n-1; bit 7 of the lowest numbered 9205 byte is considered the most significant bit (x^n-1), followed 9206 by bit 6 of the lowest numbered byte through bit 0 of the 9207 highest numbered byte (x^0). 9209 - The most significant 32 bits are complemented. 9211 - The polynomial is multiplied by x^32 then divided by G(x). The 9212 generator polynomial produces a remainder R(x) of degree <= 9213 31. 9215 - The coefficients of R(x) are considered a 32 bit sequence. 9217 - The bit sequence is complemented and the result is the CRC. 9219 - The CRC bits are mapped into the digest word. The x^31 9220 coefficient in bit 7 of the lowest numbered byte of the digest 9221 continuing through to the byte up to the x^24 coefficient in 9222 bit 0 of the lowest numbered byte, continuing with the x^23 9223 coefficient in bit 7 of next byte through x^0 in bit 0 of the 9224 highest numbered byte. 9226 - Computing the CRC over any segment (data or header) extended 9227 to include the CRC built using the generator 0x11edc6f41 will 9228 always get the value 0x1c2d19ed as its final remainder (R(x)). 9229 This value is given here in its polynomial form (i.e., not 9230 mapped as the digest word). 9232 For a discussion about selection criteria for the CRC, see [iSCSI- 9233 CRC]. For a detailed analysis of the iSCSI polynomial, see 9234 [Castagnoli93]. 9236 Julian Satran Expires August 2003 181 9237 iSCSI 19-January-03 9239 Private or public extension algorithms MAY also be negotiated for 9240 digests. Whenever a private or public digest extension algorithm is 9241 part of the default offer (the offer made in absence of explicit 9242 administrative action) the implementer MUST ensure that CRC32C is 9243 listed as an alternative in the default offer and "None" is not 9244 part of the default offer. 9246 Extension digest algorithms MUST be named using one of the following 9247 two formats: 9249 a) Y-reversed.vendor.dns_name.do_something= 9250 b) Y<#>= 9252 Digests named using the Y- format are used for private purposes 9253 (unregistered). Digests named using the Y# format (public extension) 9254 must be registered with IANA and MUST be described by an 9255 informational RFC. 9257 For private extension digests, to identify the vendor, we suggest 9258 you use the reversed DNS-name as a prefix to the proper digest 9259 names. 9261 The part of digest-name following Y- and Y# MUST conform to the 9262 format for standard-label specified in Section 5.1 Text Format. 9264 Support for public or private extension digests is OPTIONAL. 9266 12.2 MaxConnections 9268 Use: LO 9269 Senders: Initiator and Target 9270 Scope: SW 9271 Irrelevant when: SessionType=Discovery 9273 MaxConnections= 9275 Default is 1. 9276 Result function is Minimum. 9278 Initiator and target negotiate the maximum number of connections 9279 requested/acceptable. 9281 12.3 SendTargets 9283 Use: FFPO 9284 Senders: Initiator 9285 Scope: SW 9287 For a complete description, see Appendix D. - SendTargets Operation 9288 -. 9290 12.4 TargetName 9292 Use: IO by initiator, FFPO by target - only as response to a 9293 SendTargets, Declarative, Any-Stage 9295 Julian Satran Expires August 2003 182 9296 iSCSI 19-January-03 9298 Senders: Initiator and Target 9299 Scope: SW 9301 TargetName= 9303 Examples: 9305 TargetName=iqn.1993-11.com.disk-vendor:diskarrays.sn.45678 9306 TargetName=eui.020000023B040506 9308 The initiator of the TCP connection MUST provide this key to the 9309 remote endpoint in the first login request if the initiator is not 9310 establishing a discovery session. The iSCSI Target Name specifies 9311 the worldwide unique name of the target. 9313 The TargetName key may also be returned by the "SendTargets" text 9314 request (which is its only use when issued by a target). 9316 TargetName MUST not be redeclared within the login phase. 9318 12.5 InitiatorName 9320 Use: IO, Declarative, Any-Stage 9321 Senders: Initiator 9322 Scope: SW 9324 InitiatorName= 9326 Examples: 9328 InitiatorName=iqn.1992-04.com.os-vendor.plan9:cdrom.12345 9329 InitiatorName=iqn.2001-02.com.ssp.users:customer235.host90 9331 The initiator of the TCP connection MUST provide this key to the 9332 remote endpoint at the first Login of the Login Phase for every 9333 connection. The InitiatorName key enables the initiator to identify 9334 itself to the remote endpoint. 9336 InitiatorName MUST not be redeclared within the login phase. 9338 12.6 TargetAlias 9340 Use: ALL, Declarative, Any-Stage 9341 Senders: Target 9342 Scope: SW 9344 TargetAlias= 9346 Examples: 9348 TargetAlias=Bob-s Disk 9349 TargetAlias=Database Server 1 Log Disk 9350 TargetAlias=Web Server 3 Disk 20 9352 If a target has been configured with a human-readable name or 9353 description, this name SHOULD be communicated to the initiator 9355 Julian Satran Expires August 2003 183 9356 iSCSI 19-January-03 9358 during a Login Response PDU if SessionType=Normal (see Section 12.21 9359 SessionType). This string is not used as an identifier, nor is it 9360 meant to be used for authentication or authorization decisions. It 9361 can be displayed by the initiator's user interface in a list of 9362 targets to which it is connected. 9364 12.7 InitiatorAlias 9366 Use: ALL, Declarative, Any-Stage 9367 Senders: Initiator 9368 Scope: SW 9370 InitiatorAlias= 9372 Examples: 9374 InitiatorAlias=Web Server 4 9375 InitiatorAlias=spyalley.nsa.gov 9376 InitiatorAlias=Exchange Server 9378 If an initiator has been configured with a human-readable name or 9379 description, it SHOULD be communicated to the target during a Login 9380 Request PDU. If not, the host name can be used instead. This string 9381 is not used as an identifier, nor is meant to be used for 9382 authentication or authorization decisions. It can be displayed by 9383 the target's user interface in a list of initiators to which it is 9384 connected. 9386 12.8 TargetAddress 9388 Use: ALL, Declarative, Any-Stage 9389 Senders: Target 9390 Scope: SW 9392 TargetAddress=domainname[:port][,portal-group-tag] 9394 The domainname can be specified as either a DNS host name, a dotted- 9395 decimal IPv4 address, or a bracketed IPv6 address as specified in 9396 [RFC2732]. 9398 If the TCP port is not specified, it is assumed to be the IANA- 9399 assigned default port for iSCSI (see Section 13 IANA 9400 Considerations). 9402 If the TargetAddress is returned as the result of a redirect status 9403 in a login response, the comma and portal group tag MUST be omitted. 9405 If the TargetAddress is returned within a SendTargets response, the 9406 portal group tag MUST be included. 9408 Examples: 9410 TargetAddress=10.0.0.1:5003,1 9411 TargetAddress=[1080:0:0:0:8:800:200C:417A],65 9412 TargetAddress=[1080::8:800:200C:417A]:5003,1 9413 TargetAddress=computingcenter.example.com,23 9415 Julian Satran Expires August 2003 184 9416 iSCSI 19-January-03 9418 Use of the portal-group-tag is described in Appendix D. - 9419 SendTargets Operation -. The formats for the port and portal-group- 9420 tag are the same as the one specified in Section 12.9 9421 TargetPortalGroupTag. 9423 12.9 TargetPortalGroupTag 9425 Use: IO by target, Declarative, Any-Stage 9426 Senders: Target 9427 Scope: SW 9429 TargetPortalGroupTag=<16-bit-binary-value> 9431 Examples: 9432 TargetPortalGroupTag=1 9434 The target portal group tag is a 16-bit binary-value that uniquely 9435 identifies a portal group within an iSCSI target node. This key 9436 carries the value of the tag of the portal group that is servicing 9437 the Login request. The iSCSI target returns this key to the 9438 initiator in the Login Response PDU to the first Login Request PDU 9439 that has the C bit set to 0. 9441 For the complete usage expectations of this key see Section 5.3 9442 Login Phase. 9444 12.10 InitialR2T 9446 Use: LO 9447 Senders: Initiator and Target 9448 Scope: SW 9449 Irrelevant when: SessionType=Discovery 9451 InitialR2T= 9453 Examples: 9455 I->InitialR2T=No 9456 T->InitialR2T=No 9458 Default is Yes. 9459 Result function is OR. 9461 The InitialR2T key is used to turn off the default use of R2T for 9462 unidirectional and the output part of bidirectional commands, thus 9463 allowing an initiator to start sending data to a target as if it has 9464 received an initial R2T with Buffer Offset=Immediate Data Length and 9465 Desired Data Transfer Length=(min(FirstBurstLength, Expected Data 9466 Transfer Length) - Received Immediate Data Length). 9468 The default action is that R2T is required, unless both the 9469 initiator and the target send this key-pair attribute specifying 9470 InitialR2T=No. Only the first outgoing data burst (immediate data 9472 Julian Satran Expires August 2003 185 9473 iSCSI 19-January-03 9475 and/or separate PDUs) can be sent unsolicited (i.e., not requiring 9476 an explicit R2T). 9478 12.11 ImmediateData 9480 Use: LO 9481 Senders: Initiator and Target 9482 Scope: SW 9483 Irrelevant when: SessionType=Discovery 9485 ImmediateData= 9487 Default is Yes. 9488 Result function is AND. 9490 The initiator and target negotiate support for immediate data. To 9491 turn immediate data off, the initiator or target must state its 9492 desire to do so. ImmediateData can be turned on if both the 9493 initiator and target have ImmediateData=Yes. 9495 If ImmediateData is set to Yes and InitialR2T is set to Yes 9496 (default), then only immediate data are accepted in the first burst. 9498 If ImmediateData is set to No and InitialR2T is set to Yes, then the 9499 initiator MUST NOT send unsolicited data and the target MUST reject 9500 unsolicited data with the corresponding response code. 9502 If ImmediateData is set to No and InitialR2T is set to No, then the 9503 initiator MUST NOT send unsolicited immediate data, but MAY send one 9504 unsolicited burst of Data-OUT PDUs. 9506 If ImmediateData is set to Yes and InitialR2T is set to No, then the 9507 initiator MAY send unsolicited immediate data and/or one unsolicited 9508 burst of Data-OUT PDUs. 9510 The following table is a summary of unsolicited data options: 9512 +----------+-------------+------------------+--------------+ 9513 |InitialR2T|ImmediateData| Unsolicited |Immediate Data| 9514 | | | Data Out PDUs | | 9515 +----------+-------------+------------------+--------------+ 9516 | No | No | Yes | No | 9517 +----------+-------------+------------------+--------------+ 9518 | No | Yes | Yes | Yes | 9519 +----------+-------------+------------------+--------------+ 9520 | Yes | No | No | No | 9521 +----------+-------------+------------------+--------------+ 9522 | Yes | Yes | No | Yes | 9523 +----------+-------------+------------------+--------------+ 9525 12.12 MaxRecvDataSegmentLength 9527 Use: ALL, Declarative 9528 Senders: Initiator and Target 9529 Scope: CO 9531 Julian Satran Expires August 2003 186 9532 iSCSI 19-January-03 9534 MaxRecvDataSegmentLength= 9536 Default is 8192 bytes. 9538 The initiator or target declares the maximum data segment length in 9539 bytes it can receive in an iSCSI PDU. 9541 The transmitter (initiator or target) is required to send PDUs with 9542 a data segment that does not exceed MaxRecvDataSegmentLength of the 9543 receiver. 9545 A target receiver is additionally limited by MaxBurstLength for 9546 solicited data and FirstBurstLength for unsolicited data. An 9547 initiator MUST NOT send solicited PDUs exceeding MaxBurstLength nor 9548 unsolicited PDUs exceeding FirstBurstLength (or FirstBurstLength- 9549 Immediate Data Length if immediate data were sent). 9551 12.13 MaxBurstLength 9553 Use: LO 9554 Senders: Initiator and Target 9555 Scope: SW 9556 Irrelevant when: SessionType=Discovery 9558 MaxBurstLength= 9560 Default is 262144 (256 Kbytes). 9561 Result function is Minimum. 9563 The initiator and target negotiate maximum SCSI data payload in 9564 bytes in a Data-In or a solicited Data-Out iSCSI sequence. A 9565 sequence consists of one or more consecutive Data-In or Data-Out 9566 PDUs that end with a Data-In or Data-Out PDU with the F bit set to 9567 one. 9569 12.14 FirstBurstLength 9571 Use: LO 9572 Senders: Initiator and Target 9573 Scope: SW 9574 Irrelevant when: SessionType=Discovery 9575 Irrelevant when: ( InitialR2T=Yes and ImmediateData=No ) 9577 FirstBurstLength= 9579 Default is 65536 (64 Kbytes). 9580 Result function is Minimum. 9582 The initiator and target negotiate the maximum amount in bytes of 9583 unsolicited data an iSCSI initiator may send to the target during 9584 the execution of a single SCSI command. This covers the immediate 9585 data (if any) and the sequence of unsolicited Data-Out PDUs (if any) 9586 that follow the command. 9588 FirstBurstLength MUST NOT exceed MaxBurstLength. 9590 Julian Satran Expires August 2003 187 9591 iSCSI 19-January-03 9593 12.15 DefaultTime2Wait 9595 Use: LO 9596 Senders: Initiator and Target 9597 Scope: SW 9599 DefaultTime2Wait= 9601 Default is 2. 9602 Result function is Maximum. 9604 The initiator and target negotiate the minimum time, in seconds, to 9605 wait before attempting an explicit/implicit logout or an active task 9606 reassignment after an unexpected connection termination or a 9607 connection reset. 9609 A value of 0 indicates that logout or active task reassignment can 9610 be attempted immediately. 9612 12.16 DefaultTime2Retain 9614 Use: LO 9615 Senders: Initiator and Target 9616 Scope: SW 9618 DefaultTime2Retain= 9620 Default is 20. 9621 Result function is Minimum. 9623 The initiator and target negotiate the maximum time, in seconds 9624 after an initial wait (Time2Wait), before which an active task 9625 reassignment is still possible after an unexpected connection 9626 termination or a connection reset. 9628 This value is also the session state timeout if the connection in 9629 question is the last LOGGED_IN connection in the session. 9631 A value of 0 indicates that connection/task state is immediately 9632 discarded by the target. 9634 12.17 MaxOutstandingR2T 9636 Use: LO 9637 Senders: Initiator and Target 9638 Scope: SW 9640 MaxOutstandingR2T= 9641 Irrelevant when: SessionType=Discovery 9643 Default is 1. 9644 Result function is Minimum. 9646 Initiator and target negotiate the maximum number of outstanding 9647 R2Ts per task, excluding any implied initial R2T that might be part 9649 Julian Satran Expires August 2003 188 9650 iSCSI 19-January-03 9652 of that task. An R2T is considered outstanding until the last data 9653 PDU (with the F bit set to 1) is transferred, or a sequence 9654 reception timeout (Section 6.1.4.1 Recovery Within-command) is 9655 encountered for that data sequence. 9657 12.18 DataPDUInOrder 9659 Use: LO 9660 Senders: Initiator and Target 9661 Scope: SW 9662 Irrelevant when: SessionType=Discovery 9664 DataPDUInOrder= 9666 Default is Yes. 9667 Result function is OR. 9669 No is used by iSCSI to indicate that the data PDUs within sequences 9670 can be in any order. Yes is used to indicate that data PDUs within 9671 sequences have to be at continuously increasing addresses and 9672 overlays are forbidden. 9674 12.19 DataSequenceInOrder 9676 Use: LO 9677 Senders: Initiator and Target 9678 Scope: SW 9679 Irrelevant when: SessionType=Discovery 9681 DataSequenceInOrder= 9683 Default is Yes. 9684 Result function is OR. 9686 A Data Sequence is a sequence of Data-In or Data-Out PDUs that end 9687 with a Data-In or Data-Out PDU with the F bit set to one. A Data-out 9688 sequence is sent either unsolicited or in response to an R2T. 9689 Sequences cover an offset-range. 9691 If DataSequenceInOrder is set to No, Data PDU sequences may be 9692 transferred in any order. 9694 If DataSequenceInOrder is set to Yes, Data Sequences MUST be 9695 transferred using continuously non-decreasing sequence offsets (R2T 9696 buffer offset for writes, or the smallest SCSI Data-In buffer offset 9697 within a read data sequence). 9699 If DataSequenceInOrder is set to Yes, a target may retry at most the 9700 last R2T, and an initiator may at most request retransmission for 9701 the last read data sequence. For this reason, if ErrorRecoveryLevel 9702 is not 0 and DataSequenceInOrder is set to Yes then MaxOustandingR2T 9703 MUST be set to 1. 9705 12.20 ErrorRecoveryLevel 9707 Use: LO 9709 Julian Satran Expires August 2003 189 9710 iSCSI 19-January-03 9712 Senders: Initiator and Target 9713 Scope: SW 9715 ErrorRecoveryLevel= 9717 Default is 0. 9718 Result function is Minimum. 9720 The initiator and target negotiate the recovery level supported. 9722 Recovery levels represent a combination of recovery capabilities. 9723 Each recovery level includes all the capabilities of the lower 9724 recovery levels and adds some new ones to them. 9726 In the description of recovery mechanisms, certain recovery classes 9727 are specified. Section 6.1.5 Error Recovery Hierarchy describes the 9728 mapping between the classes and the levels. 9730 12.21 SessionType 9732 Use: LO, Declarative, Any-Stage 9733 Senders: Initiator 9734 Scope: SW 9736 SessionType= 9738 Default is Normal. 9740 The Initiator indicates the type of session it wants to create. The 9741 target can either accept it or reject it. 9743 A discovery session indicates to the Target that the only purpose of 9744 this Session is discovery. The only requests a target accepts in 9745 this type of session are a text request with a SendTargets key and a 9746 logout request with reason "close the session". 9748 The discovery session implies MaxConnections = 1 and overrides both 9749 the default and an explicit setting. 9751 12.22 The Private or Public Extension Key Format 9753 Use: ALL 9754 Senders: Initiator and Target 9755 Scope: specific key dependent 9757 X-reversed.vendor.dns_name.do_something= 9759 or 9761 X<#>= 9763 Keys with this format are used for public or private extension 9764 purposes. These keys always start with X- if unregistered with IANA 9765 (private) or X# if registered with IANA (public). 9767 Julian Satran Expires August 2003 190 9768 iSCSI 19-January-03 9770 For unregistered keys, to identify the vendor, we suggest you use 9771 the reversed DNS-name as a prefix to the key-proper. 9773 The part of key-name following X- and X# MUST conform to the format 9774 for key-name specified in Section 5.1 Text Format. 9776 For IANA registered keys the string following X# must be registered 9777 with IANA and the use of the key MUST be described by an 9778 informational RFC. 9780 Vendor specific keys MUST ONLY be used in normal sessions. 9782 Support for public or private extension keys is OPTIONAL. 9784 Julian Satran Expires August 2003 191 9785 iSCSI 19-January-03 9787 13. IANA Considerations 9789 The well-known TCP port number for iSCSI connections assigned by 9790 IANA is 3260. A system port must be assigned by IANA when this draft 9791 is approved to become a RFC. 9793 Extension keys, authentication methods, or digest types for which a 9794 vendor or group of vendors intend to provide publicly available 9795 descriptions MUST be described by an RFC and MUST be registered with 9796 IANA. 9798 IANA must maintain three registries: 9800 a) iSCSI extended key registry 9801 b) iSCSI authentication methods registry 9802 c) iSCSI digests registry 9804 [SEC-IPS] also instructs IANA to maintain a registry for the values 9805 of the SRP_GROUP key. The format of these values must conform to the 9806 one specified for iSCSI extension item-label in Section 13.5.4 9807 Standard iSCSI extension item-label format. 9809 For the iSCSI authentication methods registry and the iSCSI digests 9810 registry, IANA MUST also assign a 16-bit unsigned integer number 9811 (the method number for the authentication method and the digest 9812 number for the digest). 9814 The following initial values for the registry for authentication 9815 methods are specified by the standards action of this document: 9817 Authentication Method | Number | 9818 +----------------------------------------+--------+ 9819 | CHAP | 1 | 9820 +----------------------------------------+--------+ 9821 | SRP | 2 | 9822 +----------------------------------------+--------+ 9823 | KRB5 | 3 | 9824 +----------------------------------------+--------+ 9825 | SPKM1 | 4 | 9826 +----------------------------------------+--------+ 9827 | SPKM2 | 5 | 9828 +----------------------------------------+--------+ 9830 All other record numbers from 0 to 255 are reserved. IANA will 9831 register numbers above 255. 9833 Authentication methods with numbers above 255 MUST be unique within 9834 the registry and MUST be used with the prefix Y#. 9836 The following initial values for the registry for digests are 9837 specified by the standards action of this document: 9839 Julian Satran Expires August 2003 192 9840 iSCSI 19-January-03 9842 Digest | Number | 9843 +----------------------------------------+--------+ 9844 | CRC32C | 1 | 9845 +----------------------------------------+--------+ 9847 All other record numbers from 0 to 255 are reserved. IANA will 9848 register numbers above 255. 9850 Digests with numbers above 255 MUST be unique within the registry 9851 and MUST be used with the prefix Z#. 9853 The RFC that describes the item to be registered MUST indicate in 9854 the IANA consideration section the string and iSCSI registry to 9855 which it should be recorded. 9857 Extension Keys, Authentication Methods, and digests (iSCSI extension 9858 items) must conform to a number of requirements as described below. 9860 13.1 Naming Requirements 9862 Each iSCSI extension item must have a unique name in its category. 9863 This name will be used as a standard-label for the key, access 9864 method, or digest and must conform to the syntax specified in 9865 Section 13.5.4 Standard iSCSI extension item-label format for iSCSI 9866 extension item-labels. 9868 13.2 Mechanism Specification Requirements 9870 For iSCSI extension items all of the protocols and procedures used 9871 by a given iSCSI extension item must be described, either in the 9872 specification of the iSCSI extension item itself or in some other 9873 publicly available specification, in sufficient detail for the iSCSI 9874 extension item to be implemented by any competent implementor. Use 9875 of secret and/or proprietary methods in iSCSI extension items are 9876 expressly prohibited. In addition, the restrictions imposed by RFC 9877 1602 on the standardization of patented algorithms must be 9878 respected. 9880 13.3 Publication Requirements 9882 All iSCSI extension items must be described by an RFC. The RFC may 9883 be informational rather than standards-track, although standard- 9884 track review and approval are encouraged for all iSCSI extension 9885 items. 9887 13.4 Security Requirements 9889 Any known security issues that arise from the use of the iSCSI 9890 extension item must be completely and fully described. It is not 9891 required that the iSCSI extension item be secure or that it be free 9892 from risks, but that the known risks be identified. Publication of 9893 a new iSCSI extension item does not require an exhaustive security 9894 review, and the security considerations section is subject to 9895 continuing evaluation. 9897 Additional security considerations should be addressed by publishing 9899 Julian Satran Expires August 2003 193 9900 iSCSI 19-January-03 9902 revised versions of the iSCSI extension item specification. 9904 For each of these registries, IANA must record the registered 9905 string, which MUST conform to the format rules described in Section 9906 13.5.4 Standard iSCSI extension item-label format for iSCSI 9907 extension item-labels, and the RFC number that describes it. The key 9908 prefix (X#, Y# or Z#) is not part of the recorded string. 9910 13.5 Registration Procedure 9912 Registration of a new iSCSI extension item starts with the 9913 construction of a draft of an RFC. 9915 13.5.1 Present the iSCSI extension item to the Community 9917 Send a proposed access type specification to the IPS WG mailing list 9918 or if the IPS WG is disbanded at the registration time to a mailing 9919 list designated by the IETF Transport Area Director for a review 9920 period of a month. The intent of the public posting is to solicit 9921 comments and feedback on the iSCSI extension item specification and 9922 a review of any security considerations. 9924 13.5.2 iSCSI extension item review and IESG approval 9926 When the one month period has passed, the IPS WG chair or a person 9927 nominated by the IETF Transport Area Director (the iSCSI extension 9928 item reviewer) forwards the draft to the IESG for publication as an 9929 informational RFC or rejects it. If the specification is a standards 9930 track draft the usual IETF procedures for such documents are 9931 followed. 9933 Decisions made by the iSCSI extension item reviewer must be 9934 published within two weeks after the month-long review period. 9935 Decisions made by the iSCSI extension item reviewer can be appealed 9936 through the IESG appeal process. 9938 13.5.3 IANA Registration 9940 Provided that the iSCSI extension item has either passed review or 9941 has been successfully appealed to the IESG, and the specification is 9942 published as an RFC, then IANA will register the iSCSI extension 9943 item and make the registration available to the community. 9945 13.5.4 Standard iSCSI extension item-label format 9947 The following character symbols are used iSCSI extension item-labels 9948 (the hexadecimal values represent Unicode code points): 9950 (a-z, A-Z) - letters 9951 (0-9) - digits 9952 "." (0x2e) - dot 9953 "-" (0x2d) - minus 9954 "+" (0x2b) - plus 9955 "@" (0x40) - commercial at 9956 "_" (0x5f) - underscore 9958 Julian Satran Expires August 2003 194 9959 iSCSI 19-January-03 9961 An iSCSI extension item-label is a string of one or more characters 9962 that consist of letters, digits, dot, minus, plus, commercial at, or 9963 underscore. An iSCSI extension item-label MUST begin with a capital 9964 letter and must not exceed 63 characters. 9966 13.6 IANA Procedures for Registering iSCSI extension items 9968 The identity of the iSCSI extension item reviewer is communicated to 9969 the IANA by the IESG. Then, the IANA only acts in response to iSCSI 9970 extension item definitions that are approved by the iSCSI extension 9971 item reviewer and forwarded by the reviewer to the IANA for 9972 registration, or in response to a communication from the IESG that 9973 an iSCSI extension item definition appeal has overturned the iSCSI 9974 extension item reviewer's ruling. 9976 Julian Satran Expires August 2003 195 9977 iSCSI 19-January-03 9979 References and Bibliography 9981 Normative References 9983 [AESCBC] Frankel, S., Kelly, S., Glenn, R., "The AES Cipher 9984 Algorithm and Its Use with IPsec", draft-ietf-ipsec-ciph-aes- 9985 cbc-03.txt, November 2001 (Work In Progress). 9986 [AESCTR] draft-ietf-ipsec-ciph-aes-ctr-00.txt R. Housley 23- 9987 Jul-02 (Work In Progress). 9988 [CAM] ANSI X3.232-199X, Common Access Method-3. 9989 [EUI] "Guidelines for 64-bit Global Identifier (EUI-64)", http:/ 9990 /standards.ieee.org/regauth/oui/tutorials/EUI64.html 9991 [OUI] "IEEE OUI and Company_Id Assignments", http:// 9992 standards.ieee.org/regauth/oui 9993 [RFC790] J. Postel, ASSIGNED NUMBERS, September 1981. 9994 [RFC791] INTERNET PROTOCOL, DARPA INTERNET PROGRAM PROTOCOL 9995 SPECIFICATION, September 1981. 9996 [RFC793] TRANSMISSION CONTROL PROTOCOL, DARPA INTERNET PROGRAM 9997 PROTOCOL SPECIFICATION, September 1981. 9998 [RFC1035] P. Mockapetris, DOMAIN NAMES - IMPLEMENTATION AND 9999 SPECIFICATION, November 1987. 10000 [RFC1122] Requirements for Internet Hosts-Communication Layer 10001 RFC1122, R. Braden (editor). 10002 [RFC1510] J. Kohl, C. Neuman, "The Kerberos Network 10003 Authentication Service (V5)", September 1993. 10004 [RFC1737] K. Sollins, L. Masinter "Functional Requirements for 10005 Uniform Resource Names". 10006 [RFC1766] H. Alvestrand, "Tags for the Identification of 10007 Languages", March 1995. 10008 [RFC1964] J. Linn, "The Kerberos Version 5 GSS-API Mechanism", 10009 June 1996. 10010 [RFC1982] Elz, R., Bush, R., "Serial Number Arithmetic", August 10011 1996. 10012 [RFC1994] "W. Simpson, PPP Challenge Handshake Authentication 10013 Protocol (CHAP)", August 1996. 10014 [RFC2025] C. Adams, "The Simple Public-Key GSS-API Mechanism 10015 (SPKM)", October 1996. 10016 [RFC2026] Bradner, S., "The Internet Standards Process -- 10017 Revision 3", October 1996. 10018 [RFC2044] Yergeau, F., "UTF-8, a Transformation Format of 10019 Unicode and ISO 10646", October 1996. 10020 [RFC2045] N. Borenstein, N. Freed, "MIME (Multipurpose Internet 10021 Mail Extensions) Part One: Mechanisms for Specifying and 10022 Describing the Format of Internet Message Bodies", November 10023 1996. 10024 [RFC2119] Bradner, S. "Key Words for use in RFCs to Indicate 10025 Requirement Levels", BCP 14, March 1997. 10026 [RFC2234] D. Crocker, P. Overell Augmented BNF for Syntax 10027 Specifications: ABNF. 10028 [RFC2246] T. Dierks, C. Allen, " The TLS Protocol Version 1.0. 10029 [RFC2373] Hinden, R. and S. Deering, "IP Version 6 Addressing 10030 Architecture", July 1998. 10031 [RFC2396] T. Berners-Lee, R. Fielding, L. Masinter "Uniform 10032 Resource Identifiers". 10033 [RFC2401] S. Kent, R. Atkinson, "Security Architecture for the 10034 Internet Protocol", November 1998. 10036 Julian Satran Expires August 2003 196 10037 iSCSI 19-January-03 10039 [RFC2404] C. Madson, R. Glenn, "The Use of HMAC-SHA-1-96 within ESP 10040 and AH", November 1998. 10041 [RFC2406] S. Kent, R. Atkinson, "IP Encapsulating Security Payload 10042 (ESP)", November 1998. 10044 [RFC2407] D. Piper, "The Internet IP Security Domain of 10045 Interpretation of ISAKMP", November 1998. 10046 [RFC2409] D. Harkins, D. Carrel, "The Internet Key Exchange 10047 (IKE)", November 1998. 10048 [RFC2434] T. Narten, and H. Avestrand, "Guidelines for Writing 10049 an IANA Considerations Section in RFCs.", October 1998. 10050 [RFC2451] R. Pereira, R. Adams " The ESP CBC-Mode Cipher 10051 Algorithms". 10052 [RFC2732] R. Hinden, B. Carpenter, L. Masinter, "Format for 10053 Literal IPv6 Addresses in URL's", December 1999. 10054 [RFC2945] Wu, T., "The SRP Authentication and Key Exchange 10055 System", September 2000. 10056 [SAM] ANSI X3.270-1998, SCSI-3 Architecture Model (SAM). 10057 [SAM2] T10/1157D, SCSI Architecture Model - 2 (SAM-2). 10058 [SBC] NCITS.306-1998, SCSI-3 Block Commands (SBC). 10059 [SEQ-EXT] Kent, S., "IP Encapsulating Security Payload (ESP)", 10060 Internet draft (work in progress), draft-ietf-ipsec-esp-v3- 10061 03.txt, July 2002. 10062 [SEC-IPS] B. Aboba & team "Securing Block Storage Protocols over 10063 IP", Internet draft (work in progress), draft-ietf-ips- 10064 security-16.txt, September 2002. 10065 [SPC3]T10/1416-D, SCSI Primary Commands-3. 10066 [STPREP] P. Hoffman, M. Blanchet, "Preparation of 10067 Internationalized Strings", draft-hoffman-stringprep-07.txt, 10068 October 2002 (Work In Progress). 10069 [STPREP-iSCSI] M. Bakke, "String Profile for iSCSI Names", 10070 draft-ietf-ips-iscsi-string-prep-03.txt, October 2002 (Work In 10071 Progress). 10072 [UNICODE] Unicode Standard Annex #15, "Unicode Normalization 10073 Forms", http://www.unicode.org/unicode/reports/tr15 10075 Informative References: 10077 [BOOT] P. Sarkar & team draft-ietf-ips-iscsi-boot-03.txt (Work 10078 In Progress). 10079 [Castagnoli93] G. Castagnoli, S. Braeuer and M. Herrman 10080 "Optimization of Cyclic Redundancy-Check Codes with 24 and 32 10081 Parity Bits", IEEE Transact. on Communications, Vol. 41, No. 10082 6, June 1993. 10083 [CRC] ISO 3309, High-Level Data Link Control (CRC 32). 10084 [NDT] M. Bakke & team, draft-ietf-ips-iscsi-name-disc-07.txt 10085 (Work In Progress) 10086 [RFC3347] M. Krueger & team, Small Computer Systems Interface 10087 protocol over the Internet (iSCSI) Requirements and Design 10088 Considerations 10089 [RFC3385] D. Sheinwald & team, Internet Protocol Small Computer 10090 System Interface (iSCSI) Cyclic Redundancy Check (CRC)/ 10091 Checksum Considerations 10093 Julian Satran Expires August 2003 197 10094 iSCSI 19-January-03 10096 [Schneier] B. Schneier, "Applied Cryptography: Protocols, 10097 Algorithms, and Source Code in C", 2nd edition, John Wiley & 10098 Sons, New York, NY, 1996. 10100 Authors' Addresses 10102 Julian Satran 10103 IBM, Haifa Research Lab 10104 Haifa University Campus - Mount Carmel 10105 Haifa 31905, Israel 10106 Phone +972.4.829.6264 10107 E-mail: Julian_Satran@il.ibm.com 10109 Kalman Meth 10110 Haifa University Campus - Mount Carmel 10111 MATAM - Advanced Technology Center 10112 Haifa 31905, Israel 10113 Phone +972.4.829.6341 10114 E-mail: meth@il.ibm.com 10116 Costa Sapuntzakis 10117 Cisco Systems, Inc. 10118 170 W. Tasman Drive 10119 San Jose, CA 95134, USA 10120 Phone: +1.408.525.5497 10121 E-mail: csapuntz@cisco.com 10123 Efri Zeidner 10124 SANgate Systems, Inc. 10125 41 Hameyasdim Street 10126 P.O.B. 1486 10127 Even-Yehuda, Israel 40500 10128 Phone: +972.9.891.9555 10129 E-mail: efri@sangate.com 10131 Mallikarjun Chadalapaka 10132 Hewlett-Packard Company 10133 8000 Foothills Blvd. 10134 Roseville, CA 95747-5668, USA 10135 Phone: +1.916.785.5621 10136 E-mail: cbm@rose.hp.com 10138 Comments may be sent to Julian Satran 10140 Julian Satran Expires August 2003 198 10141 iSCSI 19-January-03 10143 Appendix A. Sync and Steering with Fixed Interval Markers 10145 This appendix presents a simple scheme for synchronization (PDU 10146 boundary retrieval). It uses markers that include synchronization 10147 information placed at fixed intervals in the TCP stream. 10149 A Marker consists of: 10151 Byte / 0 | 1 | 2 | 3 | 10152 / | | | | 10153 |0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7|0 1 2 3 4 5 6 7| 10154 +---------------+---------------+---------------+---------------+ 10155 0| Next-iSCSI-PDU-start pointer - copy #1 | 10156 +---------------+---------------+---------------+---------------+ 10157 4| Next-iSCSI-PDU-start pointer - copy #2 | 10158 +---------------+---------------+---------------+---------------+ 10160 The Marker scheme uses payload byte stream counting that includes 10161 every byte placed by iSCSI in the TCP stream except for the markers 10162 themselves. It also excludes any bytes that TCP counts but are not 10163 originated by iSCSI. 10165 Markers MUST NOT be included in digest calculation. 10167 The Marker indicates the offset to the next iSCSI PDU header. The 10168 Marker is eight bytes in length and contains two 32-bit offset 10169 fields that indicate how many bytes to skip in the TCP stream in 10170 order to find the next iSCSI PDU header. The marker uses two copies 10171 of the pointer so that a marker that spans a TCP packet boundary 10172 should leave at least one valid copy in one of the packets. 10174 The inserted value is independent of the marker interval. 10176 The use of markers is negotiable. The initiator and target MAY 10177 indicate their readiness to receive and/or send markers during login 10178 separately for each connection. The default is No. 10180 A.1 Markers At Fixed Intervals 10182 A marker is inserted at fixed intervals in the TCP byte stream. 10183 During login, each end of the iSCSI session specifies the interval 10184 at which it is willing to receive the marker, or it disables the 10185 marker altogether. If a receiver indicates that it desires a marker, 10186 the sender MAY agree (during negotiation) and provide the marker at 10187 the desired interval. However, in certain environments, a sender 10188 that does not provide markers to a receiver that wants markers may 10189 suffer an appreciable performance degradation. 10191 The marker interval and the initial marker-less interval are counted 10192 in terms of the bytes placed in the TCP stream data by iSCSI. 10194 When reduced to iSCSI terms, markers MUST indicate the offset to a 10195 4-byte word boundary in the stream. The least significant two bits 10196 of each marker word are reserved and are considered 0 for offset 10197 computation. 10199 Julian Satran Expires August 2003 199 10200 iSCSI 19-January-03 10202 Padding iSCSI PDU payloads to 4-byte word boundaries simplifies 10203 marker manipulation. 10205 A.2 Initial Marker-less Interval 10207 To enable the connection setup including the Login Phase 10208 negotiation, marking (if any) is only started at the first marker 10209 interval after the end of the Login Phase. However, in order to 10210 enable the marker inclusion and exclusion mechanism to work without 10211 knowledge of the length of the Login Phase, the first marker will be 10212 placed in the TCP stream as if the Marker-less interval had included 10213 markers. 10215 Thus, all markers appear in the stream at locations conforming to 10216 the formula: [(MI + 8) * n - 8] where MI = Marker Interval, n = 10217 integer number. 10219 For example, if the marker interval is 512 bytes and the login ended 10220 at byte 1003 (first iSCSI placed byte is 0), the first marker will 10221 be inserted after byte 1031 in the stream. 10223 A.3 Negotiation 10225 The following operational key=value pairs are used to negotiate the 10226 fixed interval markers. The direction (output or input) is relative 10227 to the initiator. 10229 A.3.1 OFMarker, IFMarker 10231 Use: IO 10232 Senders: Initiator and Target 10233 Scope: CO 10235 OFMarker= 10236 IFMarker= 10238 Default is No. 10240 Result function is AND. 10242 OFMarker is used to turn on or off the initiator to target markers 10243 on the connection. IFMarker is used to turn on or off the target to 10244 initiator markers on the connection. 10246 Examples: 10248 I->OFMarker=Yes,IFMarker=Yes 10249 T->OFMarker=Yes,IFMarker=Yes 10251 Results in the Marker being used in both directions while: 10253 I->OFMarker=Yes,IFMarker=Yes 10254 T->OFMarker=Yes,IFMarker=No 10256 Results in Marker being used from the initiator to the target, but 10257 not from the target to initiator. 10259 Julian Satran Expires August 2003 200 10260 iSCSI 19-January-03 10262 A.3.2 OFMarkInt, IFMarkInt 10264 Use: IO 10265 Senders: Initiator and Target 10266 Scope: CO 10267 OFMarkInt is Irrelevant when: OFMarker=No 10268 IFMarkInt is Irrelevant when: IFMarker=No 10270 Offering: 10272 OFMarkInt= 10273 IFMarkInt= 10275 Responding: 10277 OFMarkInt=|Reject 10278 IFMarkInt=|Reject 10280 OFMarkInt is used to set the interval for the initiator to target 10281 markers on the connection. IFMarkInt is used to set the interval 10282 for the target to initiator markers on the connection. 10284 For the offering, the initiator or target indicates the minimum to 10285 maximum interval (in 4-byte words) it wants the markers for one or 10286 both directions. In case it only wants a specific value, only a 10287 single value has to be specified. The responder selects a value 10288 within the minimum and maximum offered or the only value offered or 10289 indicates through the xFMarker key=value its inability to set and/or 10290 receive markers. When the interval is unacceptable the responder 10291 answers with "Reject". Reject is resetting the marker function in 10292 the specified direction (Output or Input) to No. 10294 The interval is measured from the end of a marker to the beginning 10295 of the next marker. For example, a value of 1024 means 1024 words 10296 (4096 bytes of iSCSI payload between markers). 10298 The default is 2048. 10300 Julian Satran Expires August 2003 201 10301 iSCSI 19-January-03 10303 Appendix B. Examples 10305 B.1 Read Operation Example 10307 +------------------+-----------------------+----------------------+ 10308 |Initiator Function| PDU Type | Target Function | 10309 +------------------+-----------------------+----------------------+ 10310 | Command request |SCSI Command (READ)>>> | | 10311 | (read) | | | 10312 +------------------+-----------------------+----------------------+ 10313 | | |Prepare Data Transfer | 10314 +------------------+-----------------------+----------------------+ 10315 | Receive Data | <<< SCSI Data-in | Send Data | 10316 +------------------+-----------------------+----------------------+ 10317 | Receive Data | <<< SCSI Data-in | Send Data | 10318 +------------------+-----------------------+----------------------+ 10319 | Receive Data | <<< SCSI Data-in | Send Data | 10320 +------------------+-----------------------+----------------------+ 10321 | | <<< SCSI Response |Send Status and Sense | 10322 +------------------+-----------------------+----------------------+ 10323 | Command Complete | | | 10324 +------------------+-----------------------+----------------------+ 10326 B.2 Write Operation Example 10328 +------------------+-----------------------+---------------------+ 10329 |Initiator Function| PDU Type | Target Function | 10330 +------------------+-----------------------+---------------------+ 10331 | Command request |SCSI Command (WRITE)>>>| Receive command | 10332 | (write) | | and queue it | 10333 +------------------+-----------------------+---------------------+ 10334 | | | Process old commands| 10335 +------------------+-----------------------+---------------------+ 10336 | | | Ready to process | 10337 | | <<< R2T | WRITE command | 10338 +------------------+-----------------------+---------------------+ 10339 | Send Data | SCSI Data-out >>> | Receive Data | 10340 +------------------+-----------------------+---------------------+ 10341 | | <<< R2T | Ready for data | 10342 +------------------+-----------------------+---------------------+ 10343 | | <<< R2T | Ready for data | 10344 +------------------+-----------------------+---------------------+ 10345 | Send Data | SCSI Data-out >>> | Receive Data | 10346 +------------------+-----------------------+---------------------+ 10347 | Send Data | SCSI Data-out >>> | Receive Data | 10348 +------------------+-----------------------+---------------------+ 10349 | | <<< SCSI Response |Send Status and Sense| 10350 +------------------+-----------------------+---------------------+ 10351 | Command Complete | | | 10352 +------------------+-----------------------+---------------------+ 10354 B.3 R2TSN/DataSN Use Examples 10356 Output (write) data DataSN/R2TSN Example 10358 Julian Satran Expires August 2003 202 10359 iSCSI 19-January-03 10361 +------------------+-----------------------+----------------------+ 10362 |Initiator Function| PDU Type & Content | Target Function | 10363 +------------------+-----------------------+----------------------+ 10364 | Command request |SCSI Command (WRITE)>>>| Receive command | 10365 | (write) | | and queue it | 10366 +------------------+-----------------------+----------------------+ 10367 | | | Process old commands | 10368 +------------------+-----------------------+----------------------+ 10369 | | <<< R2T | Ready for data | 10370 | | R2TSN = 0 | | 10371 +------------------+-----------------------+----------------------+ 10372 | | <<< R2T | Ready for more data | 10373 | | R2TSN = 1 | | 10374 +------------------+-----------------------+----------------------+ 10375 | Send Data | SCSI Data-out >>> | Receive Data | 10376 | for R2TSN 0 | DataSN = 0, F=0 | | 10377 +------------------+-----------------------+----------------------+ 10378 | Send Data | SCSI Data-out >>> | Receive Data | 10379 | for R2TSN 0 | DataSN = 1, F=1 | | 10380 +------------------+-----------------------+----------------------+ 10381 | Send Data | SCSI Data >>> | Receive Data | 10382 | for R2TSN 1 | DataSN = 0, F=1 | | 10383 +------------------+-----------------------+----------------------+ 10384 | | <<< SCSI Response |Send Status and Sense | 10385 | | ExpDataSN = 0 | | 10386 +------------------+-----------------------+----------------------+ 10387 | Command Complete | | | 10388 +------------------+-----------------------+----------------------+ 10390 Input (read) data DataSN Example 10392 +------------------+-----------------------+----------------------+ 10393 |Initiator Function| PDU Type | Target Function | 10394 +------------------+-----------------------+----------------------+ 10395 | Command request |SCSI Command (READ)>>> | | 10396 | (read) | | | 10397 +------------------+-----------------------+----------------------+ 10398 | | | Prepare Data Transfer| 10399 +------------------+-----------------------+----------------------+ 10400 | Receive Data | <<< SCSI Data-in | Send Data | 10401 | | DataSN = 0, F=0 | | 10402 +------------------+-----------------------+----------------------+ 10403 | Receive Data | <<< SCSI Data-in | Send Data | 10404 | | DataSN = 1, F=0 | | 10405 +------------------+-----------------------+----------------------+ 10406 | Receive Data | <<< SCSI Data-in | Send Data | 10407 | | DataSN = 2, F=1 | | 10408 +------------------+-----------------------+----------------------+ 10409 | | <<< SCSI Response |Send Status and Sense | 10410 | | ExpDataSN = 3 | | 10411 +------------------+-----------------------+----------------------+ 10412 | Command Complete | | | 10413 +------------------+-----------------------+----------------------+ 10415 Julian Satran Expires August 2003 203 10416 iSCSI 19-January-03 10418 Bidirectional DataSN Example 10420 +------------------+-----------------------+----------------------+ 10421 |Initiator Function| PDU Type | Target Function | 10422 +------------------+-----------------------+----------------------+ 10423 | Command request |SCSI Command >>> | | 10424 | (Read-Write) | Read-Write | | 10425 +------------------+-----------------------+----------------------+ 10426 | | | Process old commands | 10427 +------------------+-----------------------+----------------------+ 10428 | | <<< R2T | Ready to process | 10429 | | R2TSN = 0 | WRITE command | 10430 +------------------+-----------------------+----------------------+ 10431 | * Receive Data | <<< SCSI Data-in | Send Data | 10432 | | DataSN = 0, F=0 | | 10433 +------------------+-----------------------+----------------------+ 10434 | * Receive Data | <<< SCSI Data-in | Send Data | 10435 | | DataSN = 1, F=1 | | 10436 +------------------+-----------------------+----------------------+ 10437 | * Send Data | SCSI Data-out >>> | Receive Data | 10438 | for R2TSN 0 | DataSN = 0, F=1 | | 10439 +------------------+-----------------------+----------------------+ 10440 | | <<< SCSI Response |Send Status and Sense | 10441 | | ExpDataSN = 2 | | 10442 +------------------+-----------------------+----------------------+ 10443 | Command Complete | | | 10444 +------------------+-----------------------+----------------------+ 10446 *) Send data and Receive Data may be transferred simultaneously as 10447 in an atomic Read-Old-Write-New or sequentially as in an atomic 10448 Read-Update-Write (in the latter case the R2T may follow the 10449 received data). 10451 Unsolicited and immediate output (write) data with DataSN Example 10453 Julian Satran Expires August 2003 204 10454 iSCSI 19-January-03 10456 +------------------+-----------------------+----------------------+ 10457 |Initiator Function| PDU Type & Content | Target Function | 10458 +------------------+-----------------------+----------------------+ 10459 | Command request |SCSI Command (WRITE)>>>| Receive command | 10460 | (write) |F=0 | and data | 10461 |+ immediate data | | and queue it | 10462 +------------------+-----------------------+----------------------+ 10463 | Send Unsolicited | SCSI Write Data >>> | Receive more Data | 10464 | Data | DataSN = 0, F=1 | | 10465 +------------------+-----------------------+----------------------+ 10466 | | | Process old commands | 10467 +------------------+-----------------------+----------------------+ 10468 | | <<< R2T | Ready for more data | 10469 | | R2TSN = 0 | | 10470 +------------------+-----------------------+----------------------+ 10471 | Send Data | SCSI Write Data >>> | Receive Data | 10472 | for R2TSN 0 | DataSN = 0, F=1 | | 10473 +------------------+-----------------------+----------------------+ 10474 | | <<< SCSI Response |Send Status and Sense | 10475 | | | | 10476 +------------------+-----------------------+----------------------+ 10477 | Command Complete | | | 10478 +------------------+-----------------------+----------------------+ 10480 B.4 CRC Examples 10482 N.B. all Values are Hexadecimal 10484 32 bytes of zeroes: 10486 Byte: 0 1 2 3 10488 0: 00 00 00 00 10489 ... 10490 28: 00 00 00 00 10492 CRC: aa 36 91 8a 10494 32 bytes of ones: 10496 Byte: 0 1 2 3 10498 0: ff ff ff ff 10499 ... 10500 28: ff ff ff ff 10502 CRC: 43 ab a8 62 10504 32 bytes of incrementing 00..1f: 10506 Byte: 0 1 2 3 10508 0: 00 01 02 03 10509 ... 10510 28: 1c 1d 1e 1f 10512 Julian Satran Expires August 2003 205 10513 iSCSI 19-January-03 10515 CRC: 4e 79 dd 46 10517 32 bytes of decrementing 1f..00: 10519 Byte: 0 1 2 3 10521 0: 1f 1e 1d 1c 10522 ... 10523 28: 03 02 01 00 10525 CRC: 5c db 3f 11 10527 An iSCSI - SCSI Read (10) Command PDU 10529 Byte: 0 1 2 3 10531 0: 01 c0 00 00 10532 4: 00 00 00 00 10533 8: 00 00 00 00 10534 12: 00 00 00 00 10535 16: 14 00 00 00 10536 20: 00 00 04 00 10537 24: 00 00 00 14 10538 28: 00 00 00 18 10539 32: 28 00 00 00 10540 36: 00 00 00 00 10541 40: 02 00 00 00 10542 44: 00 00 00 00 10544 CRC: 56 3a 96 d9 10546 Julian Satran Expires August 2003 206 10547 iSCSI 19-January-03 10549 Appendix C. Login Phase Examples 10551 In the first example, the initiator and target authenticate each 10552 other via Kerberos: 10554 I-> Login (CSG,NSG=0,1 T=1) 10555 InitiatorName=iqn.1999-07.com.os:hostid.77 10556 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10557 AuthMethod=KRB5,SRP,None 10559 T-> Login (CSG,NSG=0,0 T=0) 10560 AuthMethod=KRB5 10562 I-> Login (CSG,NSG=0,1 T=1) 10563 KRB_AP_REQ= 10565 (krb_ap_req contains the Kerberos V5 ticket and authenticator 10566 with MUTUAL-REQUIRED set in the ap-options field) 10568 If the authentication is successful, the target proceeds with: 10570 T-> Login (CSG,NSG=0,1 T=1) 10571 KRB_AP_REP= 10573 (krb_ap_rep is the Kerberos V5 mutual authentication reply) 10575 If the authentication is successful, the initiator may proceed 10576 with: 10578 I-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=8192 10579 T-> Login (CSG,NSG=1,0 T=0) FirstBurstLength=4096 10580 MaxBurstLength=8192 10581 I-> Login (CSG,NSG=1,0 T=0) MaxBurstLength=8192 10582 ... more iSCSI Operational Parameters 10584 T-> Login (CSG,NSG=1,0 T=0) 10585 ... more iSCSI Operational Parameters 10587 And at the end: 10589 I-> Login (CSG,NSG=1,3 T=1) 10590 optional iSCSI parameters 10592 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10594 If the initiator's authentication by the target is not 10595 successful, the target responds with: 10597 T-> Login "login reject" 10599 instead of the Login KRB_AP_REP message, and terminates the 10600 connection. 10602 Julian Satran Expires August 2003 207 10603 iSCSI 19-January-03 10605 If the target's authentication by the initiator is not 10606 successful, the initiator terminates the connection (without 10607 responding to the Login KRB_AP_REP message). 10609 In the next example only the initiator is authenticated by the 10610 target via Kerberos: 10612 I-> Login (CSG,NSG=0,1 T=1) 10613 InitiatorName=iqn.1999-07.com.os:hostid.77 10614 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10615 AuthMethod=SRP,KRB5,None 10617 T-> Login-PR (CSG,NSG=0,0 T=0) 10618 AuthMethod=KRB5 10620 I-> Login (CSG,NSG=0,1 T=1) 10621 KRB_AP_REQ=krb_ap_req 10623 (MUTUAL-REQUIRED not set in the ap-options field of krb_ap_req) 10625 If the authentication is successful, the target proceeds with: 10627 T-> Login (CSG,NSG=0,1 T=1) 10629 I-> Login (CSG,NSG=1,0 T=0) 10630 ... iSCSI parameters 10632 T-> Login (CSG,NSG=1,0 T=0) 10633 ... iSCSI parameters 10635 . . . 10637 T-> Login (CSG,NSG=1,3 T=1)"login accept" 10639 In the next example, the initiator and target authenticate each 10640 other via SPKM1: 10642 I-> Login (CSG,NSG=0,1 T=1) 10643 InitiatorName=iqn.1999-07.com.os:hostid.77 10644 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10645 AuthMethod=SPKM1,KRB5,None 10647 T-> Login (CSG,NSG=0,0 T=0) 10648 AuthMethod=SPKM1 10650 I-> Login (CSG,NSG=0,0 T=0) 10651 SPKM_REQ= 10653 (spkm-req is the SPKM-REQ token with the mutual-state bit in the 10654 options field of the REQ-TOKEN set) 10656 T-> Login (CSG,NSG=0,0 T=0) 10657 SPKM_REP_TI= 10659 If the authentication is successful, the initiator proceeds: 10661 Julian Satran Expires August 2003 208 10662 iSCSI 19-January-03 10664 I-> Login (CSG,NSG=0,1 T=1) 10665 SPKM_REP_IT= 10667 If the authentication is successful, the target proceeds with: 10669 T-> Login (CSG,NSG=0,1 T=1) 10671 The initiator may proceed: 10673 I-> Login (CSG,NSG=1,0 T=0) ... iSCSI parameters 10674 T-> Login (CSG,NSG=1,0 T=0) ... iSCSI parameters 10676 And at the end: 10678 I-> Login (CSG,NSG=1,3 T=1) 10679 optional iSCSI parameters 10681 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10683 If the target's authentication by the initiator is not 10684 successful, the initiator terminates the connection (without 10685 responding to the Login SPKM_REP_TI message). 10687 If the initiator's authentication by the target is not 10688 successful, the target responds with: 10690 T-> Login "login reject" 10692 instead of the Login "proceed and change stage" message, and 10693 terminates the connection. 10695 In the next example, the initiator and target authenticate each 10696 other via SPKM2: 10698 I-> Login (CSG,NSG=0,0 T=0) 10699 InitiatorName=iqn.1999-07.com.os:hostid.77 10700 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10701 AuthMethod=SPKM1,SPKM2 10703 T-> Login-PR (CSG,NSG=0,0 T=0) 10704 AuthMethod=SPKM2 10706 I-> Login (CSG,NSG=0,1 T=1) 10707 SPKM_REQ= 10709 (spkm-req is the SPKM-REQ token with the mutual-state bit in the 10710 options field of the REQ-TOKEN not set) 10712 If the authentication is successful, the target proceeds with: 10714 T-> Login (CSG,NSG=0,1 T=1) 10716 The initiator may proceed: 10718 Julian Satran Expires August 2003 209 10719 iSCSI 19-January-03 10721 I-> Login (CSG,NSG=1,0 T=0) 10722 ... iSCSI parameters 10724 T-> Login (CSG,NSG=1,0 T=0) 10725 ... iSCSI parameters 10727 And at the end: 10729 I-> Login (CSG,NSG=1,3 T=1) 10730 optional iSCSI parameters 10732 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10734 In the next example, the initiator and target authenticate each 10735 other via SRP: 10737 I-> Login (CSG,NSG=0,1 T=1) 10738 InitiatorName=iqn.1999-07.com.os:hostid.77 10739 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10740 AuthMethod=KRB5,SRP,None 10742 T-> Login-PR (CSG,NSG=0,0 T=0) 10743 AuthMethod=SRP 10745 I-> Login (CSG,NSG=0,0 T=0) 10746 SRP_U= 10747 TargetAuth=Yes 10749 T-> Login (CSG,NSG=0,0 T=0) 10750 SRP_N= 10751 SRP_g= 10752 SRP_s= 10754 I-> Login (CSG,NSG=0,0 T=0) 10755 SRP_A= 10757 T-> Login (CSG,NSG=0,0 T=0) 10758 SRP_B= 10760 I-> Login (CSG,NSG=0,1 T=1) 10761 SRP_M= 10763 If the initiator authentication is successful, the target 10764 proceeds: 10766 T-> Login (CSG,NSG=0,1 T=1) 10767 SRP_HM= 10769 Where N, g, s, A, B, M, and H(A | M | K) are defined in 10770 [RFC2945]. 10772 If the target authentication is not successful, the initiator 10773 terminates the connection; otherwise, it proceeds. 10775 Julian Satran Expires August 2003 210 10776 iSCSI 19-January-03 10778 I-> Login (CSG,NSG=1,0 T=0) 10779 ... iSCSI parameters 10781 T-> Login (CSG,NSG=1,0 T=0) 10782 ... iSCSI parameters 10784 And at the end: 10786 I-> Login (CSG,NSG=1,3 T=1) 10787 optional iSCSI parameters 10789 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10791 If the initiator authentication is not successful, the target 10792 responds with: 10794 T-> Login "login reject" 10796 Instead of the T-> Login SRP_HM= message and 10797 terminates the connection. 10799 In the next example, only the initiator is authenticated by the 10800 target via SRP: 10802 I-> Login (CSG,NSG=0,1 T=1) 10803 InitiatorName=iqn.1999-07.com.os:hostid.77 10804 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10805 AuthMethod=KRB5,SRP,None 10807 T-> Login-PR (CSG,NSG=0,0 T=0) 10808 AuthMethod=SRP 10810 I-> Login (CSG,NSG=0,0 T=0) 10811 SRP_U= 10812 TargetAuth=No 10814 T-> Login (CSG,NSG=0,0 T=0) 10815 SRP_N= 10816 SRP_g= 10817 SRP_s= 10819 I-> Login (CSG,NSG=0,0 T=0) 10820 SRP_A= 10822 T-> Login (CSG,NSG=0,0 T=0) 10823 SRP_B= 10825 I-> Login (CSG,NSG=0,1 T=1) 10826 SRP_M= 10828 If the initiator authentication is successful, the target 10829 proceeds: 10831 T-> Login (CSG,NSG=0,1 T=1) 10833 I-> Login (CSG,NSG=1,0 T=0) 10835 Julian Satran Expires August 2003 211 10836 iSCSI 19-January-03 10838 ... iSCSI parameters 10840 T-> Login (CSG,NSG=1,0 T=0) 10841 ... iSCSI parameters 10843 And at the end: 10845 I-> Login (CSG,NSG=1,3 T=1) 10846 optional iSCSI parameters 10848 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10850 In the next example the initiator and target authenticate each other 10851 via CHAP: 10853 I-> Login (CSG,NSG=0,0 T=0) 10854 InitiatorName=iqn.1999-07.com.os:hostid.77 10855 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10856 AuthMethod=KRB5,CHAP,None 10858 T-> Login-PR (CSG,NSG=0,0 T=0) 10859 AuthMethod=CHAP 10861 I-> Login (CSG,NSG=0,0 T=0) 10862 CHAP_A= 10864 T-> Login (CSG,NSG=0,0 T=0) 10865 CHAP_A= 10866 CHAP_I= 10867 CHAP_C= 10869 I-> Login (CSG,NSG=0,1 T=1) 10870 CHAP_N= 10871 CHAP_R= 10872 CHAP_I= 10873 CHAP_C= 10875 If the initiator authentication is successful, the target 10876 proceeds: 10878 T-> Login (CSG,NSG=0,1 T=1) 10879 CHAP_N= 10880 CHAP_R= 10882 If the target authentication is not successful, the initiator 10883 aborts the connection; otherwise, it proceeds. 10885 I-> Login (CSG,NSG=1,0 T=0) 10886 ... iSCSI parameters 10887 T-> Login (CSG,NSG=1,0 T=0) 10888 ... iSCSI parameters 10890 And at the end: 10892 I-> Login (CSG,NSG=1,3 T=1) 10894 Julian Satran Expires August 2003 212 10895 iSCSI 19-January-03 10897 optional iSCSI parameters 10899 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10901 If the initiator authentication is not successful, the target 10902 responds with: 10904 T-> Login "login reject" 10906 Instead of the Login CHAP_R= "proceed and change 10907 stage" 10908 message and terminates the connection. 10910 In the next example, only the initiator is authenticated by the 10911 target via CHAP: 10913 I-> Login (CSG,NSG=0,1 T=0) 10914 InitiatorName=iqn.1999-07.com.os:hostid.77 10915 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10916 AuthMethod=KRB5,CHAP,None 10918 T-> Login-PR (CSG,NSG=0,0 T=0) 10919 AuthMethod=CHAP 10921 I-> Login (CSG,NSG=0,0 T=0) 10922 CHAP_A= 10924 T-> Login (CSG,NSG=0,0 T=0) 10925 CHAP_A= 10926 CHAP_I= 10927 CHAP_C= 10929 I-> Login (CSG,NSG=0,1 T=1) 10930 CHAP_N= 10931 CHAP_R= 10933 If the initiator authentication is successful, the target 10934 proceeds: 10936 T-> Login (CSG,NSG=0,1 T=1) 10938 I-> Login (CSG,NSG=1,0 T=0) 10939 ... iSCSI parameters 10941 T-> Login (CSG,NSG=1,0 T=0) 10942 ... iSCSI parameters 10944 And at the end: 10946 I-> Login (CSG,NSG=1,3 T=1) 10947 optional iSCSI parameters 10949 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10951 Julian Satran Expires August 2003 213 10952 iSCSI 19-January-03 10954 In the next example, the initiator does not offer any security 10955 parameters. It therefore may offer iSCSI parameters on the Login PDU 10956 with the T bit set to 1, and the target may respond with a final 10957 Login Response PDU immediately: 10959 I-> Login (CSG,NSG=1,3 T=1) 10960 InitiatorName=iqn.1999-07.com.os:hostid.77 10961 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10962 ... iSCSI parameters 10964 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10965 ... ISCSI parameters 10967 In the next example, the initiator does offer security 10968 parameters on the Login PDU, but the target does not choose 10969 any (i.e., chooses the "None" values): 10971 I-> Login (CSG,NSG=0,1 T=1) 10972 InitiatorName=iqn.1999-07.com.os:hostid.77 10973 TargetName=iqn.1999-07.com.example:diskarray.sn.88 10974 AuthMethod=KRB5,SRP,None 10976 T-> Login-PR (CSG,NSG=0,1 T=1) 10977 AuthMethod=None 10979 I-> Login (CSG,NSG=1,0 T=0) 10980 ... iSCSI parameters 10982 T-> Login (CSG,NSG=1,0 T=0) 10983 ... iSCSI parameters 10985 And at the end: 10987 I-> Login (CSG,NSG=1,3 T=1) 10988 optional iSCSI parameters 10990 T-> Login (CSG,NSG=1,3 T=1) "login accept" 10992 Julian Satran Expires August 2003 214 10993 iSCSI 19-January-03 10995 Appendix D. SendTargets Operation 10997 To reduce the amount of configuration required on an initiator, 10998 iSCSI provides the SendTargets text request. The initiator uses the 10999 SendTargets request to get a list of targets to which it may have 11000 access, as well as the list of addresses (IP address and TCP port) 11001 on which these targets may be accessed. 11003 To make use of SendTargets, an initiator must first establish one of 11004 two types of sessions. If the initiator establishes the session 11005 using the key "SessionType=Discovery", the session is a discovery 11006 session, and a target name does not need to be specified. 11007 Otherwise, the session is a normal, operational session. The 11008 SendTargets command MUST only be sent during the Full Feature Phase 11009 of a normal or discovery session. 11011 A system that contains targets MUST support discovery sessions on 11012 each of its iSCSI IP address-port pairs, and MUST support the 11013 SendTargets command on the discovery session. A target MUST return 11014 all path information (IP address-port pairs and portal group tags) 11015 for the targets for which the requesting initiator is authorized. 11017 A target MUST support the SendTargets command on operational 11018 sessions; these will only return path information about the target 11019 to which the session is connected, and do not need to return 11020 information about other target names that may be defined in the 11021 responding system. 11023 An initiator MAY make use of the SendTargets as it sees fit. 11025 A SendTargets command consists of a single Text request PDU. 11026 This PDU contains exactly one text key and value. The text key MUST 11027 be SendTargets. The expected response depends upon the value, as 11028 well as whether the session is a discovery or operational session. 11030 The value must be one of: 11032 All 11034 The initiator is requesting that information on all relevant 11035 targets known to the implementation be returned. This value 11036 MUST be supported on a discovery session, and MUST NOT be 11037 supported on an operational session. 11039 11041 If an iSCSI target name is specified, the session should respond 11042 with addresses for only the named target, if possible. This 11043 value MUST be supported on discovery sessions. A discovery 11044 session MUST be capable of returning addresses for those 11045 targets that would have been returned had value=All been 11046 designated. 11048 11050 Julian Satran Expires August 2003 215 11051 iSCSI 19-January-03 11053 The session should only respond with addresses for the target to 11054 which the session is logged in. This MUST be supported on 11055 operational sessions, and MUST NOT return targets other than 11056 the one to which the session is logged in. 11058 The response to this command is a text response that contains a list 11059 of zero or more targets and, optionally, their addresses. Each 11060 target is returned as a target record. A target record begins with 11061 the TargetName text key, followed by a list of TargetAddress text 11062 keys, and bounded by the end of the text response or the next 11063 TargetName key, which begins a new record. No text keys other than 11064 TargetName and TargetAddress are permitted within a SendTargets 11065 response. 11067 For the format of the TargetName, see Section 12.4 TargetName. 11069 A discovery session MAY respond to a SendTargets request with its 11070 complete list of targets, or with a list of targets that is based on 11071 the name of the initiator logged in to the session. 11073 A SendTargets response MUST NOT contain target names if there are no 11074 targets for the requesting initiator to access. 11076 Each target record returned includes zero or more TargetAddress 11077 fields. 11079 Each target record starts with one text key of the form: 11081 TargetName= 11083 Followed by zero or more address keys of the form: 11085 TargetAddress=[:], 11088 The hostname-or-ipaddress contains a domain name, IPv4 address, or 11089 IPv6 address, as specified for the TargetAddress key. 11091 Each TargetAddress belongs to a portal group, identified by its 11092 numeric portal group tag (as in Section 12.9 TargetPortalGroupTag). 11093 The iSCSI target name, together with this tag, constitutes the SCSI 11094 port identifier; the tag only needs to be unique within a given 11095 target's name list of addresses. 11097 Multiple-connection sessions can span iSCSI addresses that belong to 11098 the same portal group. 11100 Multiple-connection sessions cannot span iSCSI addresses that belong 11101 to different portal groups. 11103 If a SendTargets response reports an iSCSI address for a target, it 11104 SHOULD also report all other addresses in its portal group in the 11105 same response. 11107 A SendTargets text response can be longer than a single Text 11108 Response 11110 Julian Satran Expires August 2003 216 11111 iSCSI 19-January-03 11113 PDU, and makes use of the long text responses as specified. 11115 After obtaining a list of targets from the discovery target session, 11116 an iSCSI initiator may initiate new sessions to log in to the 11117 discovered targets for full operation. The initiator MAY keep the 11118 discovery session open, and MAY send subsequent SendTargets commands 11119 to 11120 discover new targets. 11122 Examples: 11124 This example is the SendTargets response from a single target that 11125 has no other interface ports. 11127 Initiator sends text request that contains: 11129 SendTargets=All 11131 Target sends a text response that contains: 11133 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11135 All the target had to return in the simple case was the target 11136 name. It is assumed by the initiator that the IP address and TCP 11137 port for this target are the same as used on the current connection 11138 to the default iSCSI target. 11140 The next example has two internal iSCSI targets, each accessible via 11141 two different ports with different IP addresses. The following is 11142 the text response: 11144 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11145 TargetAddress=10.1.0.45:3000,1 11146 TargetAddress=10.1.1.45:3000,2 11147 TargetName=iqn.1993-11.com.example:diskarray.sn.1234567 11148 TargetAddress=10.1.0.45:3000,1 11149 TargetAddress=10.1.1.45:3000,2 11151 Both targets share both addresses; the multiple addresses are likely 11152 used to provide multi-path support. The initiator may connect to 11153 either target name on either address. Each of the addresses has its 11154 own portal group tag; they do not support spanning multiple- 11155 connection sessions with each other. Keep in mind that the portal 11156 group tags for the two named targets are independent of one another; 11157 portal group "1" on the first target is not necessarily the same as 11158 portal group "1" on the second target. 11160 In the above example, a DNS host name or an IPv6 address could have 11161 been returned instead of an IPv4 address. 11163 The next text response shows a target that supports spanning 11164 sessions across multiple addresses, and further illustrates the use 11165 of the portal group tags: 11167 TargetName=iqn.1993-11.com.example:diskarray.sn.8675309 11169 Julian Satran Expires August 2003 217 11170 iSCSI 19-January-03 11172 TargetAddress=10.1.0.45:3000,1 11173 TargetAddress=10.1.1.46:3000,1 11174 TargetAddress=10.1.0.47:3000,2 11175 TargetAddress=10.1.1.48:3000,2 11176 TargetAddress=10.1.1.49:3000,3 11178 In this example, any of the target addresses can be used to reach 11179 the same target. A single-connection session can be established to 11180 any of these TCP addresses. A multiple-connection session could 11181 span addresses .45 and .46 or .47 and .48, but cannot span any other 11182 combination. A TargetAddress with its own tag (.49) cannot be 11183 combined with any other address within the same session. 11185 This SendTargets response does not indicate whether .49 supports 11186 multiple connections per session; it is communicated via the 11187 MaxConnections text key upon login to the target. 11189 Julian Satran Expires August 2003 218 11190 iSCSI 19-January-03 11192 Appendix E. Algorithmic Presentation of Error Recovery Classes 11194 This appendix illustrates the error recovery classes using a pseudo- 11195 programming-language. The procedure names are chosen to be obvious 11196 to most implementers. Each of the recovery classes described has 11197 initiator procedures as well as target procedures. These algorithms 11198 focus on outlining the mechanics of error recovery classes, and do 11199 not exhaustively describe all other aspects/cases. Examples of this 11200 approach are: 11202 - Handling for only certain Opcode types is shown. 11204 - Only certain reason codes (e.g., Recovery in Logout command) 11205 are outlined. 11207 - Resultant cases, such as recovery of Synchronization on a 11208 header digest error are considered out-of-scope in these 11209 algorithms. In this particular example, a header digest error 11210 may lead to connection recovery if some type of sync and 11211 steering layer is not implemented. 11213 These algorithms strive to convey the iSCSI error recovery concepts 11214 in the simplest terms, and are not designed to be optimal. 11216 E.1 General Data Structure and Procedure Description 11218 This section defines the procedures and data structures that are 11219 commonly used by all the error recovery algorithms. The structures 11220 may not be the exhaustive representations of what is required for a 11221 typical implementation. 11223 Data structure definitions - 11224 struct TransferContext { 11225 int TargetTransferTag; 11226 int ExpectedDataSN; 11227 }; 11229 struct TCB { /* task control block */ 11230 Boolean SoFarInOrder; 11231 int ExpectedDataSN; /* used for both R2Ts, and Data */ 11232 int MissingDataSNList[MaxMissingDPDU]; 11233 Boolean FbitReceived; 11234 Boolean StatusXferd; 11235 Boolean CurrentlyAllegiant; 11236 int ActiveR2Ts; 11237 int Response; 11238 char *Reason; 11239 struct TransferContext 11240 TransferContextList[MaxOutStandingR2T]; 11241 int InitiatorTaskTag; 11242 int CmdSN; 11244 int SNACK_Tag; 11246 Julian Satran Expires August 2003 219 11247 iSCSI 19-January-03 11249 }; 11251 struct Connection { 11252 struct Session SessionReference; 11253 Boolean SoFarInOrder; 11254 int CID; 11255 int State; 11257 int CurrentTimeout; 11258 int ExpectedStatSN; 11259 int MissingStatSNList[MaxMissingSPDU]; 11260 Boolean PerformConnectionCleanup; 11261 }; 11263 struct Session { 11264 int NumConnections; 11265 int CmdSN; 11266 int Maxconnections; 11267 int ErrorRecoveryLevel; 11268 struct iSCSIEndpoint OtherEndInfo; 11269 struct Connection ConnectionList[MaxSupportedConns]; 11270 }; 11272 Procedure descriptions - 11273 Receive-a-In-PDU(transport connection, inbound PDU); 11274 check-basic-validity(inbound PDU); 11275 Start-Timer(timeout handler, argument, timeout value); 11276 Build-And-Send-Reject(transport connection, bad PDU, reason code); 11278 E.2 Within-command Error Recovery Algorithms 11280 E.2.1 Procedure Descriptions 11282 Recover-Data-if-Possible(last required DataSN, task control 11283 block); 11284 Build-And-Send-DSnack(task control block); 11285 Build-And-Send-RDSnack(task control block); 11286 Build-And-Send-Abort(task control block); 11287 SCSI-Task-Completion(task control block); 11288 Build-And-Send-A-Data-Burst(transport connection, data-descriptor, 11289 task control block); 11290 Build-And-Send-R2T(transport connection, data-descriptor, 11291 task control block); 11292 Build-And-Send-Status(transport connection, task control block); 11293 Transfer-Context-Timeout-Handler(transfer context); 11295 Notes: 11297 Julian Satran Expires August 2003 220 11298 iSCSI 19-January-03 11300 - One procedure used in this section: Handle-Status-SNACK- 11301 request is defined in Within-connection recovery algorithms. 11303 - The Response processing pseudo-code, shown in the target 11304 algorithms, applies to all solicited PDUs that carry StatSN - 11305 SCSI Response, Text Response etc. 11307 E.2.2 Initiator Algorithms 11309 Recover-Data-if-Possible(LastRequiredDataSN, TCB) 11310 { 11311 if (operational ErrorRecoveryLevel > 0) { 11312 if (# of missing PDUs is trackable) { 11313 Note the missing DataSNs in TCB. 11314 if (the task spanned a change in 11315 MaxRecvDataSegmentLength) { 11316 if (TCB.StatusXferd is TRUE) 11317 drop the status PDU; 11318 Build-And-Send-RDSnack(TCB); 11319 } else { 11320 Build-And-Send-DSnack(TCB); 11321 } 11322 } else { 11323 TCB.Reason = "Protocol service CRC error"; 11324 } 11325 } else { 11326 TCB.Reason = "Protocol service CRC error"; 11327 } 11328 if (TCB.Reason == "Protocol service CRC error") { 11329 Clear the missing PDU list in the TCB. 11330 if (TCB.StatusXferd is not TRUE) 11331 Build-And-Send-Abort(TCB); 11332 } 11333 } 11335 Receive-a-In-PDU(Connection, CurrentPDU) 11336 { 11337 check-basic-validity(CurrentPDU); 11338 if (Header-Digest-Bad) discard, return; 11339 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 11340 if ((CurrentPDU.type == Data) 11341 or (CurrentPDU.type = R2T)) { 11342 if (Data-Digest-Bad for Data) { 11343 send-data-SNACK = TRUE; 11344 LastRequiredDataSN = CurrentPDU.DataSN; 11345 } else { 11346 if (TCB.SoFarInOrder = TRUE) { 11347 if (current DataSN is expected) { 11348 Increment TCB.ExpectedDataSN. 11349 } else { 11351 Julian Satran Expires August 2003 221 11352 iSCSI 19-January-03 11354 TCB.SoFarInOrder = FALSE; 11355 send-data-SNACK = TRUE; 11356 } 11357 } else { 11358 if (current DataSN was considered missing) { 11359 remove current DataSN from missing PDU list. 11360 } else if (current DataSN is higher than expected) 11361 { 11362 send-data-SNACK = TRUE; 11363 } else { 11364 discard, return; 11365 } 11366 Adjust TCB.ExpectedDataSN if appropriate. 11367 } 11368 LastRequiredDataSN = CurrentPDU.DataSN - 1; 11369 } 11370 if (send-data-SNACK is TRUE and 11371 task is not already considered failed) { 11372 Recover-Data-if-Possible(LastRequiredDataSN, TCB); 11373 } 11374 if (missing data PDU list is empty) { 11375 TCB.SoFarInOrder = TRUE; 11376 } 11377 if (CurrentPDU.type == R2T) { 11378 Increment ActiveR2Ts for this task. 11380 Create a data-descriptor for the data burst. 11381 Build-And-Send-A-Data-Burst(Connection, data-descriptor, 11383 TCB); 11384 } 11385 } else if (CurrentPDU.type == Response) { 11386 if (Data-Digest-Bad) { 11387 send-status-SNACK = TRUE; 11388 } else { 11389 TCB.StatusXferd = TRUE; 11390 Store the status information in TCB. 11391 if (ExpDataSN does not match) { 11392 TCB.SoFarInOrder = FALSE; 11393 Recover-Data-if-Possible(current DataSN, TCB); 11394 } 11395 if (missing data PDU list is empty) { 11396 TCB.SoFarInOrder = TRUE; 11397 } 11398 } 11399 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT 11400 SHOWN */ 11401 } 11402 if ((TCB.SoFarInOrder == TRUE) and 11404 Julian Satran Expires August 2003 222 11405 iSCSI 19-January-03 11407 (TCB.StatusXferd == TRUE)) { 11408 SCSI-Task-Completion(TCB); 11409 } 11410 } 11412 E.2.3 Target Algorithms 11414 Receive-a-In-PDU(Connection, CurrentPDU) 11415 { 11416 check-basic-validity(CurrentPDU); 11417 if (Header-Digest-Bad) discard, return; 11418 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 11419 if (CurrentPDU.type == Data) { 11420 Retrieve TContext from CurrentPDU.TargetTransferTag; 11421 if (Data-Digest-Bad) { 11422 Build-And-Send-Reject(Connection, CurrentPDU, 11423 Payload-Digest-Error); 11424 Note the missing data PDUs in MissingDataRange[]. 11425 send-recovery-R2T = TRUE; 11426 } else { 11427 if (current DataSN is not expected) { 11428 Note the missing data PDUs in MissingDataRange[]. 11429 send-recovery-R2T = TRUE; 11430 } 11431 if (CurrentPDU.Fbit == TRUE) { 11432 if (current PDU is solicited) { 11433 Decrement TCB.ActiveR2Ts. 11434 } 11435 if ((current PDU is unsolicited and 11436 data received is less than I/O length and 11437 data received is less than FirstBurstLength) 11438 or (current PDU is solicited and the length of 11439 this burst is less than expected)) { 11440 send-recovery-R2T = TRUE; 11441 Note the missing data in MissingDataRange[]. 11442 } 11443 } 11444 } 11445 Increment TContext.ExpectedDataSN. 11446 if (send-recovery-R2T is TRUE and 11447 task is not already considered failed) { 11448 if (operational ErrorRecoveryLevel > 0) { 11449 Increment TCB.ActiveR2Ts. 11450 Create a data-descriptor for the data burst 11451 from MissingDataRange. 11452 Build-And-Send-R2T(Connection, data-descriptor, TCB); 11453 } else { 11454 if (current PDU is the last unsolicited) 11456 Julian Satran Expires August 2003 223 11457 iSCSI 19-January-03 11459 TCB.Reason = "Not enough unsolicited data"; 11460 else 11461 TCB.Reason = "Protocol service CRC error"; 11462 } 11463 } 11464 if (TCB.ActiveR2Ts == 0) { 11465 Build-And-Send-Status(Connection, TCB); 11466 } 11467 } else if (CurrentPDU.type == SNACK) { 11468 snack-failure = FALSE; 11469 if (operational ErrorRecoveryLevel > 0) { 11470 if (CurrentPDU.type == Data/R2T) { 11471 if (the request is satisfiable) { 11473 if (request for Data) { 11474 Create a data-descriptor for the data burst 11475 from BegRun and RunLength. 11476 Build-And-Send-A-Data-Burst(Connection, 11478 data-descriptor, TCB); 11479 } else { /* R2T */ 11480 Create a data-descriptor for the data burst 11481 from BegRun and RunLength. 11482 Build-And-Send-R2T(Connection, data- 11483 descriptor, 11485 TCB); 11486 } 11487 } else { 11488 snack-failure = TRUE; 11489 } 11490 } else if (CurrentPDU.type == status) { 11491 Handle-Status-SNACK-request(Connection, CurrentPDU); 11492 } else if (CurrentPDU.type == DataACK) { 11493 Consider all data upto CurrentPDU.BegRun as 11494 acknowledged. 11495 Free up the retransmission resources for that data. 11496 } else if (CurrentPDU.type == R-Data SNACK) { 11497 Create a data descriptor for a data burst covering 11498 all unacknowledged data. 11499 Build-And-Send-A-Data-Burst(Connection, 11501 data-descriptor, TCB); 11502 TCB.SNACK_Tag = CurrentPDU.SNACK_Tag; 11503 if (there's no more data to send) { 11504 Build-And-Send-Status(Connection, TCB); 11505 } 11506 } 11507 } else { /* operational ErrorRecoveryLevel = 0 */ 11508 snack-failure = TRUE; 11510 } 11511 if (snack-failure == TRUE) { 11513 Julian Satran Expires August 2003 224 11514 iSCSI 19-January-03 11516 Build-And-Send-Reject(Connection, CurrentPDU, 11517 SNACK-Reject); 11518 if (TCB.StatusXferd != TRUE) { 11519 TCB.Reason = "SNACK Rejected"; 11520 Build-And-Send-Status(Connection, TCB); 11521 } 11522 } 11524 } else { /* REST UNRELATED TO WITHIN-COMMAND-RECOVERY, NOT SHOWN 11525 */ 11526 } 11527 } 11529 Transfer-Context-Timeout-Handler(TContext) 11530 { 11531 Retrieve TCB and Connection from TContext. 11532 Decrement TCB.ActiveR2Ts. 11533 if (operational ErrorRecoveryLevel > 0 and 11534 task is not already considered failed) { 11535 Note the missing data PDUs in MissingDataRange[]. 11536 Create a data-descriptor for the data burst 11537 from MissingDataRange[]. 11538 Build-And-Send-R2T(Connection, data-descriptor, TCB); 11539 } else { 11540 TCB.Reason = "Protocol service CRC error"; 11541 if (TCB.ActiveR2Ts = 0) { 11542 Build-And-Send-Status(Connection, TCB); 11543 } 11544 } 11545 } 11547 E.3 Within-connection Recovery Algorithms 11549 E.3.1 Procedure Descriptions 11551 Procedure descriptions: 11552 Recover-Status-if-Possible(transport connection, 11553 currently received PDU); 11554 Evaluate-a-StatSN(transport connection, currently received PDU); 11555 Retransmit-Command-if-Possible(transport connection, CmdSN); 11556 Build-And-Send-SSnack(transport connection); 11557 Build-And-Send-Command(transport connection, task control block); 11558 Command-Acknowledge-Timeout-Handler(task control block); 11559 Status-Expect-Timeout-Handler(transport connection); 11560 Build-And-Send-Nop-Out(transport connection); 11561 Handle-Status-SNACK-request(transport connection, status SNACK 11562 PDU); 11563 Retransmit-Status-Burst(status SNACK, task control block); 11565 Julian Satran Expires August 2003 225 11566 iSCSI 19-January-03 11568 Is-Acknowledged(beginning StatSN, run length); 11570 Implementation-specific tunables: 11571 InitiatorProactiveSNACKEnabled 11573 Notes: 11574 - The initiator algorithms only deal with unsolicited Nop-In 11575 PDUs for generating status SNACKs. A solicited Nop-In PDU has 11576 an assigned StatSN, which, when out of order, could trigger 11577 the out of order StatSN handling in Within-command algorithms, 11578 again leading to Recover-Status-if-Possible. 11580 - The pseudo-code shown may result in the retransmission of 11581 unacknowledged commands in more cases than necessary. This 11582 will not, however, affect the correctness of the operation 11583 because the target is required to discard the duplicate 11584 CmdSNs. 11586 - The procedure Build-And-Send-Async is defined in the 11587 Connection recovery algorithms. 11589 - The procedure Status-Expect-Timeout-Handler describes how 11590 initiators may proactively attempt to retrieve the Status if 11591 they so choose. This procedure is assumed to be triggered much 11592 before the standard ULP timeout. 11594 E.3.2 Initiator Algorithms 11596 Recover-Status-if-Possible(Connection, CurrentPDU) 11597 { 11598 if ((Connection.state == LOGGED_IN) and 11599 connection is not already considered failed) { 11600 if (operational ErrorRecoveryLevel > 0) { 11601 if (# of missing PDUs is trackable) { 11602 Note the missing StatSNs in Connection 11604 that were not already requested with SNACK; 11605 Build-And-Send-SSnack(Connection); 11606 } else { 11607 Connection.PerformConnectionCleanup = TRUE; 11608 } 11609 } else { 11610 Connection.PerformConnectionCleanup = TRUE; 11611 } 11612 if (Connection.PerformConnectionCleanup == TRUE) { 11613 Start-Timer(Connection-Cleanup-Handler, Connection, 0); 11614 } 11615 } 11616 } 11618 Retransmit-Command-if-Possible(Connection, CmdSN) 11619 { 11621 Julian Satran Expires August 2003 226 11622 iSCSI 19-January-03 11624 if (operational ErrorRecoveryLevel > 0) { 11625 Retrieve the InitiatorTaskTag, and thus TCB for the CmdSN. 11626 Build-And-Send-Command(Connection, TCB); 11627 } 11628 } 11630 Evaluate-a-StatSN(Connection, CurrentPDU) 11631 { 11632 send-status-SNACK = FALSE; 11633 if (Connection.SoFarInOrder == TRUE) { 11634 if (current StatSN is the expected) { 11635 Increment Connection.ExpectedStatSN. 11636 } else { 11637 Connection.SoFarInOrder = FALSE; 11638 send-status-SNACK = TRUE; 11639 } 11640 } else { 11641 if (current StatSN was considered missing) { 11642 remove current StatSN from the missing list. 11643 } else { 11644 if (current StatSN is higher than expected){ 11645 send-status-SNACK = TRUE; 11646 } else { 11647 send-status-SNACK = FALSE; 11648 discard the PDU; 11649 } 11650 } 11651 Adjust Connection.ExpectedStatSN if appropriate. 11652 if (missing StatSN list is empty) { 11653 Connection.SoFarInOrder = TRUE; 11654 } 11655 } 11656 return send-status-SNACK; 11657 } 11659 Receive-a-In-PDU(Connection, CurrentPDU) 11660 { 11661 check-basic-validity(CurrentPDU); 11662 if (Header-Digest-Bad) discard, return; 11663 Retrieve TCB for CurrentPDU.InitiatorTaskTag. 11664 if (CurrentPDU.type == Nop-In) { 11665 if (the PDU is unsolicited) { 11666 if (current StatSN is not expected) { 11667 Recover-Status-if-Possible(Connection, 11668 CurrentPDU); 11669 } 11670 if (current ExpCmdSN is not Session.CmdSN) { 11671 Retransmit-Command-if-Possible(Connection, 11673 Julian Satran Expires August 2003 227 11674 iSCSI 19-January-03 11676 CurrentPDU.ExpCmdSN); 11677 } 11678 } 11679 } else if (CurrentPDU.type == Reject) { 11680 if (it is a data digest error on immediate data) { 11681 Retransmit-Command-if-Possible(Connection, 11682 CurrentPDU.BadPDUHeader.CmdSN); 11683 } 11684 } else if (CurrentPDU.type == Response) { 11685 send-status-SNACK = Evaluate-a-StatSN(Connection, 11686 CurrentPDU); 11687 if (send-status-SNACK == TRUE) 11688 Recover-Status-if-Possible(Connection, CurrentPDU); 11689 } else { /* REST UNRELATED TO WITHIN-CONNECTION-RECOVERY, 11690 * NOT SHOWN */ 11691 } 11692 } 11694 Command-Acknowledge-Timeout-Handler(TCB) 11695 { 11696 Retrieve the Connection for TCB. 11697 Retransmit-Command-if-Possible(Connection, TCB.CmdSN); 11698 } 11700 Status-Expect-Timeout-Handler(Connection) 11701 { 11702 if (operational ErrorRecoveryLevel > 0) { 11703 Build-And-Send-Nop-Out(Connection); 11704 } else if (InitiatorProactiveSNACKEnabled){ 11705 if ((Connection.state == LOGGED_IN) and 11706 connection is not already considered failed) { 11707 Build-And-Send-SSnack(Connection); 11708 } 11709 } 11710 } 11712 E.3.3 Target Algorithms 11714 Handle-Status-SNACK-request(Connection, CurrentPDU) 11715 { 11716 if (operational ErrorRecoveryLevel > 0) { 11717 if (request for an acknowledged run) { 11718 Build-And-Send-Reject(Connection, CurrentPDU, 11719 Protocol-Error); 11720 } else if (request for an untransmitted run) { 11721 discard, return; 11722 } else { 11723 Retransmit-Status-Burst(CurrentPDU, TCB); 11725 Julian Satran Expires August 2003 228 11726 iSCSI 19-January-03 11728 } 11729 } else { 11730 Build-And-Send-Async(Connection, DroppedConnection, 11731 DefaultTime2Wait, 11732 DefaultTime2Retain); 11733 } 11734 } 11736 E.4 Connection Recovery Algorithms 11738 E.4.1 Procedure Descriptions 11740 Build-And-Send-Async(transport connection, reason code, 11741 minimum time, maximum time); 11742 Pick-A-Logged-In-Connection(session); 11743 Build-And-Send-Logout(transport connection, logout connection 11744 identifier, reason code); 11745 PerformImplicitLogout(transport connection, logout connection 11746 identifier, target information); 11747 PerformLogin(transport connection, target information); 11748 CreateNewTransportConnection(target information); 11749 Build-And-Send-Command(transport connection, task control block); 11750 Connection-Cleanup-Handler(transport connection); 11751 Connection-Resource-Timeout-Handler(transport connection); 11752 Quiesce-And-Prepare-for-New-Allegiance(session, task control 11753 block); 11754 Build-And-Send-Logout-Response(transport connection, 11755 CID of connection in recovery, reason 11756 code); 11757 Build-And-Send-TaskMgmt-Response(transport connection, 11758 task mgmt command PDU, response code); 11759 Establish-New-Allegiance(task control block, transport 11760 connection); 11761 Schedule-Command-To-Continue(task control block); 11763 Notes: 11764 - Transport exception conditions, such as unexpected connection 11765 termination, connection reset, and hung connection while the 11766 connection is in the full-feature phase, are all assumed to be 11767 asynchronously signaled to the iSCSI layer using the 11768 Transport_Exception_Handler procedure. 11770 E.4.2 Initiator Algorithms 11772 Receive-a-In-PDU(Connection, CurrentPDU) 11773 { 11774 check-basic-validity(CurrentPDU); 11775 if (Header-Digest-Bad) discard, return; 11777 Julian Satran Expires August 2003 229 11778 iSCSI 19-January-03 11780 Retrieve TCB from CurrentPDU.InitiatorTaskTag. 11781 if (CurrentPDU.type == Async) { 11782 if (CurrentPDU.AsyncEvent == ConnectionDropped) { 11783 Retrieve the AffectedConnection for 11784 CurrentPDU.Parameter1. 11785 AffectedConnection.CurrentTimeout = CurrentPDU.Parameter3; 11786 AffectedConnection.State = CLEANUP_WAIT; 11787 Start-Timer(Connection-Cleanup-Handler, 11788 AffectedConnection, 11789 CurrentPDU.Parameter2); 11790 } else if (CurrentPDU.AsyncEvent == LogoutRequest)) { 11791 AffectedConnection = Connection; 11792 AffectedConnection.State = LOGOUT_REQUESTED; 11793 AffectedConnection.PerformConnectionCleanup = TRUE; 11795 AffectedConnection.CurrentTimeout = 11796 CurrentPDU.Parameter3; 11797 Start-Timer(Connection-Cleanup-Handler, 11798 AffectedConnection, 0); 11799 } else if (CurrentPDU.AsyncEvent == SessionDropped)) { 11800 for (each Connection) { 11801 Connection.State = CLEANUP_WAIT; 11802 Connection.CurrentTimeout = CurrentPDU.Parameter3; 11803 Start-Timer(Connection-Cleanup-Handler, 11805 Connection, CurrentPDU.Parameter2); 11806 } 11807 Session.state = FAILED; 11808 } 11810 } else if (CurrentPDU.type == LogoutResponse) { 11811 Retrieve the CleanupConnection for CurrentPDU.CID. 11812 if (CurrentPDU.Response = failure) { 11813 CleanupConnection.State = CLEANUP_WAIT; 11814 } else { 11815 CleanupConnection.State = FREE; 11816 } 11817 } else if (CurrentPDU.type == LoginResponse) { 11818 if (this is a response to an implicit Logout) { 11819 Retrieve the CleanupConnection. 11820 if (successful) { 11821 CleanupConnection.State = FREE; 11822 Connection.State = LOGGED_IN; 11823 } else { 11824 CleanupConnection.State = CLEANUP_WAIT; 11825 DestroyTransportConnection(Connection); 11826 } 11827 } 11828 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 11830 Julian Satran Expires August 2003 230 11831 iSCSI 19-January-03 11833 * NOT SHOWN */ 11834 } 11835 if (CleanupConnection.State == FREE) { 11836 for (each command that was active on CleanupConnection) { 11837 /* Establish new connection allegiance */ 11838 NewConnection = Pick-A-Logged-In-Connection(Session); 11839 Build-And-Send-Command(NewConnection, TCB); 11840 } 11841 } 11842 } 11844 Connection-Cleanup-Handler(Connection) 11845 { 11846 Retrieve Session from Connection. 11847 if (Connection can still exchange iSCSI PDUs) { 11848 NewConnection = Connection; 11849 } else { 11850 Start-Timer(Connection-Resource-Timeout-Handler, 11851 Connection, Connection.CurrentTimeout); 11852 if (there are other logged-in connections) { 11853 NewConnection = Pick-A-Logged-In-Connection(Session); 11854 } else { 11855 NewConnection = 11856 CreateTransportConnection(Session.OtherEndInfo); 11857 Initiate an implicit Logout on NewConnection for 11858 Connection.CID. 11859 return; 11860 } 11861 } 11862 Build-And-Send-Logout(NewConnection, Connection.CID, 11863 RecoveryRemove); 11864 } 11866 Transport_Exception_Handler(Connection) 11867 { 11868 Connection.PerformConnectionCleanup = TRUE; 11869 if (the event is an unexpected transport disconnect) { 11870 Connection.State = CLEANUP_WAIT; 11872 Connection.CurrentTimeout = DefaultTime2Retain; 11873 Start-Timer(Connection-Cleanup-Handler, Connection, 11874 DefaultTime2Wait); 11876 } else { 11877 Connection.State = FREE; 11878 } 11879 } 11881 Julian Satran Expires August 2003 231 11882 iSCSI 19-January-03 11884 E.4.3 Target Algorithms 11886 Receive-a-In-PDU(Connection, CurrentPDU) 11887 { 11888 check-basic-validity(CurrentPDU); 11889 if (Header-Digest-Bad) discard, return; 11890 else if (Data-Digest-Bad) { 11891 Build-And-Send-Reject(Connection, CurrentPDU, 11892 Payload-Digest-Error); 11893 discard, return; 11894 } 11895 Retrieve TCB and Session. 11896 if (CurrentPDU.type == Logout) { 11897 if (CurrentPDU.ReasonCode = RecoveryRemove) { 11898 Retrieve the CleanupConnection from CurrentPDU.CID). 11899 for (each command active on CleanupConnection) { 11900 Quiesce-And-Prepare-for-New-Allegiance(Session, 11901 TCB); 11902 TCB.CurrentlyAllegiant = FALSE; 11903 } 11904 Cleanup-Connection-State(CleanupConnection); 11905 if ((quiescing successful) and (cleanup successful)) { 11906 Build-And-Send-Logout-Response(Connection, 11907 CleanupConnection.CID, 11908 Success); 11909 } else { 11910 Build-And-Send-Logout-Response(Connection, 11911 CleanupConnection.CID, 11912 Failure); 11913 } 11914 } 11915 } else if ((CurrentPDU.type == Login) and 11916 operational ErrorRecoveryLevel == 2) { 11917 Retrieve the CleanupConnection from CurrentPDU.CID). 11918 for (each command active on CleanupConnection) { 11919 Quiesce-And-Prepare-for-New-Allegiance(Session, 11920 TCB); 11921 TCB.CurrentlyAllegiant = FALSE; 11922 } 11923 Cleanup-Connection-State(CleanupConnection); 11924 if ((quiescing successful) and (cleanup successful)) { 11925 Continue with the rest of the Login processing; 11926 } else { 11927 Build-And-Send-Login-Response(Connection, 11928 CleanupConnection.CID, Target 11929 Error); 11930 } 11931 } 11933 Julian Satran Expires August 2003 232 11934 iSCSI 19-January-03 11936 } else if (CurrentPDU.type == TaskManagement) { 11937 if (CurrentPDU.function == "TaskReassign") { 11938 if (Session.ErrorRecoveryLevel < 2) { 11939 Build-And-Send-TaskMgmt-Response(Connection, 11940 CurrentPDU, "Allegiance reassignment 11941 not supported"); 11942 } else if (task is not found) { 11943 Build-And-Send-TaskMgmt-Response(Connection, 11944 CurrentPDU, "Task not in task set"); 11945 } else if (task is currently allegiant) { 11946 Build-And-Send-TaskMgmt-Response(Connection, 11947 CurrentPDU, "Task still allegiant"); 11948 } else { 11949 Establish-New-Allegiance(TCB, Connection); 11950 TCB.CurrentlyAllegiant = TRUE; 11951 Schedule-Command-To-Continue(TCB); 11952 } 11953 } 11954 } else { /* REST UNRELATED TO CONNECTION-RECOVERY, 11955 * NOT SHOWN */ 11956 } 11957 } 11959 Transport_Exception_Handler(Connection) 11960 { 11961 Connection.PerformConnectionCleanup = TRUE; 11962 if (the event is an unexpected transport disconnect) { 11963 Connection.State = CLEANUP_WAIT; 11964 Start-Timer(Connection-Resource-Timeout-Handler, 11965 Connection, 11967 (DefaultTime2Wait+DefaultTime2Retain)); 11968 if (this Session has full-feature phase connections left) 11969 { 11970 DifferentConnection = 11971 Pick-A-Logged-In-Connection(Session); 11972 Build-And-Send-Async(DifferentConnection, 11973 DroppedConnection, DefaultTime2Wait, 11974 DefaultTime2Retain); 11975 } 11976 } else { 11977 Connection.State = FREE; 11978 } 11979 } 11981 Julian Satran Expires August 2003 233 11982 iSCSI 19-January-03 11984 Appendix F. Clearing Effects of Various Events on Targets 11986 F.1 Clearing Effects on iSCSI Objects 11988 The following tables describe the target behavior on receiving the 11989 events specified in the rows of the table. The second table is an 11990 extension of the first table and defines clearing actions for more 11991 objects on the same events. The legend is: 11993 Y = Yes (cleared/discarded/reset on the event specified in the 11994 row). Unless otherwise noted, the clearing action is only 11995 applicable for the issuing initiator port. 11996 N = No (not affected on the event specified in the row, i.e., 11997 stays at previous value). 11998 NA = Not Applicable or Not Defined. 12000 +-----+-----+-----+-----+-----+ 12001 |IT(1)|IC(2)|CT(5)|ST(6)|PP(7)| 12002 +---------------------+-----+-----+-----+-----+-----+ 12003 |connection failure(8)|Y |Y |N |N |Y | 12004 +---------------------+-----+-----+-----+-----+-----+ 12005 |connection state |NA |NA |Y |N |NA | 12006 |timeout (9) | | | | | | 12007 +---------------------+-----+-----+-----+-----+-----+ 12008 |session timeout/ |Y |Y |Y |Y |Y(14)| 12009 |closure/reinstatement| | | | | | 12010 |(10) | | | | | | 12011 +---------------------+-----+-----+-----+-----+-----+ 12012 |session continuation |NA |NA |N(11)|N |NA | 12013 |(12) | | | | | | 12014 +---------------------+-----+-----+-----+-----+-----+ 12015 |successful connection|Y |Y |Y |N |Y(13)| 12016 |close logout | | | | | | 12017 +---------------------+-----+-----+-----+-----+-----+ 12018 |session failure (18) |Y |Y |N |N |Y | 12019 +---------------------+-----+-----+-----+-----+-----+ 12020 |successful recovery |Y |Y |N |N |Y(13)| 12021 |Logout | | | | | | 12022 +---------------------+-----+-----+-----+-----+-----+ 12023 |failed Logout |Y |Y |N |N |Y | 12024 +---------------------+-----+-----+-----+-----+-----+ 12025 |connection Login |NA |NA |NA |Y(15)|NA | 12026 |(leading) | | | | | | 12027 +---------------------+-----+-----+-----+-----+-----+ 12028 |connection Login |NA |NA |N(11)|N |Y | 12029 |(non-leading) | | | | | | 12030 +---------------------+-----+-----+-----+-----+-----+ 12031 |target cold reset(16)|Y |Y |Y |Y |Y | 12032 +---------------------+-----+-----+-----+-----+-----+ 12033 |target warm reset(16)|Y |Y |Y |Y |Y | 12034 +---------------------+-----+-----+-----+-----+-----+ 12035 |LU reset(19) |Y |Y |Y |Y |Y | 12036 +---------------------+-----+-----+-----+-----+-----+ 12037 |powercycle(16) |Y |Y |Y |Y |Y | 12038 +---------------------+-----+-----+-----+-----+-----+ 12040 Julian Satran Expires August 2003 234 12041 iSCSI 19-January-03 12043 1.Incomplete TTTs - Target Transfer Tags on which the target is 12044 still expecting PDUs to be received. Examples include TTTs received 12045 via R2T, NOP-IN, etc. 12047 2.Immediate Commands - immediate commands, but waiting for execution 12048 on a target. For example, Abort Task Set. 12050 5.Connection Tasks - tasks that are active on the iSCSI connection 12051 in question. 12053 6.Session Tasks - tasks that are active on the entire iSCSI session. 12054 A union of "connection tasks" on all participating connections. 12056 7.Partial PDUs (if any) - PDUs that are partially sent and waiting 12057 for transport window credit to complete the transmission. 12059 8.Connection failure is a connection exception condition - one of 12060 the transport connections shutdown, transport connections reset, or 12061 transport connections timed out, which abruptly terminated the iSCSI 12062 full-feature phase connection. A connection failure always takes the 12063 connection state machine to the CLEANUP_WAIT state. 12065 9.Connection state timeout happens if a connection spends more time 12066 than agreed upon during Login negotiation in the CLEANUP_WAIT state, 12067 and this takes the connection to the FREE state (M1 transition in 12068 connection cleanup state diagram). 12070 10.These are defined in Section 5.3.5 Session Reinstatement, 12071 Closure, and Timeout. 12073 11.This clearing effect is "Y" only if it is a connection 12074 reinstatement and the operational ErrorRecoveryLevel is less than 2. 12076 12.Session continuation is defined in Section 5.3.6 Session 12077 Continuation and Failure. 12079 13.This clearing effect is only valid if the connection is being 12080 logged out on a different connection and when the connection being 12081 logged out on the target may have some partial PDUs pending to be 12082 sent. In all other cases, the effect is "NA". 12084 14.This clearing effect is only valid for a "close the session" 12085 logout in a multi-connection session. In all other cases, the 12086 effect is "NA". 12088 15.Only applicable if this leading connection login is a session 12089 reinstatement. If this is not the case, it is "NA". 12091 16.This operation affects all logged-in initiators. 12093 18.Session failure is defined in Section 5.3.6 Session Continuation 12094 and Failure. 12096 19.This operation affects all logged-in initiators and the clearing 12097 effects are only applicable to the LU being reset. 12099 Julian Satran Expires August 2003 235 12100 iSCSI 19-January-03 12102 +-----+-----+-----+-----+-----+ 12103 |DC(1)|DD(2)|SS(3)|CS(4)|DS(5)| 12104 +---------------------+-----+-----+-----+-----+-----+ 12105 |connection failure |N |Y |N |N |N | 12106 +---------------------+-----+-----+-----+-----+-----+ 12107 |connection state |Y |NA |Y |N |NA | 12108 |timeout | | | | | | 12109 +---------------------+-----+-----+-----+-----+-----+ 12110 |session timeout/ |Y |Y |Y(7) |Y |NA | 12111 |closure/reinstatement| | | | | | 12112 +---------------------+-----+-----+-----+-----+-----+ 12113 |session continuation |N(11)|NA*12|NA |N |NA*13| 12114 +---------------------+-----+-----+-----+-----+-----+ 12115 |successful connection|Y |Y |Y |N |NA | 12116 |close Logout | | | | | | 12117 +---------------------+-----+-----+-----+-----+-----+ 12118 |session failure |N |Y |N |N |N | 12119 +---------------------+-----+-----+-----+-----+-----+ 12120 |successful recovery |Y |Y |Y |N |N | 12121 |Logout | | | | | | 12122 +---------------------+-----+-----+-----+-----+-----+ 12123 |failed Logout |N |Y(9) |N |N |N | 12124 +---------------------+-----+-----+-----+-----+-----+ 12125 |connection Login |NA |NA |N(8) |N(8) |NA | 12126 |(leading | | | | | | 12127 +---------------------+-----+-----+-----+-----+-----+ 12128 |connection Login |N(11)|NA*12|N(8) |N |NA*13| 12129 |(non-leading) | | | | | | 12130 +---------------------+-----+-----+-----+-----+-----+ 12131 |target cold reset |Y |Y |Y |Y(10)|NA | 12132 +---------------------+-----+-----+-----+-----+-----+ 12133 |target warm reset |Y |Y |N |N |NA | 12134 +---------------------+-----+-----+-----+-----+-----+ 12135 |LU reset |N |Y |N |N |N | 12136 +---------------------+-----+-----+-----+-----+-----+ 12137 |powercycle |Y |Y |Y |Y(10)|NA | 12138 +---------------------+-----+-----+-----+-----+-----+ 12140 1.Discontiguous Commands - commands allegiant to the connection in 12141 question and waiting to be reordered in the iSCSI layer. All "Y"s in 12142 this column assume that the task causing the event (if indeed the 12143 event is the result of a task) is issued as an immediate command, 12144 because the discontiguities can be ahead of the task. 12146 2.Discontiguous Data - data PDUs received for the task in question 12147 and waiting to be reordered due to prior discontiguities in DataSN. 12149 3.StatSN 12151 4.CmdSN 12153 5.DataSN 12155 7.It clears the StatSN on all the connections. 12157 8.This sequence number is instantiated on this event. 12159 Julian Satran Expires August 2003 236 12160 iSCSI 19-January-03 12162 9.A logout failure drives the connection state machine to the 12163 CLEANUP_WAIT state, similar to the connection failure event. Hence, 12164 it has a similar effect on this and several other protocol aspects. 12166 10.This is cleared by virtue of the fact that all sessions with all 12167 initiators are terminated. 12169 11.This clearing effect is "Y" if it is a connection reinstatement. 12171 12.This clearing effect is "Y" only if it is a connection 12172 reinstatement and the operational ErrorRecoveryLevel is 2. 12174 13.This clearing effect is "N" only if it is a connection 12175 reinstatement and the operational ErrorRecoveryLevel is 2. 12177 F.2 Clearing Effects on SCSI Objects 12179 The only iSCSI protocol action that can effect clearing actions on 12180 SCSI objects is the "I_T nexus loss" notification (Section 4.3.5.1 12181 Loss of Nexus notification). [SPC3] describes the clearing effects 12182 of this notification on a variety of SCSI attributes. In addition, 12183 SCSI standards documents (such as [SAM2] and [SBC]) define 12184 additional clearing actions that may take place for several SCSI 12185 objects on SCSI events such as LU resets and power-on resets. 12187 Since iSCSI defines a target cold reset as a protocol-equivalent to 12188 a target power-cycle, the iSCSI target cold reset must also be 12189 considered as the power-on reset event in interpreting the actions 12190 defined in the SCSI standards. 12192 When the iSCSI session is reconstructed (between the same SCSI ports 12193 with the same nexus identifier) reestablishing the same I_T nexus, 12194 all SCSI objects that are defined to not clear on the "I_T nexus 12195 loss" notification event, such as persistent reservations, are 12196 automatically associated to this new session. 12198 Julian Satran Expires August 2003 237 12199 iSCSI 19-January-03 12201 Full Copyright Statement 12203 "Copyright (C) The Internet Society (date). All Rights Reserved. 12204 This document and translations of it may be copied and furnished to 12205 others, and derivative works that comment on or otherwise explain it 12206 or assist in its implementation may be prepared, copied, published 12207 and distributed, in whole or in part, without restriction of any 12208 kind, provided that the above copyright notice and this paragraph 12209 are included on all such copies and derivative works. However, this 12210 document itself may not be modified in any way, such as by removing 12211 the copyright notice or references to the Internet Society or other 12212 Internet organizations, except as needed for the purpose of 12213 developing Internet standards in which case the procedures for 12214 copyrights defined in the Internet Standards process must be 12215 followed, or as required to translate it into languages other than 12216 English. 12218 The limited permissions granted above are perpetual and will not be 12219 revoked by the Internet Society or its successors or assigns. 12221 This document and the information contained herein is provided on an 12222 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 12223 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 12224 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 12225 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 12226 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE." 12228 Notice of Intellectual Property Rights 12230 The IETF has been notified of intellectual property rights claimed 12231 in regard to some or all of the specification contained in this 12232 document. For more information consult the online list of claimed 12233 rights. 12235 The IETF takes no position regarding the validity or scope of any 12236 intellectual property or other rights that might be claimed to 12237 pertain to the implementation or use of the technology described in 12238 this document or the extent to which any license under such rights 12239 might or might not be available; neither does it represent that it 12240 has made any effort to identify any such rights. Information on the 12241 IETF's procedures with respect to rights in standards-track and 12242 standards-related documentation can be found in BCP-11. Copies of 12243 claims of rights made available for publication and any assurances 12244 of licenses to be made available, or the result of an attempt made 12245 to obtain a general license or permission for the use of such 12246 proprietary rights by implementors or users of this specification 12247 can be obtained from the IETF Secretariat. 12249 The IETF invites any interested party to bring to its attention any 12250 copyrights, patents or patent applications, or other proprietary 12251 rights which may cover technology that may be required to practice 12252 this standard. Please address the information to the IETF Executive 12253 Director. 12255 Julian Satran Expires August 2003 238